Upload folder using huggingface_hub

Dockerfile

@@ -28,7 +28,7 @@
 # The build script (openenv build) handles context detection and sets appropriate build args.
 
 ARG BASE_IMAGE=ghcr.io/meta-pytorch/openenv-base:latest
-FROM ${BASE_IMAGE} AS builder
+FROM ${BASE_IMAGE:-ghcr.io/meta-pytorch/openenv-base:latest} AS builder
 
 WORKDIR /app
 
@@ -72,8 +72,7 @@ RUN --mount=type=cache,target=/root/.cache/uv \
     fi
 
 # Final runtime stage
-ARG BASE_IMAGE=ghcr.io/meta-pytorch/openenv-base:latest
-FROM ${BASE_IMAGE}
+FROM ${BASE_IMAGE:-ghcr.io/meta-pytorch/openenv-base:latest}
 
 WORKDIR /app
 

__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",
+]

frontend/css/styles.css

@@ -0,0 +1,603 @@
+:root {
+    --bg: #f6f7f4;
+    --surface: #ffffff;
+    --surface-2: #eef4f1;
+    --surface-3: #fff7ed;
+    --line: #d9ded8;
+    --line-strong: #b8c2bd;
+    --text: #17211d;
+    --muted: #66736d;
+    --soft: #8a948f;
+    --teal: #0f766e;
+    --teal-soft: #d9f3ee;
+    --blue: #2563eb;
+    --blue-soft: #dbeafe;
+    --amber: #b45309;
+    --amber-soft: #ffedd5;
+    --red: #b91c1c;
+    --red-soft: #fee2e2;
+    --green: #15803d;
+    --green-soft: #dcfce7;
+    --ink: #111827;
+    --shadow: 0 10px 30px rgba(23, 33, 29, 0.08);
+    --radius: 8px;
+    --font: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+    --mono: "SFMono-Regular", Consolas, "Liberation Mono", monospace;
+}
+
+* {
+    box-sizing: border-box;
+}
+
+body {
+    margin: 0;
+    min-height: 100vh;
+    background:
+        linear-gradient(180deg, rgba(15, 118, 110, 0.08), transparent 360px),
+        var(--bg);
+    color: var(--text);
+    font-family: var(--font);
+}
+
+button,
+input,
+select {
+    font: inherit;
+}
+
+button {
+    cursor: pointer;
+}
+
+button:disabled {
+    cursor: not-allowed;
+    opacity: 0.55;
+}
+
+#app {
+    min-height: 100vh;
+}
+
+.shell {
+    display: grid;
+    grid-template-rows: auto auto 1fr;
+    gap: 14px;
+    max-width: 1480px;
+    min-height: 100vh;
+    margin: 0 auto;
+    padding: 18px;
+}
+
+.topbar {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 16px;
+}
+
+.brand {
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    min-width: 280px;
+}
+
+.mark {
+    display: grid;
+    place-items: center;
+    width: 42px;
+    height: 42px;
+    border: 1px solid var(--line-strong);
+    border-radius: var(--radius);
+    background: var(--surface);
+    box-shadow: var(--shadow);
+    color: var(--teal);
+    font-weight: 800;
+}
+
+.brand h1 {
+    margin: 0;
+    font-size: 21px;
+    line-height: 1.1;
+    letter-spacing: 0;
+}
+
+.brand p {
+    margin: 4px 0 0;
+    color: var(--muted);
+    font-size: 12px;
+}
+
+.top-actions {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    flex-wrap: wrap;
+    justify-content: flex-end;
+}
+
+.panel,
+.commandbar {
+    border: 1px solid var(--line);
+    border-radius: var(--radius);
+    background: rgba(255, 255, 255, 0.92);
+    box-shadow: var(--shadow);
+}
+
+.commandbar {
+    display: grid;
+    grid-template-columns: 1.1fr 0.8fr auto;
+    gap: 12px;
+    padding: 12px;
+    align-items: end;
+}
+
+.fieldrow,
+.action-grid {
+    display: flex;
+    gap: 8px;
+    flex-wrap: wrap;
+    align-items: end;
+}
+
+.field {
+    display: grid;
+    gap: 5px;
+    min-width: 118px;
+}
+
+.field.compact {
+    min-width: 88px;
+}
+
+.field.wide {
+    min-width: 170px;
+}
+
+.field label,
+.section-title,
+.micro-label {
+    color: var(--muted);
+    font-size: 11px;
+    font-weight: 700;
+    letter-spacing: 0.03em;
+    text-transform: uppercase;
+}
+
+select,
+input[type="number"],
+input[type="range"] {
+    min-height: 36px;
+    border: 1px solid var(--line-strong);
+    border-radius: var(--radius);
+    background: #fff;
+    color: var(--text);
+    padding: 7px 9px;
+    outline: none;
+}
+
+select:focus,
+input:focus {
+    border-color: var(--teal);
+    box-shadow: 0 0 0 3px rgba(15, 118, 110, 0.14);
+}
+
+.btn {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    min-height: 36px;
+    border: 1px solid var(--line-strong);
+    border-radius: var(--radius);
+    background: var(--surface);
+    color: var(--text);
+    padding: 8px 12px;
+    font-weight: 700;
+    transition: transform 0.12s, border-color 0.12s, background 0.12s;
+}
+
+.btn:hover {
+    transform: translateY(-1px);
+    border-color: var(--teal);
+}
+
+.btn.primary {
+    border-color: var(--teal);
+    background: var(--teal);
+    color: #fff;
+}
+
+.btn.blue {
+    border-color: var(--blue);
+    background: var(--blue);
+    color: #fff;
+}
+
+.btn.warn {
+    border-color: #f59e0b;
+    background: var(--amber-soft);
+    color: #7c2d12;
+}
+
+.btn.ghost {
+    background: transparent;
+}
+
+.segmented {
+    display: inline-flex;
+    padding: 3px;
+    border: 1px solid var(--line);
+    border-radius: var(--radius);
+    background: var(--surface-2);
+}
+
+.segmented button {
+    min-height: 30px;
+    border: 0;
+    border-radius: 6px;
+    background: transparent;
+    color: var(--muted);
+    padding: 6px 10px;
+    font-weight: 800;
+}
+
+.segmented button.active {
+    background: var(--surface);
+    color: var(--teal);
+    box-shadow: 0 1px 4px rgba(23, 33, 29, 0.14);
+}
+
+.main-grid {
+    display: grid;
+    grid-template-columns: minmax(320px, 0.9fr) minmax(420px, 1.25fr) minmax(340px, 0.95fr);
+    gap: 14px;
+    align-items: start;
+}
+
+.panel {
+    overflow: hidden;
+}
+
+.panel-header {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    gap: 10px;
+    min-height: 48px;
+    padding: 12px 14px;
+    border-bottom: 1px solid var(--line);
+}
+
+.panel-header h2,
+.panel-header h3 {
+    margin: 0;
+    font-size: 14px;
+    line-height: 1.2;
+}
+
+.panel-body {
+    padding: 14px;
+}
+
+.metrics {
+    display: grid;
+    grid-template-columns: repeat(4, 1fr);
+    gap: 8px;
+}
+
+.metric {
+    padding: 10px;
+    border: 1px solid var(--line);
+    border-radius: var(--radius);
+    background: var(--surface);
+}
+
+.metric strong {
+    display: block;
+    margin-top: 4px;
+    font-size: 19px;
+}
+
+.badge {
+    display: inline-flex;
+    align-items: center;
+    min-height: 22px;
+    border-radius: 999px;
+    padding: 3px 9px;
+    background: var(--surface-2);
+    color: var(--muted);
+    font-size: 11px;
+    font-weight: 800;
+    white-space: nowrap;
+}
+
+.badge.live {
+    background: var(--green-soft);
+    color: var(--green);
+}
+
+.badge.sample {
+    background: var(--amber-soft);
+    color: var(--amber);
+}
+
+.badge.done {
+    background: var(--red-soft);
+    color: var(--red);
+}
+
+.world-map {
+    display: grid;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    gap: 10px;
+}
+
+.region-node {
+    min-height: 118px;
+    border: 1px solid var(--line);
+    border-radius: var(--radius);
+    background: var(--surface);
+    padding: 11px;
+}
+
+.region-node.hot {
+    border-color: #f97316;
+    background: #fff7ed;
+}
+
+.region-top {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    margin-bottom: 8px;
+}
+
+.region-name {
+    font-size: 18px;
+    font-weight: 900;
+}
+
+.bar {
+    height: 8px;
+    border-radius: 999px;
+    overflow: hidden;
+    background: #e5e7eb;
+}
+
+.bar span {
+    display: block;
+    height: 100%;
+    border-radius: inherit;
+    background: var(--teal);
+}
+
+.bar.load span {
+    background: #dc2626;
+}
+
+.bar.comp span {
+    background: #16a34a;
+}
+
+.region-stats {
+    display: grid;
+    gap: 7px;
+}
+
+.statline {
+    display: grid;
+    grid-template-columns: 74px 1fr 42px;
+    gap: 7px;
+    align-items: center;
+    color: var(--muted);
+    font-size: 12px;
+}
+
+.resource-grid {
+    display: grid;
+    grid-template-columns: repeat(2, 1fr);
+    gap: 8px;
+}
+
+.resource {
+    border: 1px solid var(--line);
+    border-radius: var(--radius);
+    background: var(--surface);
+    padding: 10px;
+}
+
+.resource strong {
+    display: block;
+    margin-top: 4px;
+    font-size: 18px;
+}
+
+.action-panel {
+    display: grid;
+    gap: 12px;
+}
+
+.action-form {
+    display: grid;
+    gap: 10px;
+}
+
+.param-grid {
+    display: grid;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    gap: 8px;
+}
+
+.param-grid .full {
+    grid-column: 1 / -1;
+}
+
+.council-stack {
+    display: grid;
+    gap: 10px;
+}
+
+.brain-card {
+    border: 1px solid var(--line);
+    border-radius: var(--radius);
+    background: var(--surface);
+    padding: 12px;
+}
+
+.brain-head {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 10px;
+    margin-bottom: 8px;
+}
+
+.brain-head h3 {
+    margin: 0;
+    font-size: 14px;
+}
+
+.brain-card p {
+    margin: 7px 0 0;
+    color: var(--muted);
+    font-size: 12px;
+    line-height: 1.45;
+}
+
+.decision {
+    border: 1px solid #99f6e4;
+    border-radius: var(--radius);
+    background: #ecfdf5;
+    padding: 12px;
+}
+
+.decision h3 {
+    margin: 0 0 6px;
+    font-size: 14px;
+}
+
+.timeline {
+    display: grid;
+    gap: 8px;
+    max-height: 260px;
+    overflow: auto;
+}
+
+.timeline-entry {
+    display: grid;
+    grid-template-columns: 44px 1fr auto;
+    gap: 8px;
+    align-items: center;
+    border: 1px solid var(--line);
+    border-radius: var(--radius);
+    background: var(--surface);
+    padding: 9px;
+    font-size: 12px;
+}
+
+.timeline-entry strong {
+    font-family: var(--mono);
+}
+
+.timeline-entry.rejected {
+    border-color: #fecaca;
+    background: #fff1f2;
+}
+
+.replay-row {
+    display: grid;
+    grid-template-columns: auto 1fr auto;
+    gap: 10px;
+    align-items: center;
+}
+
+.empty {
+    display: grid;
+    place-items: center;
+    min-height: 160px;
+    border: 1px dashed var(--line-strong);
+    border-radius: var(--radius);
+    color: var(--muted);
+    text-align: center;
+    padding: 20px;
+}
+
+.tiny {
+    color: var(--soft);
+    font-size: 11px;
+    line-height: 1.35;
+}
+
+.mono {
+    font-family: var(--mono);
+}
+
+#toast-root {
+    position: fixed;
+    right: 16px;
+    bottom: 16px;
+    display: grid;
+    gap: 8px;
+    z-index: 20;
+}
+
+.toast {
+    max-width: 360px;
+    border-radius: var(--radius);
+    background: var(--ink);
+    color: #fff;
+    padding: 11px 13px;
+    box-shadow: var(--shadow);
+    font-size: 13px;
+    transition: opacity 0.2s, transform 0.2s;
+}
+
+.toast-error {
+    background: var(--red);
+}
+
+.toast-success {
+    background: var(--green);
+}
+
+.toast-out {
+    opacity: 0;
+    transform: translateY(4px);
+}
+
+@media (max-width: 1180px) {
+    .main-grid,
+    .commandbar {
+        grid-template-columns: 1fr;
+    }
+
+    .metrics {
+        grid-template-columns: repeat(2, 1fr);
+    }
+}
+
+@media (max-width: 720px) {
+    .shell {
+        padding: 10px;
+    }
+
+    .topbar {
+        align-items: flex-start;
+        flex-direction: column;
+    }
+
+    .brand {
+        min-width: 0;
+    }
+
+    .world-map,
+    .resource-grid,
+    .param-grid,
+    .metrics {
+        grid-template-columns: 1fr;
+    }
+
+    .replay-row {
+        grid-template-columns: 1fr;
+    }
+}

frontend/index.html

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>CrisisWorld Cortex</title>
+    <meta name="description" content="Interactive CrisisWorld Cortex dashboard for outbreak-control episodes">
+    <link rel="stylesheet" href="/cortex/css/styles.css">
+</head>
+<body>
+    <div id="app"></div>
+    <div id="toast-root" aria-live="polite"></div>
+    <script type="module" src="/cortex/js/app.js"></script>
+</body>
+</html>

frontend/js/actions.js

@@ -0,0 +1,118 @@
+export const RESOURCE_TYPES = [
+    'test_kits',
+    'hospital_beds',
+    'mobile_units',
+    'vaccine_doses',
+];
+
+export const DATA_TYPES = [
+    'case_survey',
+    'hospital_audit',
+    'compliance_check',
+];
+
+export const SEVERITIES = [
+    'none',
+    'light',
+    'moderate',
+    'strict',
+];
+
+export const AUTHORITIES = [
+    'regional',
+    'national',
+];
+
+export const ACTION_KINDS = [
+    { id: 'deploy_resource', label: 'Deploy' },
+    { id: 'request_data', label: 'Request Data' },
+    { id: 'restrict_movement', label: 'Restrict' },
+    { id: 'escalate', label: 'Escalate' },
+    { id: 'reallocate_budget', label: 'Reallocate' },
+    { id: 'no_op', label: 'No-op' },
+];
+
+export function normalizeRegionSelection(state) {
+    const regions = state.observation?.regions || [];
+    if (!regions.length) return {};
+    if (regions.some((region) => region.region === state.selectedRegion)) return {};
+    return { selectedRegion: regions[0].region };
+}
+
+export function buildAction(state) {
+    const region = state.selectedRegion || state.observation?.regions?.[0]?.region || 'R1';
+    const quantity = Math.max(0, Number.parseInt(state.quantity, 10) || 0);
+    switch (state.selectedActionKind) {
+        case 'deploy_resource':
+            return {
+                kind: 'deploy_resource',
+                region,
+                resource_type: state.selectedResource,
+                quantity,
+            };
+        case 'request_data':
+            return {
+                kind: 'request_data',
+                region,
+                data_type: state.dataType,
+            };
+        case 'restrict_movement':
+            return {
+                kind: 'restrict_movement',
+                region,
+                severity: state.severity,
+            };
+        case 'escalate':
+            return {
+                kind: 'escalate',
+                to_authority: state.authority,
+            };
+        case 'reallocate_budget':
+            return {
+                kind: 'reallocate_budget',
+                from_resource: state.selectedResource,
+                to_resource: state.selectedToResource,
+                amount: quantity,
+            };
+        case 'no_op':
+        default:
+            return { kind: 'no_op' };
+    }
+}
+
+export function formatAction(action) {
+    if (!action) return 'none';
+    switch (action.kind) {
+        case 'deploy_resource':
+            return `deploy ${action.quantity} ${labelize(action.resource_type)} to ${action.region}`;
+        case 'request_data':
+            return `request ${labelize(action.data_type)} for ${action.region}`;
+        case 'restrict_movement':
+            return `${action.severity} movement limits in ${action.region}`;
+        case 'escalate':
+            return `escalate to ${action.to_authority}`;
+        case 'reallocate_budget':
+            return `move ${action.amount} from ${labelize(action.from_resource)} to ${labelize(action.to_resource)}`;
+        case 'public_communication':
+            return `public communication to ${action.audience}`;
+        case 'no_op':
+        default:
+            return 'no-op';
+    }
+}
+
+export function actionFromLogEntry(entry) {
+    return entry?.action || null;
+}
+
+export function labelize(value) {
+    return String(value || '')
+        .replaceAll('_', ' ')
+        .replace(/\b\w/g, (letter) => letter.toUpperCase());
+}
+
+export function resourceValue(resources, resourceType) {
+    if (!resources) return 0;
+    if (resourceType === 'hospital_beds') return resources.hospital_beds_free || 0;
+    return resources[resourceType] || 0;
+}

frontend/js/api.js

@@ -0,0 +1,45 @@
+async function postJson(url, payload) {
+    const response = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(payload),
+    });
+
+    let data = null;
+    try {
+        data = await response.json();
+    } catch {
+        data = null;
+    }
+
+    if (!response.ok) {
+        const detail = data?.detail || data?.message || `${response.status} ${response.statusText}`;
+        throw new Error(detail);
+    }
+    return data;
+}
+
+export async function resetEnvironment({ taskName, seed, maxTicks }) {
+    return postJson('/web/reset', {
+        task_name: taskName,
+        seed,
+        max_ticks: maxTicks,
+    });
+}
+
+export async function stepEnvironment(payload) {
+    return postJson('/web/step', {
+        action: {
+            action: payload,
+            metadata: {},
+        },
+    });
+}
+
+export async function getEnvironmentState() {
+    const response = await fetch('/web/state');
+    if (!response.ok) {
+        throw new Error(`${response.status} ${response.statusText}`);
+    }
+    return response.json();
+}

frontend/js/app.js

@@ -0,0 +1,613 @@
+import { resetEnvironment, stepEnvironment } from './api.js';
+import {
+    ACTION_KINDS,
+    AUTHORITIES,
+    DATA_TYPES,
+    RESOURCE_TYPES,
+    SEVERITIES,
+    buildAction,
+    formatAction,
+    labelize,
+    normalizeRegionSelection,
+    resourceValue,
+} from './actions.js';
+import { narrateCouncil } from './council-narration.js';
+import { goToFrame, setReplayTrace, stopReplay, toggleReplayPlayback } from './replay.js';
+import { SAMPLE_TRACE } from './samples.js';
+import { AppState, addTraceFrame, setState, showToast, subscribe } from './state.js';
+
+const app = document.getElementById('app');
+let liveAutoplayTimer = null;
+
+function init() {
+    const first = SAMPLE_TRACE[0];
+    setState({
+        replayTrace: SAMPLE_TRACE,
+        replayIndex: 0,
+        observation: first.observation,
+        reward: first.reward,
+        done: first.done,
+        council: narrateCouncil(first.observation, first.reward),
+    });
+    subscribe(render);
+    render();
+}
+
+function render() {
+    const regionPatch = normalizeRegionSelection(AppState);
+    if (Object.keys(regionPatch).length) {
+        setState(regionPatch);
+        return;
+    }
+    const council = narrateCouncil(AppState.observation, AppState.reward || 0);
+    AppState.council = council;
+    app.innerHTML = `
+        <main class="shell">
+            ${renderTopbar()}
+            ${renderCommandbar()}
+            <section class="main-grid">
+                <div class="left-col">
+                    ${renderPhasePanel(council)}
+                    ${renderWorldPanel()}
+                    ${renderResourcesPanel()}
+                </div>
+                <div class="center-col">
+                    ${renderActionPanel(council)}
+                    ${renderTimelinePanel()}
+                </div>
+                <div class="right-col">
+                    ${renderCouncilPanel(council)}
+                    ${renderReplayPanel()}
+                </div>
+            </section>
+        </main>
+    `;
+    bindEvents();
+}
+
+function renderTopbar() {
+    return `
+        <header class="topbar">
+            <div class="brand">
+                <div class="mark">CW</div>
+                <div>
+                    <h1>CrisisWorld Cortex</h1>
+                    <p>Outbreak response dashboard for live OpenEnv episodes and replay traces.</p>
+                </div>
+            </div>
+            <div class="top-actions">
+                <span class="badge ${AppState.mode === 'live' ? 'live' : 'sample'}">${AppState.mode === 'live' ? 'Live env' : 'Sample replay'}</span>
+                ${AppState.done ? '<span class="badge done">Terminal</span>' : ''}
+                <span class="badge">${AppState.connection}</span>
+                <button class="btn ghost" data-action="load-sample">Load Sample</button>
+                <button class="btn ghost" data-action="open-web">Open /web</button>
+            </div>
+        </header>
+    `;
+}
+
+function renderCommandbar() {
+    return `
+        <section class="commandbar">
+            <div class="fieldrow">
+                <label class="field wide">
+                    <span>Task</span>
+                    <select data-bind="taskName">
+                        ${option('outbreak_easy', 'Outbreak Easy', AppState.taskName)}
+                        ${option('outbreak_medium', 'Outbreak Medium', AppState.taskName)}
+                        ${option('outbreak_hard', 'Outbreak Hard', AppState.taskName)}
+                    </select>
+                </label>
+                <label class="field compact">
+                    <span>Seed</span>
+                    <input type="number" min="0" step="1" data-bind="seed" value="${AppState.seed}">
+                </label>
+                <label class="field compact">
+                    <span>Max ticks</span>
+                    <input type="number" min="1" max="30" step="1" data-bind="maxTicks" value="${AppState.maxTicks}">
+                </label>
+                <button class="btn primary" data-action="reset-live">Reset Live Episode</button>
+            </div>
+            <div class="fieldrow">
+                <label class="field wide">
+                    <span>Replay speed</span>
+                    <input type="range" min="350" max="2600" step="50" data-bind="replaySpeedMs" value="${AppState.replaySpeedMs}">
+                </label>
+                <span class="badge">${AppState.replaySpeedMs} ms</span>
+            </div>
+            <div class="fieldrow">
+                <button class="btn ${AppState.autoplayLive ? 'warn' : 'blue'}" data-action="toggle-live-autoplay" ${AppState.mode !== 'live' || AppState.done ? 'disabled' : ''}>
+                    ${AppState.autoplayLive ? 'Stop Autoplay' : 'Autoplay Decisions'}
+                </button>
+            </div>
+        </section>
+    `;
+}
+
+function renderPhasePanel(council) {
+    const obs = AppState.observation;
+    return `
+        <section class="panel">
+            <div class="panel-header">
+                <h2>Episode State</h2>
+                <span class="badge">${AppState.statusMessage}</span>
+            </div>
+            <div class="panel-body">
+                <div class="metrics">
+                    ${metric('Tick', obs?.tick ?? '-', `${obs?.ticks_remaining ?? '-'} left`)}
+                    ${metric('Phase', council.phase, `round ${council.round}`)}
+                    ${metric('Budget', council.budget || '-', 'cognition')}
+                    ${metric('Reward', formatReward(AppState.reward), `total ${formatReward(AppState.totalReward)}`)}
+                </div>
+            </div>
+        </section>
+    `;
+}
+
+function renderWorldPanel() {
+    const obs = AppState.observation;
+    if (!obs) return panel('World State', '<div class="empty">No observation loaded.</div>');
+    const regions = obs.regions || [];
+    const maxScore = Math.max(...regions.map((region) => pressure(region)), 1);
+    const html = `
+        <div class="world-map">
+            ${regions.map((region) => renderRegion(region, pressure(region) / maxScore)).join('')}
+        </div>
+    `;
+    return panel('World State', html);
+}
+
+function renderRegion(region, heat) {
+    const hot = heat > 0.78 ? 'hot' : '';
+    return `
+        <article class="region-node ${hot}">
+            <div class="region-top">
+                <span class="region-name">${region.region}</span>
+                <span class="badge">${Math.round(heat * 100)} pressure</span>
+            </div>
+            <div class="region-stats">
+                ${statline('Cases', clamp(region.reported_cases_d_ago / 180, 0, 1), region.reported_cases_d_ago)}
+                ${statline('Load', region.hospital_load, pct(region.hospital_load), 'load')}
+                ${statline('Comply', region.compliance_proxy, pct(region.compliance_proxy), 'comp')}
+            </div>
+        </article>
+    `;
+}
+
+function renderResourcesPanel() {
+    const obs = AppState.observation;
+    const resources = obs?.resources || {};
+    const constraints = obs?.legal_constraints || [];
+    const restrictions = obs?.active_restrictions || [];
+    return panel('Resources and Constraints', `
+        <div class="resource-grid">
+            ${RESOURCE_TYPES.map((type) => `
+                <div class="resource">
+                    <span class="micro-label">${labelize(type)}</span>
+                    <strong>${resourceValue(resources, type)}</strong>
+                </div>
+            `).join('')}
+        </div>
+        <div style="height: 12px"></div>
+        <div class="section-title">Active restrictions</div>
+        <div class="timeline" style="max-height: 130px; margin-top: 8px;">
+            ${restrictions.length ? restrictions.map((item) => `
+                <div class="timeline-entry">
+                    <strong>${item.region}</strong>
+                    <span>${labelize(item.severity)} movement limits</span>
+                    <span class="badge">${item.ticks_remaining} ticks</span>
+                </div>
+            `).join('') : '<div class="tiny">None active.</div>'}
+        </div>
+        <div style="height: 12px"></div>
+        <div class="section-title">Legal constraints</div>
+        <div class="timeline" style="max-height: 130px; margin-top: 8px;">
+            ${constraints.length ? constraints.map((item) => `
+                <div class="timeline-entry rejected">
+                    <strong>${item.rule_id}</strong>
+                    <span>Blocks ${item.blocked_action}</span>
+                    <span class="badge">${item.unlock_via}</span>
+                </div>
+            `).join('') : '<div class="tiny">No active legal blockers.</div>'}
+        </div>
+    `);
+}
+
+function renderActionPanel(council) {
+    const selected = AppState.selectedActionKind;
+    return panel('Task Controls', `
+        <div class="action-panel">
+            <div class="segmented" role="tablist" aria-label="Action type">
+                ${ACTION_KINDS.map((kind) => `
+                    <button data-kind="${kind.id}" class="${selected === kind.id ? 'active' : ''}">${kind.label}</button>
+                `).join('')}
+            </div>
+            <div class="action-form">
+                ${renderActionInputs(selected)}
+                <div class="fieldrow">
+                    <button class="btn primary" data-action="submit-action" ${AppState.mode !== 'live' || AppState.done ? 'disabled' : ''}>Submit Action</button>
+                    <button class="btn blue" data-action="apply-recommendation" ${AppState.mode !== 'live' || AppState.done ? 'disabled' : ''}>Apply Recommendation</button>
+                    <span class="tiny">Recommendation: ${formatAction(council.decision)}</span>
+                </div>
+            </div>
+        </div>
+    `);
+}
+
+function renderActionInputs(kind) {
+    const regions = AppState.observation?.regions || [{ region: AppState.selectedRegion || 'R1' }];
+    const regionSelect = `
+        <label class="field">
+            <span>Region</span>
+            <select data-bind="selectedRegion">
+                ${regions.map((region) => option(region.region, region.region, AppState.selectedRegion)).join('')}
+            </select>
+        </label>
+    `;
+    const resourceSelect = (bindName, label) => `
+        <label class="field">
+            <span>${label}</span>
+            <select data-bind="${bindName}">
+                ${RESOURCE_TYPES.map((type) => option(type, labelize(type), AppState[bindName])).join('')}
+            </select>
+        </label>
+    `;
+    const quantity = `
+        <label class="field">
+            <span>${kind === 'reallocate_budget' ? 'Amount' : 'Quantity'}</span>
+            <input type="number" min="0" step="1" data-bind="quantity" value="${AppState.quantity}">
+        </label>
+    `;
+    if (kind === 'deploy_resource') {
+        return `<div class="param-grid">${regionSelect}${resourceSelect('selectedResource', 'Resource')}${quantity}</div>`;
+    }
+    if (kind === 'request_data') {
+        return `
+            <div class="param-grid">
+                ${regionSelect}
+                <label class="field">
+                    <span>Data type</span>
+                    <select data-bind="dataType">${DATA_TYPES.map((type) => option(type, labelize(type), AppState.dataType)).join('')}</select>
+                </label>
+            </div>
+        `;
+    }
+    if (kind === 'restrict_movement') {
+        return `
+            <div class="param-grid">
+                ${regionSelect}
+                <label class="field">
+                    <span>Severity</span>
+                    <select data-bind="severity">${SEVERITIES.map((type) => option(type, labelize(type), AppState.severity)).join('')}</select>
+                </label>
+            </div>
+        `;
+    }
+    if (kind === 'escalate') {
+        return `
+            <div class="param-grid">
+                <label class="field">
+                    <span>Authority</span>
+                    <select data-bind="authority">${AUTHORITIES.map((type) => option(type, labelize(type), AppState.authority)).join('')}</select>
+                </label>
+            </div>
+        `;
+    }
+    if (kind === 'reallocate_budget') {
+        return `<div class="param-grid">${resourceSelect('selectedResource', 'From')}${resourceSelect('selectedToResource', 'To')}${quantity}</div>`;
+    }
+    return '<div class="tiny">No parameters required.</div>';
+}
+
+function renderCouncilPanel(council) {
+    return panel('Narrated Council', `
+        <div class="tiny" style="margin-bottom: 10px;">
+            Frontend visualization derived from observations. It is not a live Cortex runtime or LLM council.
+        </div>
+        <div class="decision">
+            <h3>Converged action</h3>
+            <strong>${formatAction(council.decision)}</strong>
+            <p class="tiny">${council.rationale}</p>
+        </div>
+        <div style="height: 10px"></div>
+        <div class="council-stack">
+            ${council.recommendations.map((report) => renderBrain(report)).join('')}
+        </div>
+        <div style="height: 10px"></div>
+        <div class="section-title">Preserved dissent</div>
+        <div class="timeline" style="max-height: 150px; margin-top: 8px;">
+            ${council.preservedDissent.length ? council.preservedDissent.map((item, index) => `
+                <div class="timeline-entry">
+                    <strong>D${index + 1}</strong>
+                    <span>${item}</span>
+                    <span></span>
+                </div>
+            `).join('') : '<div class="tiny">No dissent preserved on this frame.</div>'}
+        </div>
+    `);
+}
+
+function renderBrain(report) {
+    return `
+        <article class="brain-card">
+            <div class="brain-head">
+                <h3>${report.name}</h3>
+                <span class="badge">${Math.round(report.confidence * 100)} conf</span>
+            </div>
+            <div class="bar"><span style="width: ${Math.round(report.confidence * 100)}%"></span></div>
+            <p><strong>${formatAction(report.action)}</strong></p>
+            <p>${report.summary}</p>
+            <p><span class="micro-label">Challenge</span><br>${report.challenge}</p>
+            <p><span class="micro-label">Minority</span><br>${formatAction(report.minority)}</p>
+        </article>
+    `;
+}
+
+function renderTimelinePanel() {
+    const log = AppState.observation?.recent_action_log || [];
+    const liveTrace = AppState.liveTrace || [];
+    return panel('Final Action Timeline', `
+        <div class="timeline">
+            ${log.length ? log.map((entry) => `
+                <div class="timeline-entry ${entry.accepted ? '' : 'rejected'}">
+                    <strong>T${entry.tick}</strong>
+                    <span>${formatAction(entry.action)}</span>
+                    <span class="badge">${entry.accepted ? 'accepted' : 'rejected'}</span>
+                </div>
+            `).join('') : '<div class="empty">No actions have been submitted yet.</div>'}
+        </div>
+        <div style="height: 12px"></div>
+        <div class="tiny">Live trace frames captured this session: ${liveTrace.length}</div>
+    `);
+}
+
+function renderReplayPanel() {
+    const max = Math.max(0, AppState.replayTrace.length - 1);
+    return panel('Replay', `
+        <div class="replay-row">
+            <button class="btn" data-action="toggle-replay">${AppState.replayPlaying ? 'Pause' : 'Play'}</button>
+            <input type="range" min="0" max="${max}" step="1" value="${AppState.replayIndex}" data-action="scrub-replay" ${max === 0 ? 'disabled' : ''}>
+            <span class="badge">${AppState.replayIndex + 1}/${AppState.replayTrace.length || 1}</span>
+        </div>
+        <div style="height: 10px"></div>
+        <div class="fieldrow">
+            <button class="btn ghost" data-action="use-live-trace" ${AppState.liveTrace.length ? '' : 'disabled'}>Use Live Trace</button>
+            <button class="btn ghost" data-action="load-sample">Use Sample Trace</button>
+        </div>
+        <p class="tiny">Replay changes the displayed frame only. It does not step the environment.</p>
+    `);
+}
+
+function panel(title, body) {
+    return `
+        <section class="panel">
+            <div class="panel-header">
+                <h2>${title}</h2>
+            </div>
+            <div class="panel-body">${body}</div>
+        </section>
+    `;
+}
+
+function metric(label, value, hint) {
+    return `
+        <div class="metric">
+            <span class="micro-label">${label}</span>
+            <strong>${value}</strong>
+            <span class="tiny">${hint}</span>
+        </div>
+    `;
+}
+
+function statline(label, value, display, extraClass = '') {
+    return `
+        <div class="statline">
+            <span>${label}</span>
+            <div class="bar ${extraClass}"><span style="width: ${Math.round(clamp(value, 0, 1) * 100)}%"></span></div>
+            <strong>${display}</strong>
+        </div>
+    `;
+}
+
+function bindEvents() {
+    document.querySelectorAll('[data-bind]').forEach((element) => {
+        element.addEventListener('change', () => {
+            const key = element.dataset.bind;
+            const value = element.type === 'number' || element.type === 'range'
+                ? Number.parseInt(element.value, 10)
+                : element.value;
+            setState({ [key]: value });
+        });
+        if (element.type === 'range') {
+            element.addEventListener('input', () => {
+                const key = element.dataset.bind;
+                setState({ [key]: Number.parseInt(element.value, 10) });
+            });
+        }
+    });
+
+    document.querySelectorAll('[data-kind]').forEach((button) => {
+        button.addEventListener('click', () => setState({ selectedActionKind: button.dataset.kind }));
+    });
+
+    document.querySelectorAll('[data-action]').forEach((element) => {
+        element.addEventListener('click', () => handleAction(element.dataset.action, element));
+        if (element.dataset.action === 'scrub-replay') {
+            element.addEventListener('input', () => {
+                stopReplay();
+                goToFrame(Number.parseInt(element.value, 10));
+            });
+        }
+    });
+}
+
+async function handleAction(actionName, element) {
+    if (actionName === 'open-web') {
+        window.location.href = '/web/';
+        return;
+    }
+    if (actionName === 'load-sample') {
+        stopLiveAutoplay();
+        setReplayTrace(SAMPLE_TRACE);
+        setState({
+            mode: 'sample',
+            statusMessage: 'Sample trace loaded',
+            council: narrateCouncil(SAMPLE_TRACE[0].observation, SAMPLE_TRACE[0].reward),
+        });
+        showToast('Sample trace loaded', 'success');
+        return;
+    }
+    if (actionName === 'use-live-trace') {
+        if (!AppState.liveTrace.length) return;
+        setReplayTrace(AppState.liveTrace);
+        setState({ mode: 'replay', statusMessage: 'Live trace replay' });
+        return;
+    }
+    if (actionName === 'toggle-replay') {
+        toggleReplayPlayback();
+        return;
+    }
+    if (actionName === 'scrub-replay') {
+        stopReplay();
+        goToFrame(Number.parseInt(element.value, 10));
+        return;
+    }
+    if (actionName === 'reset-live') {
+        await resetLive();
+        return;
+    }
+    if (actionName === 'submit-action') {
+        await submitAction(buildAction(AppState));
+        return;
+    }
+    if (actionName === 'apply-recommendation') {
+        await submitAction(AppState.council?.decision || { kind: 'no_op' });
+        return;
+    }
+    if (actionName === 'toggle-live-autoplay') {
+        toggleLiveAutoplay();
+    }
+}
+
+async function resetLive() {
+    stopReplay();
+    stopLiveAutoplay();
+    setState({ connection: 'resetting', statusMessage: 'Resetting live episode' });
+    try {
+        const data = await resetEnvironment({
+            taskName: AppState.taskName,
+            seed: AppState.seed,
+            maxTicks: AppState.maxTicks,
+        });
+        const frame = {
+            label: `Live reset: ${AppState.taskName}`,
+            action: null,
+            observation: data.observation,
+            reward: data.reward ?? 0,
+            done: Boolean(data.done),
+        };
+        setState({
+            mode: 'live',
+            connection: 'connected',
+            observation: data.observation,
+            reward: data.reward ?? 0,
+            done: Boolean(data.done),
+            totalReward: 0,
+            liveTrace: [frame],
+            replayTrace: [frame],
+            replayIndex: 0,
+            statusMessage: 'Live episode ready',
+        });
+        showToast('Live episode reset', 'success');
+    } catch (error) {
+        setState({ connection: 'error', statusMessage: 'Reset failed' });
+        showToast(`Reset failed: ${error.message}`, 'error');
+    }
+}
+
+async function submitAction(payload) {
+    if (AppState.mode !== 'live') {
+        showToast('Reset a live episode before submitting actions.', 'error');
+        return;
+    }
+    if (AppState.done) {
+        showToast('Episode is terminal. Reset to continue.', 'error');
+        return;
+    }
+    setState({ connection: 'stepping', statusMessage: `Submitting ${payload.kind}` });
+    try {
+        const data = await stepEnvironment(payload);
+        const reward = Number(data.reward ?? 0);
+        const frame = {
+            label: `Submitted ${formatAction(payload)}`,
+            action: payload,
+            observation: data.observation,
+            reward,
+            done: Boolean(data.done),
+        };
+        addTraceFrame(frame);
+        setState({
+            mode: 'live',
+            connection: 'connected',
+            observation: data.observation,
+            reward,
+            done: Boolean(data.done),
+            totalReward: AppState.totalReward + reward,
+            statusMessage: data.done ? 'Episode complete' : 'Action accepted',
+        });
+        if (data.done) {
+            stopLiveAutoplay();
+            showToast('Episode complete', 'success');
+        }
+    } catch (error) {
+        stopLiveAutoplay();
+        setState({ connection: 'error', statusMessage: 'Step failed' });
+        showToast(`Step failed: ${error.message}`, 'error');
+    }
+}
+
+function toggleLiveAutoplay() {
+    if (AppState.autoplayLive) {
+        stopLiveAutoplay();
+        return;
+    }
+    if (AppState.mode !== 'live' || AppState.done) return;
+    setState({ autoplayLive: true });
+    liveAutoplayTimer = window.setInterval(async () => {
+        if (AppState.done || AppState.mode !== 'live') {
+            stopLiveAutoplay();
+            return;
+        }
+        await submitAction(AppState.council?.decision || { kind: 'no_op' });
+    }, AppState.replaySpeedMs);
+}
+
+function stopLiveAutoplay() {
+    if (liveAutoplayTimer) {
+        window.clearInterval(liveAutoplayTimer);
+        liveAutoplayTimer = null;
+    }
+    if (AppState.autoplayLive) setState({ autoplayLive: false });
+}
+
+function option(value, label, selected) {
+    return `<option value="${value}" ${value === selected ? 'selected' : ''}>${label}</option>`;
+}
+
+function pressure(region) {
+    return region.reported_cases_d_ago / 1000 + region.hospital_load * 1.55 + (1 - region.compliance_proxy) * 0.75;
+}
+
+function pct(value) {
+    return `${Math.round((value || 0) * 100)}%`;
+}
+
+function formatReward(value) {
+    return typeof value === 'number' ? value.toFixed(2) : '-';
+}
+
+function clamp(value, min, max) {
+    return Math.max(min, Math.min(max, value));
+}
+
+init();

frontend/js/council-narration.js

@@ -0,0 +1,253 @@
+import { formatAction, resourceValue } from './actions.js';
+
+const BRAINS = [
+    {
+        id: 'epidemiology',
+        name: 'Epidemiology',
+        tone: 'Transmission risk and hospital pressure',
+    },
+    {
+        id: 'logistics',
+        name: 'Logistics',
+        tone: 'Resource fit and operational scarcity',
+    },
+    {
+        id: 'governance',
+        name: 'Governance',
+        tone: 'Compliance, legality, and escalation risk',
+    },
+];
+
+// This module is deliberately a frontend visualization layer. It does not call
+// the real Cortex runtime or any LLM subagent; it narrates deterministic,
+// observation-derived deliberation so the Space feels alive without coupling UI
+// code to the simulator, reward, schemas, or training stack.
+export function narrateCouncil(obs, lastReward = 0) {
+    if (!obs) {
+        return {
+            phase: 'Divergence',
+            round: 1,
+            budget: 0,
+            recommendations: [],
+            preservedDissent: [],
+            decision: { kind: 'no_op' },
+            rationale: 'No observation loaded yet.',
+            challenge: 'Start a live episode or load the sample trace.',
+        };
+    }
+
+    const regions = obs.regions || [];
+    const pressure = regions.map((region) => ({
+        region: region.region,
+        score: region.reported_cases_d_ago / 1000 + region.hospital_load * 1.55 + (1 - region.compliance_proxy) * 0.75,
+        cases: region.reported_cases_d_ago,
+        load: region.hospital_load,
+        compliance: region.compliance_proxy,
+    })).sort((a, b) => b.score - a.score);
+
+    const hot = pressure[0] || { region: 'R1', score: 0, cases: 0, load: 0, compliance: 1 };
+    const resources = obs.resources || {};
+    const strictBlocked = (obs.legal_constraints || []).some(
+        (constraint) => constraint.blocked_action === 'restrict_movement.strict',
+    );
+    const budget = obs.cognition_budget_remaining || 0;
+    const urgency = clamp((hot.score + (obs.ticks_remaining <= 4 ? 0.35 : 0)) / 2.6, 0, 1);
+    const agreement = clamp(1 - Math.abs((resourceValue(resources, 'hospital_beds') / 500) - urgency), 0.1, 0.98);
+
+    const epiAction = chooseEpidemiologyAction(hot, strictBlocked, obs);
+    const logAction = chooseLogisticsAction(hot, resources);
+    const govAction = chooseGovernanceAction(hot, strictBlocked, obs);
+    const raw = [
+        brainReport(BRAINS[0], epiAction, hot, urgency, lastReward, obs),
+        brainReport(BRAINS[1], logAction, hot, urgency, lastReward, obs),
+        brainReport(BRAINS[2], govAction, hot, urgency, lastReward, obs),
+    ];
+
+    const decision = chooseDecision(raw, obs, strictBlocked);
+    const preservedDissent = raw
+        .filter((report) => report.action.kind !== decision.kind || report.action.region !== decision.region)
+        .slice(0, 2)
+        .map((report) => `${report.name}: ${report.challenge}`);
+
+    return {
+        phase: phaseFor(obs, agreement),
+        round: urgency > 0.72 && agreement < 0.72 ? 2 : 1,
+        budget,
+        agreement,
+        recommendations: raw,
+        preservedDissent,
+        decision,
+        rationale: decisionRationale(decision, hot, strictBlocked, obs),
+        challenge: raw.reduce((best, report) => report.challengeScore > best.challengeScore ? report : best, raw[0]).challenge,
+    };
+}
+
+function chooseEpidemiologyAction(hot, strictBlocked, obs) {
+    if (hot.load > 0.72 || hot.cases > 120) {
+        return {
+            kind: 'restrict_movement',
+            region: hot.region,
+            severity: strictBlocked ? 'moderate' : 'strict',
+        };
+    }
+    if ((obs.ticks_remaining || 0) > 6 && hot.cases < 35) {
+        return {
+            kind: 'request_data',
+            region: hot.region,
+            data_type: 'case_survey',
+        };
+    }
+    return {
+        kind: 'deploy_resource',
+        region: hot.region,
+        resource_type: 'test_kits',
+        quantity: 80,
+    };
+}
+
+function chooseLogisticsAction(hot, resources) {
+    if (resourceValue(resources, 'hospital_beds') < 120 && resourceValue(resources, 'mobile_units') >= 2) {
+        return {
+            kind: 'deploy_resource',
+            region: hot.region,
+            resource_type: 'mobile_units',
+            quantity: Math.min(3, resourceValue(resources, 'mobile_units')),
+        };
+    }
+    if (resourceValue(resources, 'test_kits') > 120) {
+        return {
+            kind: 'deploy_resource',
+            region: hot.region,
+            resource_type: 'test_kits',
+            quantity: Math.min(120, resourceValue(resources, 'test_kits')),
+        };
+    }
+    if (resourceValue(resources, 'vaccine_doses') > 80) {
+        return {
+            kind: 'deploy_resource',
+            region: hot.region,
+            resource_type: 'vaccine_doses',
+            quantity: Math.min(160, resourceValue(resources, 'vaccine_doses')),
+        };
+    }
+    return { kind: 'no_op' };
+}
+
+function chooseGovernanceAction(hot, strictBlocked, obs) {
+    if (strictBlocked && hot.load > 0.62) {
+        return {
+            kind: 'escalate',
+            to_authority: 'national',
+        };
+    }
+    if (hot.compliance < 0.68) {
+        return {
+            kind: 'restrict_movement',
+            region: hot.region,
+            severity: 'light',
+        };
+    }
+    if ((obs.legal_constraints || []).length && (obs.ticks_remaining || 0) <= 5) {
+        return {
+            kind: 'escalate',
+            to_authority: 'regional',
+        };
+    }
+    return {
+        kind: 'request_data',
+        region: hot.region,
+        data_type: 'compliance_check',
+    };
+}
+
+function brainReport(brain, action, hot, urgency, lastReward, obs) {
+    const confidenceBase = brain.id === 'logistics'
+        ? 0.58 + urgency * 0.25
+        : brain.id === 'governance'
+            ? 0.54 + (1 - hot.compliance) * 0.34
+            : 0.6 + hot.load * 0.28;
+    const confidence = clamp(confidenceBase + Math.max(lastReward, -0.15) * 0.08, 0.18, 0.96);
+    const minority = action.kind === 'restrict_movement'
+        ? { kind: 'request_data', region: hot.region, data_type: 'hospital_audit' }
+        : { kind: 'restrict_movement', region: hot.region, severity: 'light' };
+    return {
+        id: brain.id,
+        name: brain.name,
+        tone: brain.tone,
+        action,
+        confidence,
+        summary: summaryFor(brain.id, action, hot, obs),
+        challenge: challengeFor(brain.id, action, hot, obs),
+        challengeScore: 1 - confidence + (action.kind === 'no_op' ? 0.25 : 0),
+        minority,
+    };
+}
+
+function chooseDecision(reports, obs, strictBlocked) {
+    const counts = new Map();
+    for (const report of reports) {
+        const key = actionKey(report.action);
+        counts.set(key, (counts.get(key) || 0) + report.confidence);
+    }
+    let winner = reports[0].action;
+    let winnerScore = -1;
+    for (const report of reports) {
+        const score = counts.get(actionKey(report.action)) || 0;
+        if (score > winnerScore) {
+            winner = report.action;
+            winnerScore = score;
+        }
+    }
+    if (strictBlocked && winner.kind === 'restrict_movement' && winner.severity === 'strict') {
+        return { kind: 'escalate', to_authority: 'national' };
+    }
+    if (obs.done) return { kind: 'no_op' };
+    return winner;
+}
+
+function summaryFor(brainId, action, hot, obs) {
+    if (brainId === 'epidemiology') {
+        return `${hot.region} is carrying the highest observed pressure; ${formatAction(action)} is the fastest epidemiological lever.`;
+    }
+    if (brainId === 'logistics') {
+        return `Available stock should be spent where hospital load is most exposed; ${formatAction(action)} has the cleanest operational path.`;
+    }
+    const locked = (obs.legal_constraints || []).length ? 'legal constraints remain active' : 'legal constraints are clear';
+    return `${locked}; ${formatAction(action)} balances actionability with compliance risk.`;
+}
+
+function challengeFor(brainId, action, hot, obs) {
+    if (brainId === 'epidemiology') {
+        return `Telemetry is delayed, so ${hot.region} may not be the only active chain.`;
+    }
+    if (brainId === 'logistics') {
+        return action.kind === 'deploy_resource'
+            ? `Stock spent now cannot cover a late spike if the episode stretches ${obs.ticks_remaining} more ticks.`
+            : 'Inaction may waste scarce response windows.';
+    }
+    return action.kind === 'restrict_movement'
+        ? 'Movement limits can backfire if compliance is already weak.'
+        : 'Escalation consumes attention and may not reduce spread by itself.';
+}
+
+function decisionRationale(action, hot, strictBlocked, obs) {
+    if (obs.done) return 'Episode is terminal; replay the trace or reset for another run.';
+    const legal = strictBlocked ? ' Strict movement is legally blocked until escalation.' : '';
+    return `Converged on ${formatAction(action)} because ${hot.region} has the highest combined case, load, and compliance pressure.${legal}`;
+}
+
+function phaseFor(obs, agreement) {
+    if (!obs.recent_action_log?.length) return 'Divergence';
+    if (agreement < 0.55) return 'Challenge';
+    if ((obs.ticks_remaining || 0) <= 3) return 'Convergence';
+    return 'Narrowing';
+}
+
+function actionKey(action) {
+    if (!action) return 'none';
+    return [action.kind, action.region || '', action.resource_type || '', action.severity || '', action.to_authority || ''].join(':');
+}
+
+function clamp(value, min, max) {
+    return Math.max(min, Math.min(max, value));
+}

frontend/js/replay.js

@@ -0,0 +1,54 @@
+import { AppState, currentFrame, setState } from './state.js';
+
+let replayTimer = null;
+
+export function setReplayTrace(trace) {
+    const replayTrace = Array.isArray(trace) ? trace : [];
+    setState({
+        replayTrace,
+        replayIndex: 0,
+        replayPlaying: false,
+        observation: replayTrace[0]?.observation || null,
+        reward: replayTrace[0]?.reward ?? null,
+        done: Boolean(replayTrace[0]?.done),
+    });
+}
+
+export function goToFrame(index) {
+    const bounded = Math.max(0, Math.min(index, AppState.replayTrace.length - 1));
+    const frame = AppState.replayTrace[bounded];
+    if (!frame) return;
+    setState({
+        replayIndex: bounded,
+        observation: frame.observation,
+        reward: frame.reward ?? null,
+        done: Boolean(frame.done),
+        statusMessage: frame.label || `Replay frame ${bounded + 1}`,
+    });
+}
+
+export function toggleReplayPlayback(renderTick) {
+    if (AppState.replayPlaying) {
+        stopReplay();
+        return;
+    }
+    if (AppState.replayTrace.length < 2) return;
+    setState({ replayPlaying: true });
+    replayTimer = window.setInterval(() => {
+        const next = AppState.replayIndex + 1;
+        if (next >= AppState.replayTrace.length) {
+            stopReplay();
+            return;
+        }
+        goToFrame(next);
+        if (typeof renderTick === 'function') renderTick(currentFrame());
+    }, AppState.replaySpeedMs);
+}
+
+export function stopReplay() {
+    if (replayTimer) {
+        window.clearInterval(replayTimer);
+        replayTimer = null;
+    }
+    setState({ replayPlaying: false });
+}

frontend/js/samples.js

@@ -0,0 +1,99 @@
+export const SAMPLE_TRACE = [
+    {
+        label: 'Reset hard outbreak',
+        reward: 0,
+        done: false,
+        action: null,
+        observation: {
+            regions: [
+                { region: 'R1', reported_cases_d_ago: 52, hospital_load: 0.41, compliance_proxy: 0.75 },
+                { region: 'R2', reported_cases_d_ago: 49, hospital_load: 0.39, compliance_proxy: 0.74 },
+                { region: 'R3', reported_cases_d_ago: 56, hospital_load: 0.44, compliance_proxy: 0.72 },
+                { region: 'R4', reported_cases_d_ago: 45, hospital_load: 0.36, compliance_proxy: 0.77 },
+                { region: 'R5', reported_cases_d_ago: 47, hospital_load: 0.34, compliance_proxy: 0.78 },
+            ],
+            resources: { test_kits: 200, hospital_beds_free: 150, mobile_units: 5, vaccine_doses: 400 },
+            active_restrictions: [],
+            legal_constraints: [{ rule_id: 'L1', blocked_action: 'restrict_movement.strict', unlock_via: 'escalate' }],
+            tick: 0,
+            ticks_remaining: 12,
+            cognition_budget_remaining: 6000,
+            recent_action_log: [],
+        },
+    },
+    {
+        label: 'Escalation unlocks strict controls',
+        reward: 0.11,
+        done: false,
+        action: { kind: 'escalate', to_authority: 'national' },
+        observation: {
+            regions: [
+                { region: 'R1', reported_cases_d_ago: 55, hospital_load: 0.47, compliance_proxy: 0.74 },
+                { region: 'R2', reported_cases_d_ago: 52, hospital_load: 0.43, compliance_proxy: 0.73 },
+                { region: 'R3', reported_cases_d_ago: 62, hospital_load: 0.52, compliance_proxy: 0.70 },
+                { region: 'R4', reported_cases_d_ago: 49, hospital_load: 0.40, compliance_proxy: 0.75 },
+                { region: 'R5', reported_cases_d_ago: 48, hospital_load: 0.37, compliance_proxy: 0.77 },
+            ],
+            resources: { test_kits: 200, hospital_beds_free: 150, mobile_units: 5, vaccine_doses: 400 },
+            active_restrictions: [],
+            legal_constraints: [],
+            tick: 1,
+            ticks_remaining: 11,
+            cognition_budget_remaining: 6000,
+            recent_action_log: [
+                { tick: 0, action: { kind: 'escalate', to_authority: 'national' }, accepted: true },
+            ],
+        },
+    },
+    {
+        label: 'Strict restriction contains R3 pressure',
+        reward: 0.19,
+        done: false,
+        action: { kind: 'restrict_movement', region: 'R3', severity: 'strict' },
+        observation: {
+            regions: [
+                { region: 'R1', reported_cases_d_ago: 58, hospital_load: 0.48, compliance_proxy: 0.73 },
+                { region: 'R2', reported_cases_d_ago: 55, hospital_load: 0.44, compliance_proxy: 0.72 },
+                { region: 'R3', reported_cases_d_ago: 75, hospital_load: 0.61, compliance_proxy: 0.69 },
+                { region: 'R4', reported_cases_d_ago: 51, hospital_load: 0.42, compliance_proxy: 0.75 },
+                { region: 'R5', reported_cases_d_ago: 50, hospital_load: 0.39, compliance_proxy: 0.76 },
+            ],
+            resources: { test_kits: 200, hospital_beds_free: 150, mobile_units: 5, vaccine_doses: 400 },
+            active_restrictions: [{ region: 'R3', severity: 'strict', ticks_remaining: 2 }],
+            legal_constraints: [],
+            tick: 2,
+            ticks_remaining: 10,
+            cognition_budget_remaining: 6000,
+            recent_action_log: [
+                { tick: 0, action: { kind: 'escalate', to_authority: 'national' }, accepted: true },
+                { tick: 1, action: { kind: 'restrict_movement', region: 'R3', severity: 'strict' }, accepted: true },
+            ],
+        },
+    },
+    {
+        label: 'Mobile units cover hospital load',
+        reward: 0.24,
+        done: false,
+        action: { kind: 'deploy_resource', region: 'R3', resource_type: 'mobile_units', quantity: 3 },
+        observation: {
+            regions: [
+                { region: 'R1', reported_cases_d_ago: 59, hospital_load: 0.48, compliance_proxy: 0.74 },
+                { region: 'R2', reported_cases_d_ago: 57, hospital_load: 0.45, compliance_proxy: 0.72 },
+                { region: 'R3', reported_cases_d_ago: 82, hospital_load: 0.56, compliance_proxy: 0.71 },
+                { region: 'R4', reported_cases_d_ago: 54, hospital_load: 0.44, compliance_proxy: 0.75 },
+                { region: 'R5', reported_cases_d_ago: 52, hospital_load: 0.40, compliance_proxy: 0.76 },
+            ],
+            resources: { test_kits: 200, hospital_beds_free: 150, mobile_units: 2, vaccine_doses: 400 },
+            active_restrictions: [{ region: 'R3', severity: 'strict', ticks_remaining: 1 }],
+            legal_constraints: [],
+            tick: 3,
+            ticks_remaining: 9,
+            cognition_budget_remaining: 6000,
+            recent_action_log: [
+                { tick: 0, action: { kind: 'escalate', to_authority: 'national' }, accepted: true },
+                { tick: 1, action: { kind: 'restrict_movement', region: 'R3', severity: 'strict' }, accepted: true },
+                { tick: 2, action: { kind: 'deploy_resource', region: 'R3', resource_type: 'mobile_units', quantity: 3 }, accepted: true },
+            ],
+        },
+    },
+];

frontend/js/state.js

@@ -0,0 +1,65 @@
+const subscribers = new Set();
+
+export const AppState = {
+    connection: 'idle',
+    mode: 'sample',
+    taskName: 'outbreak_easy',
+    seed: 0,
+    maxTicks: 12,
+    observation: null,
+    reward: null,
+    done: false,
+    totalReward: 0,
+    liveTrace: [],
+    replayTrace: [],
+    replayIndex: 0,
+    replayPlaying: false,
+    replaySpeedMs: 1200,
+    autoplayLive: false,
+    selectedActionKind: 'deploy_resource',
+    selectedRegion: 'R1',
+    selectedResource: 'test_kits',
+    selectedToResource: 'hospital_beds',
+    quantity: 50,
+    dataType: 'case_survey',
+    severity: 'moderate',
+    authority: 'regional',
+    council: null,
+    statusMessage: 'Sample trace loaded',
+};
+
+export function subscribe(callback) {
+    subscribers.add(callback);
+    return () => subscribers.delete(callback);
+}
+
+export function setState(patch) {
+    Object.assign(AppState, patch);
+    subscribers.forEach((callback) => callback(AppState));
+}
+
+export function addTraceFrame(frame) {
+    const liveTrace = [...AppState.liveTrace, frame];
+    setState({
+        liveTrace,
+        replayTrace: liveTrace,
+        replayIndex: liveTrace.length - 1,
+    });
+}
+
+export function currentFrame() {
+    return AppState.replayTrace[AppState.replayIndex] || null;
+}
+
+export function showToast(message, type = 'info') {
+    const root = document.getElementById('toast-root');
+    if (!root) return;
+    const toast = document.createElement('div');
+    toast.className = `toast toast-${type}`;
+    toast.textContent = message;
+    root.appendChild(toast);
+    window.setTimeout(() => {
+        toast.classList.add('toast-out');
+        window.setTimeout(() => toast.remove(), 220);
+    }, 3200);
+}

inference.py

@@ -37,22 +37,21 @@ Score formula (Session 7a §7 + 7b §9.4 revision): see compute_score.
 
 from __future__ import annotations
 
+import argparse
 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 CrisisWorldCortex.baselines.flat_agent import B1FlatAgent, B1StepEvent
-from CrisisWorldCortex.cortex.llm_client import LLMClient
+from typing import Any, Dict, List, Literal, Optional
+
+from baselines.flat_agent import B1FlatAgent, B1StepEvent
+from cortex.llm_client import LLMClient
 from CrisisWorldCortex.models import OuterActionPayload
 from CrisisWorldCortex.server.graders import terminal_bonus
 from CrisisWorldCortex.server.simulator import WorldState
 
+AgentKind = Literal["b1", "b2", "b3"]
+_AGENT_CHOICES: tuple = ("b1", "b2", "b3")
+
 # ============================================================================
 # Constants
 # ============================================================================
@@ -67,8 +66,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
@@ -268,7 +267,7 @@ def _make_env_from_spaces(base_url: str) -> Any:
 
 
 # ============================================================================
-# Episode loop — delegates to B1FlatAgent.run_episode(step_callback=...)
+# Episode loop — delegates to the selected agent's run_episode(step_callback=...)
 # ============================================================================
 
 
@@ -310,6 +309,43 @@ class _SyncEnvAdapter:
         return obs
 
 
+def _make_agent(kind: str, env: Any, llm: Any) -> Any:
+    """Construct the B1/B2/B3 agent for ``kind``.
+
+    All three agents share the ``(env, llm)`` constructor signature and
+    expose ``run_episode(task, seed, max_ticks, *, step_callback)`` per
+    Phase A Decision 54. Lazy imports for B2/B3 keep the cold-start cost
+    of the default B1 path unchanged.
+    """
+    if kind == "b1":
+        return B1FlatAgent(env=env, llm=llm)
+    if kind == "b2":
+        from baselines.flat_agent_matched_compute import B2MatchedComputeAgent
+
+        return B2MatchedComputeAgent(env=env, llm=llm)
+    if kind == "b3":
+        from baselines.cortex_fixed_router import B3CortexFixedRouter
+
+        return B3CortexFixedRouter(env=env, llm=llm)
+    raise ValueError(f"unknown agent kind: {kind!r}; expected one of {_AGENT_CHOICES}")
+
+
+def _build_argparser() -> argparse.ArgumentParser:
+    """Argparse for inference.py CLI flags. Default --agent=b1 keeps the
+    pre-Session-13 invocation working for the existing eval suite."""
+    parser = argparse.ArgumentParser(
+        prog="inference",
+        description="CrisisWorldCortex inference harness (B1/B2/B3 dispatch).",
+    )
+    parser.add_argument(
+        "--agent",
+        choices=_AGENT_CHOICES,
+        default="b1",
+        help="Agent to run: b1 (flat), b2 (matched-compute), b3 (cortex+deterministic-router).",
+    )
+    return parser
+
+
 def _run_episode(
     env: Any,
     llm: LLMClient,
@@ -317,8 +353,9 @@ def _run_episode(
     seed: int,
     model_name: str,
     max_ticks: int,
+    agent_kind: str = "b1",
 ) -> dict:
-    """Stream one episode end-to-end via ``B1FlatAgent.run_episode``.
+    """Stream one episode end-to-end via ``<Agent>.run_episode``.
 
     The agent owns the per-tick LLM-call + parse + env.step loop; this
     harness owns the [START] / [STEP] / [END] stdout protocol via a
@@ -351,7 +388,7 @@ def _run_episode(
         env,
         reset_kwargs={"task_name": task_name, "seed": seed, "max_ticks": max_ticks},
     )
-    agent = B1FlatAgent(env=adapter, llm=llm)
+    agent = _make_agent(agent_kind, adapter, llm)
 
     try:
         traj = agent.run_episode(
@@ -407,6 +444,7 @@ def _run_episode(
 
 def main() -> None:
     """Entry point for ``uv run python inference.py`` and the validator."""
+    args = _build_argparser().parse_args()
     api_base_url = os.getenv("API_BASE_URL", DEFAULT_API_BASE_URL)
     model_name = os.getenv("MODEL_NAME", DEFAULT_MODEL)
     hf_token = os.getenv("HF_TOKEN")
@@ -451,6 +489,7 @@ def main() -> None:
                 seed=cfg["seed"],
                 model_name=model_name,
                 max_ticks=cfg["max_ticks"],
+                agent_kind=args.agent,
             )
             results.append(result)
         finally:

notebooks/train_b1_grpo.ipynb

@@ -2,6 +2,7 @@
  "cells": [
   {
    "cell_type": "markdown",
+   "id": "7fb27b941602401d91542211134fc71a",
    "metadata": {},
    "source": [
     "# B1 GRPO training on Qwen3-1.7B (Workstream B Phase 3)\n",
@@ -19,6 +20,7 @@
   },
   {
    "cell_type": "markdown",
+   "id": "acae54e37e7d407bbb7b55eff062a284",
    "metadata": {},
    "source": [
     "## 1. Install dependencies\n",
@@ -29,6 +31,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
+   "id": "9a63283cbaf04dbcab1f6479b197f3a8",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -41,6 +44,7 @@
   },
   {
    "cell_type": "markdown",
+   "id": "8dd0d8092fe74a7c96281538738b07e2",
    "metadata": {},
    "source": [
     "## 2. Authenticate with Hugging Face\n",
@@ -51,6 +55,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
+   "id": "72eea5119410473aa328ad9291626812",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -58,10 +63,12 @@
     "\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",
@@ -71,6 +78,7 @@
   },
   {
    "cell_type": "markdown",
+   "id": "8edb47106e1a46a883d545849b8ab81b",
    "metadata": {},
    "source": [
     "## 3. Clone CrisisWorldCortex and install\n",
@@ -81,6 +89,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
+   "id": "10185d26023b46108eb7d9f57d49d2b3",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -94,26 +103,30 @@
   {
    "cell_type": "code",
    "execution_count": null,
+   "id": "8763a12b2bbd4a93a75aff182afb95dc",
    "metadata": {},
    "outputs": [],
    "source": [
     "# Sanity: imports resolve, env client constructs.\n",
     "import sys\n",
+    "\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",
+    "from CrisisWorldCortex import CrisisworldcortexAction, CrisisworldcortexObservation\n",
+    "from CrisisWorldCortex.client import CrisisworldcortexEnv\n",
+    "\n",
     "print(\"CrisisWorld imports OK\")"
    ]
   },
   {
    "cell_type": "markdown",
+   "id": "7623eae2785240b9bd12b16a66d81610",
    "metadata": {},
    "source": [
     "## 4. Load Qwen3-1.7B with LoRA via Unsloth\n",
@@ -124,11 +137,12 @@
   {
    "cell_type": "code",
    "execution_count": null,
+   "id": "7cdc8c89c7104fffa095e18ddfef8986",
    "metadata": {},
    "outputs": [],
    "source": [
-    "from unsloth import FastLanguageModel\n",
     "import torch\n",
+    "from unsloth import FastLanguageModel\n",
     "\n",
     "MAX_SEQ_LEN = 4096\n",
     "MODEL_NAME = \"unsloth/Qwen3-1.7B\"\n",
@@ -145,8 +159,7 @@
     "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",
+    "    target_modules=[\"q_proj\", \"k_proj\", \"v_proj\", \"o_proj\", \"gate_proj\", \"up_proj\", \"down_proj\"],\n",
     "    lora_alpha=64,\n",
     "    use_gradient_checkpointing=\"unsloth\",\n",
     "    random_state=42,\n",
@@ -156,6 +169,7 @@
   },
   {
    "cell_type": "markdown",
+   "id": "b118ea5561624da68c537baed56e602f",
    "metadata": {},
    "source": [
     "## 5. Connect to the deployed CrisisWorld env\n",
@@ -166,6 +180,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
+   "id": "938c804e27f84196a10c8828c723f798",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -173,9 +188,11 @@
     "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]}\")"
@@ -183,6 +200,7 @@
   },
   {
    "cell_type": "markdown",
+   "id": "504fb2a444614c0babb325280ed9130a",
    "metadata": {},
    "source": [
     "## 6. Build the prompt dataset and reward function\n",
@@ -197,17 +215,21 @@
   {
    "cell_type": "code",
    "execution_count": null,
+   "id": "59bbdb311c014d738909a11f9e486628",
    "metadata": {},
    "outputs": [],
    "source": [
-    "from datasets import Dataset\n",
     "import random\n",
     "\n",
+    "from datasets import Dataset\n",
+    "\n",
     "SYSTEM_PROMPT = build_system_prompt()\n",
     "\n",
+    "\n",
     "def build_user_prompt(obs: CrisisworldcortexObservation) -> str:\n",
     "    return serialize_observation(obs)\n",
     "\n",
+    "\n",
     "def make_chat_prompt(obs: CrisisworldcortexObservation) -> str:\n",
     "    return tokenizer.apply_chat_template(\n",
     "        [\n",
@@ -218,6 +240,7 @@
     "        add_generation_prompt=True,\n",
     "    )\n",
     "\n",
+    "\n",
     "rng = random.Random(0)\n",
     "_seed_pool = []\n",
     "for task in TASKS:\n",
@@ -233,17 +256,20 @@
     "    _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",
+    "train_dataset = Dataset.from_dict(\n",
+    "    {\n",
+    "        \"prompt\": _prompts,\n",
+    "        \"task\": [m[\"task\"] for m in _meta],\n",
+    "        \"seed\": [m[\"seed\"] for m in _meta],\n",
+    "    }\n",
+    ")\n",
     "print(f\"Dataset built: {len(train_dataset)} examples\")"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
+   "id": "b43b363d81ae4b689946ece5c682cd59",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -278,6 +304,7 @@
   },
   {
    "cell_type": "markdown",
+   "id": "8a65eabff63a45729fe45fb5ade58bdc",
    "metadata": {},
    "source": [
     "## 7. GRPO training\n",
@@ -288,6 +315,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
+   "id": "c3933fab20d04ec698c2621248eb3be0",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -331,6 +359,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
+   "id": "4dd4641cc4064e0191573fe9c69df29b",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -339,6 +368,7 @@
   },
   {
    "cell_type": "markdown",
+   "id": "8309879909854d7188b41380fd92a7c3",
    "metadata": {},
    "source": [
     "## 8. Save the trained LoRA adapter to HF Hub\n",
@@ -349,6 +379,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
+   "id": "3ed186c9a28b402fb0bc4494df01f08d",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -372,6 +403,7 @@
   },
   {
    "cell_type": "markdown",
+   "id": "cb1e1581032b452c9409d6c6813c49d1",
    "metadata": {},
    "source": [
     "## 9. Eval: trained adapter vs base model on 3 tasks\n",
@@ -382,6 +414,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
+   "id": "379cbbc1e968416e875cc15c1202d7eb",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -394,9 +427,13 @@
     "    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",
+    "            **inputs,\n",
+    "            max_new_tokens=max_new_tokens,\n",
+    "            do_sample=False,\n",
+    "            temperature=0.0,\n",
     "        )\n",
-    "    return tokenizer_inst.decode(out[0][inputs[\"input_ids\"].shape[1]:], skip_special_tokens=True)\n",
+    "    return tokenizer_inst.decode(out[0][inputs[\"input_ids\"].shape[1] :], skip_special_tokens=True)\n",
+    "\n",
     "\n",
     "def run_one_episode(model_inst, tokenizer_inst, task: str, seed: int) -> float:\n",
     "    env = make_env()\n",
@@ -413,6 +450,7 @@
     "            break\n",
     "    return cumulative\n",
     "\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}\")"
@@ -421,6 +459,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
+   "id": "277c27b1587741f2af2001be3712ef0d",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -438,6 +477,7 @@
   },
   {
    "cell_type": "markdown",
+   "id": "db7b79bc585a40fcaf58bf750017e135",
    "metadata": {},
    "source": [
     "## 10. Plot eval comparison\n",
@@ -448,6 +488,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
+   "id": "916684f9a58a4a2aa5f864670399430d",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -462,8 +503,8 @@
     "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.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",
@@ -476,6 +517,11 @@
   }
  ],
  "metadata": {
+  "accelerator": "GPU",
+  "colab": {
+   "gpuType": "T4",
+   "provenance": []
+  },
   "kernelspec": {
    "display_name": "Python 3",
    "language": "python",
@@ -484,11 +530,6 @@
   "language_info": {
    "name": "python",
    "version": "3.10"
-  },
-  "accelerator": "GPU",
-  "colab": {
-   "gpuType": "T4",
-   "provenance": []
   }
  },
  "nbformat": 4,

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
+

pyproject.toml

@@ -25,7 +25,6 @@ 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/Dockerfile

@@ -28,7 +28,7 @@
 # The build script (openenv build) handles context detection and sets appropriate build args.
 
 ARG BASE_IMAGE=ghcr.io/meta-pytorch/openenv-base:latest
-FROM ${BASE_IMAGE} AS builder
+FROM ${BASE_IMAGE:-ghcr.io/meta-pytorch/openenv-base:latest} AS builder
 
 WORKDIR /app
 
@@ -72,8 +72,7 @@ RUN --mount=type=cache,target=/root/.cache/uv \
     fi
 
 # Final runtime stage
-ARG BASE_IMAGE=ghcr.io/meta-pytorch/openenv-base:latest
-FROM ${BASE_IMAGE}
+FROM ${BASE_IMAGE:-ghcr.io/meta-pytorch/openenv-base:latest}
 
 WORKDIR /app
 

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,13 +29,17 @@ 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
 except Exception as e:  # pragma: no cover
     raise ImportError(
         "openenv is required for the web interface. Install dependencies with '\n    uv sync\n'"
     ) from e
 
+from pathlib import Path
+
+from fastapi.responses import FileResponse
+from starlette.staticfiles import StaticFiles
+
 # Wire types use canonical ``CrisisWorldCortex.models`` (Session 7d):
 # the container's wheel install resolves this to one ``sys.modules`` entry,
 # matching the deep server modules (graders/, simulator/) that already use
@@ -57,6 +61,18 @@ app = create_app(
     max_concurrent_envs=1,  # increase this number to allow more concurrent WebSocket sessions
 )
 
+FRONTEND_DIR = Path(__file__).resolve().parent.parent / "frontend"
+
+if FRONTEND_DIR.exists():
+    app.mount("/cortex/css", StaticFiles(directory=str(FRONTEND_DIR / "css")), name="cortex-css")
+    app.mount("/cortex/js", StaticFiles(directory=str(FRONTEND_DIR / "js")), name="cortex-js")
+
+    @app.get("/cortex", include_in_schema=False)
+    @app.get("/cortex/", include_in_schema=False)
+    async def serve_cortex_frontend() -> FileResponse:
+        """Serve the additive Cortex dashboard without replacing /web."""
+        return FileResponse(str(FRONTEND_DIR / "index.html"))
+
 
 def main() -> None:
     """

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/test_inference_agent_dispatch.py

@@ -0,0 +1,87 @@
+"""inference.py --agent CLI dispatch smoke tests.
+
+Per the user's Session 13 follow-up: argparse with ``--agent`` choices
+{b1, b2, b3} (default b1 for backward compat) + dispatch table that
+constructs the corresponding agent class. All three agents expose the
+same ``run_episode(task, seed, max_ticks, *, step_callback)`` surface
+per Phase A Decision 54, so the rest of the inference loop is unchanged.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+import inference
+from baselines.cortex_fixed_router import B3CortexFixedRouter
+from baselines.flat_agent import B1FlatAgent
+from baselines.flat_agent_matched_compute import B2MatchedComputeAgent
+from CrisisWorldCortex.models import (
+    CrisisworldcortexAction,
+    CrisisworldcortexObservation,
+)
+from tests._helpers.llm_stub import StubLLMClient
+
+
+class _FakeEnv:
+    """Quack-duck env used only to satisfy agent constructors.
+
+    ``run_episode`` is not called in dispatch tests; we only verify
+    the right class is instantiated.
+    """
+
+    def reset(self) -> CrisisworldcortexObservation:  # pragma: no cover
+        raise NotImplementedError
+
+    def step(
+        self, action: CrisisworldcortexAction
+    ) -> CrisisworldcortexObservation:  # pragma: no cover
+        raise NotImplementedError
+
+
+# ============================================================================
+# Dispatch table
+# ============================================================================
+
+
+def test_make_agent_b1_returns_b1_flat_agent() -> None:
+    agent = inference._make_agent("b1", _FakeEnv(), StubLLMClient(scripted_responses=[]))
+    assert isinstance(agent, B1FlatAgent)
+
+
+def test_make_agent_b2_returns_b2_matched_compute_agent() -> None:
+    agent = inference._make_agent("b2", _FakeEnv(), StubLLMClient(scripted_responses=[]))
+    assert isinstance(agent, B2MatchedComputeAgent)
+
+
+def test_make_agent_b3_returns_b3_cortex_fixed_router() -> None:
+    agent = inference._make_agent("b3", _FakeEnv(), StubLLMClient(scripted_responses=[]))
+    assert isinstance(agent, B3CortexFixedRouter)
+
+
+def test_make_agent_invalid_raises_value_error() -> None:
+    with pytest.raises(ValueError):
+        inference._make_agent("b99", _FakeEnv(), StubLLMClient(scripted_responses=[]))
+
+
+# ============================================================================
+# Argparse
+# ============================================================================
+
+
+def test_argparse_default_is_b1_for_backward_compat() -> None:
+    parser = inference._build_argparser()
+    args = parser.parse_args([])
+    assert args.agent == "b1"
+
+
+def test_argparse_accepts_b1_b2_b3() -> None:
+    parser = inference._build_argparser()
+    for name in ("b1", "b2", "b3"):
+        args = parser.parse_args(["--agent", name])
+        assert args.agent == name
+
+
+def test_argparse_rejects_unknown_agent() -> None:
+    parser = inference._build_argparser()
+    with pytest.raises(SystemExit):
+        parser.parse_args(["--agent", "b99"])

tests/test_training_multi_model_skeleton.py

@@ -0,0 +1,169 @@
+"""Static checks for training/scripts/train_cortex_multi_model.py.
+
+Phase 6 skeleton tests. No GPU / no HF Hub access — these tests verify
+the script's configuration surface, preflight logic, memory budget guard,
+and adapter signatures without loading Unsloth/torch or hitting the
+network.
+
+Live multi-model training (~2 hours a100-large, ~$5) is a manual Phase-7
+step gated on user approval, not pytest-driven.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+SCRIPT_PATH = Path(__file__).parent.parent / "training" / "scripts" / "train_cortex_multi_model.py"
+
+
+def _load_module():
+    """Load the script as a module without running main()."""
+    import os
+
+    os.environ.setdefault("HF_TOKEN", "test_token_static_only")
+    os.environ.setdefault("HUB_REPO_ID", "test/multi_model_static_load")
+    spec = importlib.util.spec_from_file_location(
+        "train_cortex_multi_model_under_test", SCRIPT_PATH
+    )
+    assert spec is not None and spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def test_script_exists_and_loads() -> None:
+    """File present and importable."""
+    assert SCRIPT_PATH.exists(), f"missing {SCRIPT_PATH}"
+    mod = _load_module()
+    for attr in (
+        "main",
+        "preflight_model_access",
+        "check_memory_budget",
+        "_UnslothLLMAdapter",
+        "_TrainableRoutingPolicy",
+    ):
+        assert hasattr(mod, attr), f"missing {attr}"
+
+
+def test_default_brain_models() -> None:
+    """Defaults: Qwen-7B for epi+governance (shared), Llama-8B for logistics."""
+    mod = _load_module()
+    assert mod.EPI_BRAIN_MODEL.startswith("unsloth/Qwen3-7B-Instruct")
+    assert mod.LOGISTICS_BRAIN_MODEL == "meta-llama/Llama-3.1-8B-Instruct"
+
+
+def test_governance_shares_with_epi_by_default() -> None:
+    """M-FR-27: governance brain shares weights with epi by default."""
+    mod = _load_module()
+    assert mod.GOVERNANCE_BRAIN_MODEL == mod.EPI_BRAIN_MODEL
+
+
+def test_default_router_is_qwen_1p5b() -> None:
+    """M-FR-28: small LLM router."""
+    mod = _load_module()
+    assert mod.ROUTER_MODEL.startswith("unsloth/Qwen3-1.5B")
+
+
+def test_router_base_falls_back_to_router_model() -> None:
+    """Phase-5e style fallback for SFT-warmstarted router checkpoints."""
+    mod = _load_module()
+    assert mod.ROUTER_BASE_MODEL == mod.ROUTER_MODEL
+
+
+def test_default_lora_rank_is_16_for_router() -> None:
+    """M-FR-28: router rank 16 (smaller than B1's 32 because 1.5B model)."""
+    mod = _load_module()
+    assert mod.LORA_RANK == 16
+
+
+def test_default_gpu_mem_util_is_0p5() -> None:
+    """Phase-A M-FR-10: tighter than B1's 0.6 to leave room for frozen brains."""
+    mod = _load_module()
+    assert abs(mod.GPU_MEM_UTIL - 0.5) < 1e-9
+
+
+def test_default_brain_call_timeout() -> None:
+    """Phase-A M-FR-9: 30s timeout per brain call."""
+    mod = _load_module()
+    assert mod.BRAIN_CALL_TIMEOUT_S == 30
+
+
+def test_check_memory_budget_aborts_on_low_free_gpu() -> None:
+    """Memory guard raises RuntimeError when < MIN_FREE_GPU_GB free."""
+    mod = _load_module()
+    fake_torch = MagicMock()
+    fake_torch.cuda.is_available.return_value = True
+    # Return (free_bytes, total_bytes) with only 10 GB free.
+    fake_torch.cuda.mem_get_info.return_value = (10 * 1024**3, 80 * 1024**3)
+    with patch.dict("sys.modules", {"torch": fake_torch}):
+        with pytest.raises(RuntimeError, match="Insufficient GPU memory"):
+            mod.check_memory_budget()
+
+
+def test_check_memory_budget_passes_when_ample_free() -> None:
+    """Memory guard does not raise when 60+ GB free."""
+    mod = _load_module()
+    fake_torch = MagicMock()
+    fake_torch.cuda.is_available.return_value = True
+    fake_torch.cuda.mem_get_info.return_value = (60 * 1024**3, 80 * 1024**3)
+    with patch.dict("sys.modules", {"torch": fake_torch}):
+        mod.check_memory_budget()  # should not raise
+
+
+def test_check_memory_budget_skipped_when_no_cuda() -> None:
+    """Memory guard skips gracefully when CUDA isn't available (DRY_RUN path)."""
+    mod = _load_module()
+    fake_torch = MagicMock()
+    fake_torch.cuda.is_available.return_value = False
+    with patch.dict("sys.modules", {"torch": fake_torch}):
+        mod.check_memory_budget()  # should not raise
+
+
+def test_required_env_vars_raise_systemexit_when_missing() -> None:
+    """HF_TOKEN and HUB_REPO_ID required."""
+    import os
+    import subprocess
+    import sys
+
+    env = {k: v for k, v in os.environ.items() if k not in ("HF_TOKEN", "HUB_REPO_ID")}
+    env["PYTHONPATH"] = str(SCRIPT_PATH.parent.parent.parent)
+    result = subprocess.run(
+        [sys.executable, str(SCRIPT_PATH)],
+        env=env,
+        capture_output=True,
+        text=True,
+        timeout=30,
+    )
+    assert result.returncode != 0
+    out = result.stdout + result.stderr
+    assert "HF_TOKEN" in out or "HUB_REPO_ID" in out
+
+
+def test_unsloth_adapter_signature() -> None:
+    """_UnslothLLMAdapter implements _LLMClientLike (chat + tokens_used_for)."""
+    mod = _load_module()
+    AdapterCls = mod._UnslothLLMAdapter
+    fake_model = MagicMock()
+    fake_tokenizer = MagicMock()
+    adapter = AdapterCls(fake_model, fake_tokenizer, brain_label="test")
+    assert callable(adapter.chat)
+    assert callable(adapter.tokens_used_for)
+    assert adapter.tokens_used_for("never_called") == 0
+
+
+def test_trainable_routing_policy_signature() -> None:
+    """_TrainableRoutingPolicy has the forward() shape required by Council."""
+    mod = _load_module()
+    PolicyCls = mod._TrainableRoutingPolicy
+    fake_model = MagicMock()
+    fake_tokenizer = MagicMock()
+    policy = PolicyCls(fake_model, fake_tokenizer)
+    assert callable(policy.forward)
+    assert (
+        "system_prompt" in PolicyCls.SYSTEM_PROMPT.lower()
+        or "router" in PolicyCls.SYSTEM_PROMPT.lower()
+    )

training/scripts/train_cortex_multi_model.py

@@ -0,0 +1,500 @@
+"""Multi-model Cortex GRPO training (Workstream B Phase 6).
+
+Trains the Cortex router LM (Qwen3-1.5B-Instruct + LoRA) via GRPO
+against episode reward, while three frozen brain LLMs (Qwen-7B epi,
+Llama-8B logistics, Qwen-7B governance via shared weights) drive the
+deliberation rollouts.
+
+Per Phase-A docs/CORTEX_ARCHITECTURE.md and root CLAUDE.md "Frozen"
+section: this is the multi-model training surface. Each Brain instance
+holds its own LLMClient pointing to a different model — Session 11's
+``Brain(__init__(llm_client))`` is multi-model-ready by design (audited
+M-FR-12).
+
+Memory budget on a100-large (80GB):
+  - Qwen3-7B 4-bit (epi):                ~14 GB
+  - Llama-3.1-8B 4-bit (logistics):      ~16 GB
+  - Qwen3-7B 4-bit (governance, shared): ~ 0 GB additional
+  - Qwen3-1.5B 4-bit + LoRA (router):    ~ 3 GB
+  - vLLM rollout overhead (router only): ~10 GB
+  - Total used:                         ~43 GB, ~37 GB headroom.
+
+Per Phase-A M-FR-31: only the trainable router uses vLLM; frozen brains
+use plain ``transformers.generate`` to avoid 4-way vLLM contention.
+
+Trainer.train() is commented out below — the live run is user-gated
+(~2 hours a100-large, ~$5). Skeleton ships with the full integration
+graph; uncomment the train() line after a 5-step dry-run smoke-tests
+the orchestration end-to-end.
+
+Usage on HF Jobs:
+    hf jobs run --hardware a100-large --secret HF_TOKEN \\
+        --env HUB_REPO_ID=Angshuman28/crisisworld-cortex-router-llm \\
+        ghcr.io/astral-sh/uv:latest \\
+        bash -c "git clone https://huggingface.co/spaces/Angshuman28/CrisisWorldCortex /app && \\
+                 cd /app && uv sync && uv run python training/scripts/train_cortex_multi_model.py"
+
+Local DRY_RUN test (no GPU):
+    DRY_RUN=1 HUB_REPO_ID=local/test \\
+        uv run python training/scripts/train_cortex_multi_model.py
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import time
+from typing import Any, List, Optional
+
+
+def _env(name: str, default: Optional[str] = None, *, required: bool = False) -> str:
+    value = os.environ.get(name, default)
+    if required and not value:
+        raise SystemExit(f"[FATAL] env var {name} is required but unset")
+    return value or ""
+
+
+# ============================================================================
+# Configuration (env-var driven)
+# ============================================================================
+
+HF_TOKEN = _env("HF_TOKEN", required=True)
+
+# Brain model choices. Default: Qwen-7B for epi+governance (shared), Llama-8B
+# for logistics. Each can be overridden to point at SFT-warmstarted checkpoints.
+EPI_BRAIN_MODEL = _env("EPI_BRAIN_MODEL", "unsloth/Qwen3-7B-Instruct-bnb-4bit")
+LOGISTICS_BRAIN_MODEL = _env("LOGISTICS_BRAIN_MODEL", "meta-llama/Llama-3.1-8B-Instruct")
+GOVERNANCE_BRAIN_MODEL = _env("GOVERNANCE_BRAIN_MODEL", EPI_BRAIN_MODEL)  # M-FR-27 default
+
+# Router model (the only trainable surface).
+ROUTER_MODEL = _env("ROUTER_MODEL", "unsloth/Qwen3-1.5B-Instruct-bnb-4bit")
+ROUTER_BASE_MODEL = _env("ROUTER_BASE_MODEL", ROUTER_MODEL)  # Phase-5e style fallback
+
+HUB_REPO_ID = _env("HUB_REPO_ID", required=True)
+ENV_URL = _env("ENV_URL", "https://angshuman28-crisisworldcortex.hf.space")
+OUTPUT_DIR = _env("OUTPUT_DIR", "/tmp/cortex_router_grpo_lora")
+
+MAX_TRAIN_STEPS = int(_env("MAX_TRAIN_STEPS", "300"))
+GROUP_SIZE = int(_env("GROUP_SIZE", "4"))
+BRAIN_CALL_TIMEOUT_S = int(_env("BRAIN_CALL_TIMEOUT_S", "30"))  # Phase-A M-FR-9
+LR = float(_env("LR", "5e-6"))
+LORA_RANK = int(_env("LORA_RANK", "16"))  # M-FR-28: smaller for 1.5B
+GPU_MEM_UTIL = float(_env("GPU_MEM_UTIL", "0.5"))  # Phase-A M-FR-10
+MAX_PROMPT_LEN = int(_env("MAX_PROMPT_LEN", "512"))
+MAX_COMPLETION_LEN = int(_env("MAX_COMPLETION_LEN", "256"))  # Phase-A M-FR-11
+TASKS_CSV = _env("TASKS_CSV", "outbreak_easy,outbreak_medium,outbreak_hard")
+EPISODE_TICKS = int(_env("EPISODE_TICKS", "12"))
+SEED = int(_env("SEED", "42"))
+DRY_RUN = _env("DRY_RUN", "0") not in ("0", "", "false", "False")
+
+# Memory budget hard floor: abort if less than this many GB free at script
+# start. Conservative — the steady-state is ~43 GB used; this leaves a 30-GB
+# margin for first-call activation peaks before the first vLLM kv-cache lock.
+MIN_FREE_GPU_GB = float(_env("MIN_FREE_GPU_GB", "30"))
+
+
+def log(*args: object) -> None:
+    print("[cortex-multi-model]", *args, flush=True)
+
+
+# ============================================================================
+# Pre-flight
+# ============================================================================
+
+
+def preflight_model_access(model_name: str, token: str) -> None:
+    """Same fail-loud check as Phase-5b/5d. Llama-3.1-8B may be gated."""
+    log(f"preflight: checking model access {model_name}")
+    from huggingface_hub import HfApi
+    from huggingface_hub.utils import GatedRepoError, RepositoryNotFoundError
+
+    try:
+        info = HfApi().model_info(model_name, token=token)
+        if getattr(info, "gated", False) and not getattr(info, "private", False):
+            log(f"preflight: {model_name} is gated; access verified")
+    except GatedRepoError as exc:
+        raise SystemExit(
+            f"[FATAL] {model_name} is gated and HF_TOKEN lacks access. "
+            f"Visit https://huggingface.co/{model_name} and accept the license. "
+            f"Original: {exc}"
+        ) from exc
+    except RepositoryNotFoundError as exc:
+        raise SystemExit(f"[FATAL] {model_name} not found on HF Hub: {exc}") from exc
+    log(f"preflight: {model_name} accessible")
+
+
+def check_memory_budget() -> None:
+    """Pre-flight torch.cuda.mem_get_info() check.
+
+    Hard floor: MIN_FREE_GPU_GB free. If less, abort before the first
+    model-load OOM crash mid-loading.
+    """
+    try:
+        import torch
+    except ImportError:
+        log("WARN torch not importable — skipping memory check")
+        return
+    if not torch.cuda.is_available():
+        log("WARN CUDA not available — skipping memory check (DRY_RUN expected)")
+        return
+    free, total = torch.cuda.mem_get_info()
+    free_gb = free / (1024**3)
+    total_gb = total / (1024**3)
+    log(f"GPU memory: {free_gb:.1f} GB free / {total_gb:.1f} GB total")
+    if free_gb < MIN_FREE_GPU_GB:
+        raise RuntimeError(
+            f"Insufficient GPU memory: {free_gb:.1f} GB free, need >= {MIN_FREE_GPU_GB} GB. "
+            f"Reduce LORA_RANK / GPU_MEM_UTIL or pick a smaller GOVERNANCE_BRAIN_MODEL "
+            f"(default shares with EPI). Aborting before model load."
+        )
+
+
+# ============================================================================
+# Adapters: Unsloth-loaded model -> cortex._LLMClientLike
+# ============================================================================
+
+
+class _UnslothLLMAdapter:
+    """Wrap an Unsloth-loaded (model, tokenizer) pair as a ``_LLMClientLike``.
+
+    Matches ``cortex.subagents._base._LLMClientLike`` protocol so it can
+    drop into ``Brain.__init__(llm_client=...)``. Frozen brains call this
+    via plain ``transformers.generate`` (M-FR-31 — no vLLM for brains).
+
+    Token accounting (``tokens_used_for``) returns 0 in this MVP; the
+    GRPO reward signal is the env's ``obs.reward``, not the budget
+    composition. If we later add token-budget-shaped reward, plug
+    ``training.reward_shaping.shape_reward`` into the rollout.
+    """
+
+    def __init__(self, model: Any, tokenizer: Any, *, brain_label: str) -> None:
+        self._model = model
+        self._tokenizer = tokenizer
+        self._brain_label = brain_label
+        self._call_counts: dict[str, int] = {}
+
+    def chat(
+        self,
+        caller_id: str,
+        messages: List[Any],
+        max_tokens: Optional[int] = None,
+        temperature: Optional[float] = None,
+    ) -> Any:
+        from cortex.llm_client import ChatResponse
+
+        prompt = self._tokenizer.apply_chat_template(
+            [{"role": m.role, "content": m.content} for m in messages],
+            tokenize=False,
+            add_generation_prompt=True,
+        )
+        import torch
+
+        inputs = self._tokenizer(prompt, return_tensors="pt").to(self._model.device)
+        gen_kwargs: dict[str, Any] = {
+            "max_new_tokens": max_tokens or 256,
+            "do_sample": (temperature or 0.0) > 0,
+        }
+        if (temperature or 0.0) > 0:
+            gen_kwargs["temperature"] = temperature
+        with torch.no_grad():
+            out = self._model.generate(**inputs, **gen_kwargs)
+        prompt_tokens = inputs["input_ids"].shape[1]
+        completion_tokens = out.shape[1] - prompt_tokens
+        text = self._tokenizer.decode(out[0][prompt_tokens:], skip_special_tokens=True)
+        self._call_counts[caller_id] = self._call_counts.get(caller_id, 0) + 1
+        # cortex.llm_client.ChatResponse signature: text + tokens_in + tokens_out.
+        return ChatResponse(text=text, tokens_in=prompt_tokens, tokens_out=completion_tokens)
+
+    def tokens_used_for(self, caller_id: str) -> int:
+        return self._call_counts.get(caller_id, 0)
+
+
+# ============================================================================
+# Adapter: trainable Unsloth router -> cortex.RoutingPolicy
+# ============================================================================
+
+
+class _TrainableRoutingPolicy:
+    """Wrap the Unsloth-loaded router LM as a ``cortex.RoutingPolicy``.
+
+    Input: ``MetacognitionState``. Output: ``RoutingAction``.
+
+    The router emits structured JSON per the system prompt. On parse
+    failure, returns ``stop_and_no_op`` per Phase-A M-FR-5 (close the
+    tick gracefully; the negative reward gradient teaches the router
+    to emit valid JSON).
+    """
+
+    SYSTEM_PROMPT = (
+        "You are the Cortex router. You receive a metacognition state summary and emit "
+        "ONE routing action as JSON. Allowed kinds: call_subagent (brain + subagent), "
+        "request_challenge (challenger_brain + target_brain), switch_phase (new_phase), "
+        "preserve_dissent (tag), emit_outer_action (action), stop_and_no_op. Hard caps: "
+        "<=2 rounds/tick, <=1 cross-brain challenge/tick, <=1 critic per brain/tick, "
+        "<=6000 tokens/tick. Output exactly one JSON object — no prose, no fences."
+    )
+
+    def __init__(self, model: Any, tokenizer: Any) -> None:
+        self._model = model
+        self._tokenizer = tokenizer
+
+    @staticmethod
+    def _state_to_prompt(state: Any) -> str:
+        return (
+            f"tick={getattr(state, 'tick', 0)} round={getattr(state, 'round', 1)} "
+            f"phase={getattr(state, 'phase', 'divergence')}\n"
+            f"agreement={getattr(state, 'inter_brain_agreement', 0.0):.2f} "
+            f"avg_conf={getattr(state, 'average_confidence', 0.0):.2f} "
+            f"evidence={getattr(state, 'average_evidence_support', 0.0):.2f}\n"
+            f"novelty={getattr(state, 'novelty_yield_last_round', 0.0):.2f} "
+            f"collapse={getattr(state, 'collapse_suspicion', 0.0):.2f} "
+            f"budget_frac={getattr(state, 'budget_remaining_frac', 1.0):.2f} "
+            f"urgency={getattr(state, 'urgency', 0.0):.2f}\n"
+            f"preserved_dissent={getattr(state, 'preserved_dissent_count', 0)} "
+            f"challenge_used={bool(getattr(state, 'challenge_used_this_tick', 0))}\n"
+            f"Choose the next routing action."
+        )
+
+    def forward(self, state: Any) -> Any:
+        import json
+
+        import torch
+        from pydantic import TypeAdapter, ValidationError
+
+        from cortex.schemas import RoutingAction, StopAndNoOp
+
+        prompt = self._tokenizer.apply_chat_template(
+            [
+                {"role": "system", "content": self.SYSTEM_PROMPT},
+                {"role": "user", "content": self._state_to_prompt(state)},
+            ],
+            tokenize=False,
+            add_generation_prompt=True,
+        )
+        inputs = self._tokenizer(prompt, return_tensors="pt").to(self._model.device)
+        with torch.no_grad():
+            out = self._model.generate(
+                **inputs, max_new_tokens=MAX_COMPLETION_LEN, do_sample=False, temperature=0.0
+            )
+        text = self._tokenizer.decode(
+            out[0][inputs["input_ids"].shape[1] :], skip_special_tokens=True
+        ).strip()
+        try:
+            data = json.loads(text)
+            return TypeAdapter(RoutingAction).validate_python(data)
+        except (json.JSONDecodeError, ValidationError):
+            # Phase-A M-FR-5 graceful fallback.
+            return StopAndNoOp()
+
+
+# ============================================================================
+# Main
+# ============================================================================
+
+
+def main() -> int:
+    log(f"EPI_BRAIN_MODEL={EPI_BRAIN_MODEL}")
+    log(f"LOGISTICS_BRAIN_MODEL={LOGISTICS_BRAIN_MODEL}")
+    log(f"GOVERNANCE_BRAIN_MODEL={GOVERNANCE_BRAIN_MODEL}")
+    log(f"ROUTER_MODEL={ROUTER_MODEL} ROUTER_BASE_MODEL={ROUTER_BASE_MODEL}")
+    log(f"HUB_REPO_ID={HUB_REPO_ID} ENV_URL={ENV_URL}")
+    log(f"MAX_TRAIN_STEPS={MAX_TRAIN_STEPS} GROUP_SIZE={GROUP_SIZE} LR={LR}")
+    log(f"LORA_RANK={LORA_RANK} GPU_MEM_UTIL={GPU_MEM_UTIL}")
+
+    preflight_model_access(EPI_BRAIN_MODEL, HF_TOKEN)
+    preflight_model_access(LOGISTICS_BRAIN_MODEL, HF_TOKEN)
+    if GOVERNANCE_BRAIN_MODEL != EPI_BRAIN_MODEL:
+        preflight_model_access(GOVERNANCE_BRAIN_MODEL, HF_TOKEN)
+    preflight_model_access(ROUTER_BASE_MODEL, HF_TOKEN)
+
+    if DRY_RUN:
+        log("DRY_RUN=1 — preflight only; not loading models or training")
+        return 0
+
+    check_memory_budget()
+
+    # Lazy imports — keeps DRY_RUN fast and avoids loading torch/Unsloth on
+    # local machines that don't have GPU.
+    from datasets import Dataset
+    from trl import GRPOConfig, GRPOTrainer
+    from unsloth import FastLanguageModel
+
+    from cortex.brains import EpiBrain, GovernanceBrain, LogisticsBrain
+    from cortex.council import Council
+    from CrisisWorldCortex.client import CrisisworldcortexEnv
+
+    # Phase 7 will import baselines.cortex_fixed_router inline at the warmup-data
+    # step. Cannot import here at module scope: training/* MUST NOT import
+    # baselines/* per the import-graph rule (enforced by tests/test_import_graph.py).
+
+    # ---- Load 3 frozen brain LLMs (M-FR-31: no vLLM for brains) ----
+    def _load_frozen(model_name: str, label: str) -> tuple[Any, Any]:
+        log(f"loading frozen {label} brain: {model_name}")
+        m, t = FastLanguageModel.from_pretrained(
+            model_name=model_name,
+            max_seq_length=4096,
+            load_in_4bit=True,
+            fast_inference=False,  # plain transformers.generate per M-FR-31
+            gpu_memory_utilization=GPU_MEM_UTIL,
+        )
+        FastLanguageModel.for_inference(m)
+        return m, t
+
+    epi_model, epi_tok = _load_frozen(EPI_BRAIN_MODEL, "epi")
+    logistics_model, logistics_tok = _load_frozen(LOGISTICS_BRAIN_MODEL, "logistics")
+    if GOVERNANCE_BRAIN_MODEL == EPI_BRAIN_MODEL:
+        log("governance: sharing weights with epi (M-FR-27)")
+        governance_model, governance_tok = epi_model, epi_tok
+    else:
+        governance_model, governance_tok = _load_frozen(GOVERNANCE_BRAIN_MODEL, "governance")
+
+    # Build per-brain LLM client adapters.
+    epi_client = _UnslothLLMAdapter(epi_model, epi_tok, brain_label="epi")
+    logistics_client = _UnslothLLMAdapter(logistics_model, logistics_tok, brain_label="logistics")
+    governance_client = _UnslothLLMAdapter(
+        governance_model, governance_tok, brain_label="governance"
+    )
+
+    # Construct the 3 brains via Session-11 factory functions.
+    brains = {
+        "epidemiology": EpiBrain(llm_client=epi_client),
+        "logistics": LogisticsBrain(llm_client=logistics_client),
+        "governance": GovernanceBrain(llm_client=governance_client),
+    }
+    log(f"brains constructed: {list(brains.keys())}")
+
+    # ---- Load the trainable router LLM (M-FR-31: only this one uses vLLM) ----
+    log(f"loading trainable router: {ROUTER_BASE_MODEL} (LoRA r={LORA_RANK})")
+    router_model, router_tok = FastLanguageModel.from_pretrained(
+        model_name=ROUTER_BASE_MODEL,
+        max_seq_length=MAX_PROMPT_LEN + MAX_COMPLETION_LEN,
+        load_in_4bit=True,
+        fast_inference=True,
+        max_lora_rank=LORA_RANK,
+        gpu_memory_utilization=GPU_MEM_UTIL,
+    )
+    router_model = FastLanguageModel.get_peft_model(
+        router_model,
+        r=LORA_RANK,
+        target_modules=[
+            "q_proj",
+            "k_proj",
+            "v_proj",
+            "o_proj",
+            "gate_proj",
+            "up_proj",
+            "down_proj",
+        ],
+        lora_alpha=LORA_RANK * 2,
+        use_gradient_checkpointing="unsloth",
+        random_state=SEED,
+    )
+    router_policy = _TrainableRoutingPolicy(router_model, router_tok)
+    log("trainable router ready")
+
+    # ---- Build prompt dataset from B3 deterministic-router trajectories ----
+    # Phase 7 will populate this from real B3 rollouts; the skeleton emits
+    # one placeholder row so GRPOTrainer construction succeeds.
+    tasks = tuple(t.strip() for t in TASKS_CSV.split(",") if t.strip())
+    log(f"tasks={tasks}")
+
+    def make_env() -> CrisisworldcortexEnv:
+        return CrisisworldcortexEnv(base_url=ENV_URL)
+
+    train_dataset = Dataset.from_dict(
+        {
+            "prompt": ["placeholder until live B3 corpus collection"],
+            "task": ["outbreak_easy"],
+            "seed": [0],
+        }
+    )
+
+    # ---- Reward function: full-episode rollout per (prompt, completion) ----
+    def cortex_reward(
+        prompts: list[str],
+        completions: list[str],
+        task: list[str],
+        seed: list[int],
+        **_kwargs: object,
+    ) -> list[float]:
+        rewards: list[float] = []
+        for _completion, t, s in zip(completions, task, seed):
+            try:
+                council = Council(brains=brains, routing_policy=router_policy)
+                env = make_env()
+                obs = env.reset(task_name=t, seed=int(s), max_ticks=EPISODE_TICKS)
+                cumulative = 0.0
+                last_reward = 0.0
+                for _ in range(EPISODE_TICKS):
+                    action = council.step(obs, last_reward=last_reward)
+                    result = env.step(action)
+                    next_obs = result.observation if hasattr(result, "observation") else result
+                    last_reward = next_obs.reward if next_obs.reward is not None else 0.0
+                    cumulative += last_reward
+                    obs = next_obs
+                    if next_obs.done:
+                        break
+                rewards.append(float(cumulative))
+            except Exception as exc:
+                log(f"WARN rollout failed task={t} seed={s}: {exc}")
+                rewards.append(-1.0)
+        return rewards
+
+    # ---- GRPO config + trainer ----
+    log("constructing GRPOTrainer (router-only)")
+    training_args = GRPOConfig(
+        output_dir=OUTPUT_DIR,
+        learning_rate=LR,
+        per_device_train_batch_size=GROUP_SIZE,
+        gradient_accumulation_steps=1,
+        num_generations=GROUP_SIZE,
+        max_prompt_length=MAX_PROMPT_LEN,
+        max_completion_length=MAX_COMPLETION_LEN,
+        max_steps=MAX_TRAIN_STEPS,
+        save_steps=max(MAX_TRAIN_STEPS // 3, 1),
+        logging_steps=max(MAX_TRAIN_STEPS // 60, 1),
+        report_to="none",
+        bf16=True,
+        optim="adamw_8bit",
+        temperature=0.8,
+        use_vllm=True,
+        vllm_mode="colocate",
+        seed=SEED,
+    )
+    trainer = GRPOTrainer(
+        model=router_model,  # M-FR-23: router is the ONLY trainable surface
+        processing_class=router_tok,
+        reward_funcs=[cortex_reward],
+        args=training_args,
+        train_dataset=train_dataset,
+    )
+    log(f"trainer constructed: {type(trainer).__name__}")
+    log("# Phase 6 ships skeleton — uncomment trainer.train() in Phase 7 after")
+    log("# (a) B3 corpus has populated train_dataset, and (b) a 5-step dry-run")
+    log("# verifies multi-model orchestration end-to-end (~$0.50).")
+    # trainer.train()  # Phase 7 unblock: uncomment after dry-run verification.
+
+    log(f"saving router LoRA to {OUTPUT_DIR}")
+    router_model.save_pretrained(OUTPUT_DIR)
+    router_tok.save_pretrained(OUTPUT_DIR)
+
+    log(f"pushing to https://huggingface.co/{HUB_REPO_ID}")
+    from huggingface_hub import HfApi
+
+    api = HfApi()
+    api.create_repo(HUB_REPO_ID, exist_ok=True, repo_type="model", private=False, token=HF_TOKEN)
+    api.upload_folder(
+        folder_path=OUTPUT_DIR,
+        repo_id=HUB_REPO_ID,
+        repo_type="model",
+        token=HF_TOKEN,
+    )
+    log("push complete")
+    return 0
+
+
+if __name__ == "__main__":
+    t0 = time.time()
+    rc = main()
+    log(f"done in {time.time() - t0:.1f}s")
+    sys.exit(rc)

uv.lock

@@ -1650,7 +1650,6 @@ source = { editable = "." }
 dependencies = [
     { name = "openai" },
     { name = "openenv-core", extra = ["core"] },
-    { name = "python-dotenv" },
 ]
 
 [package.optional-dependencies]
@@ -1668,7 +1667,6 @@ requires-dist = [
     { name = "pre-commit", marker = "extra == 'dev'", specifier = ">=4.0.0" },
     { name = "pytest", marker = "extra == 'dev'", specifier = ">=8.0.0" },
     { name = "pytest-cov", marker = "extra == 'dev'", specifier = ">=4.0.0" },
-    { name = "python-dotenv", specifier = ">=1.0.0" },
     { name = "ruff", marker = "extra == 'dev'", specifier = ">=0.8.0" },
 ]
 provides-extras = ["dev"]