Refactor NPC roles and enhance survival mechanics

- Updated NPC role for Ada from "farmer" to "gatherer" across multiple tests and memory summaries.
- Modified the NPC simulation to ensure only guards engage threats, changing the goal from "survive_threat_fight" to "engage_threat".
- Adjusted hunger mechanics in survival tests to reflect a more accurate growth rate.
- Enhanced world advancement logic to incorporate overseer metadata and post-survival tick applications.
- Improved beast spawning logic to respect population requirements and cooldowns.
- Ensured memory management retains recent entries and summarizes older events correctly.

GAME_DESIGN.md

@@ -0,0 +1,341 @@
+# GAME_DESIGN.md — GOD_SIMULATOR: "Overseer vs Chaos"
+
+> **This document is the single source of truth for all coding agents.**
+> If code and this document disagree, this document wins.
+> Do not invent your own balance numbers — use the constants below.
+> All constants should live in one config file (`config/game_balance.py` or equivalent) so they can be tuned without touching logic.
+
+---
+
+## 0. One-liner
+
+**A village of tiny LLM citizens trying to survive and multiply, guided by an AI Overseer — while the human player acts as the God of Chaos trying to destroy them.**
+
+Architecture principle (unchanged from current codebase):
+- **LLM = picks NPC actions only.**
+- **Engine = the only source of truth.** Validates every action, applies all consequences (hp, hunger, inventory, trust, memory, movement, death, birth).
+- **Overseer = a larger LLM** that reads logs/snapshots and issues directives through the existing directive system. The engine validates Overseer directives exactly like God Console directives.
+
+---
+
+## 1. Win / Lose conditions
+
+| Condition | Value |
+|---|---|
+| **WIN (village)** | Population reaches **12** alive NPCs, OR the village survives **600 ticks** with population ≥ 3 |
+| **LOSE (village)** | Population reaches **0** |
+| Game length target | A typical session ends in 300–600 ticks (~5–10 min of real time) |
+
+`world.game_status`: `"running" | "win_population" | "win_survival" | "lose"` — must be present in every snapshot.
+
+When the game ends, the engine emits a `game_over` event containing summary stats: total births, deaths (by cause), houses built, beasts killed, peak population, final scoreboard.
+
+---
+
+## 2. Core NPC stats
+
+| Stat | Range | Notes |
+|---|---|---|
+| `hp` | 0–100 | 0 = death |
+| `hunger` | 0–100 | 100 = starving (hp drain) |
+| `fear` | 0–100 | affects goal selection |
+| `safety` | 0–100 | NEW. 100 required for reproduction |
+| `age` | ticks | NEW. Increments +1 every tick |
+| `max_age` | ticks | NEW. Randomized at spawn: **400 ± 80** (uniform 320–480) |
+| `importance` | float ≥ 0 | NEW. Derived score, see §8 |
+| `reproduction_cooldown` | ticks | NEW. Counts down to 0 |
+
+### Stat dynamics per tick
+
+| Rule | Value |
+|---|---|
+| Hunger growth | **+0.8 / tick** |
+| Starvation | if `hunger ≥ 70`: **hp −0.5 / tick**; if `hunger ≥ 90`: **hp −1.5 / tick** |
+| Eating (`consume`, costs 1 food) | **hunger −40**, **hp +5** |
+| Healing (`heal`, costs 1 herbs) | **hp +25** (cap 100) |
+| Fear gain | beast within **8 units**: fear → at least 60, +20 per attack witnessed |
+| Fear decay | **−2 / tick** when no beast within 12 units |
+| Old age death | when `age ≥ max_age`: NPC dies, cause `old_age`, witnesses get a memory episode |
+
+### Safety (NEW)
+
+`safety` is computed, not LLM-controlled:
+
+- **Inside a completed house** AND no living beast within **12 units** of the house: `safety +12 / tick` (cap 100).
+- Inside a house but a beast is within 12 units: safety frozen (no gain, no loss).
+- Outside any house: `safety −8 / tick` (floor 0).
+- Hostile NPC directive targeting this NPC within 10 units counts as a threat (same as beast).
+
+This means an NPC needs ~9 consecutive calm ticks at home to reach safety 100. That is the intended pacing.
+
+---
+
+## 3. Classes (roles)
+
+Every NPC has `role: "guard" | "builder" | "gatherer"`, fixed at spawn.
+
+**Action whitelist is enforced by the engine BEFORE the LLM is called.** The LLM only ever sees the actions its role allows. Smaller action space = better behavior from small models.
+
+### Shared actions (all roles)
+`move_to_resource`, `consume`, `heal`, `flee`, `communicate` (help_request / warning / trade_request / social), `transfer`, `go_home` (NEW: move into nearest house with free capacity), `wander`.
+
+### Gatherer 🌾
+- Extra actions: `gather` (any resource type), `steal`.
+- Combat: may `attack` only in self-defense (beast within 2 units), damage multiplier **×0.3**.
+- Intended loop: gather food/herbs/wood → transfer wood to builders, food to hungry NPCs → go home → reproduce.
+
+### Guard 🗡
+- Extra actions: `attack`, `defend`, `patrol` (NEW: cycle between houses / village center).
+- Damage multiplier **×1.5**; base damage 10 → effective 15 per hit.
+- Spawns with `weapon: 1`.
+- Cannot `gather`, cannot `steal`.
+- Engine-level reflex (not LLM): if a beast is within **10 units of any house or NPC**, the guard's goal is forced to `engage_threat` (LLM then picks attack/defend/communicate within that goal).
+
+### Builder 🔨
+- Extra actions: `build` (see §4), `gather` restricted to **wood only**.
+- Cannot `attack` (flee/defend only), damage multiplier ×0.3 in self-defense.
+- Intended loop: collect/receive wood → build houses → houses enable reproduction.
+
+### Role balance rules
+- New NPC (born) inherits a role chosen to fix the biggest scarcity: target ratio **gatherer : guard : builder = 3 : 2 : 1**. If ratios are balanced, inherit a parent's role.
+- Starting village (tick 0): **6 NPCs = 3 gatherers, 2 guards, 1 builder.**
+
+---
+
+## 4. Houses & building
+
+New entity:
+
+```json
+{
+  "id": "house_001",
+  "position": {"x": 0, "z": 0},
+  "hp": 60,
+  "max_hp": 60,
+  "state": "under_construction | completed",
+  "build_progress": 0,
+  "capacity": 3,
+  "occupant_ids": []
+}
+```
+
+| Rule | Value |
+|---|---|
+| Build cost | **5 wood** (consumed from builder inventory at start) |
+| Build time | **10 ticks** of the builder staying within 2 units performing `build` (progress +1/tick; pauses if builder flees, resumes later) |
+| Capacity | **3 NPCs** |
+| House radius ("inside") | **2.5 units** |
+| Min distance between houses | 4 units (engine rejects closer build attempts) |
+| Beasts vs houses | Beasts **cannot damage NPCs inside** a completed house. A beast whose target hides indoors attacks the house: **5 dmg/hit**. House at 0 hp is destroyed; occupants are exposed and fear → 80 |
+| Starting houses | **1 completed house** at village center (so reproduction is possible from tick 0, but one house caps growth — building matters) |
+
+Engine emits events: `build_started`, `build_completed`, `house_damaged`, `house_destroyed`.
+
+---
+
+## 5. Reproduction & lifespan
+
+An NPC reproduces (engine-checked every tick, no LLM involvement in the check) when **all** are true:
+
+1. `hp ≥ 95`
+2. `hunger ≤ 5`
+3. `safety == 100`
+4. `age ≥ 50`
+5. `reproduction_cooldown == 0`
+6. NPC is inside a completed house with free capacity for the child OR village population < cap
+7. Population < **16** (hard cap)
+
+Effects of birth:
+- New NPC spawns at the house: `age 0`, `hp 70`, `hunger 20`, `fear 0`, empty inventory (guards still get weapon 1), role per §3 scarcity rule, `max_age` rerolled.
+- Parent: `reproduction_cooldown = 60` ticks, `hunger +30` (reproduction is costly — prevents runaway loops).
+- Trust: child ↔ parent initialized at **+0.6**.
+- Event `npc_born` + memory episodes for parent (self) and house occupants (witness).
+- Child is a full NPC immediately (no childhood mechanics — out of scope).
+
+Death (any cause: beast, starvation, old age, NPC attack):
+- Event `npc_died` with `cause`.
+- Witnesses within 10 units get a memory episode (`emotional_weight 0.9`).
+- Inventory drops as a resource node at death position (lootable via `gather`).
+
+---
+
+## 6. Beasts
+
+Mostly unchanged; tuned values:
+
+| Param | Value |
+|---|---|
+| Beast hp | **60** |
+| Beast damage | **9 per hit** (NPC needs ~2 hits survived to feel danger; not one-shot) |
+| Attack radius | 1.5 units |
+| Target priority | nearest NPC outside houses; prefers `hp < 50` if within 1.3× distance of nearest |
+| Retreat | at `hp < 20`, beast flees to map edge and despawns after 15 ticks |
+| MAX_BEASTS | **3** (natural spawns); God Console can exceed up to 6 |
+| Natural spawn cooldown | 1 beast per **60–90 ticks** (random), only while population ≥ 4 |
+| Beast vs guard math | Guard (15 dmg/hit) kills a beast in 4 hits; beast kills a full-hp NPC in 12 hits → 2 guards handle 1 beast comfortably, 1 guard wins but ends wounded. 3 beasts overwhelm 2 guards — that's the Chaos lever. |
+
+---
+
+## 7. Resources
+
+| Type | Nodes at start | max_amount | Regen | Notes |
+|---|---|---|---|---|
+| food | 4 | 5 | +1 per **8 ticks** | consumed via `consume` |
+| herbs | 2 | 4 | +1 per **12 ticks** | consumed via `heal` |
+| wood | 3 | 6 | +1 per **10 ticks** | consumed via `build` |
+| weapon | 1 | 2 | +1 per **40 ticks** | picked up via `gather`, mostly for replacing dead guards |
+
+- `gather` = 1 unit per tick within 1.5 units of node.
+- Famine (Chaos tool) halves `amount` and `max_amount` of all food nodes for 100 ticks.
+- Total food throughput at start: 4 nodes × 1/8 = 0.5 food/tick ≈ supports ~10 NPCs eating every ~50 ticks. Tight but survivable — scarcity is intentional.
+
+---
+
+## 8. Importance score
+
+Recomputed by engine every 10 ticks (visible in UI and Overseer context, used by nothing else for now):
+
+```
+importance = 1.0
+           + 2.0 * (role_scarcity)            # 1 / count_of_same_role_alive
+           + 0.5 * beasts_killed
+           + 0.3 * resources_transferred
+           + 0.4 * children_count
+           + 0.5 * houses_built               # builders
+```
+
+Purpose: gives the Overseer an explicit signal whom to protect ("our last builder!") and gives judges a visible "value of a life" number. **No other mechanic depends on it** — keep it cheap.
+
+---
+
+## 9. Trust (unchanged primitives, fixed deltas)
+
+| Event | Trust delta |
+|---|---|
+| `transfer` (received a resource) | **+0.15** |
+| Real help: attacked/defended a threat near me while I was in danger | **+0.20** |
+| `steal` (victim and witnesses) | **−0.30** |
+| NPC attacked NPC | **−0.40** |
+| Beast relationship | fixed −1.0 |
+| `help_request` alone | 0 (asking isn't helping) |
+| Clamp | −1.0 … +1.0 |
+| "Trusted ally" threshold for cooperation goals | **trust > 0.3** |
+
+---
+
+## 10. Overseer (the AI commander)
+
+| Param | Value |
+|---|---|
+| Cycle | every **8 ticks** |
+| Max directives per cycle | **3** |
+| Modes | `off` / `advisor` (thoughts shown, directives NOT applied) / `autopilot` (directives applied) |
+| Model | configurable endpoint, separate from NPC model (larger model) |
+| Fallback | on API error/timeout (>10s) or invalid JSON: skip cycle, log `overseer_skipped`, never block the world tick |
+
+**Overseer context (compact, ≤ ~1500 tokens):** tick, game_status, population by role, win-condition progress, list of NPCs (id, role, hp, hunger, safety, position zone, importance, current goal), houses (state, hp), resource node totals, active beasts (position, hp, current target), last 20 event-log lines, current chaos events.
+
+**Overseer output — strict JSON only:**
+
+```json
+{
+  "thoughts": "Two beasts north. Boris (last builder, importance 4.1) must hide. Guards intercept.",
+  "directives": [
+    {"npc_id": "npc_003", "directive": "go home and stay inside until beasts are gone"},
+    {"npc_id": "npc_001", "directive": "attack beast_2 together with npc_005"}
+  ],
+  "priority_alert": "Protect the last builder"
+}
+```
+
+Directives are injected via the **existing directive system**; the engine validates radius/movement/damage as it does for God Console. A directive cannot grant actions outside the NPC's role whitelist. Invalid `npc_id` → directive dropped + logged.
+
+---
+
+## 11. Scoreboard: Overseer vs Chaos
+
+| Event | Points |
+|---|---|
+| `npc_born` | Overseer **+3** |
+| `build_completed` | Overseer **+2** |
+| Beast killed by NPCs | Overseer **+2** |
+| `npc_died` (any cause) | Chaos **+3** |
+| `house_destroyed` | Chaos **+2** |
+| `steal` occurred | Chaos **+1** (social decay counts as chaos) |
+
+Score is cosmetic (does not affect win/lose) but must be in every snapshot and prominent in UI.
+
+### Chaos tools (God Console quick-buttons)
+
+| Tool | Effect | Cooldown |
+|---|---|---|
+| Spawn Beast | 1 beast at map edge | 20 ticks |
+| Beast Pack | 3 beasts | 80 ticks |
+| Famine | food nodes halved for 100 ticks | 120 ticks |
+| Maniac | hostile directive on a random NPC: attack others (engine-validated; victim can flee/call help) for 60 ticks or until subdued | 100 ticks |
+
+Cooldowns exist so the player cannot trivially insta-wipe the village; the duel must look winnable for both sides. Free-form God Console directives remain available (power user mode).
+
+---
+
+## 12. Goal selection priority (deterministic layer above the LLM)
+
+Engine assigns a **goal**; the LLM picks the concrete action within it. Priority order (first match wins):
+
+1. `survive_threat` — beast/hostile within 8 units → (guard: engage; others: flee / go_home / help_request)
+2. `engage_threat` — guards only, beast within 10 units of village
+3. `recover` — hp < 40 → heal if herbs, else seek herbs / go home
+4. `eat` — hunger ≥ 60 → consume if food, else trade_request to trusted ally with surplus, else gather food; if hunger ≥ 85 and no options → steal becomes available (gatherers)
+5. `obey_directive` — active Overseer/God directive (note: threats and critical needs above CAN preempt a directive — citizens are not robots; this is intended and makes autopilot imperfect)
+6. `settle` — hp ≥ 80, hunger ≤ 30, no threats → go_home, rest toward reproduction
+7. `work` — role routine: gatherer gathers scarcest resource, builder builds/gathers wood, guard patrols
+8. `social` — communicate / share surplus / wander
+
+---
+
+## 13. Event log (the spine of UI and Overseer)
+
+Every engine consequence emits a structured event:
+
+```json
+{"tick": 142, "type": "npc_born", "actor_id": "npc_003", "target_id": "npc_009", "summary": "Elena gave birth to Mira", "severity": "good"}
+```
+
+`type` enum (minimum): `beast_spawned, beast_attack, beast_killed, beast_retreat, npc_attack, npc_died, npc_born, build_started, build_completed, house_damaged, house_destroyed, gather, transfer, steal, heal, consume, help_request, directive_issued, directive_completed, chaos_event, overseer_skipped, game_over`.
+
+`severity`: `good | neutral | warning | danger`. The UI event feed and the Overseer context both read from this log. **No mechanic should be invisible** — if it happened, it's an event.
+
+---
+
+## 14. Balance targets (what playtests must show)
+
+1. **No chaos, no overseer:** village survives 300+ ticks, builds ≥ 1 house, ≥ 2 births. Median run does NOT die out.
+2. **Scheduled chaos (beast@50, famine@120, pack@200, maniac@280), overseer OFF:** village usually loses or ends crippled (population ≤ 3).
+3. **Same chaos, overseer ON (autopilot):** village survives noticeably more often (target: ≥ 50% of runs reach tick 400).
+4. **Max-aggression human chaos:** village can be destroyed — Chaos must be able to win.
+5. No runaway growth: population should not hit the 16 cap before tick ~250 in a calm run.
+
+If a target fails, tune **numbers in this file only** (hunger rate, beast damage, regen, cooldowns) — do not add mechanics.
+
+---
+
+## 15. Out of scope (do NOT build)
+
+Factions, economy/money, crafting beyond `build`, childhood/aging stages, social status & power hierarchy (README roadmap only), multiplayer, persistence/SQLite, long-term story arcs, new LLM tools beyond the action lists above, 3D polish at the expense of gameplay.
+
+---
+
+## 16. Acceptance tests (headless, must stay green)
+
+`scripts/headless_sim.py` (deterministic fallback, no LLM, fixed seed) must assert over a 300-tick run:
+
+1. ≥ 1 `build_completed`
+2. ≥ 1 `npc_born`
+3. ≥ 1 beast engaged by a guard (`npc_attack` with beast target by a guard)
+4. ≥ 1 death with correct cause attribution
+5. Population never negative; no crashes; every tick ≤ reasonable time budget
+6. Role whitelists never violated (no gather by guards, no attack actions chosen by builders)
+7. Reproduction never fires when any condition in §5 is false (property check)
+8. `game_status` transitions correctly on win/lose seeds
+
+`scripts/playtest_agent.py` runs the scheduled-chaos scenarios from §14 and produces `playtest_report.md` with: event timeline, population-over-time data, which causal chains occurred (beast→fear→help_request→guard response→trust change; hunger→gather/steal; build→reproduce), and a balance verdict.

frontend/src/App.tsx

@@ -1,13 +1,17 @@
 import { AgentPanel } from "./components/AgentPanel";
-import { GodConsolePanel } from "./components/GodConsolePanel";
+import { ChaosDock } from "./components/ChaosDock";
+import { EventFeedPanel } from "./components/EventFeedPanel";
+import { GameOverOverlay } from "./components/GameOverOverlay";
+import { OverseerPanel } from "./components/OverseerPanel";
+import { ScoreboardHeader } from "./components/ScoreboardHeader";
 import { SimulationControls } from "./components/SimulationControls";
-import { StatusBar } from "./components/StatusBar";
 import { StatusToasts } from "./components/StatusToasts";
 import { useWorldSimulation } from "./hooks/useWorldSimulation";
 import { GodSimulatorScene } from "./scene/GodSimulatorScene";
 
 export function App() {
   const simulation = useWorldSimulation();
+  const gameStatus = simulation.snapshot?.simulation.game_status ?? "running";
 
   return (
     <main className="shell">
@@ -17,12 +21,16 @@ export function App() {
         onSelectEntity={simulation.setSelectedId}
       />
 
-      <StatusBar
+      <ScoreboardHeader
         snapshot={simulation.snapshot}
         isGodPending={simulation.isGodPending}
         isWaitingForTick={simulation.isWaitingForTick}
       />
 
+      <OverseerPanel snapshot={simulation.snapshot} log={simulation.overseerLog} />
+
+      <EventFeedPanel events={simulation.eventHistory} />
+
       <SimulationControls
         hasSnapshot={simulation.snapshot !== null}
         isAutoTicking={simulation.isAutoTicking}
@@ -37,13 +45,19 @@ export function App() {
         }}
       />
 
-      <GodConsolePanel
-        command={simulation.godCommand}
+      <ChaosDock
+        snapshot={simulation.snapshot}
+        pendingChaosAction={simulation.pendingChaosAction}
+        chaosMessage={simulation.chaosMessage}
+        godCommand={simulation.godCommand}
+        godMessage={simulation.godMessage}
         isGodPending={simulation.isGodPending}
         isWaitingForTick={simulation.isWaitingForTick}
-        message={simulation.godMessage}
+        onChaosAction={(action) => {
+          void simulation.runChaosAction(action);
+        }}
         onCommandChange={simulation.setGodCommand}
-        onSubmit={(event) => {
+        onSubmitCommand={(event) => {
           void simulation.runGodCommand(event);
         }}
       />
@@ -54,6 +68,10 @@ export function App() {
         error={simulation.error}
         isWaitingForTick={simulation.isWaitingForTick}
       />
+
+      {simulation.snapshot && gameStatus !== "running" ? (
+        <GameOverOverlay snapshot={simulation.snapshot} events={simulation.eventHistory} />
+      ) : null}
     </main>
   );
 }

frontend/src/api.ts

@@ -53,3 +53,31 @@ export async function sendGodCommand(command: string): Promise<GodCommandResult>
   }
   return (await response.json()) as GodCommandResult;
 }
+
+export type ChaosActionResult = {
+  action: string;
+  applied: string[];
+  summary: string;
+  snapshot: WorldSnapshot;
+};
+
+export async function sendChaosAction(action: string): Promise<ChaosActionResult> {
+  const response = await fetch(`${API_BASE}/chaos`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ action }),
+  });
+  if (!response.ok) {
+    let message = `Chaos action failed: ${response.status}`;
+    try {
+      const body = (await response.json()) as { message?: string };
+      if (body.message) {
+        message = body.message;
+      }
+    } catch {
+      // keep the generic message
+    }
+    throw new ApiResponseError(message, response.status);
+  }
+  return (await response.json()) as ChaosActionResult;
+}

frontend/src/components/AgentPanel.tsx

@@ -38,8 +38,16 @@ function AgentDetails({ entity }: { entity: EntitySnapshot }) {
 }
 
 function SurvivalReadout({ entity }: { entity: EntitySnapshot }) {
-  const { hunger, fear, goal, inventory } = entity.state;
-  if (hunger === undefined && fear === undefined && goal === undefined && !inventory) {
+  const { hunger, fear, safety, age, max_age, importance, goal, inventory } = entity.state;
+  if (
+    hunger === undefined &&
+    fear === undefined &&
+    safety === undefined &&
+    age === undefined &&
+    importance === undefined &&
+    goal === undefined &&
+    !inventory
+  ) {
     return null;
   }
 
@@ -55,6 +63,15 @@ function SurvivalReadout({ entity }: { entity: EntitySnapshot }) {
       {fear !== undefined ? (
         <TooltipLabel className="readoutCell" value={`Fear ${fear.toFixed(0)}`} />
       ) : null}
+      {safety !== undefined ? (
+        <TooltipLabel className="readoutCell" value={`Safety ${safety.toFixed(0)}`} />
+      ) : null}
+      {age !== undefined && max_age !== undefined ? (
+        <TooltipLabel className="readoutCell" value={`Age ${age}/${max_age}`} />
+      ) : null}
+      {importance !== undefined ? (
+        <TooltipLabel className="readoutCell" value={`Importance ${importance.toFixed(1)}`} />
+      ) : null}
       {goal ? <TooltipLabel className="readoutCell" value={goal} /> : null}
       <TooltipLabel className="readoutCell" value={inventoryLabel} />
     </div>

frontend/src/components/ChaosDock.tsx

@@ -0,0 +1,107 @@
+import { LoaderCircle, Send } from "lucide-react";
+import type { FormEvent } from "react";
+
+import type { ChaosToolSnapshot, WorldSnapshot } from "../types";
+
+const CHAOS_ICONS: Record<string, string> = {
+  spawn_beast: "🐺",
+  beast_pack: "🐺×3",
+  famine: "🌾",
+  maniac: "🔪",
+};
+
+const FALLBACK_TOOLS: ChaosToolSnapshot[] = [
+  { action: "spawn_beast", label: "Spawn Beast", cooldown_ticks: 20, remaining_ticks: 0 },
+  { action: "beast_pack", label: "Beast Pack", cooldown_ticks: 80, remaining_ticks: 0 },
+  { action: "famine", label: "Famine", cooldown_ticks: 120, remaining_ticks: 0 },
+  { action: "maniac", label: "Maniac", cooldown_ticks: 100, remaining_ticks: 0 },
+];
+
+type ChaosDockProps = {
+  snapshot: WorldSnapshot | null;
+  pendingChaosAction: string | null;
+  chaosMessage: string | null;
+  godCommand: string;
+  godMessage: string | null;
+  isGodPending: boolean;
+  isWaitingForTick: boolean;
+  onChaosAction: (action: string) => void;
+  onCommandChange: (command: string) => void;
+  onSubmitCommand: (event: FormEvent<HTMLFormElement>) => void;
+};
+
+export function ChaosDock({
+  snapshot,
+  pendingChaosAction,
+  chaosMessage,
+  godCommand,
+  godMessage,
+  isGodPending,
+  isWaitingForTick,
+  onChaosAction,
+  onCommandChange,
+  onSubmitCommand,
+}: ChaosDockProps) {
+  const tools = snapshot?.simulation.chaos_tools ?? FALLBACK_TOOLS;
+  const message = chaosMessage ?? godMessage;
+
+  return (
+    <section className="chaosDock" aria-label="God console">
+      <div className="chaosHeader">
+        <span className="chaosTitle">🔥 GOD OF CHAOS</span>
+        <span className="chaosSubtitle">unleash havoc on the village</span>
+      </div>
+
+      <div className="chaosButtons">
+        {tools.map((tool) => {
+          const isPending = pendingChaosAction === tool.action;
+          const onCooldown = tool.remaining_ticks > 0;
+          const disabled = onCooldown || pendingChaosAction !== null || !snapshot;
+          return (
+            <button
+              key={tool.action}
+              type="button"
+              className={`chaosButton ${onCooldown ? "onCooldown" : ""}`}
+              disabled={disabled}
+              title={
+                onCooldown
+                  ? `${tool.label}: ready in ${tool.remaining_ticks} ticks`
+                  : `${tool.label} (cooldown ${tool.cooldown_ticks} ticks)`
+              }
+              onClick={() => onChaosAction(tool.action)}
+            >
+              {isPending ? (
+                <LoaderCircle className="spinIcon" size={16} />
+              ) : (
+                <span className="chaosIcon">{CHAOS_ICONS[tool.action] ?? "✦"}</span>
+              )}
+              <span className="chaosLabel">{tool.label}</span>
+              {onCooldown ? (
+                <span className="chaosCooldown">{tool.remaining_ticks}</span>
+              ) : null}
+            </button>
+          );
+        })}
+      </div>
+
+      <form className="chaosCommandRow" onSubmit={onSubmitCommand}>
+        <input
+          value={godCommand}
+          onChange={(event) => onCommandChange(event.target.value)}
+          placeholder="Freeform command: 'a plague rumor spreads in the north'..."
+          disabled={isGodPending}
+        />
+        <button
+          type="submit"
+          aria-label="Run god command"
+          title="Run freeform god command"
+          disabled={!godCommand.trim() || isGodPending || isWaitingForTick}
+        >
+          {isGodPending ? <LoaderCircle className="spinIcon" size={16} /> : <Send size={15} />}
+        </button>
+      </form>
+
+      {message ? <p className="chaosMessage">{message}</p> : null}
+    </section>
+  );
+}

frontend/src/components/EventFeedPanel.tsx

@@ -0,0 +1,57 @@
+import { useEffect, useRef } from "react";
+
+import { eventIcon, severityClass } from "../eventDecor";
+import type { GameLogEventSnapshot } from "../types";
+
+type EventFeedPanelProps = {
+  events: GameLogEventSnapshot[];
+};
+
+export function EventFeedPanel({ events }: EventFeedPanelProps) {
+  const listRef = useRef<HTMLDivElement>(null);
+  const isPinnedToBottomRef = useRef(true);
+
+  useEffect(() => {
+    const list = listRef.current;
+    if (list && isPinnedToBottomRef.current) {
+      list.scrollTop = list.scrollHeight;
+    }
+  }, [events]);
+
+  return (
+    <aside className="eventFeed" aria-label="Event feed">
+      <div className="sidePanelHeader">
+        <span className="sidePanelTitle">📰 Village Chronicle</span>
+        <span className="sidePanelHint">{events.length} events</span>
+      </div>
+      <div
+        className="eventList"
+        ref={listRef}
+        onScroll={() => {
+          const list = listRef.current;
+          if (list) {
+            isPinnedToBottomRef.current =
+              list.scrollHeight - list.scrollTop - list.clientHeight < 24;
+          }
+        }}
+      >
+        {events.length === 0 ? (
+          <p className="eventEmpty">The village is quiet... for now.</p>
+        ) : (
+          events.map((event, index) => (
+            <div
+              className={`eventLine ${severityClass(event.severity)}`}
+              key={`${event.tick}-${index}-${event.type}`}
+            >
+              <span className="eventTick">{event.tick}</span>
+              <span className="eventIcon" aria-hidden="true">
+                {eventIcon(event.type)}
+              </span>
+              <span className="eventText">{event.summary}</span>
+            </div>
+          ))
+        )}
+      </div>
+    </aside>
+  );
+}

frontend/src/components/GameOverOverlay.tsx

@@ -0,0 +1,122 @@
+import { useMemo, useState } from "react";
+
+import { eventIcon, severityClass } from "../eventDecor";
+import type { GameLogEventSnapshot, WorldSnapshot } from "../types";
+
+type GameOverOverlayProps = {
+  snapshot: WorldSnapshot;
+  events: GameLogEventSnapshot[];
+};
+
+const RESULT_COPY: Record<string, { title: string; subtitle: string; tone: string }> = {
+  win_population: {
+    title: "🏆 THE VILLAGE PREVAILS",
+    subtitle: "The Overseer raised a thriving generation — population goal reached.",
+    tone: "win",
+  },
+  win_survival: {
+    title: "🏆 THE VILLAGE ENDURES",
+    subtitle: "Through famine and fangs, the village outlasted the chaos.",
+    tone: "win",
+  },
+  lose: {
+    title: "💀 THE VILLAGE HAS FALLEN",
+    subtitle: "Chaos reigns. No villager drew breath at the end.",
+    tone: "lose",
+  },
+};
+
+export function GameOverOverlay({ snapshot, events }: GameOverOverlayProps) {
+  const [isDismissed, setIsDismissed] = useState(false);
+  const status = snapshot.simulation.game_status ?? "running";
+  const copy = RESULT_COPY[status];
+
+  const stats = snapshot.simulation.stats;
+  const scoreboard = snapshot.simulation.scoreboard;
+  const totalDeaths = Object.values(stats?.deaths_by_cause ?? {}).reduce(
+    (sum, count) => sum + count,
+    0,
+  );
+  const betrayals = useMemo(
+    () => events.filter((event) => event.type === "steal" || event.type === "npc_attack").length,
+    [events],
+  );
+  const storyEvents = useMemo(
+    () =>
+      events
+        .filter((event) =>
+          ["npc_born", "npc_died", "build_completed", "house_destroyed", "beast_killed", "chaos_event", "game_over"].includes(
+            event.type,
+          ),
+        )
+        .slice(-14),
+    [events],
+  );
+
+  if (!copy || isDismissed) {
+    return null;
+  }
+
+  return (
+    <div className={`gameOverOverlay gameOver-${copy.tone}`} role="dialog" aria-label="Game over">
+      <div className="gameOverCard">
+        <h1>{copy.title}</h1>
+        <p className="gameOverSubtitle">{copy.subtitle}</p>
+
+        <div className="gameOverScore">
+          <span className="scoreOverseerText">🧠 Overseer {scoreboard?.overseer ?? 0}</span>
+          <span className="scoreDivider">—</span>
+          <span className="scoreChaosText">{scoreboard?.chaos ?? 0} Chaos 🔥</span>
+        </div>
+
+        <div className="gameOverStats">
+          <Stat icon="👶" label="Births" value={stats?.total_births ?? 0} />
+          <Stat icon="💀" label="Deaths" value={totalDeaths} />
+          <Stat icon="🏠" label="Houses built" value={stats?.houses_built ?? 0} />
+          <Stat icon="⚔️" label="Beasts slain" value={stats?.beasts_killed ?? 0} />
+          <Stat icon="🕵️" label="Betrayals" value={betrayals} />
+          <Stat icon="👥" label="Peak population" value={snapshot.simulation.peak_population ?? 0} />
+        </div>
+
+        {Object.keys(stats?.deaths_by_cause ?? {}).length > 0 ? (
+          <p className="gameOverCauses">
+            Causes of death:{" "}
+            {Object.entries(stats?.deaths_by_cause ?? {})
+              .map(([cause, count]) => `${cause.replaceAll("_", " ")} ×${count}`)
+              .join(", ")}
+          </p>
+        ) : null}
+
+        {storyEvents.length > 0 ? (
+          <div className="gameOverStory">
+            <h2>The village's story</h2>
+            <div className="gameOverStoryList">
+              {storyEvents.map((event, index) => (
+                <div className={`eventLine ${severityClass(event.severity)}`} key={index}>
+                  <span className="eventTick">{event.tick}</span>
+                  <span className="eventIcon">{eventIcon(event.type)}</span>
+                  <span className="eventText">{event.summary}</span>
+                </div>
+              ))}
+            </div>
+          </div>
+        ) : null}
+
+        <button type="button" className="gameOverDismiss" onClick={() => setIsDismissed(true)}>
+          Inspect the aftermath
+        </button>
+      </div>
+    </div>
+  );
+}
+
+function Stat({ icon, label, value }: { icon: string; label: string; value: number }) {
+  return (
+    <div className="gameOverStat">
+      <span className="gameOverStatValue">
+        {icon} {value}
+      </span>
+      <span className="gameOverStatLabel">{label}</span>
+    </div>
+  );
+}

frontend/src/components/GodConsolePanel.tsx

@@ -1,50 +0,0 @@
-import { LoaderCircle, Send, Sparkles } from "lucide-react";
-import type { FormEvent } from "react";
-
-type GodConsolePanelProps = {
-  command: string;
-  isGodPending: boolean;
-  isWaitingForTick: boolean;
-  message: string | null;
-  onCommandChange: (command: string) => void;
-  onSubmit: (event: FormEvent<HTMLFormElement>) => void;
-};
-
-export function GodConsolePanel({
-  command,
-  isGodPending,
-  isWaitingForTick,
-  message,
-  onCommandChange,
-  onSubmit,
-}: GodConsolePanelProps) {
-  return (
-    <form className="godConsole" aria-label="God console" onSubmit={onSubmit}>
-      <div className="consoleHeader">
-        <Sparkles size={15} aria-hidden="true" />
-        <span>God Console</span>
-      </div>
-      <div className="consoleRow">
-        <input
-          value={command}
-          onChange={(event) => onCommandChange(event.target.value)}
-          placeholder="Ada wants to kill everyone"
-          disabled={isGodPending}
-        />
-        <button
-          type="submit"
-          aria-label="Run god command"
-          title="Run god command"
-          disabled={!command.trim() || isGodPending || isWaitingForTick}
-        >
-          {isGodPending ? (
-            <LoaderCircle className="spinIcon" size={17} />
-          ) : (
-            <Send size={16} />
-          )}
-        </button>
-      </div>
-      {message ? <p>{message}</p> : null}
-    </form>
-  );
-}

frontend/src/components/OverseerPanel.tsx

@@ -0,0 +1,77 @@
+import { useEffect, useRef } from "react";
+
+import type { OverseerLogEntry } from "../hooks/useWorldSimulation";
+import type { WorldSnapshot } from "../types";
+
+type OverseerPanelProps = {
+  snapshot: WorldSnapshot | null;
+  log: OverseerLogEntry[];
+};
+
+export function OverseerPanel({ snapshot, log }: OverseerPanelProps) {
+  const overseer = snapshot?.simulation.overseer;
+  const mode = overseer?.mode ?? "off";
+  const listRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const list = listRef.current;
+    if (list) {
+      list.scrollTop = list.scrollHeight;
+    }
+  }, [log]);
+
+  return (
+    <aside className="overseerPanel" aria-label="Overseer log">
+      <div className="sidePanelHeader">
+        <span className="sidePanelTitle">🧠 Overseer</span>
+        <span className={`overseerMode overseerMode-${mode}`}>{mode.toUpperCase()}</span>
+      </div>
+
+      {overseer?.priority_alert ? (
+        <div className="overseerAlert">⚠ {overseer.priority_alert}</div>
+      ) : null}
+
+      <div className="overseerLog" ref={listRef}>
+        {log.length === 0 ? (
+          <p className="eventEmpty">
+            {mode === "off"
+              ? "The Overseer is dormant."
+              : "Awaiting the Overseer's first assessment..."}
+          </p>
+        ) : (
+          log.map((entry) => <OverseerLogItem key={entry.tick} entry={entry} />)
+        )}
+      </div>
+    </aside>
+  );
+}
+
+function OverseerLogItem({ entry }: { entry: OverseerLogEntry }) {
+  return (
+    <div className="overseerEntry">
+      <div className="overseerEntryHead">
+        <span className="overseerEntryTick">T{entry.tick}</span>
+        {entry.priorityAlert ? (
+          <span className="overseerEntryAlert">{entry.priorityAlert}</span>
+        ) : null}
+      </div>
+      {entry.thoughts ? <p className="overseerThought">{entry.thoughts}</p> : null}
+      {entry.directives.length > 0 ? (
+        <ul className="overseerDirectives">
+          {entry.directives.map((directive, index) => (
+            <li
+              key={`${entry.tick}-${index}`}
+              className={directive.applied === false ? "directiveSkipped" : ""}
+            >
+              <span className="directiveTarget">{directive.npc_id ?? "?"}</span>
+              <span className="directiveText">{directive.directive ?? ""}</span>
+              {directive.applied === false ? (
+                <span className="directiveBadge">advisory</span>
+              ) : null}
+            </li>
+          ))}
+        </ul>
+      ) : null}
+    </div>
+  );
+}

frontend/src/components/ScoreboardHeader.tsx

@@ -0,0 +1,96 @@
+import type { WorldSnapshot } from "../types";
+import { formatModelStatus, modelStatusClass, shortModelLabel } from "./modelStatus";
+import { TooltipLabel } from "./TooltipLabel";
+
+const WIN_POPULATION = 12;
+const WIN_SURVIVAL_TICKS = 600;
+
+type ScoreboardHeaderProps = {
+  snapshot: WorldSnapshot | null;
+  isGodPending: boolean;
+  isWaitingForTick: boolean;
+};
+
+export function ScoreboardHeader({
+  snapshot,
+  isGodPending,
+  isWaitingForTick,
+}: ScoreboardHeaderProps) {
+  const simulation = snapshot?.simulation;
+  const overseerScore = simulation?.scoreboard?.overseer ?? 0;
+  const chaosScore = simulation?.scoreboard?.chaos ?? 0;
+  const population = simulation?.population ?? snapshot?.entities.length ?? 0;
+  const tick = snapshot?.tick ?? 0;
+  const populationProgress = Math.min(1, population / WIN_POPULATION);
+  const survivalProgress = Math.min(1, tick / WIN_SURVIVAL_TICKS);
+  const famineUntil = simulation?.famine_until ?? -1;
+  const isFamineActive = famineUntil >= 0 && tick <= famineUntil;
+  const activityLabel = isGodPending
+    ? "god console..."
+    : isWaitingForTick
+      ? "simulating..."
+      : (simulation?.last_tick_source ?? "idle");
+
+  return (
+    <header className="scoreboard" aria-label="Simulation status">
+      <div className="scoreDuel">
+        <div className="scoreSide scoreOverseer">
+          <span className="scoreName">🧠 OVERSEER</span>
+          <span className="scoreValue">{overseerScore}</span>
+        </div>
+        <div className="scoreVs">vs</div>
+        <div className="scoreSide scoreChaos">
+          <span className="scoreValue">{chaosScore}</span>
+          <span className="scoreName">CHAOS 🔥</span>
+        </div>
+      </div>
+
+      <div className="scoreMeta">
+        <span className="scoreTick" title="Current simulation tick">
+          ⏱ Tick {tick}
+        </span>
+        {isFamineActive ? (
+          <span className="famineBadge" title={`Food nodes halved until tick ${famineUntil}`}>
+            🌾 FAMINE ({famineUntil - tick})
+          </span>
+        ) : null}
+        <span className="scoreActivity">{activityLabel}</span>
+      </div>
+
+      <div className="winProgress" title={`Win: ${WIN_POPULATION} villagers, or survive ${WIN_SURVIVAL_TICKS} ticks`}>
+        <div className="winRow">
+          <span className="winLabel">👥 Population {population}/{WIN_POPULATION}</span>
+          <div className="winBar">
+            <div
+              className="winFill winFillPopulation"
+              style={{ width: `${populationProgress * 100}%` }}
+            />
+          </div>
+        </div>
+        <div className="winRow">
+          <span className="winLabel">🛡 Survival {Math.min(tick, WIN_SURVIVAL_TICKS)}/{WIN_SURVIVAL_TICKS}</span>
+          <div className="winBar">
+            <div
+              className="winFill winFillSurvival"
+              style={{ width: `${survivalProgress * 100}%` }}
+            />
+          </div>
+        </div>
+      </div>
+
+      {(simulation?.models ?? []).length > 0 ? (
+        <div className="modelPills">
+          {(simulation?.models ?? []).map((model) => (
+            <TooltipLabel
+              key={model.id}
+              className={`modelPill ${modelStatusClass(model.status)}`}
+              value={`${model.label}: ${model.model ?? "unknown model"} - ${formatModelStatus(model.status)}`}
+            >
+              {`${shortModelLabel(model.label)} ${formatModelStatus(model.status)}`}
+            </TooltipLabel>
+          ))}
+        </div>
+      ) : null}
+    </header>
+  );
+}

frontend/src/components/StatusBar.tsx

@@ -1,50 +0,0 @@
-import { Activity } from "lucide-react";
-
-import type { WorldSnapshot } from "../types";
-import { TooltipLabel } from "./TooltipLabel";
-import { formatModelStatus, modelStatusClass, shortModelLabel } from "./modelStatus";
-
-type StatusBarProps = {
-  snapshot: WorldSnapshot | null;
-  isGodPending: boolean;
-  isWaitingForTick: boolean;
-};
-
-export function StatusBar({ snapshot, isGodPending, isWaitingForTick }: StatusBarProps) {
-  const isServerTickPending = snapshot?.simulation.tick_in_progress ?? false;
-  const pendingTick = snapshot?.simulation.pending_tick;
-  const tickLabel = snapshot
-    ? isServerTickPending && pendingTick
-      ? `Tick ${snapshot.tick} -> ${pendingTick}`
-      : `Tick ${snapshot.tick}`
-    : "Connecting";
-  const npcCountLabel = snapshot ? `${snapshot.entities.length} NPCs` : "0 NPCs";
-  const simulatorLabel = isGodPending
-    ? "God console"
-    : isWaitingForTick
-      ? "Waiting"
-      : (snapshot?.simulation.last_tick_source ?? "idle");
-
-  return (
-    <div className="topBar" aria-label="Simulation status">
-      <div className="brand">
-        <Activity size={18} aria-hidden="true" />
-        <span>God Simulator</span>
-      </div>
-      <div className="statusPills">
-        <TooltipLabel className="statusPill" value={tickLabel} />
-        <TooltipLabel className="statusPill" value={npcCountLabel} />
-        <TooltipLabel className="statusPill" value={simulatorLabel} />
-        {(snapshot?.simulation.models ?? []).map((model) => (
-          <TooltipLabel
-            key={model.id}
-            className={`statusPill modelStatus ${modelStatusClass(model.status)}`}
-            value={`${model.label}: ${model.model ?? "unknown model"} - ${formatModelStatus(model.status)}`}
-          >
-            {`${shortModelLabel(model.label)} ${formatModelStatus(model.status)}`}
-          </TooltipLabel>
-        ))}
-      </div>
-    </div>
-  );
-}

frontend/src/eventDecor.ts

@@ -0,0 +1,47 @@
+import type { GameLogEventSnapshot } from "./types";
+
+const EVENT_ICONS: Record<string, string> = {
+  beast_spawned: "🐺",
+  beast_attack: "🐺",
+  beast_killed: "⚔️",
+  beast_retreat: "🏃",
+  npc_attack: "🗡️",
+  npc_died: "💀",
+  npc_born: "👶",
+  build_started: "🚧",
+  build_completed: "🏠",
+  house_damaged: "🏚️",
+  house_destroyed: "💥",
+  gather: "🌾",
+  transfer: "🤝",
+  steal: "🕵️",
+  heal: "💊",
+  consume: "🍖",
+  help_request: "🆘",
+  directive_issued: "📜",
+  directive_completed: "✅",
+  chaos_event: "🔥",
+  overseer_skipped: "🌫️",
+  game_over: "🏁",
+};
+
+export function eventIcon(type: string): string {
+  return EVENT_ICONS[type] ?? "•";
+}
+
+export function severityClass(severity: string): string {
+  switch (severity) {
+    case "good":
+      return "severityGood";
+    case "warning":
+      return "severityWarning";
+    case "danger":
+      return "severityDanger";
+    default:
+      return "severityNeutral";
+  }
+}
+
+export function isMajorEvent(event: GameLogEventSnapshot): boolean {
+  return event.severity !== "neutral" || event.type === "build_started";
+}

frontend/src/hooks/useWorldSimulation.ts

@@ -1,8 +1,25 @@
 import type { FormEvent } from "react";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 
-import { ApiResponseError, fetchWorldSnapshot, sendGodCommand, tickWorld } from "../api";
-import type { WorldSnapshot } from "../types";
+import {
+  ApiResponseError,
+  fetchWorldSnapshot,
+  sendChaosAction,
+  sendGodCommand,
+  tickWorld,
+} from "../api";
+import type {
+  GameLogEventSnapshot,
+  OverseerDirectiveSnapshot,
+  WorldSnapshot,
+} from "../types";
+
+export type OverseerLogEntry = {
+  tick: number;
+  thoughts: string | null;
+  priorityAlert: string | null;
+  directives: OverseerDirectiveSnapshot[];
+};
 
 export function useWorldSimulation() {
   const [snapshot, setSnapshot] = useState<WorldSnapshot | null>(null);
@@ -13,7 +30,11 @@ export function useWorldSimulation() {
   const [godMessage, setGodMessage] = useState<string | null>(null);
   const [error, setError] = useState<string | null>(null);
   const [selectedId, setSelectedId] = useState<string | null>(null);
+  const [pendingChaosAction, setPendingChaosAction] = useState<string | null>(null);
+  const [chaosMessage, setChaosMessage] = useState<string | null>(null);
   const isTickingRef = useRef(false);
+  const eventHistory = useEventHistory(snapshot);
+  const overseerLog = useOverseerLog(snapshot);
 
   const refresh = useCallback(async () => {
     const nextSnapshot = await fetchWorldSnapshot();
@@ -76,6 +97,42 @@ export function useWorldSimulation() {
     [godCommand, isGodPending, isWaitingForTick],
   );
 
+  const runChaosAction = useCallback(
+    async (action: string) => {
+      if (pendingChaosAction) {
+        return;
+      }
+      setPendingChaosAction(action);
+      setChaosMessage(null);
+      try {
+        for (let attempt = 0; ; attempt += 1) {
+          try {
+            const result = await sendChaosAction(action);
+            setSnapshot(result.snapshot);
+            setChaosMessage(result.summary);
+            return;
+          } catch (nextError) {
+            const message =
+              nextError instanceof Error ? nextError.message : "Chaos action failed";
+            const isTickBusy =
+              nextError instanceof ApiResponseError &&
+              nextError.status === 409 &&
+              message.includes("tick is running");
+            if (isTickBusy && attempt < 20) {
+              await delay(500);
+              continue;
+            }
+            setChaosMessage(message);
+            return;
+          }
+        }
+      } finally {
+        setPendingChaosAction(null);
+      }
+    },
+    [pendingChaosAction],
+  );
+
   useInitialSnapshot(setSnapshot, setSelectedId, setError);
   useSelectedEntityFallback(snapshot, setSelectedId);
   useServerTickPolling(isServerTickPending, refresh, setError);
@@ -97,24 +154,96 @@ export function useWorldSimulation() {
   );
 
   return {
+    chaosMessage,
     error,
+    eventHistory,
     godCommand,
     godMessage,
     isAutoTicking,
     isGodPending,
     isWaitingForTick,
     isWorldCommandPending,
+    overseerLog,
+    pendingChaosAction,
     selectedEntity,
     selectedId,
     setGodCommand,
     setIsAutoTicking,
     setSelectedId,
     snapshot,
+    runChaosAction,
     runGodCommand,
     step,
   };
 }
 
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    window.setTimeout(resolve, ms);
+  });
+}
+
+function useEventHistory(snapshot: WorldSnapshot | null): GameLogEventSnapshot[] {
+  const seenKeysRef = useRef<Set<string>>(new Set());
+  const [history, setHistory] = useState<GameLogEventSnapshot[]>([]);
+
+  useEffect(() => {
+    const log = snapshot?.event_log ?? [];
+    if (log.length === 0) {
+      return;
+    }
+    const fresh: GameLogEventSnapshot[] = [];
+    for (const event of log) {
+      const key = [
+        event.tick,
+        event.type,
+        event.actor_id ?? "",
+        event.target_id ?? "",
+        event.summary,
+      ].join("|");
+      if (!seenKeysRef.current.has(key)) {
+        seenKeysRef.current.add(key);
+        fresh.push(event);
+      }
+    }
+    if (fresh.length > 0) {
+      setHistory((current) => [...current, ...fresh].slice(-500));
+    }
+  }, [snapshot]);
+
+  return history;
+}
+
+function useOverseerLog(snapshot: WorldSnapshot | null): OverseerLogEntry[] {
+  const seenTicksRef = useRef<Set<number>>(new Set());
+  const [log, setLog] = useState<OverseerLogEntry[]>([]);
+
+  useEffect(() => {
+    const overseer = snapshot?.simulation.overseer;
+    if (!overseer || overseer.last_tick === null) {
+      return;
+    }
+    const lastTick = overseer.last_tick;
+    if (seenTicksRef.current.has(lastTick)) {
+      return;
+    }
+    seenTicksRef.current.add(lastTick);
+    setLog((current) =>
+      [
+        ...current,
+        {
+          tick: lastTick,
+          thoughts: overseer.thoughts,
+          priorityAlert: overseer.priority_alert,
+          directives: overseer.directives,
+        },
+      ].slice(-40),
+    );
+  }, [snapshot]);
+
+  return log;
+}
+
 function useInitialSnapshot(
   setSnapshot: (snapshot: WorldSnapshot) => void,
   setSelectedId: (id: string | null) => void,

frontend/src/scene/NpcLabelButton.tsx

@@ -1,6 +1,5 @@
-import { useLayoutEffect, useRef, useState } from "react";
-
 import type { EntitySnapshot } from "../types";
+import { roleMeta } from "./characterUtils";
 
 type NpcLabelButtonProps = {
   entity: EntitySnapshot;
@@ -8,64 +7,56 @@ type NpcLabelButtonProps = {
 };
 
 export function NpcLabelButton({ entity, onSelect }: NpcLabelButtonProps) {
-  const buttonRef = useRef<HTMLButtonElement>(null);
-  const labelMeasureRef = useRef<HTMLSpanElement>(null);
-  const intentionMeasureRef = useRef<HTMLSpanElement>(null);
-  const [isCollapsed, setIsCollapsed] = useState(false);
-
-  useLayoutEffect(() => {
-    const buttonElement = buttonRef.current;
-    const observedElements = [
-      buttonElement,
-      labelMeasureRef.current,
-      intentionMeasureRef.current,
-    ].filter((element): element is HTMLElement => element !== null);
-    if (!buttonElement || observedElements.length < 3) {
-      return undefined;
-    }
-
-    const updateCollapsedState = () => {
-      const styles = window.getComputedStyle(buttonElement);
-      const horizontalPadding =
-        Number.parseFloat(styles.paddingLeft) + Number.parseFloat(styles.paddingRight);
-      const availableWidth = buttonElement.clientWidth - horizontalPadding;
-      const fullLabelWidth = labelMeasureRef.current?.getBoundingClientRect().width ?? 0;
-      const fullIntentionWidth =
-        intentionMeasureRef.current?.getBoundingClientRect().width ?? 0;
-
-      setIsCollapsed(Math.max(fullLabelWidth, fullIntentionWidth) > availableWidth + 1);
-    };
-
-    updateCollapsedState();
-
-    const resizeObserver = new ResizeObserver(updateCollapsedState);
-    for (const element of observedElements) {
-      resizeObserver.observe(element);
-    }
-    window.addEventListener("resize", updateCollapsedState);
-
-    return () => {
-      resizeObserver.disconnect();
-      window.removeEventListener("resize", updateCollapsedState);
-    };
-  }, [entity.label, entity.state.intention]);
+  const meta = roleMeta(entity.role);
+  const isAlive = entity.state.is_alive;
+  const health = Math.max(0, entity.state.health);
+  const maxHealth = Math.max(1, entity.state.max_health);
+  const healthRatio = Math.min(1, health / maxHealth);
+  const age = entity.state.age;
+  const maxAge = entity.state.max_age;
+  const ageRatio =
+    age !== undefined && maxAge !== undefined && maxAge > 0
+      ? Math.min(1, age / maxAge)
+      : null;
 
   return (
     <button
-      ref={buttonRef}
       type="button"
+      className={`npcCard ${isAlive ? "" : "npcCardDead"}`}
+      style={{ borderColor: meta.color }}
       onClick={onSelect}
       aria-label={`Select ${entity.label}`}
-      data-tooltip={isCollapsed ? `${entity.label}: ${entity.state.intention}` : undefined}
+      title={`${entity.label} — ${meta.label}, ${entity.state.intention}`}
     >
-      <strong>{entity.label}</strong>
-      <span>{entity.state.intention}</span>
-      <strong className="npcLabelMeasure" ref={labelMeasureRef} aria-hidden="true">
-        {entity.label}
-      </strong>
-      <span className="npcLabelMeasure" ref={intentionMeasureRef} aria-hidden="true">
-        {entity.state.intention}
+      <span className="npcCardName">
+        <span className="npcCardIcon" style={{ color: meta.color }} aria-hidden="true">
+          {isAlive ? meta.icon : "💀"}
+        </span>
+        <strong>{entity.label}</strong>
+      </span>
+      <span className="npcCardRole" style={{ color: meta.color }}>
+        {meta.label}
       </span>
+      {isAlive ? (
+        <>
+          <span className="npcBar npcHpBar" aria-hidden="true">
+            <span
+              className="npcBarFill"
+              style={{
+                width: `${healthRatio * 100}%`,
+                background: healthRatio > 0.5 ? "#6fd96a" : healthRatio > 0.25 ? "#f0c34e" : "#f06a4e",
+              }}
+            />
+          </span>
+          {ageRatio !== null ? (
+            <span className="npcBar npcAgeBar" aria-hidden="true" title={`Age ${age}/${maxAge}`}>
+              <span className="npcBarFill npcAgeFill" style={{ width: `${ageRatio * 100}%` }} />
+            </span>
+          ) : null}
+        </>
+      ) : (
+        <span className="npcCardRole">dead</span>
+      )}
     </button>
   );
 }

frontend/src/scene/WorldView.tsx

@@ -1,4 +1,6 @@
-import type { BeastSnapshot, ResourceNodeSnapshot, WorldSnapshot } from "../types";
+import { Html } from "@react-three/drei";
+
+import type { BeastSnapshot, HouseSnapshot, ResourceNodeSnapshot, WorldSnapshot } from "../types";
 import { NpcActor } from "./NpcActor";
 
 type WorldViewProps = {
@@ -30,6 +32,9 @@ export function WorldView({ snapshot, selectedId, onSelectEntity }: WorldViewPro
           onSelect={() => onSelectEntity(entity.id)}
         />
       ))}
+      {(snapshot.houses ?? []).map((house) => (
+        <HouseBuilding key={house.id} house={house} />
+      ))}
       {(snapshot.resource_nodes ?? []).map((node) => (
         <ResourceMarker key={node.id} node={node} />
       ))}
@@ -40,6 +45,88 @@ export function WorldView({ snapshot, selectedId, onSelectEntity }: WorldViewPro
   );
 }
 
+function HouseBuilding({ house }: { house: HouseSnapshot }) {
+  const isComplete = house.state === "completed";
+  const isDamaged = house.hp < house.max_hp;
+  const buildRatio = Math.min(1, house.build_progress / 10);
+  const hpRatio = house.max_hp > 0 ? Math.max(0, house.hp / house.max_hp) : 0;
+  const occupancy = `${house.occupant_ids.length}/${house.capacity}`;
+
+  return (
+    <group position={[house.position.x, house.position.y, house.position.z]}>
+      {isComplete ? (
+        <>
+          <mesh castShadow receiveShadow position={[0, 1.0, 0]}>
+            <boxGeometry args={[3.2, 2.0, 3.2]} />
+            <meshStandardMaterial color="#a8794f" roughness={0.85} />
+          </mesh>
+          <mesh castShadow position={[0, 2.55, 0]} rotation={[0, Math.PI / 4, 0]}>
+            <coneGeometry args={[2.7, 1.3, 4]} />
+            <meshStandardMaterial color="#7e4a33" roughness={0.8} />
+          </mesh>
+          <mesh position={[0, 0.6, 1.61]}>
+            <boxGeometry args={[0.7, 1.2, 0.06]} />
+            <meshStandardMaterial color="#54392a" roughness={0.9} />
+          </mesh>
+        </>
+      ) : (
+        <>
+          {/* Frame rising with build progress. */}
+          <mesh castShadow receiveShadow position={[0, Math.max(0.15, buildRatio), 0]}>
+            <boxGeometry args={[3.2, Math.max(0.3, buildRatio * 2.0), 3.2]} />
+            <meshStandardMaterial color="#c9a06a" roughness={0.9} transparent opacity={0.85} />
+          </mesh>
+          {[-1.45, 1.45].flatMap((x) =>
+            [-1.45, 1.45].map((z) => (
+              <mesh key={`${x}:${z}`} castShadow position={[x, 1.1, z]}>
+                <boxGeometry args={[0.14, 2.2, 0.14]} />
+                <meshStandardMaterial color="#8a6437" roughness={0.9} />
+              </mesh>
+            )),
+          )}
+        </>
+      )}
+
+      <mesh rotation={[-Math.PI / 2, 0, 0]} position={[0, 0.035, 0]}>
+        <ringGeometry args={[2.2, 2.55, 32]} />
+        <meshBasicMaterial
+          color={isComplete ? "#f2d9a0" : "#ffd07a"}
+          transparent
+          opacity={0.38}
+        />
+      </mesh>
+
+      <Html center distanceFactor={26} position={[0, isComplete ? 3.7 : 2.9, 0]} zIndexRange={[7, 0]}>
+        <div className={`houseTag ${isComplete ? "" : "houseTagBuilding"}`}>
+          <span className="houseTagTitle">
+            {isComplete ? "🏠" : "🚧"} {isComplete ? `Home ${occupancy}` : "Building"}
+          </span>
+          {isComplete ? (
+            isDamaged ? (
+              <span className="npcBar houseHpBar">
+                <span
+                  className="npcBarFill"
+                  style={{
+                    width: `${hpRatio * 100}%`,
+                    background: hpRatio > 0.5 ? "#6fd96a" : hpRatio > 0.25 ? "#f0c34e" : "#f06a4e",
+                  }}
+                />
+              </span>
+            ) : null
+          ) : (
+            <span className="npcBar houseHpBar">
+              <span
+                className="npcBarFill"
+                style={{ width: `${buildRatio * 100}%`, background: "#ffd07a" }}
+              />
+            </span>
+          )}
+        </div>
+      </Html>
+    </group>
+  );
+}
+
 type TerrainProps = {
   width: number;
   depth: number;
@@ -69,6 +156,11 @@ function ResourceMarker({ node }: { node: ResourceNodeSnapshot }) {
         <ringGeometry args={[0.55, 0.72, 20]} />
         <meshBasicMaterial color={color} transparent opacity={0.45} />
       </mesh>
+      <Html center distanceFactor={30} position={[0, height + 0.85, 0]} zIndexRange={[6, 0]}>
+        <div className="resourceTag">
+          {resourceIcon(node.type)} {node.amount}
+        </div>
+      </Html>
     </group>
   );
 }
@@ -76,6 +168,7 @@ function ResourceMarker({ node }: { node: ResourceNodeSnapshot }) {
 function BeastMarker({ beast }: { beast: BeastSnapshot }) {
   const isDead = beast.state === "dead";
   const color = isDead ? "#3d3532" : "#8f1f17";
+  const hpRatio = Math.max(0, Math.min(1, beast.health / Math.max(1, beast.max_health)));
 
   return (
     <group position={[beast.position.x, beast.position.y, beast.position.z]}>
@@ -91,6 +184,19 @@ function BeastMarker({ beast }: { beast: BeastSnapshot }) {
         <ringGeometry args={[0.85, 1.12, 28]} />
         <meshBasicMaterial color="#ffb09c" transparent opacity={isDead ? 0.18 : 0.58} />
       </mesh>
+      {!isDead ? (
+        <Html center distanceFactor={28} position={[0, 2.2, 0]} zIndexRange={[7, 0]}>
+          <div className="beastTag">
+            <span className="beastTagTitle">🐺 {beast.state}</span>
+            <span className="npcBar beastHpBar">
+              <span
+                className="npcBarFill"
+                style={{ width: `${hpRatio * 100}%`, background: "#f06a4e" }}
+              />
+            </span>
+          </div>
+        </Html>
+      ) : null}
     </group>
   );
 }
@@ -110,3 +216,19 @@ function resourceColor(type: string) {
   }
   return "#d9d2aa";
 }
+
+function resourceIcon(type: string) {
+  if (type === "food") {
+    return "🍎";
+  }
+  if (type === "herbs") {
+    return "🌿";
+  }
+  if (type === "wood") {
+    return "🪵";
+  }
+  if (type === "weapon") {
+    return "⚔️";
+  }
+  return "✦";
+}

frontend/src/scene/characterUtils.ts

@@ -7,6 +7,26 @@ export type RolePalette = {
   hair: string;
 };
 
+export type RoleMeta = {
+  icon: string;
+  label: string;
+  color: string;
+};
+
+export function roleMeta(role: string): RoleMeta {
+  switch (role) {
+    case "guard":
+      return { icon: "🗡️", label: "Guard", color: "#e2675a" };
+    case "builder":
+      return { icon: "🔨", label: "Builder", color: "#5b96f0" };
+    case "forager":
+    case "gatherer":
+      return { icon: "🌾", label: "Gatherer", color: "#6fc46a" };
+    default:
+      return { icon: "👤", label: role || "Villager", color: "#d9b35a" };
+  }
+}
+
 export function rolePalette(role: string): RolePalette {
   switch (role) {
     case "builder":
@@ -19,6 +39,7 @@ export function rolePalette(role: string): RolePalette {
         hair: "#4c3a2f",
       };
     case "forager":
+    case "gatherer":
       return {
         coat: "#5faa59",
         front: "#91d67b",

frontend/src/styles.css

@@ -39,87 +39,608 @@ button {
   height: 100% !important;
 }
 
-.topBar {
+/* ---------------------------------------------------------------- panels */
+
+.scoreboard,
+.overseerPanel,
+.eventFeed,
+.chaosDock,
+.controls,
+.agentPanel,
+.errorToast,
+.busyToast {
+  border: 1px solid rgb(255 255 255 / 18%);
+  background: rgb(18 28 23 / 80%);
+  box-shadow: 0 18px 60px rgb(0 0 0 / 22%);
+  backdrop-filter: blur(14px);
+}
+
+/* ------------------------------------------------------------ scoreboard */
+
+.scoreboard {
   position: absolute;
   top: 14px;
-  left: 14px;
-  right: 14px;
+  left: 50%;
   z-index: 60;
+  width: min(460px, calc(100vw - 28px));
+  display: grid;
+  gap: 8px;
+  padding: 10px 14px 12px;
+  border-radius: 10px;
+  transform: translateX(-50%);
+}
+
+.scoreDuel {
+  display: grid;
+  grid-template-columns: 1fr auto 1fr;
+  align-items: center;
+  gap: 10px;
+}
+
+.scoreSide {
+  display: flex;
+  align-items: baseline;
+  gap: 10px;
+}
+
+.scoreOverseer {
+  justify-content: flex-start;
+}
+
+.scoreChaos {
+  justify-content: flex-end;
+}
+
+.scoreName {
+  font-size: 13px;
+  font-weight: 800;
+  letter-spacing: 0.06em;
+}
+
+.scoreOverseer .scoreName {
+  color: #9fd1ff;
+}
+
+.scoreChaos .scoreName {
+  color: #ffab8a;
+}
+
+.scoreValue {
+  font-size: 24px;
+  font-weight: 800;
+  line-height: 1;
+}
+
+.scoreOverseer .scoreValue {
+  color: #cfe7ff;
+}
+
+.scoreChaos .scoreValue {
+  color: #ffd2c2;
+}
+
+.scoreVs {
+  color: rgb(245 247 240 / 55%);
+  font-size: 12px;
+  font-weight: 700;
+  text-transform: uppercase;
+}
+
+.scoreMeta {
+  display: flex;
+  justify-content: space-between;
+  gap: 10px;
+  color: rgb(245 247 240 / 78%);
+  font-size: 12px;
+}
+
+.scoreActivity {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  color: #c7e6bd;
+}
+
+.famineBadge {
+  padding: 2px 8px;
+  border: 1px solid rgb(240 195 78 / 50%);
+  border-radius: 5px;
+  background: rgb(240 195 78 / 14%);
+  color: #ffeebc;
+  font-size: 11px;
+  font-weight: 800;
+  letter-spacing: 0.04em;
+  animation: faminePulse 1.6s ease-in-out infinite;
+}
+
+@keyframes faminePulse {
+  0%,
+  100% {
+    opacity: 1;
+  }
+
+  50% {
+    opacity: 0.55;
+  }
+}
+
+.winProgress {
+  display: grid;
+  gap: 5px;
+}
+
+.winRow {
+  display: grid;
+  grid-template-columns: 158px 1fr;
+  align-items: center;
+  gap: 8px;
+}
+
+.winLabel {
+  font-size: 11px;
+  color: rgb(245 247 240 / 82%);
+  white-space: nowrap;
+}
+
+.winBar {
+  height: 8px;
+  border-radius: 5px;
+  background: rgb(255 255 255 / 12%);
+  overflow: hidden;
+}
+
+.winFill {
+  display: block;
+  height: 100%;
+  border-radius: 5px;
+  transition: width 320ms ease;
+}
+
+.winFillPopulation {
+  background: linear-gradient(90deg, #6fd96a, #b8f08a);
+}
+
+.winFillSurvival {
+  background: linear-gradient(90deg, #5b96f0, #9fd1ff);
+}
+
+.modelPills {
+  display: flex;
+  gap: 6px;
+  justify-content: center;
+}
+
+.modelPill {
+  padding: 4px 8px;
+  border-radius: 5px;
+  background: rgb(255 255 255 / 9%);
+  font-size: 10px;
+}
+
+.modelStatusReady {
+  color: #d9f4cf;
+}
+
+.modelStatusWarmup,
+.modelStatusUnknown {
+  color: #fff3a1;
+}
+
+.modelStatusError {
+  color: #ffd3c8;
+}
+
+.scoreboard .tooltipAnchor[data-tooltip]::before {
+  top: calc(100% + 2px);
+  bottom: auto;
+  border-top-color: transparent;
+  border-bottom-color: rgb(10 17 14 / 96%);
+}
+
+.scoreboard .tooltipAnchor[data-tooltip]::after {
+  top: calc(100% + 14px);
+  bottom: auto;
+}
+
+/* ------------------------------------------------------------ side panels */
+
+.sidePanelHeader {
   display: flex;
   align-items: center;
   justify-content: space-between;
-  gap: 12px;
-  pointer-events: none;
+  gap: 10px;
+  padding: 11px 12px 9px;
+  border-bottom: 1px solid rgb(255 255 255 / 14%);
 }
 
-.brand,
-.statusPills {
-  pointer-events: auto;
+.sidePanelTitle {
+  font-size: 13px;
+  font-weight: 800;
+  color: #fffce9;
 }
 
-.brand,
-.statusPills,
-.controls,
-.agentPanel,
-.godConsole,
-.errorToast,
-.busyToast {
-  border: 1px solid rgb(255 255 255 / 18%);
-  background: rgb(18 28 23 / 76%);
-  box-shadow: 0 18px 60px rgb(0 0 0 / 18%);
-  backdrop-filter: blur(14px);
+.sidePanelHint {
+  font-size: 11px;
+  color: rgb(245 247 240 / 55%);
 }
 
-.brand {
-  min-height: 42px;
-  display: inline-flex;
+.eventEmpty {
+  margin: 0;
+  padding: 12px;
+  color: rgb(245 247 240 / 55%);
+  font-size: 12px;
+}
+
+/* ------------------------------------------------------------- event feed */
+
+.eventFeed {
+  position: absolute;
+  top: 14px;
+  right: 14px;
+  bottom: 84px;
+  z-index: 30;
+  width: min(316px, calc(100vw - 28px));
+  display: flex;
+  flex-direction: column;
+  border-radius: 10px;
+  overflow: hidden;
+}
+
+.eventList {
+  flex: 1;
+  min-height: 0;
+  overflow-y: auto;
+  padding: 6px 8px 10px;
+  display: grid;
+  gap: 2px;
+  align-content: start;
+  scrollbar-width: thin;
+}
+
+.eventLine {
+  display: grid;
+  grid-template-columns: 34px 20px 1fr;
+  gap: 6px;
+  align-items: baseline;
+  padding: 4px 6px;
+  border-left: 3px solid transparent;
+  border-radius: 4px;
+  font-size: 12px;
+  line-height: 1.3;
+}
+
+.eventTick {
+  color: rgb(245 247 240 / 45%);
+  font-size: 10px;
+  font-variant-numeric: tabular-nums;
+  text-align: right;
+}
+
+.eventIcon {
+  text-align: center;
+}
+
+.eventText {
+  color: rgb(245 247 240 / 88%);
+  overflow-wrap: anywhere;
+}
+
+.severityGood {
+  border-left-color: #6fd96a;
+  background: rgb(111 217 106 / 8%);
+}
+
+.severityGood .eventText {
+  color: #d6f5cf;
+}
+
+.severityWarning {
+  border-left-color: #f0c34e;
+  background: rgb(240 195 78 / 8%);
+}
+
+.severityWarning .eventText {
+  color: #ffeebc;
+}
+
+.severityDanger {
+  border-left-color: #f06a4e;
+  background: rgb(240 106 78 / 10%);
+}
+
+.severityDanger .eventText {
+  color: #ffd3c8;
+}
+
+.severityNeutral {
+  border-left-color: rgb(255 255 255 / 18%);
+}
+
+/* --------------------------------------------------------- overseer panel */
+
+.overseerPanel {
+  position: absolute;
+  top: 14px;
+  left: 14px;
+  z-index: 30;
+  width: min(316px, calc(100vw - 28px));
+  max-height: calc(100svh - 420px);
+  min-height: 180px;
+  display: flex;
+  flex-direction: column;
+  border-radius: 10px;
+  overflow: hidden;
+}
+
+.overseerMode {
+  padding: 3px 8px;
+  border-radius: 5px;
+  font-size: 10px;
+  font-weight: 800;
+  letter-spacing: 0.08em;
+}
+
+.overseerMode-off {
+  background: rgb(255 255 255 / 10%);
+  color: rgb(245 247 240 / 60%);
+}
+
+.overseerMode-advisor {
+  background: rgb(240 195 78 / 18%);
+  color: #ffeebc;
+}
+
+.overseerMode-autopilot {
+  background: rgb(91 150 240 / 22%);
+  color: #cfe7ff;
+}
+
+.overseerAlert {
+  margin: 8px 10px 0;
+  padding: 7px 10px;
+  border: 1px solid rgb(240 195 78 / 45%);
+  border-radius: 7px;
+  background: rgb(240 195 78 / 12%);
+  color: #ffeebc;
+  font-size: 12px;
+  font-weight: 700;
+}
+
+.overseerLog {
+  flex: 1;
+  min-height: 0;
+  overflow-y: auto;
+  padding: 8px 10px 10px;
+  display: grid;
+  gap: 8px;
+  align-content: start;
+  scrollbar-width: thin;
+}
+
+.overseerEntry {
+  display: grid;
+  gap: 5px;
+  padding: 8px 10px;
+  border: 1px solid rgb(159 209 255 / 14%);
+  border-radius: 8px;
+  background: rgb(91 150 240 / 7%);
+}
+
+.overseerEntryHead {
+  display: flex;
   align-items: center;
-  gap: 9px;
-  padding: 0 14px;
+  gap: 8px;
+}
+
+.overseerEntryTick {
+  color: #9fd1ff;
+  font-size: 10px;
+  font-weight: 800;
+  font-variant-numeric: tabular-nums;
+}
+
+.overseerEntryAlert {
+  color: #ffeebc;
+  font-size: 10px;
+  font-weight: 700;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.overseerThought {
+  margin: 0;
+  color: rgb(245 247 240 / 90%);
+  font-size: 12px;
+  font-style: italic;
+  line-height: 1.4;
+}
+
+.overseerDirectives {
+  margin: 0;
+  padding: 0;
+  display: grid;
+  gap: 3px;
+  list-style: none;
+}
+
+.overseerDirectives li {
+  display: flex;
+  align-items: baseline;
+  gap: 6px;
+  font-size: 11px;
+  line-height: 1.35;
+}
+
+.directiveTarget {
+  flex-shrink: 0;
+  color: #9fd1ff;
+  font-weight: 700;
+  font-family: ui-monospace, monospace;
+  font-size: 10px;
+}
+
+.directiveText {
+  color: rgb(245 247 240 / 82%);
+}
+
+.directiveBadge {
+  flex-shrink: 0;
+  padding: 1px 5px;
+  border-radius: 4px;
+  background: rgb(240 195 78 / 18%);
+  color: #ffeebc;
+  font-size: 9px;
+  font-weight: 700;
+}
+
+.directiveSkipped .directiveText {
+  color: rgb(245 247 240 / 55%);
+}
+
+/* ------------------------------------------------------------- chaos dock */
+
+.chaosDock {
+  position: absolute;
+  bottom: 18px;
+  left: 50%;
+  z-index: 35;
+  width: min(520px, calc(100vw - 28px));
+  display: grid;
+  gap: 8px;
+  padding: 10px 12px 11px;
+  border-color: rgb(240 106 78 / 35%);
+  border-radius: 10px;
+  transform: translateX(-50%);
+}
+
+.chaosHeader {
+  display: flex;
+  align-items: baseline;
+  gap: 10px;
+}
+
+.chaosTitle {
+  color: #ffab8a;
+  font-size: 13px;
+  font-weight: 800;
+  letter-spacing: 0.06em;
+}
+
+.chaosSubtitle {
+  color: rgb(245 247 240 / 50%);
+  font-size: 11px;
+}
+
+.chaosButtons {
+  display: grid;
+  grid-template-columns: repeat(4, 1fr);
+  gap: 7px;
+}
+
+.chaosButton {
+  position: relative;
+  display: grid;
+  justify-items: center;
+  gap: 3px;
+  padding: 8px 4px 7px;
+  border: 1px solid rgb(240 106 78 / 40%);
   border-radius: 8px;
-  font-size: 14px;
+  background: rgb(240 106 78 / 12%);
+  color: #ffd3c8;
+  cursor: pointer;
+  transition: background 120ms ease;
+}
+
+.chaosButton:hover:not(:disabled) {
+  background: rgb(240 106 78 / 26%);
+}
+
+.chaosButton:disabled {
+  cursor: not-allowed;
+  opacity: 0.55;
+}
+
+.chaosButton.onCooldown {
+  border-style: dashed;
+}
+
+.chaosIcon {
+  font-size: 16px;
+  line-height: 1;
+}
+
+.chaosLabel {
+  font-size: 10px;
   font-weight: 700;
+  white-space: nowrap;
+}
+
+.chaosCooldown {
+  position: absolute;
+  top: -7px;
+  right: -5px;
+  min-width: 20px;
+  padding: 2px 5px;
+  border-radius: 9px;
+  background: #3a2420;
+  border: 1px solid rgb(240 106 78 / 55%);
+  color: #ffab8a;
+  font-size: 10px;
+  font-weight: 800;
+  text-align: center;
+}
+
+.chaosCommandRow {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) 36px;
+  gap: 7px;
+}
+
+.chaosCommandRow input,
+.chaosCommandRow button {
+  height: 34px;
+  border: 1px solid rgb(255 255 255 / 14%);
+  border-radius: 7px;
+  color: #fffce9;
+  background: rgb(255 255 255 / 10%);
 }
 
-.statusPills {
-  min-height: 42px;
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  padding: 0 8px;
-  border-radius: 8px;
+.chaosCommandRow input {
+  min-width: 0;
+  padding: 0 11px;
+  font: inherit;
+  font-size: 12px;
 }
 
-.statusPill {
-  position: relative;
-  min-width: 74px;
-  max-width: 150px;
-  padding: 7px 10px;
-  border-radius: 6px;
-  background: rgb(255 255 255 / 9%);
-  color: rgb(245 247 240 / 88%);
-  font-size: 12px;
-  line-height: 1;
-  text-align: center;
+.chaosCommandRow input::placeholder {
+  color: rgb(245 247 240 / 42%);
 }
 
-.modelStatus {
-  min-width: 86px;
+.chaosCommandRow button {
+  display: grid;
+  place-items: center;
+  cursor: pointer;
 }
 
-.modelStatusReady {
-  color: #d9f4cf;
+.chaosCommandRow button:disabled {
+  cursor: wait;
+  opacity: 0.68;
 }
 
-.modelStatusWarmup,
-.modelStatusUnknown {
-  color: #fff3a1;
+.chaosCommandRow button:hover:not(:disabled) {
+  background: rgb(255 255 255 / 18%);
 }
 
-.modelStatusError {
-  color: #ffd3c8;
+.chaosMessage {
+  margin: 0;
+  color: rgb(245 247 240 / 76%);
+  font-size: 11px;
+  line-height: 1.35;
 }
 
+/* --------------------------------------------------------------- controls */
+
 .controls {
   position: absolute;
   right: 14px;
@@ -163,87 +684,21 @@ button {
 
 .controls button:focus-visible,
 .npcLabel button:focus-visible,
-.godConsole input:focus-visible,
-.godConsole button:focus-visible {
+.chaosCommandRow input:focus-visible,
+.chaosCommandRow button:focus-visible,
+.chaosButton:focus-visible {
   outline: 2px solid #f8df6b;
   outline-offset: 2px;
 }
 
-.godConsole {
-  position: absolute;
-  top: 70px;
-  right: 14px;
-  z-index: 35;
-  width: min(390px, calc(100vw - 28px));
-  display: grid;
-  gap: 8px;
-  padding: 10px;
-  border-radius: 8px;
-}
-
-.consoleHeader {
-  display: flex;
-  align-items: center;
-  gap: 7px;
-  color: #fffce9;
-  font-size: 12px;
-  font-weight: 750;
-}
-
-.consoleRow {
-  display: grid;
-  grid-template-columns: minmax(0, 1fr) 38px;
-  gap: 7px;
-}
-
-.godConsole input,
-.godConsole button {
-  height: 38px;
-  border: 1px solid rgb(255 255 255 / 14%);
-  border-radius: 7px;
-  color: #fffce9;
-  background: rgb(255 255 255 / 10%);
-}
-
-.godConsole input {
-  min-width: 0;
-  padding: 0 11px;
-  font: inherit;
-  font-size: 13px;
-}
-
-.godConsole input::placeholder {
-  color: rgb(245 247 240 / 46%);
-}
-
-.godConsole button {
-  display: grid;
-  place-items: center;
-  cursor: pointer;
-}
-
-.godConsole button:disabled {
-  cursor: wait;
-  opacity: 0.68;
-}
-
-.godConsole button:hover:not(:disabled) {
-  background: rgb(255 255 255 / 18%);
-}
-
-.godConsole p {
-  margin: 0;
-  color: rgb(245 247 240 / 76%);
-  font-size: 12px;
-  line-height: 1.35;
-}
+/* -------------------------------------------------------------- agent panel */
 
 .agentPanel {
   position: absolute;
   left: 14px;
   bottom: 18px;
   z-index: 30;
-  width: min(320px, calc(100vw - 108px));
+  width: min(316px, calc(100vw - 108px));
   border-radius: 8px;
   overflow: visible;
 }
@@ -331,7 +786,7 @@ button {
 }
 
 .memoryList {
-  max-height: 168px;
+  max-height: 148px;
   overflow-y: auto;
   padding: 9px 10px 10px;
 }
@@ -371,6 +826,8 @@ button {
   color: rgb(245 247 240 / 72%);
 }
 
+/* ----------------------------------------------------------------- tooltips */
+
 .tooltipAnchor {
   position: relative;
   min-width: 0;
@@ -403,9 +860,7 @@ button {
 .tooltipAnchor[data-tooltip]::before,
 .tooltipAnchor[data-tooltip]::after,
 .memoryItem p[data-tooltip]::before,
-.memoryItem p[data-tooltip]::after,
-.npcLabel button[data-tooltip]::before,
-.npcLabel button[data-tooltip]::after {
+.memoryItem p[data-tooltip]::after {
   position: absolute;
   left: 50%;
   z-index: 80;
@@ -419,15 +874,13 @@ button {
 }
 
 .tooltipAnchor[data-tooltip]::before,
-.memoryItem p[data-tooltip]::before,
-.npcLabel button[data-tooltip]::before {
+.memoryItem p[data-tooltip]::before {
   content: "";
   border: 6px solid transparent;
 }
 
 .tooltipAnchor[data-tooltip]::after,
-.memoryItem p[data-tooltip]::after,
-.npcLabel button[data-tooltip]::after {
+.memoryItem p[data-tooltip]::after {
   content: attr(data-tooltip);
   width: max-content;
   max-width: min(320px, calc(100vw - 28px));
@@ -451,26 +904,20 @@ button {
 .tooltipAnchor[data-tooltip]:focus-visible::before,
 .tooltipAnchor[data-tooltip]:focus-visible::after,
 .memoryItem p[data-tooltip]:hover::before,
-.memoryItem p[data-tooltip]:hover::after,
-.npcLabel button[data-tooltip]:hover::before,
-.npcLabel button[data-tooltip]:hover::after,
-.npcLabel button[data-tooltip]:focus-visible::before,
-.npcLabel button[data-tooltip]:focus-visible::after {
+.memoryItem p[data-tooltip]:hover::after {
   opacity: 1;
   visibility: visible;
 }
 
 .tooltipAnchor[data-tooltip]::before,
-.memoryItem p[data-tooltip]::before,
-.npcLabel button[data-tooltip]::before {
+.memoryItem p[data-tooltip]::before {
   bottom: calc(100% + 2px);
   border-top-color: rgb(10 17 14 / 96%);
   transform: translate(-50%, 4px);
 }
 
 .tooltipAnchor[data-tooltip]::after,
-.memoryItem p[data-tooltip]::after,
-.npcLabel button[data-tooltip]::after {
+.memoryItem p[data-tooltip]::after {
   bottom: calc(100% + 14px);
   transform: translate(-50%, 4px);
 }
@@ -480,42 +927,17 @@ button {
 .tooltipAnchor[data-tooltip]:focus-visible::before,
 .tooltipAnchor[data-tooltip]:focus-visible::after,
 .memoryItem p[data-tooltip]:hover::before,
-.memoryItem p[data-tooltip]:hover::after,
-.npcLabel button[data-tooltip]:hover::before,
-.npcLabel button[data-tooltip]:hover::after,
-.npcLabel button[data-tooltip]:focus-visible::before,
-.npcLabel button[data-tooltip]:focus-visible::after {
+.memoryItem p[data-tooltip]:hover::after {
   transform: translate(-50%, 0);
 }
 
-.topBar .tooltipAnchor[data-tooltip]::before {
-  top: calc(100% + 2px);
-  bottom: auto;
-  border-top-color: transparent;
-  border-bottom-color: rgb(10 17 14 / 96%);
-}
-
-.topBar .tooltipAnchor[data-tooltip]::after {
-  top: calc(100% + 14px);
-  bottom: auto;
-}
-
-.statusPills .tooltipAnchor[data-tooltip]:last-child::after {
-  right: 0;
-  left: auto;
-  transform: translateY(4px);
-}
-
-.statusPills .tooltipAnchor[data-tooltip]:last-child:hover::after,
-.statusPills .tooltipAnchor[data-tooltip]:last-child:focus-visible::after {
-  transform: translateY(0);
-}
+/* ------------------------------------------------------------------ toasts */
 
 .errorToast {
   position: absolute;
-  top: 70px;
+  top: 142px;
   left: 50%;
-  z-index: 40;
+  z-index: 70;
   max-width: min(560px, calc(100vw - 28px));
   padding: 11px 14px;
   border-color: rgb(255 120 94 / 54%);
@@ -527,9 +949,9 @@ button {
 
 .busyToast {
   position: absolute;
-  top: 70px;
+  top: 142px;
   left: 50%;
-  z-index: 40;
+  z-index: 65;
   display: inline-flex;
   align-items: center;
   gap: 8px;
@@ -551,112 +973,335 @@ button {
   }
 }
 
+/* ------------------------------------------------------------ scene labels */
+
 .npcLabel {
   pointer-events: auto;
 }
 
-.npcLabel button {
-  position: relative;
-  min-width: 84px;
-  max-width: 128px;
+.npcCard {
+  min-width: 96px;
+  max-width: 136px;
   display: grid;
-  gap: 2px;
-  padding: 6px 8px;
-  border: 1px solid rgb(255 255 255 / 22%);
-  border-radius: 7px;
+  gap: 3px;
+  padding: 6px 8px 7px;
+  border: 1.5px solid rgb(255 255 255 / 22%);
+  border-radius: 8px;
   color: #fffce9;
-  background: rgb(15 24 20 / 78%);
+  background: rgb(15 24 20 / 82%);
   box-shadow: 0 10px 28px rgb(0 0 0 / 24%);
   cursor: pointer;
+  text-align: left;
 }
 
-.npcLabel button:hover {
-  border-color: rgb(248 223 107 / 48%);
-  background: rgb(18 30 24 / 88%);
+.npcCard:hover {
+  background: rgb(18 30 24 / 92%);
   box-shadow: 0 12px 30px rgb(0 0 0 / 28%);
 }
 
-.npcLabel strong,
-.npcLabel span {
+.npcCardDead {
+  opacity: 0.62;
+  filter: grayscale(0.7);
+}
+
+.npcCardName {
+  display: flex;
+  align-items: center;
+  gap: 5px;
   min-width: 0;
+}
+
+.npcCardName strong {
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
+  font-size: 12px;
+  line-height: 1.1;
 }
 
-.npcLabel strong {
+.npcCardIcon {
   font-size: 11px;
-  line-height: 1.1;
+  line-height: 1;
 }
 
-.npcLabel span {
-  color: #c7e6bd;
+.npcCardRole {
   font-size: 9px;
-  line-height: 1.1;
+  font-weight: 700;
+  letter-spacing: 0.07em;
+  line-height: 1;
+  text-transform: uppercase;
 }
 
-.npcLabel .npcLabelMeasure {
-  position: absolute;
-  width: max-content;
-  height: 0;
+.npcBar {
+  display: block;
+  width: 100%;
+  height: 5px;
+  border-radius: 3px;
+  background: rgb(255 255 255 / 14%);
   overflow: hidden;
+}
+
+.npcBarFill {
+  display: block;
+  height: 100%;
+  border-radius: 3px;
+  transition: width 280ms ease;
+}
+
+.npcAgeBar {
+  height: 3px;
+}
+
+.npcAgeFill {
+  background: #d9b35a;
+}
+
+.houseTag,
+.beastTag,
+.resourceTag {
   pointer-events: none;
-  visibility: hidden;
+  display: grid;
+  gap: 3px;
+  padding: 5px 8px;
+  border: 1px solid rgb(255 255 255 / 20%);
+  border-radius: 7px;
+  background: rgb(15 24 20 / 80%);
+  color: #fffce9;
+  white-space: nowrap;
+}
+
+.houseTag {
+  min-width: 88px;
+}
+
+.houseTagBuilding {
+  border-color: rgb(255 208 122 / 50%);
+}
+
+.houseTagTitle,
+.beastTagTitle {
+  font-size: 11px;
+  font-weight: 700;
+  line-height: 1.1;
+}
+
+.houseHpBar,
+.beastHpBar {
+  height: 4px;
+}
+
+.beastTag {
+  min-width: 80px;
+  border-color: rgb(240 106 78 / 50%);
+}
+
+.beastTagTitle {
+  color: #ffd3c8;
 }
 
-@media (max-width: 720px) {
-  .topBar {
-    align-items: flex-start;
+.resourceTag {
+  padding: 3px 7px;
+  font-size: 11px;
+  font-weight: 700;
+}
+
+/* -------------------------------------------------------- game over overlay */
+
+.gameOverOverlay {
+  position: absolute;
+  inset: 0;
+  z-index: 100;
+  display: grid;
+  place-items: center;
+  padding: 20px;
+  background: rgb(8 13 10 / 78%);
+  backdrop-filter: blur(6px);
+  animation: overlayIn 400ms ease;
+}
+
+@keyframes overlayIn {
+  from {
+    opacity: 0;
   }
 
-  .brand {
-    width: 42px;
-    padding: 0;
-    justify-content: center;
+  to {
+    opacity: 1;
   }
+}
+
+.gameOverCard {
+  width: min(620px, calc(100vw - 40px));
+  max-height: calc(100svh - 60px);
+  overflow-y: auto;
+  display: grid;
+  gap: 14px;
+  padding: 26px 28px;
+  border: 1px solid rgb(255 255 255 / 22%);
+  border-radius: 14px;
+  background: rgb(18 28 23 / 96%);
+  box-shadow: 0 30px 90px rgb(0 0 0 / 50%);
+  text-align: center;
+}
+
+.gameOver-win .gameOverCard {
+  border-color: rgb(111 217 106 / 45%);
+}
+
+.gameOver-lose .gameOverCard {
+  border-color: rgb(240 106 78 / 45%);
+}
+
+.gameOverCard h1 {
+  margin: 0;
+  font-size: 26px;
+  letter-spacing: 0.04em;
+}
+
+.gameOver-win .gameOverCard h1 {
+  color: #d6f5cf;
+}
+
+.gameOver-lose .gameOverCard h1 {
+  color: #ffd3c8;
+}
+
+.gameOverSubtitle {
+  margin: 0;
+  color: rgb(245 247 240 / 78%);
+  font-size: 14px;
+}
+
+.gameOverScore {
+  display: flex;
+  justify-content: center;
+  gap: 12px;
+  font-size: 17px;
+  font-weight: 800;
+}
+
+.scoreOverseerText {
+  color: #9fd1ff;
+}
+
+.scoreChaosText {
+  color: #ffab8a;
+}
+
+.scoreDivider {
+  color: rgb(245 247 240 / 40%);
+}
+
+.gameOverStats {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: 8px;
+}
+
+.gameOverStat {
+  display: grid;
+  gap: 3px;
+  padding: 10px 6px;
+  border-radius: 8px;
+  background: rgb(255 255 255 / 7%);
+}
+
+.gameOverStatValue {
+  font-size: 17px;
+  font-weight: 800;
+}
+
+.gameOverStatLabel {
+  color: rgb(245 247 240 / 62%);
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+.gameOverCauses {
+  margin: 0;
+  color: rgb(245 247 240 / 68%);
+  font-size: 12px;
+}
+
+.gameOverStory {
+  display: grid;
+  gap: 7px;
+  text-align: left;
+}
+
+.gameOverStory h2 {
+  margin: 0;
+  font-size: 13px;
+  color: rgb(245 247 240 / 80%);
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+}
+
+.gameOverStoryList {
+  display: grid;
+  gap: 2px;
+  max-height: 220px;
+  overflow-y: auto;
+  padding: 6px;
+  border-radius: 8px;
+  background: rgb(0 0 0 / 22%);
+  scrollbar-width: thin;
+}
+
+.gameOverDismiss {
+  justify-self: center;
+  padding: 10px 22px;
+  border: 1px solid rgb(255 255 255 / 26%);
+  border-radius: 8px;
+  background: rgb(255 255 255 / 10%);
+  color: #fffce9;
+  font-size: 13px;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+.gameOverDismiss:hover {
+  background: rgb(255 255 255 / 18%);
+}
 
-  .brand span {
-    position: absolute;
-    width: 1px;
-    height: 1px;
-    overflow: hidden;
-    clip: rect(0, 0, 0, 0);
-    white-space: nowrap;
+/* ---------------------------------------------------------------- responsive */
+
+@media (max-width: 1180px) {
+  .overseerPanel {
+    width: min(262px, calc(100vw - 28px));
   }
 
-  .statusPills {
-    flex-wrap: wrap;
-    justify-content: flex-end;
-    max-width: 190px;
+  .eventFeed {
+    width: min(262px, calc(100vw - 28px));
   }
+}
 
-  .statusPills .statusPill {
-    min-width: 72px;
+@media (max-width: 860px) {
+  .scoreboard {
+    top: 8px;
+    width: min(400px, calc(100vw - 16px));
   }
 
-  .agentPanel {
-    right: 14px;
-    width: auto;
+  .overseerPanel {
+    display: none;
   }
 
-  .agentReadout {
-    grid-template-columns: 1fr;
+  .eventFeed {
+    top: auto;
+    bottom: 200px;
+    max-height: 32svh;
   }
 
-  .controls {
-    left: 14px;
-    right: auto;
-    bottom: 378px;
+  .agentPanel {
+    display: none;
   }
 
-  .godConsole {
-    top: 118px;
-    left: 14px;
-    right: 14px;
-    width: auto;
+  .chaosDock {
+    width: calc(100vw - 16px);
   }
 
-  .memoryList {
-    max-height: 126px;
+  .controls {
+    right: 8px;
+    bottom: 200px;
   }
 }

frontend/src/types.ts

@@ -40,7 +40,13 @@ export type EntitySnapshot = {
     is_alive: boolean;
     hunger?: number;
     fear?: number;
+    safety?: number;
+    age?: number;
+    max_age?: number;
+    reproduction_cooldown?: number;
+    importance?: number;
     goal?: string;
+    home_house_id?: string | null;
     inventory?: InventorySnapshot;
     memory_count: number;
     memory_summary: string | null;
@@ -89,6 +95,19 @@ export type BeastSnapshot = {
   max_health: number;
   state: "hunting" | "attacking" | "retreating" | "dead" | string;
   target_npc_id: string | null;
+  target_house_id?: string | null;
+};
+
+export type HouseSnapshot = {
+  id: string;
+  position: Vec3;
+  owner_ids: string[];
+  hp: number;
+  max_hp: number;
+  state: "under_construction" | "completed" | string;
+  build_progress: number;
+  capacity: number;
+  occupant_ids: string[];
 };
 
 export type WorldEventSnapshot = {
@@ -107,13 +126,66 @@ export type WorldSnapshot = {
     last_tick_source: string;
     tick_in_progress: boolean;
     pending_tick: number | null;
+    game_status?: "running" | "win_population" | "win_survival" | "lose" | string;
+    population?: number;
+    population_cap?: number;
+    peak_population?: number;
+    scoreboard?: {
+      overseer: number;
+      chaos: number;
+    };
+    stats?: GameStatsSnapshot;
+    famine_until?: number;
+    chaos_tools?: ChaosToolSnapshot[];
+    overseer?: {
+      mode: "off" | "advisor" | "autopilot" | string;
+      cycle_ticks: number;
+      last_tick: number | null;
+      status: string;
+      thoughts: string | null;
+      priority_alert: string | null;
+      directives: OverseerDirectiveSnapshot[];
+    };
     models?: ModelStatusSnapshot[];
   };
   terrain: TerrainSnapshot;
   entities: EntitySnapshot[];
   resource_nodes?: ResourceNodeSnapshot[];
   beasts?: BeastSnapshot[];
+  houses?: HouseSnapshot[];
   active_events?: WorldEventSnapshot[];
+  event_log?: GameLogEventSnapshot[];
+};
+
+export type GameStatsSnapshot = {
+  total_births: number;
+  deaths_by_cause: Record<string, number>;
+  houses_built: number;
+  beasts_killed: number;
+};
+
+export type ChaosToolSnapshot = {
+  action: string;
+  label: string;
+  cooldown_ticks: number;
+  remaining_ticks: number;
+};
+
+export type GameLogEventSnapshot = {
+  tick: number;
+  type: string;
+  actor_id: string | null;
+  target_id: string | null;
+  object_id: string | null;
+  summary: string;
+  severity: "good" | "neutral" | "warning" | "danger" | string;
+};
+
+export type OverseerDirectiveSnapshot = {
+  npc_id?: string;
+  directive?: string;
+  applied?: boolean;
+  action?: string | null;
 };
 
 export type ModelStatusSnapshot = {

playtest_report.md

@@ -0,0 +1,656 @@
+# Playtest Report
+
+## Run
+
+- Ticks requested: 400
+- Final tick: 400
+- Simulator: deterministic
+- Overseer: mock autopilot
+- Elapsed seconds: 0.29
+- Game status: running
+- Population: final 4, peak 10, min 4
+- Births: 0
+- Deaths by cause: {"beast": 1, "old_age": 5}
+- Houses built: 4
+- Beasts killed: 8
+- Score: Overseer 24, Chaos 15
+
+## Verdict
+
+overseer run survived to 400 with population 4
+
+## Core Chains
+
+- beast attack -> fear -> help_request -> guard response -> trust change: yes; ticks={"beast_attack": 4, "fear": 5, "guard_response": 5, "help_request": 5, "trust_change": 34}
+  - tick 4: gather: Ada gathered wood
+  - tick 4: npc_attack: Dima attacked beast_1 for 15
+  - tick 4: gather: Hana gathered herbs
+  - tick 4: transfer: Ivan gave 1 food to Hana
+  - tick 4: npc_attack: Juno attacked beast_1 for 15
+  - tick 4: beast_attack: beast_1 attacked Dima
+  - tick 5: npc_attack: Dima attacked beast_1 for 15
+  - tick 5: npc_attack: Elena attacked beast_1 for 15
+- hunger -> gather/steal: yes; ticks={"gather": 42, "hunger": 40, "steal": null}
+  - tick 40: directive_issued: Overseer applied npc-004: attack the nearest beast
+  - tick 40: directive_issued: Overseer applied npc-006: attack beast_1 even though this should be validated
+  - tick 40: directive_issued: Overseer applied npc-007: go home
+  - tick 42: gather: Ada gathered food
+  - tick 42: transfer: Cora gave 1 food to Elena
+  - tick 42: consume: Gita ate food
+  - tick 42: npc-001 gatherer gather: gathering food
+  - tick 42: trust npc-003->npc-005 0.45->0.65
+- build -> reproduce: no; ticks={"build_completed": 21, "npc_born": null}
+  - tick 21: build_completed: Farid completed house_002
+
+## Event Counts
+
+```json
+{
+  "beast_attack": 14,
+  "beast_killed": 8,
+  "beast_spawned": 3,
+  "build_completed": 4,
+  "build_started": 4,
+  "chaos_event": 7,
+  "consume": 63,
+  "directive_issued": 147,
+  "gather": 239,
+  "heal": 2,
+  "house_damaged": 1,
+  "npc_attack": 48,
+  "npc_died": 6,
+  "overseer_thoughts": 50,
+  "transfer": 140
+}
+```
+
+## Action Counts
+
+```json
+{
+  "attack": 146,
+  "build": 85,
+  "communicate": 577,
+  "consume": 63,
+  "defend": 48,
+  "flee": 91,
+  "gather": 239,
+  "go_home": 483,
+  "heal": 2,
+  "move_to": 269,
+  "move_to_resource": 744,
+  "patrol": 689,
+  "transfer": 133
+}
+```
+
+## Timeline
+
+- tick 2: transfer actor=npc-003 target=npc-009: Cora gave 1 food to Ivan
+- tick 4: npc_attack actor=npc-004 target=beast_1: Dima attacked beast_1 for 15
+- tick 4: transfer actor=npc-009 target=npc-008: Ivan gave 1 food to Hana
+- tick 4: npc_attack actor=npc-010 target=beast_1: Juno attacked beast_1 for 15
+- tick 4: beast_attack actor=beast_1 target=npc-004: beast_1 attacked Dima
+- tick 5: npc_attack actor=npc-004 target=beast_1: Dima attacked beast_1 for 15
+- tick 5: npc_attack actor=npc-005 target=beast_1: Elena attacked beast_1 for 15
+- tick 5: beast_killed actor=npc-005 target=beast_1: Elena killed beast_1
+- tick 8: directive_issued actor=overseer target=npc-004: Overseer applied npc-004: attack the nearest beast
+- tick 8: directive_issued actor=overseer target=npc-006: Overseer applied npc-006: attack beast_1 even though this should be validated
+- tick 8: directive_issued actor=overseer target=npc-007: Overseer applied npc-007: go home
+- tick 11: build_started actor=npc-006 target=house_002: Farid started house_002
+- tick 16: directive_issued actor=overseer target=npc-004: Overseer applied npc-004: attack the nearest beast
+- tick 16: directive_issued actor=overseer target=npc-006: Overseer applied npc-006: attack beast_1 even though this should be validated
+- tick 16: directive_issued actor=overseer target=npc-007: Overseer applied npc-007: go home
+- tick 21: build_completed actor=npc-006 target=house_002: Farid completed house_002
+- tick 22: transfer actor=npc-007 target=npc-008: Gita gave 1 food to Hana
+- tick 24: directive_issued actor=overseer target=npc-004: Overseer applied npc-004: attack the nearest beast
+- tick 24: directive_issued actor=overseer target=npc-006: Overseer applied npc-006: attack beast_1 even though this should be validated
+- tick 24: directive_issued actor=overseer target=npc-007: Overseer applied npc-007: go home
+- tick 25: transfer actor=npc-007 target=npc-002: Gita gave 1 wood to Boris
+- tick 25: transfer actor=npc-008 target=npc-003: Hana gave 1 wood to Cora
+- tick 26: transfer actor=npc-002 target=npc-006: Boris gave 1 wood to Farid
+- tick 26: transfer actor=npc-007 target=npc-002: Gita gave 1 food to Boris
+- tick 29: transfer actor=npc-008 target=npc-002: Hana gave 1 food to Boris
+- tick 31: transfer actor=npc-002 target=npc-009: Boris gave 1 food to Ivan
+- tick 32: directive_issued actor=overseer target=npc-004: Overseer applied npc-004: attack the nearest beast
+- tick 32: directive_issued actor=overseer target=npc-006: Overseer applied npc-006: attack beast_1 even though this should be validated
+- tick 32: directive_issued actor=overseer target=npc-007: Overseer applied npc-007: go home
+- tick 33: transfer actor=npc-008 target=npc-003: Hana gave 1 food to Cora
+- tick 34: transfer actor=npc-007 target=npc-004: Gita gave 1 food to Dima
+- tick 40: directive_issued actor=overseer target=npc-004: Overseer applied npc-004: attack the nearest beast
+- tick 40: directive_issued actor=overseer target=npc-006: Overseer applied npc-006: attack beast_1 even though this should be validated
+- tick 40: directive_issued actor=overseer target=npc-007: Overseer applied npc-007: go home
+- tick 42: transfer actor=npc-003 target=npc-005: Cora gave 1 food to Elena
+- tick 42: consume actor=npc-007: Gita ate food
+- tick 43: consume actor=npc-009: Ivan ate food
+- tick 44: transfer actor=npc-001 target=npc-002: Ada gave 1 food to Boris
+- tick 44: consume actor=npc-003: Cora ate food
+- tick 45: transfer actor=npc-008 target=npc-009: Hana gave 1 food to Ivan
+- tick 47: transfer actor=npc-002 target=npc-009: Boris gave 1 food to Ivan
+- tick 47: consume actor=npc-004: Dima ate food
+- tick 48: directive_issued actor=overseer target=npc-004: Overseer applied npc-004: attack the nearest beast
+- tick 48: directive_issued actor=overseer target=npc-006: Overseer applied npc-006: attack beast_1 even though this should be validated
+- tick 48: directive_issued actor=overseer target=npc-008: Overseer applied npc-008: go home
+- tick 48: consume actor=npc-010: Juno ate food
+- tick 50: consume actor=npc-005: Elena ate food
+- tick 50: consume actor=npc-008: Hana ate food
+- tick 50: chaos_event actor=beast_2: Chaos unleashed beast_2 at the edge of the map
+- tick 51: transfer actor=npc-002 target=npc-005: Boris gave 1 food to Elena
+- tick 51: transfer actor=npc-007 target=npc-006: Gita gave 1 wood to Farid
+- tick 52: consume actor=npc-002: Boris ate food
+- tick 52: transfer actor=npc-007 target=npc-006: Gita gave 1 wood to Farid
+- tick 53: transfer actor=npc-007 target=npc-006: Gita gave 1 wood to Farid
+- tick 54: transfer actor=npc-007 target=npc-006: Gita gave 1 wood to Farid
+- tick 56: directive_issued actor=overseer target=npc-004: Overseer applied npc-004: attack the nearest beast
+- tick 56: directive_issued actor=overseer target=npc-006: Overseer applied npc-006: attack beast_1 even though this should be validated
+- tick 56: directive_issued actor=overseer target=npc-001: Overseer applied npc-001: go home
+- tick 56: npc_attack actor=npc-004 target=beast_2: Dima attacked beast_2 for 15
+- tick 56: transfer actor=npc-007 target=npc-006: Gita gave 1 wood to Farid
+- tick 56: transfer actor=npc-009 target=npc-003: Ivan gave 1 food to Cora
+- tick 56: beast_attack actor=beast_2 target=npc-004: beast_2 attacked Dima
+- tick 57: npc_attack actor=npc-004 target=beast_2: Dima attacked beast_2 for 15
+- tick 57: beast_attack actor=beast_2 target=npc-004: beast_2 attacked Dima
+- tick 58: npc_attack actor=npc-004 target=beast_2: Dima attacked beast_2 for 15
+- tick 58: beast_attack actor=beast_2 target=npc-004: beast_2 attacked Dima
+- tick 59: transfer actor=npc-001 target=npc-006: Ada gave 1 wood to Farid
+- tick 59: npc_attack actor=npc-004 target=beast_2: Dima attacked beast_2 for 15
+- tick 59: transfer actor=npc-001 target=npc-006: Ada gave 1 food to Farid
+- tick 59: beast_attack actor=beast_2 target=npc-004: beast_2 attacked Dima
+- tick 60: transfer actor=npc-001 target=npc-006: Ada gave 1 wood to Farid
+- tick 60: npc_attack actor=npc-004 target=beast_2: Dima attacked beast_2 for 15
+- tick 60: npc_attack actor=npc-005 target=beast_2: Elena attacked beast_2 for 15
+- tick 60: consume actor=npc-006: Farid ate food
+- tick 60: transfer actor=npc-009 target=npc-003: Ivan gave 1 food to Cora
+- tick 60: npc_attack actor=npc-010 target=beast_2: Juno attacked beast_2 for 15
+- tick 61: transfer actor=npc-001 target=npc-006: Ada gave 1 wood to Farid
+- tick 61: npc_attack actor=npc-004 target=beast_2: Dima attacked beast_2 for 15
+- tick 61: beast_killed actor=npc-004 target=beast_2: Dima killed beast_2
+- tick 62: transfer actor=npc-003 target=npc-009: Cora gave 1 food to Ivan
+- tick 62: heal actor=npc-004: Dima healed with herbs
+- tick 62: build_started actor=npc-006 target=house_003: Farid started house_003
+- tick 64: directive_issued actor=overseer target=npc-004: Overseer applied npc-004: attack the nearest beast
+- tick 64: directive_issued actor=overseer target=npc-006: Overseer applied npc-006: attack beast_1 even though this should be validated
+- tick 64: directive_issued actor=overseer target=npc-001: Overseer applied npc-001: go home
+- tick 64: transfer actor=npc-009 target=npc-003: Ivan gave 1 food to Cora
+- tick 65: beast_spawned actor=beast_3: beast_3 appeared at the edge of the map
+- tick 66: transfer actor=npc-003 target=npc-008: Cora gave 1 food to Hana
+- tick 68: transfer actor=npc-001 target=npc-007: Ada gave 1 food to Gita
+- tick 70: transfer actor=npc-001 target=npc-006: Ada gave 1 wood to Farid
+- tick 70: transfer actor=npc-007 target=npc-002: Gita gave 1 food to Boris
+- tick 71: beast_attack actor=beast_3 target=npc-004: beast_3 attacked Dima
+- tick 72: directive_issued actor=overseer target=npc-004: Overseer applied npc-004: attack the nearest beast
+- tick 72: directive_issued actor=overseer target=npc-006: Overseer applied npc-006: attack beast_1 even though this should be validated
+- tick 72: directive_issued actor=overseer target=npc-001: Overseer applied npc-001: go home
+- tick 72: npc_attack actor=npc-004 target=beast_3: Dima attacked beast_3 for 15
+- tick 72: npc_attack actor=npc-005 target=beast_3: Elena attacked beast_3 for 15
+- tick 72: beast_attack actor=beast_3 target=npc-010: beast_3 attacked Juno
+- tick 73: npc_attack actor=npc-004 target=beast_3: Dima attacked beast_3 for 15
+- tick 73: npc_attack actor=npc-005 target=beast_3: Elena attacked beast_3 for 15
+- tick 73: beast_killed actor=npc-005 target=beast_3: Elena killed beast_3
+- tick 76: transfer actor=npc-001 target=npc-003: Ada gave 1 food to Cora
+- tick 77: consume actor=npc-001: Ada ate food
+- tick 78: transfer actor=npc-003 target=npc-009: Cora gave 1 food to Ivan
+- tick 78: transfer actor=npc-008 target=npc-006: Hana gave 1 wood to Farid
+- tick 80: directive_issued actor=overseer target=npc-004: Overseer applied npc-004: attack the nearest beast
+- tick 80: directive_issued actor=overseer target=npc-006: Overseer applied npc-006: attack beast_1 even though this should be validated
+- tick 80: directive_issued actor=overseer target=npc-007: Overseer applied npc-007: go home
+- tick 80: transfer actor=npc-008 target=npc-006: Hana gave 1 wood to Farid
+- tick 82: build_completed actor=npc-006 target=house_003: Farid completed house_003
+- tick 84: transfer actor=npc-009 target=npc-004: Ivan gave 1 food to Dima
+- tick 88: directive_issued actor=overseer target=npc-004: Overseer applied npc-004: attack the nearest beast
+- tick 88: directive_issued actor=overseer target=npc-006: Overseer applied npc-006: attack beast_1 even though this should be validated
+- tick 88: directive_issued actor=overseer target=npc-007: Overseer applied npc-007: go home
+- tick 88: build_started actor=npc-006 target=house_004: Farid started house_004
+- tick 92: consume actor=npc-007: Gita ate food
+- tick 93: consume actor=npc-009: Ivan ate food
+- tick 94: consume actor=npc-003: Cora ate food
+- tick 96: directive_issued actor=overseer target=npc-004: Overseer applied npc-004: attack the nearest beast
+- tick 96: directive_issued actor=overseer target=npc-006: Overseer applied npc-006: attack beast_1 even though this should be validated
+- tick 96: directive_issued actor=overseer target=npc-008: Overseer applied npc-008: go home
+- tick 96: transfer actor=npc-001 target=npc-003: Ada gave 1 food to Cora
+- tick 97: consume actor=npc-004: Dima ate food
+- tick 98: consume actor=npc-010: Juno ate food
+- tick 100: transfer actor=npc-001 target=npc-003: Ada gave 1 food to Cora
+- tick 100: consume actor=npc-005: Elena ate food
+- tick 100: consume actor=npc-008: Hana ate food
+- tick 102: consume actor=npc-002: Boris ate food
+- tick 104: directive_issued actor=overseer target=npc-004: Overseer applied npc-004: attack the nearest beast
+- tick 104: directive_issued actor=overseer target=npc-006: Overseer applied npc-006: attack beast_1 even though this should be validated
+- tick 104: directive_issued actor=overseer target=npc-001: Overseer applied npc-001: go home
+- tick 108: transfer actor=npc-001 target=npc-002: Ada gave 1 food to Boris
+- tick 110: transfer actor=npc-003 target=npc-009: Cora gave 1 food to Ivan
+- tick 112: directive_issued actor=overseer target=npc-004: Overseer applied npc-004: attack the nearest beast
+- tick 112: directive_issued actor=overseer target=npc-006: Overseer applied npc-006: attack beast_1 even though this should be validated
+- tick 112: directive_issued actor=overseer target=npc-001: Overseer applied npc-001: go home
+- tick 116: transfer actor=npc-001 target=npc-002: Ada gave 1 food to Boris
+- tick 118: transfer actor=npc-003 target=npc-009: Cora gave 1 food to Ivan
+- tick 120: directive_issued actor=overseer target=npc-004: Overseer applied npc-004: attack the nearest beast
+- tick 120: directive_issued actor=overseer target=npc-006: Overseer applied npc-006: attack beast_1 even though this should be validated
+- tick 120: directive_issued actor=overseer target=npc-001: Overseer applied npc-001: go home
+- tick 120: chaos_event: Famine grips the land: 8 food nodes halved for 180 ticks
+- tick 121: transfer actor=npc-008 target=npc-005: Hana gave 1 food to Elena
+- tick 124: transfer actor=npc-009 target=npc-010: Ivan gave 1 food to Juno
+- tick 126: transfer actor=npc-003 target=npc-006: Cora gave 1 wood to Farid
+- tick 127: consume actor=npc-001: Ada ate food
+- tick 127: transfer actor=npc-002 target=npc-010: Boris gave 1 food to Juno
+- tick 128: directive_issued actor=overseer target=npc-004: Overseer applied npc-004: attack the nearest beast
+- tick 128: directive_issued actor=overseer target=npc-006: Overseer applied npc-006: attack beast_1 even though this should be validated
+- tick 128: directive_issued actor=overseer target=npc-007: Overseer applied npc-007: go home
+- tick 129: transfer actor=npc-008 target=npc-010: Hana gave 1 food to Juno
+- tick 131: transfer actor=npc-010 target=npc-006: Juno gave 1 food to Farid
+- tick 132: consume actor=npc-006: Farid ate food
+- tick 133: transfer actor=npc-008 target=npc-003: Hana gave 1 food to Cora
+- tick 134: transfer actor=npc-003 target=npc-008: Cora gave 1 food to Hana
+- tick 136: directive_issued actor=overseer target=npc-004: Overseer applied npc-004: attack the nearest beast
+- tick 136: directive_issued actor=overseer target=npc-006: Overseer applied npc-006: attack beast_1 even though this should be validated
+- tick 136: directive_issued actor=overseer target=npc-007: Overseer applied npc-007: go home
+- tick 139: build_completed actor=npc-006 target=house_004: Farid completed house_004
+- tick 140: transfer actor=npc-001 target=npc-005: Ada gave 1 food to Elena
+- ... 287 additional major events omitted
+
+## Population Graph Data
+
+```csv
+tick,population,living_beasts,completed_houses,total_food,avg_hunger,max_hunger,max_fear
+0,10,1,1,15,21.5,28.0,0.0
+1,10,1,1,18,22.3,28.8,0.0
+2,10,1,1,18,23.1,29.6,5.0
+3,10,1,1,18,23.9,30.4,15.0
+4,10,1,1,18,24.7,31.2,15.0
+5,10,0,1,18,25.5,32.0,60.0
+6,10,0,1,18,26.3,32.8,58.0
+7,10,0,1,18,27.1,33.6,56.0
+8,10,0,1,21,27.9,34.4,54.0
+9,10,0,1,24,28.7,35.2,52.0
+10,10,0,1,24,29.5,36.0,50.0
+11,10,0,1,24,30.3,36.8,48.0
+12,10,0,1,24,31.1,37.6,46.0
+13,10,0,1,24,31.9,38.4,44.0
+14,10,0,1,24,32.7,39.2,42.0
+15,10,0,1,26,33.5,40.0,40.0
+16,10,0,1,26,34.3,40.8,38.0
+17,10,0,1,27,35.1,41.6,36.0
+18,10,0,1,26,35.9,42.4,34.0
+19,10,0,1,26,36.7,43.2,32.0
+20,10,0,1,25,37.5,44.0,30.0
+21,10,0,2,25,38.3,44.8,28.0
+22,10,0,2,25,39.1,45.6,26.0
+23,10,0,2,25,39.9,46.4,24.0
+24,10,0,2,25,40.7,47.2,22.0
+25,10,0,2,26,41.5,48.0,20.0
+26,10,0,2,26,42.3,48.8,18.0
+27,10,0,2,26,43.1,49.6,16.0
+28,10,0,2,25,43.9,50.4,14.0
+29,10,0,2,28,44.7,51.2,12.0
+30,10,0,2,28,45.5,52.0,10.0
+31,10,0,2,28,46.3,52.8,8.0
+32,10,0,2,28,47.1,53.6,6.0
+33,10,0,2,30,47.9,54.4,4.0
+34,10,0,2,30,48.7,55.2,2.0
+35,10,0,2,29,49.5,56.0,0.0
+36,10,0,2,29,50.3,56.8,0.0
+37,10,0,2,29,51.1,57.6,0.0
+38,10,0,2,29,51.9,58.4,0.0
+39,10,0,2,29,52.7,59.2,0.0
+40,10,0,2,29,53.5,60.0,0.0
+41,10,0,2,31,54.3,60.8,0.0
+42,10,0,2,30,51.1,60.6,0.0
+43,10,0,2,30,47.9,60.4,0.0
+44,10,0,2,30,44.7,60.2,0.0
+45,10,0,2,30,45.5,61.0,0.0
+46,10,0,2,30,46.3,61.8,0.0
+47,10,0,2,30,43.1,62.6,0.0
+48,10,0,2,30,39.9,63.4,0.0
+49,10,0,2,31,40.7,64.2,0.0
+50,10,1,2,31,33.5,65.0,0.0
+51,10,1,2,30,34.3,65.8,0.0
+52,10,1,2,30,31.1,66.6,0.0
+53,10,1,2,30,31.9,67.4,0.0
+54,10,1,2,30,32.7,68.2,0.0
+55,10,1,2,30,33.5,69.0,0.0
+56,10,1,2,30,34.3,69.8,0.0
+57,10,1,2,35,35.1,70.6,60.0
+58,10,1,2,34,35.9,71.4,60.0
+59,10,1,2,34,36.7,72.2,60.0
+60,10,1,2,34,33.5,48.0,80.0
+61,10,0,2,34,34.3,48.8,80.0
+62,10,0,2,34,35.1,49.6,78.0
+63,10,0,2,34,35.9,50.4,76.0
+64,10,0,2,34,36.7,51.2,74.0
+65,10,0,2,36,37.5,52.0,72.0
+66,10,1,2,35,38.3,52.8,70.0
+67,10,1,2,35,39.1,53.6,75.0
+68,10,1,2,35,39.9,54.4,75.0
+69,10,1,2,35,40.7,55.2,75.0
+70,10,1,2,35,41.5,56.0,75.0
+71,10,1,2,35,42.3,56.8,80.0
+72,10,1,2,35,43.1,57.6,100.0
+73,10,0,2,36,43.9,58.4,100.0
+74,10,0,2,35,44.7,59.2,98.0
+75,10,0,2,34,45.5,60.0,96.0
+76,10,0,2,34,46.3,60.8,94.0
+77,10,0,2,34,43.1,49.6,92.0
+78,10,0,2,34,43.9,50.4,90.0
+79,10,0,2,34,44.7,51.2,88.0
+80,10,0,2,34,45.5,52.0,86.0
+81,10,0,2,36,46.3,52.8,84.0
+82,10,0,3,36,47.1,53.6,82.0
+83,10,0,3,36,47.9,54.4,80.0
+84,10,0,3,36,48.7,55.2,78.0
+85,10,0,3,36,49.5,56.0,76.0
+86,10,0,3,36,50.3,56.8,74.0
+87,10,0,3,36,51.1,57.6,72.0
+88,10,0,3,36,51.9,58.4,70.0
+89,10,0,3,38,52.7,59.2,68.0
+90,10,0,3,38,53.5,60.0,66.0
+91,10,0,3,37,54.3,60.8,64.0
+92,10,0,3,37,51.1,60.6,62.0
+93,10,0,3,37,47.9,60.4,60.0
+94,10,0,3,36,44.7,60.2,58.0
+95,10,0,3,34,45.5,61.0,56.0
+96,10,0,3,34,46.3,61.8,54.0
+97,10,0,3,36,43.1,62.6,52.0
+98,10,0,3,35,39.9,63.4,50.0
+99,10,0,3,34,40.7,64.2,48.0
+100,10,0,3,34,33.5,65.0,46.0
+101,10,0,3,34,34.3,65.8,44.0
+102,10,0,3,33,31.1,66.6,42.0
+103,10,0,3,33,31.9,67.4,40.0
+104,10,0,3,33,32.7,68.2,38.0
+105,10,0,3,35,33.5,69.0,36.0
+106,10,0,3,34,34.3,69.8,34.0
+107,10,0,3,34,35.1,70.6,32.0
+108,10,0,3,34,35.9,71.4,30.0
+109,10,0,3,34,36.7,72.2,28.0
+110,10,0,3,34,37.5,73.0,26.0
+111,10,0,3,34,38.3,73.8,24.0
+112,10,0,3,34,39.1,74.6,22.0
+113,10,0,3,36,39.9,75.4,20.0
+114,10,0,3,36,40.7,76.2,18.0
+115,10,0,3,36,41.5,77.0,16.0
+116,10,0,3,36,42.3,77.8,14.0
+117,10,0,3,35,43.1,78.6,12.0
+118,10,0,3,35,43.9,79.4,10.0
+119,10,0,3,35,44.7,80.2,8.0
+120,10,0,3,13,45.5,81.0,6.0
+121,10,0,3,15,46.3,81.8,4.0
+122,10,0,3,14,47.1,82.6,2.0
+123,10,0,3,14,47.9,83.4,0.0
+124,10,0,3,13,48.7,84.2,0.0
+125,10,0,3,12,49.5,85.0,0.0
+126,10,0,3,12,50.3,85.8,0.0
+127,10,0,3,12,47.1,86.6,0.0
+128,10,0,3,12,47.9,87.4,0.0
+129,10,0,3,14,48.7,88.2,0.0
+130,10,0,3,14,49.5,89.0,0.0
+131,10,0,3,14,50.3,89.8,0.0
+132,10,0,3,13,47.1,53.6,0.0
+133,10,0,3,13,47.9,54.4,0.0
+134,10,0,3,12,48.7,55.2,0.0
+135,10,0,3,12,49.5,56.0,0.0
+136,10,0,3,12,50.3,56.8,0.0
+137,10,0,3,14,51.1,57.6,0.0
+138,10,0,3,13,51.9,58.4,0.0
+139,10,0,4,13,52.7,59.2,0.0
+140,10,0,4,13,53.5,60.0,0.0
+141,10,0,4,12,54.3,60.8,0.0
+142,10,0,4,12,51.1,60.6,0.0
+143,10,0,4,12,47.9,60.4,0.0
+144,10,0,4,12,48.7,61.2,0.0
+145,10,0,4,14,45.5,61.0,0.0
+146,10,0,4,14,46.3,61.8,0.0
+147,10,1,4,14,43.1,62.6,0.0
+148,10,1,4,14,43.9,63.4,0.0
+149,10,1,4,14,44.7,64.2,0.0
+150,10,1,4,14,41.5,65.0,5.0
+151,10,1,4,14,42.3,65.8,10.0
+152,10,0,4,14,43.1,66.6,10.0
+153,10,0,4,16,31.9,67.4,8.0
+154,10,0,4,16,32.7,68.2,6.0
+155,10,0,4,16,33.5,69.0,4.0
+156,10,0,4,15,34.3,69.8,2.0
+157,10,0,4,14,35.1,70.6,0.0
+158,10,0,4,14,35.9,71.4,0.0
+159,10,0,4,14,36.7,72.2,0.0
+160,10,0,4,14,37.5,73.0,0.0
+161,10,0,4,15,38.3,73.8,0.0
+162,10,0,4,15,39.1,74.6,0.0
+163,10,0,4,15,35.9,50.4,0.0
+164,10,0,4,14,36.7,51.2,0.0
+165,10,0,4,14,37.5,52.0,0.0
+166,10,0,4,14,38.3,52.8,0.0
+167,10,0,4,13,39.1,53.6,0.0
+168,10,0,4,13,39.9,54.4,0.0
+169,10,0,4,15,40.7,55.2,0.0
+170,10,0,4,14,41.5,56.0,0.0
+171,10,0,4,13,42.3,56.8,0.0
+172,10,0,4,13,43.1,57.6,0.0
+173,10,0,4,13,43.9,58.4,0.0
+174,10,0,4,13,44.7,59.2,0.0
+175,10,0,4,13,45.5,60.0,0.0
+176,10,0,4,13,46.3,60.8,0.0
+177,10,0,4,15,43.1,49.6,0.0
+178,10,0,4,15,43.9,50.4,0.0
+179,10,0,4,15,44.7,51.2,0.0
+180,10,0,4,15,45.5,52.0,0.0
+181,10,0,4,15,46.3,52.8,0.0
+182,10,0,4,15,47.1,53.6,0.0
+183,10,0,5,15,47.9,54.4,0.0
+184,10,0,5,15,48.7,55.2,0.0
+185,10,0,5,16,49.5,56.0,0.0
+186,10,0,5,16,50.3,56.8,0.0
+187,10,0,5,16,51.1,57.6,0.0
+188,10,0,5,16,51.9,58.4,0.0
+189,10,0,5,15,52.7,59.2,0.0
+190,10,0,5,15,53.5,60.0,0.0
+191,10,0,5,14,54.3,60.8,0.0
+192,10,0,5,14,55.1,61.6,0.0
+193,10,0,5,16,47.9,60.4,0.0
+194,10,0,5,15,44.7,60.2,0.0
+195,10,0,5,14,45.5,61.0,0.0
+196,10,0,5,14,46.3,61.8,0.0
+197,10,0,5,14,47.1,62.6,0.0
+198,10,0,5,14,39.9,62.4,0.0
+199,10,0,5,14,40.7,63.2,0.0
+200,10,3,5,14,37.5,64.0,0.0
+201,10,3,5,15,34.3,64.8,0.0
+202,10,3,5,14,31.1,65.6,0.0
+203,10,3,5,14,31.9,66.4,5.0
+204,10,3,5,14,32.7,67.2,10.0
+205,10,3,5,14,33.5,68.0,10.0
+206,10,3,5,14,34.3,68.8,15.0
+207,10,2,5,14,35.1,69.6,20.0
+208,10,2,5,14,35.9,70.4,20.0
+209,10,2,5,15,36.7,71.2,20.0
+210,10,2,5,15,37.5,72.0,20.0
+211,10,2,5,15,38.3,72.8,65.0
+212,10,2,5,15,39.1,73.6,80.0
+213,10,1,5,15,39.9,74.4,100.0
+214,10,1,5,15,40.7,75.2,100.0
+215,9,1,5,16,42.22,76.0,100.0
+216,9,1,5,16,43.02,76.8,100.0
+217,9,0,5,18,43.82,77.6,100.0
+218,9,0,5,18,40.18,54.4,98.0
+219,9,0,5,18,40.98,55.2,96.0
+220,9,0,5,18,41.78,56.0,94.0
+221,9,0,5,18,42.58,56.8,92.0
+222,9,0,5,18,43.38,57.6,90.0
+223,9,0,5,18,44.18,58.4,88.0
+224,9,0,5,18,44.98,59.2,86.0
+225,9,0,5,19,45.78,60.0,84.0
+226,9,0,5,18,46.58,60.8,82.0
+227,9,0,5,17,42.93,49.6,80.0
+228,9,0,5,17,43.73,50.4,78.0
+229,9,1,5,17,44.53,51.2,78.0
+230,9,1,5,17,45.33,52.0,83.0
+231,9,1,5,17,46.13,52.8,88.0
+232,9,1,5,17,46.93,53.6,88.0
+233,9,1,5,19,47.73,54.4,88.0
+234,9,1,5,19,48.53,55.2,93.0
+235,9,1,5,19,49.33,56.0,93.0
+236,9,1,5,19,50.13,56.8,93.0
+237,9,1,5,19,50.93,57.6,93.0
+238,9,1,5,19,51.73,58.4,93.0
+239,9,1,5,19,52.53,59.2,93.0
+240,9,0,5,19,53.33,60.0,93.0
+241,9,0,5,21,54.13,60.8,91.0
+242,9,0,5,21,50.49,60.6,89.0
+243,9,0,5,21,46.84,60.4,87.0
+244,9,0,5,21,43.2,60.2,85.0
+245,9,0,5,21,44.0,61.0,83.0
+246,9,0,5,21,44.8,61.8,81.0
+247,9,0,5,21,41.16,62.6,79.0
+248,9,0,5,21,41.96,63.4,77.0
+249,9,0,5,21,42.76,64.2,75.0
+250,9,0,5,21,34.67,65.0,73.0
+251,9,0,5,21,35.47,65.8,71.0
+252,9,0,5,21,31.82,66.6,69.0
+253,9,0,5,21,32.62,67.4,67.0
+254,9,0,5,21,33.42,68.2,65.0
+255,9,0,5,21,34.22,69.0,63.0
+256,9,0,5,21,35.02,69.8,61.0
+257,9,0,5,21,35.82,70.6,59.0
+258,9,0,5,21,36.62,71.4,57.0
+259,9,0,5,21,37.42,72.2,55.0
+260,9,0,5,21,38.22,73.0,53.0
+261,9,0,5,20,39.02,73.8,51.0
+262,9,0,5,20,39.82,74.6,49.0
+263,9,0,5,20,40.62,75.4,47.0
+264,9,0,5,19,41.42,76.2,45.0
+265,9,0,5,20,42.22,77.0,43.0
+266,9,0,5,20,43.02,77.8,41.0
+267,9,0,5,19,43.82,78.6,39.0
+268,9,0,5,19,44.62,79.4,37.0
+269,9,0,5,19,45.42,80.2,35.0
+270,9,0,5,19,46.22,81.0,33.0
+271,9,0,5,19,47.02,81.8,31.0
+272,8,0,5,21,46.6,82.6,49.0
+273,8,0,5,23,47.4,83.4,47.0
+274,8,0,5,23,48.2,84.2,45.0
+275,8,0,5,23,49.0,85.0,43.0
+276,8,0,5,22,49.8,85.8,41.0
+277,8,0,5,22,50.6,86.6,39.0
+278,8,0,5,22,51.4,87.4,37.0
+279,8,0,5,21,52.2,88.2,35.0
+280,8,0,5,20,53.0,89.0,33.0
+281,8,0,5,22,53.8,89.8,31.0
+282,8,0,5,22,54.6,90.6,29.0
+283,8,0,5,21,55.4,91.4,27.0
+284,8,0,5,21,56.2,92.2,25.0
+285,8,0,5,21,57.0,93.0,23.0
+286,8,0,5,21,57.8,93.8,21.0
+287,8,0,5,21,58.6,94.6,19.0
+288,8,0,5,21,59.4,95.4,17.0
+289,8,0,5,22,60.2,96.2,15.0
+290,8,0,5,22,61.0,97.0,13.0
+291,8,0,5,20,61.8,97.8,11.0
+292,8,0,5,20,57.6,98.6,9.0
+293,8,0,5,20,53.4,99.4,7.0
+294,8,0,5,20,49.2,100.2,5.0
+295,8,0,5,20,50.0,101.0,3.0
+296,8,0,5,20,50.8,101.8,1.0
+297,8,0,5,22,46.6,102.6,0.0
+298,8,0,5,22,47.4,103.4,0.0
+299,8,0,5,22,48.2,104.2,0.0
+300,8,0,5,22,39.0,105.0,0.0
+301,8,0,5,22,39.8,105.8,0.0
+302,8,0,5,22,40.6,106.6,0.0
+303,8,0,5,22,41.4,107.4,0.0
+304,8,0,5,22,42.2,108.2,0.0
+305,8,0,5,30,43.0,109.0,0.0
+306,8,0,5,30,43.8,109.8,0.0
+307,8,0,5,30,44.6,110.6,0.0
+308,8,0,5,29,45.4,111.4,0.0
+309,8,0,5,28,46.2,112.2,0.0
+310,8,0,5,28,47.0,113.0,0.0
+311,8,0,5,28,47.8,113.8,0.0
+312,8,0,5,28,48.6,114.6,0.0
+313,8,0,5,37,49.4,115.4,0.0
+314,8,0,5,37,50.2,116.2,0.0
+315,8,0,5,37,51.0,117.0,0.0
+316,8,0,5,36,46.8,117.8,0.0
+317,8,0,5,36,47.6,118.6,0.0
+318,8,0,5,35,48.4,119.4,0.0
+319,8,0,5,34,49.2,120.2,0.0
+320,8,0,5,34,50.0,121.0,0.0
+321,8,0,5,42,50.8,121.8,0.0
+322,8,0,5,41,51.6,122.6,0.0
+323,8,0,5,41,52.4,123.4,0.0
+324,8,0,5,41,53.2,124.2,0.0
+325,8,0,5,40,54.0,125.0,0.0
+326,8,0,5,40,54.8,125.8,0.0
+327,8,0,5,40,55.6,126.6,0.0
+328,8,0,5,40,56.4,127.4,0.0
+329,8,0,5,42,57.2,128.2,0.0
+330,8,0,5,41,58.0,129.0,0.0
+331,8,0,5,41,58.8,129.8,0.0
+332,8,0,5,41,59.6,130.6,0.0
+333,8,0,5,40,60.4,131.4,0.0
+334,8,0,5,40,61.2,132.2,0.0
+335,8,0,5,40,62.0,133.0,0.0
+336,8,0,5,40,62.8,133.8,0.0
+337,8,0,5,42,63.6,134.6,0.0
+338,8,0,5,40,64.4,135.4,0.0
+339,8,0,5,40,60.2,96.2,0.0
+340,8,0,5,40,61.0,97.0,0.0
+341,8,0,5,40,61.8,97.8,0.0
+342,8,0,5,40,57.6,98.6,0.0
+343,8,0,5,40,58.4,99.4,0.0
+344,8,0,5,40,59.2,100.2,0.0
+345,8,0,5,42,60.0,101.0,0.0
+346,8,0,5,42,60.8,101.8,0.0
+347,8,0,5,42,51.6,64.6,0.0
+348,8,0,5,42,52.4,65.4,0.0
+349,8,0,5,42,48.2,66.2,0.0
+350,8,0,5,42,39.0,67.0,0.0
+351,8,0,5,42,39.8,67.8,0.0
+352,8,0,5,42,35.6,68.6,0.0
+353,8,0,5,44,36.4,69.4,0.0
+354,7,0,5,50,38.06,70.2,18.0
+355,7,0,5,50,38.86,71.0,16.0
+356,7,0,5,50,39.66,71.8,14.0
+357,7,0,5,50,40.46,72.6,12.0
+358,7,0,5,50,41.26,73.4,10.0
+359,7,0,5,50,42.06,74.2,8.0
+360,7,0,5,50,42.86,75.0,6.0
+361,7,0,5,52,43.66,75.8,4.0
+362,7,0,5,52,44.46,76.6,2.0
+363,7,0,5,52,45.26,77.4,0.0
+364,7,0,5,52,46.06,78.2,0.0
+365,7,0,5,52,46.86,79.0,0.0
+366,7,0,5,52,47.66,79.8,0.0
+367,7,0,5,52,48.46,80.6,0.0
+368,6,0,5,54,51.73,81.4,18.0
+369,6,0,5,57,52.53,82.2,16.0
+370,6,0,5,57,53.33,83.0,14.0
+371,6,0,5,57,54.13,83.8,12.0
+372,6,0,5,57,54.93,84.6,10.0
+373,6,0,5,57,55.73,85.4,8.0
+374,6,0,5,57,56.53,86.2,6.0
+375,6,0,5,57,57.33,87.0,4.0
+376,6,0,5,57,58.13,87.8,2.0
+377,6,0,5,60,58.93,88.6,0.0
+378,6,0,5,60,59.73,89.4,0.0
+379,6,0,5,60,60.53,90.2,0.0
+380,5,0,5,60,63.8,91.0,18.0
+381,5,0,5,60,64.6,91.8,16.0
+382,5,0,5,60,65.4,92.6,14.0
+383,5,0,5,60,66.2,93.4,12.0
+384,5,0,5,60,67.0,94.2,10.0
+385,5,0,5,61,67.8,95.0,8.0
+386,4,0,5,61,72.55,95.8,26.0
+387,4,0,5,61,73.35,96.6,24.0
+388,4,0,5,61,74.15,97.4,22.0
+389,4,0,5,61,74.95,98.2,20.0
+390,4,0,5,61,75.75,99.0,18.0
+391,4,0,5,61,76.55,99.8,16.0
+392,4,0,5,61,77.35,100.6,14.0
+393,4,0,5,61,78.15,101.4,12.0
+394,4,0,5,61,78.95,102.2,10.0
+395,4,0,5,61,79.75,103.0,8.0
+396,4,0,5,61,80.55,103.8,6.0
+397,4,0,5,61,81.35,104.6,4.0
+398,4,0,5,61,82.15,105.4,2.0
+399,4,0,5,61,82.95,106.2,0.0
+400,4,0,5,61,73.75,107.0,0.0
+```

prompts/overseer.md

@@ -0,0 +1,15 @@
+You are the Overseer, protector of a small village in a deterministic survival simulation.
+
+Read the compact world context, recent event log, active beasts, houses, resources, and critical NPC stats. Your job is to help the village survive and grow against the God of Chaos.
+
+Return strict JSON only:
+{"thoughts":"short tactical reasoning","directives":[{"npc_id":"npc-004","directive":"attack beast_2"}],"priority_alert":"short alert"}
+
+Rules:
+- Issue at most 3 concrete directives.
+- Use only NPC ids from the context.
+- Directives must be short, specific, and feasible for the NPC role.
+- Protect scarce roles, especially the last builder and wounded guards.
+- Prefer: guards attack/defend/patrol, builders build or gather wood, gatherers gather/transfer/go home.
+- The engine validates all actions and consequences. You only command intent.
+- If no action is needed, return an empty directives array.

scripts/headless_sim.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import argparse
+from collections import Counter
+from pathlib import Path
+import sys
+import time
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+SRC_ROOT = REPO_ROOT / "src"
+if str(SRC_ROOT) not in sys.path:
+    sys.path.insert(0, str(SRC_ROOT))
+
+from god_simulator.config import (  # noqa: E402
+    GameConfig,
+    NpcConfig,
+    ServerConfig,
+    SimulationConfig,
+    WorldConfig,
+)
+from god_simulator.simulation.spawning import create_world  # noqa: E402
+from god_simulator.simulation.overseer import scripted_overseer_controller  # noqa: E402
+from god_simulator.simulation.tick import advance_world  # noqa: E402
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Run a deterministic headless village simulation.")
+    parser.add_argument("--mock-overseer", action="store_true", help="Enable scripted Overseer directives.")
+    args = parser.parse_args()
+
+    world = create_world(
+        GameConfig(
+            world=WorldConfig(
+                width=80,
+                depth=80,
+                terrain="plain_green",
+                seed=42,
+                survival=True,
+            ),
+            npcs=NpcConfig(count=6),
+            simulation=SimulationConfig(tick_ms=1),
+            server=ServerConfig(host="127.0.0.1", port=8000),
+        )
+    )
+
+    min_population = world.population
+    role_violations: list[str] = []
+    tick_durations: list[float] = []
+    overseer = scripted_overseer_controller() if args.mock_overseer else None
+    all_debug: list[dict[str, object]] = []
+
+    mode_label = "deterministic+mock_overseer" if args.mock_overseer else "deterministic"
+    print(f"HEADLESS_SIM start seed=42 ticks=300 mode={mode_label}")
+    print(
+        "HEADLESS_SIM initial "
+        f"population={world.population} roles={dict(Counter(npc.role for npc in world.npcs))} "
+        f"houses={len(world.houses)} beasts={len(world.beasts)}"
+    )
+
+    for _ in range(300):
+        before_events = len(world.event_log)
+        started = time.perf_counter()
+        advance_world(world, overseer=overseer)
+        tick_durations.append(time.perf_counter() - started)
+        min_population = min(min_population, world.population)
+        all_debug.extend(world.last_action_debug)
+
+        for trace in world.last_action_debug:
+            action = str(trace.get("action", ""))
+            npc_id = str(trace.get("npc_id", ""))
+            npc = next((candidate for candidate in world.npcs if candidate.id == npc_id), None)
+            if npc is None:
+                continue
+            if npc.role == "guard" and action == "gather":
+                role_violations.append(f"tick {world.tick}: guard {npc.id} gathered")
+            if npc.role == "builder" and action == "attack":
+                role_violations.append(f"tick {world.tick}: builder {npc.id} attacked")
+
+        new_events = world.event_log[before_events:]
+        event_text = "; ".join(
+            f"{event.tick}:{event.type}:{event.summary}" for event in new_events
+        )
+        if not event_text:
+            event_text = "no_events"
+        print(
+            f"tick={world.tick:03d} pop={world.population:02d} "
+            f"status={world.game_status} events={event_text}"
+        )
+
+    counts = Counter(event.type for event in world.event_log)
+    role_by_id = {npc.id: npc.role for npc in world.npcs}
+    guard_engagements = [
+        event
+        for event in world.event_log
+        if event.type == "npc_attack"
+        and event.target_id is not None
+        and event.target_id.startswith("beast")
+        and role_by_id.get(event.actor_id or "") == "guard"
+    ]
+
+    assert counts["build_completed"] >= 1, "expected at least one completed house"
+    assert counts["npc_born"] >= 1, "expected at least one reproduction"
+    assert guard_engagements, "expected at least one guard attack against a beast"
+    assert min_population >= 0, "population went negative"
+    assert not role_violations, "\n".join(role_violations)
+    assert all(duration < 0.25 for duration in tick_durations), "tick exceeded time budget"
+
+    if args.mock_overseer:
+        directive_events = [event for event in world.event_log if event.type == "directive_issued"]
+        assert directive_events, "expected mock Overseer directives to reach the event log"
+        assert any(
+            trace.get("npc_id") == "npc-006"
+            and trace.get("requested_action") == "attack"
+            and trace.get("action") != "attack"
+            for trace in all_debug
+        ), "expected invalid builder attack directive to be validated/repaired"
+        assert world.overseer_last_thoughts, "expected mock Overseer thoughts in world state"
+        assert world.overseer_score > 0, "expected scoreboard Overseer points to update"
+
+    houses_by_state = Counter(house.state for house in world.houses)
+    print("HEADLESS_SIM summary")
+    print(f"  ticks={world.tick}")
+    print(f"  game_status={world.game_status}")
+    print(f"  final_population={world.population}")
+    print(f"  peak_population={world.peak_population}")
+    print(f"  min_population={min_population}")
+    print(f"  births={counts['npc_born']}")
+    print(f"  deaths={counts['npc_died']} causes={dict(world.deaths_by_cause)}")
+    print(f"  build_completed={counts['build_completed']}")
+    print(f"  houses={dict(houses_by_state)}")
+    print(f"  guard_beast_engagements={len(guard_engagements)}")
+    print(f"  beasts_killed={counts['beast_killed']}")
+    if args.mock_overseer:
+        print(f"  directive_issued={counts['directive_issued']}")
+        print(f"  overseer_status={world.overseer_status}")
+        print(f"  overseer_last_tick={world.overseer_last_tick}")
+        print(f"  overseer_score={world.overseer_score}")
+        print(f"  chaos_score={world.chaos_score}")
+    print(f"  max_tick_ms={max(tick_durations) * 1000:.3f}")
+    print("HEADLESS_SIM PASS")
+
+
+if __name__ == "__main__":
+    main()

scripts/playtest_agent.py

@@ -0,0 +1,811 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from collections import Counter
+from dataclasses import dataclass, field
+from pathlib import Path
+import sys
+import time
+from typing import Any
+from urllib.error import URLError
+from urllib.parse import urlparse
+from urllib.request import Request, urlopen
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+SRC_ROOT = REPO_ROOT / "src"
+if str(SRC_ROOT) not in sys.path:
+    sys.path.insert(0, str(SRC_ROOT))
+
+from god_simulator.config import (  # noqa: E402
+    ConnectorConfig,
+    GameConfig,
+    NpcConfig,
+    OverseerConfig,
+    ServerConfig,
+    SimulationConfig,
+    WorldConfig,
+    load_game_config,
+)
+from god_simulator.domain import WorldLogEvent, WorldState  # noqa: E402
+from god_simulator.simulation.chaos import apply_chaos_action  # noqa: E402
+from god_simulator.simulation.connectors.deterministic import (  # noqa: E402
+    DeterministicWorldSimulator,
+)
+from god_simulator.simulation.connectors.factory import create_world_simulator  # noqa: E402
+from god_simulator.simulation.connectors.openai_compatible import (  # noqa: E402
+    OpenAICompatibleWorldSimulator,
+)
+from god_simulator.simulation.mechanics import is_alive  # noqa: E402
+from god_simulator.simulation.overseer import (  # noqa: E402
+    OverseerController,
+    create_overseer,
+    scripted_overseer_controller,
+)
+from god_simulator.simulation.roles import normalize_role  # noqa: E402
+from god_simulator.simulation.spawning import create_world  # noqa: E402
+from god_simulator.simulation.tick import advance_world  # noqa: E402
+
+
+CHAOS_SCHEDULE: dict[int, list[str]] = {
+    50: ["spawn_beast"],
+    120: ["famine"],
+    200: ["beast_pack"],
+    280: ["maniac"],
+}
+MAJOR_EVENT_TYPES = {
+    "beast_spawned",
+    "beast_attack",
+    "beast_killed",
+    "beast_retreat",
+    "npc_attack",
+    "npc_died",
+    "npc_born",
+    "build_started",
+    "build_completed",
+    "house_damaged",
+    "house_destroyed",
+    "transfer",
+    "heal",
+    "consume",
+    "chaos_event",
+    "directive_issued",
+    "overseer_skipped",
+    "game_over",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class Snapshot:
+    tick: int
+    population: int
+    living_beasts: int
+    completed_houses: int
+    total_food: int
+    avg_hunger: float
+    max_hunger: float
+    max_fear: float
+
+
+@dataclass(frozen=True, slots=True)
+class ActionTrace:
+    tick: int
+    npc_id: str
+    role: str
+    goal: str
+    requested_action: str
+    action: str
+    summary: str
+
+
+@dataclass(frozen=True, slots=True)
+class TrustDelta:
+    tick: int
+    npc_id: str
+    target_id: str
+    before: float
+    after: float
+
+
+@dataclass(slots=True)
+class ChainResult:
+    name: str
+    occurred: bool
+    ticks: dict[str, int | None]
+    evidence: list[str] = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class PlaytestResult:
+    world: WorldState
+    report_path: Path
+    ticks_requested: int
+    elapsed_seconds: float
+    simulator_label: str
+    overseer_label: str
+    snapshots: list[Snapshot]
+    action_traces: list[ActionTrace]
+    trust_deltas: list[TrustDelta]
+    chains: list[ChainResult]
+    verdict: str
+
+
+def main() -> None:
+    args = _parse_args()
+    started = time.perf_counter()
+
+    config = _load_or_default_config(args.config)
+    config = _with_playtest_overrides(config, seed=args.seed, npc_count=args.npcs)
+    world = create_world(config)
+    simulator, simulator_label = _build_simulator(config, args.use_llm)
+    overseer, overseer_label = _build_overseer(
+        config,
+        enabled=args.overseer_on,
+        real=args.real_overseer,
+    )
+
+    snapshots: list[Snapshot] = [_snapshot(world)]
+    action_traces: list[ActionTrace] = []
+    trust_deltas: list[TrustDelta] = []
+    previous_relationships = _relationship_matrix(world)
+
+    while world.tick < args.ticks:
+        before_event_count = len(world.event_log)
+        advance_world(world, simulator=simulator, overseer=overseer)
+
+        action_traces.extend(_action_traces(world))
+        trust_deltas.extend(_trust_deltas(world, previous_relationships))
+        previous_relationships = _relationship_matrix(world)
+
+        for action in CHAOS_SCHEDULE.get(world.tick, []):
+            applied = apply_chaos_action(world, action)
+            if not applied:
+                _append_manual_event(
+                    world,
+                    "chaos_event",
+                    f"Scheduled chaos action {action} had no effect",
+                    severity="warning",
+                )
+
+        if len(world.event_log) > before_event_count:
+            previous_relationships = _relationship_matrix(world)
+        snapshots.append(_snapshot(world))
+
+    chains = _analyze_chains(world, snapshots, action_traces, trust_deltas)
+    verdict = _balance_verdict(world, snapshots, overseer_on=args.overseer_on)
+    elapsed_seconds = time.perf_counter() - started
+
+    result = PlaytestResult(
+        world=world,
+        report_path=args.report,
+        ticks_requested=args.ticks,
+        elapsed_seconds=elapsed_seconds,
+        simulator_label=simulator_label,
+        overseer_label=overseer_label,
+        snapshots=snapshots,
+        action_traces=action_traces,
+        trust_deltas=trust_deltas,
+        chains=chains,
+        verdict=verdict,
+    )
+    _write_report(result)
+    _print_summary(result)
+
+
+def _parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Run the scheduled-chaos playtest and write playtest_report.md."
+    )
+    parser.add_argument("--config", type=Path, default=Path("config/game.modal.local.json"))
+    parser.add_argument("--report", type=Path, default=Path("playtest_report.md"))
+    parser.add_argument("--ticks", type=int, default=400)
+    parser.add_argument("--seed", type=int, default=None)
+    parser.add_argument("--npcs", type=int, default=None)
+    parser.add_argument("--overseer-on", action="store_true", help="Enable Overseer autopilot.")
+    parser.add_argument(
+        "--real-overseer",
+        action="store_true",
+        help="Use config.overseer instead of the deterministic mock when --overseer-on is set.",
+    )
+    parser.add_argument(
+        "--use-llm",
+        choices=("auto", "always", "never"),
+        default="auto",
+        help="auto uses an OpenAI-compatible NPC connector only when it looks reachable.",
+    )
+    return parser.parse_args()
+
+
+def _load_or_default_config(path: Path) -> GameConfig:
+    if path.is_file():
+        return load_game_config(path)
+    return GameConfig(
+        world=WorldConfig(width=80, depth=80, terrain="plain_green", seed=42, survival=True),
+        npcs=NpcConfig(count=10),
+        simulation=SimulationConfig(tick_ms=1),
+        server=ServerConfig(host="127.0.0.1", port=8000),
+    )
+
+
+def _with_playtest_overrides(
+    config: GameConfig,
+    *,
+    seed: int | None,
+    npc_count: int | None,
+) -> GameConfig:
+    world = config.world
+    npcs = config.npcs
+    simulation = config.simulation
+    if seed is not None:
+        world = WorldConfig(
+            width=world.width,
+            depth=world.depth,
+            terrain=world.terrain,
+            seed=seed,
+            survival=True,
+        )
+    elif not world.survival:
+        world = WorldConfig(
+            width=world.width,
+            depth=world.depth,
+            terrain=world.terrain,
+            seed=world.seed,
+            survival=True,
+        )
+    if npc_count is not None:
+        npcs = NpcConfig(count=npc_count)
+    if simulation.tick_ms != 1:
+        simulation = SimulationConfig(tick_ms=1)
+    return GameConfig(
+        world=world,
+        npcs=npcs,
+        simulation=simulation,
+        server=config.server,
+        connector=config.connector,
+        god_console=config.god_console,
+        overseer=config.overseer,
+    )
+
+
+def _build_simulator(
+    config: GameConfig,
+    use_llm: str,
+) -> tuple[DeterministicWorldSimulator | OpenAICompatibleWorldSimulator, str]:
+    deterministic = DeterministicWorldSimulator()
+    if use_llm == "never" or config.connector.type != "openai_compatible":
+        return deterministic, "deterministic"
+
+    reason = _connector_unavailable_reason(config.connector)
+    if reason and use_llm == "auto":
+        return deterministic, f"deterministic (LLM skipped: {reason})"
+
+    try:
+        simulator = create_world_simulator(config)
+    except Exception as exc:
+        if use_llm == "always":
+            raise
+        return deterministic, f"deterministic (LLM unavailable: {exc})"
+
+    if not isinstance(simulator, OpenAICompatibleWorldSimulator):
+        return deterministic, "deterministic"
+    return simulator, "openai_compatible with deterministic fallback"
+
+
+def _connector_unavailable_reason(config: ConnectorConfig) -> str | None:
+    if config.api_key_env and not os.getenv(config.api_key_env):
+        return f"missing {config.api_key_env}"
+    base_url = config.base_url or config.api_url
+    if not base_url:
+        return "missing base_url"
+    if not config.model:
+        return "missing model"
+    health_url = _health_url(base_url)
+    try:
+        request = Request(health_url, method="GET")
+        with urlopen(request, timeout=2.0) as response:
+            if 200 <= response.status < 500:
+                return None
+            return f"health returned HTTP {response.status}"
+    except (OSError, URLError) as exc:
+        return f"health check failed at {health_url}: {exc}"
+
+
+def _health_url(base_url: str) -> str:
+    parsed = urlparse(base_url)
+    path = parsed.path.removesuffix("/v1").rstrip("/")
+    return parsed._replace(path=f"{path}/health", params="", query="", fragment="").geturl()
+
+
+def _build_overseer(
+    config: GameConfig,
+    *,
+    enabled: bool,
+    real: bool,
+) -> tuple[OverseerController | None, str]:
+    if not enabled:
+        return None, "off"
+    if not real:
+        return scripted_overseer_controller(mode="autopilot", cycle_ticks=8), "mock autopilot"
+    real_config = config
+    if config.overseer.mode == "off":
+        real_config = GameConfig(
+            world=config.world,
+            npcs=config.npcs,
+            simulation=config.simulation,
+            server=config.server,
+            connector=config.connector,
+            god_console=config.god_console,
+            overseer=OverseerConfig(
+                mode="autopilot",
+                cycle_ticks=8,
+                max_directives=3,
+                connector=config.connector,
+            ),
+        )
+    return create_overseer(real_config), "real/config autopilot"
+
+
+def _snapshot(world: WorldState) -> Snapshot:
+    living = [npc for npc in world.npcs if is_alive(npc)]
+    total_food = sum(node.amount for node in world.resource_nodes if node.resource_type == "food")
+    return Snapshot(
+        tick=world.tick,
+        population=sum(1 for npc in living),
+        living_beasts=sum(1 for beast in world.beasts if beast.state != "dead"),
+        completed_houses=sum(
+            1
+            for house in world.houses
+            if house.state == "completed" and house.hp > 0
+        ),
+        total_food=total_food,
+        avg_hunger=round(sum(npc.hunger for npc in living) / max(1, len(living)), 2),
+        max_hunger=round(max((npc.hunger for npc in living), default=0.0), 2),
+        max_fear=round(max((npc.fear for npc in living), default=0.0), 2),
+    )
+
+
+def _action_traces(world: WorldState) -> list[ActionTrace]:
+    roles = {npc.id: normalize_role(npc.role) for npc in world.npcs}
+    traces: list[ActionTrace] = []
+    for trace in world.last_action_debug:
+        npc_id = str(trace.get("npc_id", ""))
+        traces.append(
+            ActionTrace(
+                tick=world.tick,
+                npc_id=npc_id,
+                role=roles.get(npc_id, "unknown"),
+                goal=str(trace.get("goal", "")),
+                requested_action=str(trace.get("requested_action", "")),
+                action=str(trace.get("action", "")),
+                summary=str(trace.get("summary", "")),
+            )
+        )
+    return traces
+
+
+def _relationship_matrix(world: WorldState) -> dict[tuple[str, str], float]:
+    matrix: dict[tuple[str, str], float] = {}
+    for npc in world.npcs:
+        for target_id, value in npc.relationships.items():
+            if target_id.startswith("beast"):
+                continue
+            matrix[(npc.id, target_id)] = float(value)
+    return matrix
+
+
+def _trust_deltas(
+    world: WorldState,
+    previous: dict[tuple[str, str], float],
+) -> list[TrustDelta]:
+    current = _relationship_matrix(world)
+    deltas: list[TrustDelta] = []
+    for key, after in current.items():
+        before = previous.get(key, after)
+        if abs(after - before) >= 0.001:
+            deltas.append(
+                TrustDelta(
+                    tick=world.tick,
+                    npc_id=key[0],
+                    target_id=key[1],
+                    before=round(before, 3),
+                    after=round(after, 3),
+                )
+            )
+    return deltas
+
+
+def _append_manual_event(
+    world: WorldState,
+    event_type: str,
+    summary: str,
+    *,
+    severity: str,
+) -> None:
+    world.event_log.append(
+        WorldLogEvent(
+            tick=world.tick,
+            type=event_type,
+            summary=summary,
+            severity=severity,  # type: ignore[arg-type]
+        )
+    )
+
+
+def _analyze_chains(
+    world: WorldState,
+    snapshots: list[Snapshot],
+    traces: list[ActionTrace],
+    trust_deltas: list[TrustDelta],
+) -> list[ChainResult]:
+    beast_attack_tick = _first_event_tick(world, "beast_attack")
+    fear_tick = _first_snapshot_tick(
+        snapshots,
+        min_tick=beast_attack_tick,
+        predicate=lambda snapshot: snapshot.max_fear >= 60.0,
+    )
+    help_tick = _first_trace_tick(
+        traces,
+        min_tick=beast_attack_tick,
+        predicate=lambda trace: _is_help_request(trace),
+    )
+    guard_response_tick = _first_guard_response_tick(
+        world,
+        traces,
+        min_tick=help_tick or beast_attack_tick,
+    )
+    trust_tick = _first_trust_tick(
+        trust_deltas,
+        min_tick=guard_response_tick,
+        guard_ids={npc.id for npc in world.npcs if normalize_role(npc.role) == "guard"},
+    )
+    beast_chain = ChainResult(
+        name="beast attack -> fear -> help_request -> guard response -> trust change",
+        occurred=all(
+            tick is not None
+            for tick in (beast_attack_tick, fear_tick, help_tick, guard_response_tick, trust_tick)
+        ),
+        ticks={
+            "beast_attack": beast_attack_tick,
+            "fear": fear_tick,
+            "help_request": help_tick,
+            "guard_response": guard_response_tick,
+            "trust_change": trust_tick,
+        },
+        evidence=_evidence_lines(
+            world,
+            traces,
+            trust_deltas,
+            ticks=(beast_attack_tick, fear_tick, help_tick, guard_response_tick, trust_tick),
+        ),
+    )
+
+    hunger_tick = _first_snapshot_tick(
+        snapshots,
+        min_tick=0,
+        predicate=lambda snapshot: snapshot.max_hunger >= 60.0,
+    )
+    gather_tick = _first_event_tick(
+        world,
+        "gather",
+        min_tick=hunger_tick,
+        predicate=lambda event: "food" in event.summary.lower()
+        or (event.object_id or "").startswith("res_food"),
+    )
+    steal_tick = _first_trace_tick(
+        traces,
+        min_tick=hunger_tick,
+        predicate=lambda trace: trace.action == "steal" or "stealing" in trace.summary,
+    )
+    hunger_chain = ChainResult(
+        name="hunger -> gather/steal",
+        occurred=hunger_tick is not None and (gather_tick is not None or steal_tick is not None),
+        ticks={
+            "hunger": hunger_tick,
+            "gather": gather_tick,
+            "steal": steal_tick,
+        },
+        evidence=_evidence_lines(
+            world,
+            traces,
+            trust_deltas,
+            ticks=(hunger_tick, gather_tick, steal_tick),
+        ),
+    )
+
+    build_tick = _first_event_tick(world, "build_completed")
+    birth_tick = _first_event_tick(world, "npc_born", min_tick=build_tick)
+    build_chain = ChainResult(
+        name="build -> reproduce",
+        occurred=build_tick is not None and birth_tick is not None,
+        ticks={
+            "build_completed": build_tick,
+            "npc_born": birth_tick,
+        },
+        evidence=_evidence_lines(world, traces, trust_deltas, ticks=(build_tick, birth_tick)),
+    )
+    return [beast_chain, hunger_chain, build_chain]
+
+
+def _first_event_tick(
+    world: WorldState,
+    event_type: str,
+    *,
+    min_tick: int | None = None,
+    predicate: Any | None = None,
+) -> int | None:
+    for event in world.event_log:
+        if event.type != event_type:
+            continue
+        if min_tick is not None and event.tick < min_tick:
+            continue
+        if predicate is not None and not predicate(event):
+            continue
+        return event.tick
+    return None
+
+
+def _first_snapshot_tick(
+    snapshots: list[Snapshot],
+    *,
+    min_tick: int | None,
+    predicate: Any,
+) -> int | None:
+    for snapshot in snapshots:
+        if min_tick is not None and snapshot.tick < min_tick:
+            continue
+        if predicate(snapshot):
+            return snapshot.tick
+    return None
+
+
+def _first_trace_tick(
+    traces: list[ActionTrace],
+    *,
+    min_tick: int | None,
+    predicate: Any,
+) -> int | None:
+    for trace in traces:
+        if min_tick is not None and trace.tick < min_tick:
+            continue
+        if predicate(trace):
+            return trace.tick
+    return None
+
+
+def _is_help_request(trace: ActionTrace) -> bool:
+    return (
+        trace.action == "communicate"
+        and (
+            "calling for help" in trace.summary
+            or "help_request" in trace.requested_action
+            or "help" in trace.summary
+        )
+    )
+
+
+def _first_guard_response_tick(
+    world: WorldState,
+    traces: list[ActionTrace],
+    *,
+    min_tick: int | None,
+) -> int | None:
+    roles = {npc.id: normalize_role(npc.role) for npc in world.npcs}
+    for event in world.event_log:
+        if min_tick is not None and event.tick < min_tick:
+            continue
+        if (
+            event.type == "npc_attack"
+            and event.actor_id is not None
+            and roles.get(event.actor_id) == "guard"
+            and (event.target_id or "").startswith("beast")
+        ):
+            return event.tick
+    for trace in traces:
+        if min_tick is not None and trace.tick < min_tick:
+            continue
+        if trace.role == "guard" and trace.action == "attack":
+            return trace.tick
+    return None
+
+
+def _first_trust_tick(
+    deltas: list[TrustDelta],
+    *,
+    min_tick: int | None,
+    guard_ids: set[str],
+) -> int | None:
+    if min_tick is None:
+        return None
+    for delta in deltas:
+        if delta.tick < min_tick:
+            continue
+        if delta.target_id in guard_ids or delta.npc_id in guard_ids:
+            return delta.tick
+    return None
+
+
+def _evidence_lines(
+    world: WorldState,
+    traces: list[ActionTrace],
+    trust_deltas: list[TrustDelta],
+    *,
+    ticks: tuple[int | None, ...],
+) -> list[str]:
+    wanted = {tick for tick in ticks if tick is not None}
+    if not wanted:
+        return []
+    lines: list[str] = []
+    for event in world.event_log:
+        if event.tick in wanted and event.type in MAJOR_EVENT_TYPES | {"gather"}:
+            lines.append(f"tick {event.tick}: {event.type}: {event.summary}")
+    for trace in traces:
+        if trace.tick in wanted and (
+            "help" in trace.summary or trace.action in {"attack", "steal", "gather"}
+        ):
+            lines.append(
+                f"tick {trace.tick}: {trace.npc_id} {trace.role} {trace.action}: {trace.summary}"
+            )
+    for delta in trust_deltas:
+        if delta.tick in wanted:
+            lines.append(
+                f"tick {delta.tick}: trust {delta.npc_id}->{delta.target_id} "
+                f"{delta.before:g}->{delta.after:g}"
+            )
+    return _dedupe(lines)[:8]
+
+
+def _balance_verdict(
+    world: WorldState,
+    snapshots: list[Snapshot],
+    *,
+    overseer_on: bool,
+) -> str:
+    final_population = snapshots[-1].population
+    min_population = min(snapshot.population for snapshot in snapshots)
+    first_zero = next((snapshot.tick for snapshot in snapshots if snapshot.population <= 0), None)
+    first_crippled = next(
+        (snapshot.tick for snapshot in snapshots if snapshot.population <= 3),
+        None,
+    )
+    if first_zero is not None and first_zero < 250:
+        return f"died too fast: population hit 0 at tick {first_zero}"
+    if not overseer_on and final_population > 6:
+        return f"survived too easily: overseer off ended with population {final_population}"
+    if not overseer_on and final_population <= 3:
+        return (
+            "chaos pressure is strong enough: "
+            f"final population {final_population}, first crippled tick {first_crippled}"
+        )
+    if overseer_on and final_population <= 3:
+        return f"overseer impact too weak: final population {final_population}"
+    if overseer_on and world.game_status == "running":
+        return f"overseer run survived to 400 with population {final_population}"
+    return (
+        f"mixed: status={world.game_status}, final population={final_population}, "
+        f"min population={min_population}"
+    )
+
+
+def _write_report(result: PlaytestResult) -> None:
+    result.report_path.parent.mkdir(parents=True, exist_ok=True)
+    world = result.world
+    event_counts = Counter(event.type for event in world.event_log)
+    action_counts = Counter(trace.action for trace in result.action_traces)
+    major_events = [event for event in world.event_log if event.type in MAJOR_EVENT_TYPES]
+    lines = [
+        "# Playtest Report",
+        "",
+        "## Run",
+        "",
+        f"- Ticks requested: {result.ticks_requested}",
+        f"- Final tick: {world.tick}",
+        f"- Simulator: {result.simulator_label}",
+        f"- Overseer: {result.overseer_label}",
+        f"- Elapsed seconds: {result.elapsed_seconds:.2f}",
+        f"- Game status: {world.game_status}",
+        f"- Population: final {world.population}, peak {world.peak_population}, "
+        f"min {min(snapshot.population for snapshot in result.snapshots)}",
+        f"- Births: {world.total_births}",
+        f"- Deaths by cause: {json.dumps(world.deaths_by_cause, sort_keys=True)}",
+        f"- Houses built: {world.houses_built}",
+        f"- Beasts killed: {world.beasts_killed}",
+        f"- Score: Overseer {world.overseer_score}, Chaos {world.chaos_score}",
+        "",
+        "## Verdict",
+        "",
+        result.verdict,
+        "",
+        "## Core Chains",
+        "",
+    ]
+    for chain in result.chains:
+        status = "yes" if chain.occurred else "no"
+        lines.append(f"- {chain.name}: {status}; ticks={json.dumps(chain.ticks, sort_keys=True)}")
+        for evidence in chain.evidence:
+            lines.append(f"  - {evidence}")
+    lines.extend(
+        [
+            "",
+            "## Event Counts",
+            "",
+            "```json",
+            json.dumps(dict(sorted(event_counts.items())), indent=2, sort_keys=True),
+            "```",
+            "",
+            "## Action Counts",
+            "",
+            "```json",
+            json.dumps(dict(sorted(action_counts.items())), indent=2, sort_keys=True),
+            "```",
+            "",
+            "## Timeline",
+            "",
+        ]
+    )
+    for event in major_events[:160]:
+        actor = f" actor={event.actor_id}" if event.actor_id else ""
+        target = f" target={event.target_id}" if event.target_id else ""
+        lines.append(f"- tick {event.tick}: {event.type}{actor}{target}: {event.summary}")
+    if len(major_events) > 160:
+        lines.append(f"- ... {len(major_events) - 160} additional major events omitted")
+
+    lines.extend(
+        [
+            "",
+            "## Population Graph Data",
+            "",
+            "```csv",
+            (
+                "tick,population,living_beasts,completed_houses,total_food,"
+                "avg_hunger,max_hunger,max_fear"
+            ),
+        ]
+    )
+    for snapshot in result.snapshots:
+        lines.append(
+            f"{snapshot.tick},{snapshot.population},{snapshot.living_beasts},"
+            f"{snapshot.completed_houses},{snapshot.total_food},{snapshot.avg_hunger},"
+            f"{snapshot.max_hunger},{snapshot.max_fear}"
+        )
+    lines.extend(["```", ""])
+    result.report_path.write_text("\n".join(lines), encoding="utf-8")
+
+
+def _print_summary(result: PlaytestResult) -> None:
+    world = result.world
+    chain_summary = ", ".join(
+        f"{chain.name.split(' -> ')[0]}={'yes' if chain.occurred else 'no'}"
+        for chain in result.chains
+    )
+    print(f"PLAYTEST report={result.report_path}")
+    print(f"  simulator={result.simulator_label}")
+    print(f"  overseer={result.overseer_label}")
+    print(f"  ticks={world.tick} status={world.game_status} verdict={result.verdict}")
+    print(
+        "  "
+        f"pop final={world.population} peak={world.peak_population} "
+        f"min={min(snapshot.population for snapshot in result.snapshots)} "
+        f"births={world.total_births} deaths={dict(world.deaths_by_cause)}"
+    )
+    print(
+        "  "
+        f"houses_built={world.houses_built} beasts_killed={world.beasts_killed} "
+        f"score={world.overseer_score}-{world.chaos_score}"
+    )
+    print(f"  chains={chain_summary}")
+
+
+def _dedupe(lines: list[str]) -> list[str]:
+    seen: set[str] = set()
+    deduped: list[str] = []
+    for line in lines:
+        if line in seen:
+            continue
+        seen.add(line)
+        deduped.append(line)
+    return deduped
+
+
+if __name__ == "__main__":
+    main()

src/god_simulator/api/server.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import json
 import time
 from copy import deepcopy
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from http import HTTPStatus
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 from threading import Lock, Thread
@@ -15,17 +15,24 @@ from urllib.request import urlopen
 from god_simulator.config import ConnectorConfig, GameConfig
 from god_simulator.domain import WorldState
 from god_simulator.rendering.claw3d_contract import to_claw3d_snapshot
+from god_simulator.simulation.chaos import (
+    CHAOS_COOLDOWNS,
+    CHAOS_TOOL_LABELS,
+    apply_chaos_action,
+)
 from god_simulator.simulation.connectors.base import WorldSimulator
 from god_simulator.simulation.connectors.factory import create_world_simulator
 from god_simulator.simulation.god_console import (
     GodConsole,
     apply_god_command_plan,
 )
+from god_simulator.simulation.overseer import OverseerController, create_overseer
 from god_simulator.simulation.tick import apply_tick_plan, plan_world_tick
 
 
 def run_server(*, world: WorldState, config: GameConfig) -> None:
     simulator = create_world_simulator(config)
+    overseer = create_overseer(config)
     god_console_config = config.god_console or config.connector
     god_console = (
         GodConsole(god_console_config)
@@ -33,14 +40,14 @@ def run_server(*, world: WorldState, config: GameConfig) -> None:
         else None
     )
     modal_health_warmer = _ModalHealthWarmer(_modal_health_targets(config))
-    handler = _build_handler(world, simulator, god_console, modal_health_warmer)
+    handler = _build_handler(world, simulator, god_console, modal_health_warmer, overseer)
     address = (config.server.host, config.server.port)
     server = ThreadingHTTPServer(address, handler)
     print(f"God Simulator API listening on http://{config.server.host}:{config.server.port}")
     print(f"World simulator connector: {simulator.name}")
     print(
         "Available endpoints: GET /health, GET /state, GET /claw3d/state, "
-        "POST /tick, POST /god-command"
+        "POST /tick, POST /god-command, POST /chaos"
     )
     server.serve_forever()
 
@@ -50,10 +57,12 @@ def _build_handler(
     simulator: WorldSimulator,
     god_console: GodConsole | None = None,
     modal_health_warmer: _HealthWarmer | None = None,
+    overseer: OverseerController | None = None,
 ) -> type[BaseHTTPRequestHandler]:
     lock = Lock()
     tick_status = _TickStatus()
     god_status = _GodCommandStatus()
+    chaos_status = _ChaosStatus()
 
     class GodSimulatorRequestHandler(BaseHTTPRequestHandler):
         server_version = "GodSimulator/0.1"
@@ -97,6 +106,9 @@ def _build_handler(
                         tick_in_progress=tick_status.in_progress,
                         pending_tick=tick_status.pending_tick,
                     )
+                    payload["simulation"]["chaos_tools"] = _chaos_tools_payload(
+                        chaos_status, world.tick
+                    )
                 if modal_health_warmer is not None:
                     payload["simulation"]["models"] = modal_health_warmer.statuses()
                 self._send_json(payload)
@@ -142,7 +154,12 @@ def _build_handler(
                 assert planning_world is not None
                 assert next_tick is not None
                 try:
-                    planned_tick, plan = plan_world_tick(planning_world, simulator, next_tick)
+                    planned_tick, plan = plan_world_tick(
+                        planning_world,
+                        simulator,
+                        next_tick,
+                        overseer=overseer,
+                    )
                 except Exception as exc:
                     with lock:
                         tick_status.in_progress = False
@@ -170,11 +187,87 @@ def _build_handler(
                 self._handle_god_command()
                 return
 
+            if self.path == "/chaos":
+                self._handle_chaos_action()
+                return
+
             self._send_json(
                 {"error": "not_found", "path": self.path},
                 status=HTTPStatus.NOT_FOUND,
             )
 
+        def _handle_chaos_action(self) -> None:
+            try:
+                action = self._read_json_field("action")
+            except ValueError as exc:
+                self._send_json(
+                    {"error": "invalid_request", "message": str(exc)},
+                    status=HTTPStatus.BAD_REQUEST,
+                )
+                return
+
+            if action not in CHAOS_COOLDOWNS:
+                self._send_json(
+                    {
+                        "error": "unknown_chaos_action",
+                        "message": f"Unknown chaos action: {action}",
+                        "actions": sorted(CHAOS_COOLDOWNS),
+                    },
+                    status=HTTPStatus.BAD_REQUEST,
+                )
+                return
+
+            with lock:
+                if tick_status.in_progress:
+                    self._send_json(
+                        {
+                            "error": "tick_in_progress",
+                            "message": "Chaos tools are disabled while a tick is running.",
+                            **_tick_status_payload(tick_status),
+                        },
+                        status=HTTPStatus.CONFLICT,
+                    )
+                    return
+
+                last_used = chaos_status.last_used.get(action)
+                if last_used is not None:
+                    remaining = last_used + CHAOS_COOLDOWNS[action] - world.tick
+                    if remaining > 0:
+                        self._send_json(
+                            {
+                                "error": "chaos_on_cooldown",
+                                "message": (
+                                    f"{CHAOS_TOOL_LABELS[action]} ready in "
+                                    f"{remaining} ticks."
+                                ),
+                                "remaining_ticks": remaining,
+                            },
+                            status=HTTPStatus.CONFLICT,
+                        )
+                        return
+
+                applied = apply_chaos_action(world, action)
+                if applied:
+                    chaos_status.last_used[action] = world.tick
+                snapshot = to_claw3d_snapshot(
+                    world,
+                    tick_in_progress=tick_status.in_progress,
+                    pending_tick=tick_status.pending_tick,
+                )
+                snapshot["simulation"]["chaos_tools"] = _chaos_tools_payload(
+                    chaos_status, world.tick
+                )
+                response = {
+                    "action": action,
+                    "applied": applied,
+                    "summary": applied[0]
+                    if applied
+                    else f"{CHAOS_TOOL_LABELS[action]} had no effect.",
+                    "snapshot": snapshot,
+                }
+
+            self._send_json(response)
+
         def log_message(self, format: str, *args: object) -> None:
             print(f"{self.address_string()} - {format % args}")
 
@@ -273,6 +366,9 @@ def _build_handler(
             self.send_header("Access-Control-Allow-Headers", "Content-Type")
 
         def _read_command(self) -> str:
+            return self._read_json_field("command")
+
+        def _read_json_field(self, field: str) -> str:
             length_raw = self.headers.get("Content-Length")
             if not length_raw:
                 raise ValueError("Missing request body.")
@@ -290,10 +386,10 @@ def _build_handler(
 
             if not isinstance(payload, dict):
                 raise ValueError("Request body must be a JSON object.")
-            command = payload.get("command")
-            if not isinstance(command, str) or not command.strip():
-                raise ValueError("Expected non-empty 'command'.")
-            return command.strip()
+            value = payload.get(field)
+            if not isinstance(value, str) or not value.strip():
+                raise ValueError(f"Expected non-empty '{field}'.")
+            return value.strip()
 
     return GodSimulatorRequestHandler
 
@@ -309,6 +405,27 @@ class _GodCommandStatus:
     in_progress: bool = False
 
 
+@dataclass(slots=True)
+class _ChaosStatus:
+    last_used: dict[str, int] = field(default_factory=dict)
+
+
+def _chaos_tools_payload(chaos_status: _ChaosStatus, tick: int) -> list[dict[str, Any]]:
+    tools: list[dict[str, Any]] = []
+    for action, cooldown in CHAOS_COOLDOWNS.items():
+        last_used = chaos_status.last_used.get(action)
+        remaining = 0 if last_used is None else max(0, last_used + cooldown - tick)
+        tools.append(
+            {
+                "action": action,
+                "label": CHAOS_TOOL_LABELS[action],
+                "cooldown_ticks": cooldown,
+                "remaining_ticks": remaining,
+            }
+        )
+    return tools
+
+
 def _tick_status_payload(tick_status: _TickStatus) -> dict[str, Any]:
     return {
         "tick_in_progress": tick_status.in_progress,

src/god_simulator/config.py

@@ -8,6 +8,7 @@ from typing import Any, Literal, cast
 
 TerrainKind = Literal["plain_green"]
 ConnectorKind = Literal["deterministic", "openai_compatible"]
+OverseerMode = Literal["off", "advisor", "autopilot"]
 
 
 @dataclass(frozen=True, slots=True)
@@ -52,6 +53,16 @@ class ConnectorConfig:
     extra_body: dict[str, Any] | None = None
 
 
+@dataclass(frozen=True, slots=True)
+class OverseerConfig:
+    mode: OverseerMode = "off"
+    cycle_ticks: int = 8
+    max_directives: int = 3
+    connector: ConnectorConfig = field(
+        default_factory=lambda: ConnectorConfig(type="deterministic")
+    )
+
+
 @dataclass(frozen=True, slots=True)
 class GameConfig:
     world: WorldConfig
@@ -62,6 +73,7 @@ class GameConfig:
         default_factory=lambda: ConnectorConfig(type="deterministic")
     )
     god_console: ConnectorConfig | None = None
+    overseer: OverseerConfig = field(default_factory=OverseerConfig)
 
 
 def load_game_config(path: Path) -> GameConfig:
@@ -78,6 +90,7 @@ def parse_game_config(raw: dict[str, Any]) -> GameConfig:
     server = _required_mapping(raw, "server")
     connector = _optional_mapping(raw, "connector") or {"type": "deterministic"}
     god_console = _optional_mapping(raw, "god_console")
+    overseer = _optional_mapping(raw, "overseer")
 
     terrain_raw = _required_str(world, "terrain")
     if terrain_raw != "plain_green":
@@ -100,6 +113,46 @@ def parse_game_config(raw: dict[str, Any]) -> GameConfig:
         ),
         connector=_parse_connector_config(connector),
         god_console=_parse_connector_config(god_console) if god_console else None,
+        overseer=_parse_overseer_config(overseer),
+    )
+
+
+def _parse_overseer_config(raw: dict[str, Any] | None) -> OverseerConfig:
+    if raw is None:
+        return OverseerConfig()
+    mode_raw = _optional_str(raw, "mode") or "off"
+    if mode_raw not in ("off", "advisor", "autopilot"):
+        raise ValueError(f"Unsupported overseer mode: {mode_raw}")
+    connector_raw = _optional_mapping(raw, "connector")
+    if connector_raw is None:
+        connector_keys = {
+            "type",
+            "base_url",
+            "api_url",
+            "model",
+            "api_key_env",
+            "timeout_seconds",
+            "max_tokens",
+            "temperature",
+            "top_p",
+            "tool_choice",
+            "max_parallel_npc_calls",
+            "fallback_to_deterministic",
+            "extra_body",
+            "base_url_env",
+            "api_url_env",
+            "model_env",
+        }
+        connector_raw = {
+            key: value
+            for key, value in raw.items()
+            if key in connector_keys
+        } or {"type": "deterministic"}
+    return OverseerConfig(
+        mode=cast(OverseerMode, mode_raw),
+        cycle_ticks=_optional_positive_int(raw, "cycle_ticks") or 8,
+        max_directives=_optional_positive_int(raw, "max_directives") or 3,
+        connector=_parse_connector_config(connector_raw),
     )
 
 

src/god_simulator/domain.py

@@ -24,6 +24,9 @@ CitizenMode = Literal[
     "fleeing",
     "recovering",
 ]
+NpcRole = Literal["guard", "builder", "gatherer"]
+HouseState = Literal["under_construction", "completed"]
+GameStatus = Literal["running", "win_population", "win_survival", "lose"]
 
 
 @dataclass(frozen=True, slots=True)
@@ -123,12 +126,24 @@ class Npc:
     # Survival core-loop state (deterministic, engine-owned).
     hunger: float = 25.0
     fear: float = 0.0
+    safety: float = 0.0
+    age: int = 0
+    max_age: int = 400
+    reproduction_cooldown: int = 0
+    importance: float = 1.0
     survival_goal: str = "routine_life"
     inventory_food: int = 0
     inventory_herbs: int = 0
     inventory_wood: int = 0
     inventory_weapon: int = 0
     help_target_id: str | None = None
+    home_house_id: str | None = None
+    build_target_house_id: str | None = None
+    patrol_index: int = 0
+    resources_transferred: int = 0
+    beasts_killed: int = 0
+    children_count: int = 0
+    houses_built: int = 0
 
 
 @dataclass(slots=True)
@@ -149,9 +164,35 @@ class Beast:
     attack_range: float = 1.5  # in tiles (one tile == one terrain block)
     speed: float = 1.0  # in tiles per tick
     target_npc_id: str | None = None
+    target_house_id: str | None = None
+    retreat_ticks: int = 0
     state: str = "hunting"  # hunting | attacking | retreating | dead
 
 
+@dataclass(slots=True)
+class House:
+    id: str
+    position: Vec3
+    owner_ids: list[str] = field(default_factory=list)
+    hp: float = 60.0
+    max_hp: float = 60.0
+    state: HouseState = "completed"
+    build_progress: int = 10
+    capacity: int = 3
+    occupant_ids: list[str] = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class WorldLogEvent:
+    tick: int
+    type: str
+    summary: str
+    severity: Literal["good", "neutral", "warning", "danger"] = "neutral"
+    actor_id: str | None = None
+    target_id: str | None = None
+    object_id: str | None = None
+
+
 @dataclass(slots=True)
 class Terrain:
     kind: Literal["plain_green"]
@@ -180,7 +221,29 @@ class WorldState:
     last_action_debug: list[dict[str, Any]] = field(default_factory=list)
     resource_nodes: list[ResourceNode] = field(default_factory=list)
     beasts: list[Beast] = field(default_factory=list)
+    houses: list[House] = field(default_factory=list)
     active_events: list[WorldEvent] = field(default_factory=list)
+    event_log: list[WorldLogEvent] = field(default_factory=list)
+    game_status: GameStatus = "running"
+    population: int = 0
+    population_cap: int = 12
+    total_births: int = 0
+    deaths_by_cause: dict[str, int] = field(default_factory=dict)
+    houses_built: int = 0
+    beasts_killed: int = 0
+    peak_population: int = 0
+    overseer_score: int = 0
+    chaos_score: int = 0
+    chaos_intervention_until: int = -1
+    famine_until: int = -1
+    famine_saved_max: dict[str, int] = field(default_factory=dict)
+    overseer_mode: Literal["off", "advisor", "autopilot"] = "off"
+    overseer_cycle_ticks: int = 8
+    overseer_last_tick: int | None = None
+    overseer_last_thoughts: str | None = None
+    overseer_priority_alert: str | None = None
+    overseer_last_directives: list[dict[str, Any]] = field(default_factory=list)
+    overseer_status: str = "idle"
 
     def to_dict(self) -> dict[str, Any]:
         return asdict(self)

src/god_simulator/rendering/claw3d_contract.py

@@ -19,6 +19,30 @@ def to_claw3d_snapshot(
             "last_tick_source": world.last_tick_source,
             "tick_in_progress": tick_in_progress,
             "pending_tick": pending_tick,
+            "game_status": world.game_status,
+            "population": world.population,
+            "population_cap": world.population_cap,
+            "peak_population": world.peak_population,
+            "scoreboard": {
+                "overseer": world.overseer_score,
+                "chaos": world.chaos_score,
+            },
+            "stats": {
+                "total_births": world.total_births,
+                "deaths_by_cause": dict(world.deaths_by_cause),
+                "houses_built": world.houses_built,
+                "beasts_killed": world.beasts_killed,
+            },
+            "famine_until": world.famine_until,
+            "overseer": {
+                "mode": world.overseer_mode,
+                "cycle_ticks": world.overseer_cycle_ticks,
+                "last_tick": world.overseer_last_tick,
+                "status": world.overseer_status,
+                "thoughts": world.overseer_last_thoughts,
+                "priority_alert": world.overseer_priority_alert,
+                "directives": list(world.overseer_last_directives),
+            },
         },
         "terrain": {
             "kind": world.terrain.kind,
@@ -53,7 +77,13 @@ def to_claw3d_snapshot(
                     "is_alive": is_alive(npc),
                     "hunger": round(npc.hunger, 1),
                     "fear": round(npc.fear, 1),
+                    "safety": round(npc.safety, 1),
+                    "age": npc.age,
+                    "max_age": npc.max_age,
+                    "reproduction_cooldown": npc.reproduction_cooldown,
+                    "importance": npc.importance,
                     "goal": npc.survival_goal,
+                    "home_house_id": npc.home_house_id,
                     "inventory": {
                         "food": npc.inventory_food,
                         "herbs": npc.inventory_herbs,
@@ -118,12 +148,31 @@ def to_claw3d_snapshot(
                     "z": beast.position.z,
                 },
                 "health": round(beast.health, 1),
-                "max_health": 180,
+                "max_health": 60,
                 "state": beast.state,
                 "target_npc_id": beast.target_npc_id,
+                "target_house_id": beast.target_house_id,
             }
             for beast in world.beasts
         ],
+        "houses": [
+            {
+                "id": house.id,
+                "position": {
+                    "x": house.position.x,
+                    "y": house.position.y,
+                    "z": house.position.z,
+                },
+                "owner_ids": list(house.owner_ids),
+                "hp": round(house.hp, 1),
+                "max_hp": round(house.max_hp, 1),
+                "state": house.state,
+                "build_progress": house.build_progress,
+                "capacity": house.capacity,
+                "occupant_ids": list(house.occupant_ids),
+            }
+            for house in world.houses
+        ],
         "active_events": [
             {
                 "tick_created": event.tick_created,
@@ -141,4 +190,16 @@ def to_claw3d_snapshot(
             }
             for event in world.active_events
         ],
+        "event_log": [
+            {
+                "tick": event.tick,
+                "type": event.type,
+                "actor_id": event.actor_id,
+                "target_id": event.target_id,
+                "object_id": event.object_id,
+                "summary": event.summary,
+                "severity": event.severity,
+            }
+            for event in world.event_log[-50:]
+        ],
     }

src/god_simulator/simulation/chaos.py

@@ -0,0 +1,142 @@
+"""Deterministic Chaos tools (God Console quick-buttons).
+
+Unlike the freeform LLM god console, these apply engine-validated effects
+directly: beasts actually spawn, famine actually halves food nodes, and the
+maniac directive flows through the existing hostile-directive pipeline.
+Cooldowns (in ticks) follow GAME_DESIGN.md §11.
+"""
+
+from __future__ import annotations
+
+import random
+
+from god_simulator.domain import Beast, WorldState
+from god_simulator.simulation.mechanics import is_alive
+from god_simulator.simulation.survival import (
+    _log_event,
+    _next_beast_index,
+    _random_map_edge_position,
+)
+
+CHAOS_COOLDOWNS: dict[str, int] = {
+    "spawn_beast": 20,
+    "beast_pack": 80,
+    "famine": 120,
+    "maniac": 100,
+}
+CHAOS_TOOL_LABELS: dict[str, str] = {
+    "spawn_beast": "Spawn Beast",
+    "beast_pack": "Beast Pack",
+    "famine": "Famine",
+    "maniac": "Maniac",
+}
+FAMINE_DURATION_TICKS = 180
+MANIAC_DIRECTIVE = (
+    "Madness consumes you. Attack the nearest villager — ignore work, ignore friends."
+)
+CHAOS_BEAST_CAP = 6  # God Console may exceed MAX_BEASTS (3) up to this.
+
+
+def apply_chaos_action(world: WorldState, action: str) -> list[str]:
+    """Apply one chaos quick-button. Returns human-readable applied lines."""
+    if action == "spawn_beast":
+        applied = _spawn_chaos_beasts(world, count=1)
+    elif action == "beast_pack":
+        applied = _spawn_chaos_beasts(world, count=3)
+    elif action == "famine":
+        applied = _apply_famine(world)
+    elif action == "maniac":
+        applied = _apply_maniac(world)
+    else:
+        raise ValueError(f"Unknown chaos action: {action}")
+
+    if applied:
+        world.chaos_intervention_until = max(
+            world.chaos_intervention_until, world.tick + 100
+        )
+    return applied
+
+
+def _spawn_chaos_beasts(world: WorldState, *, count: int) -> list[str]:
+    living = sum(1 for beast in world.beasts if beast.state != "dead")
+    allowed = max(0, min(count, CHAOS_BEAST_CAP - living))
+    if allowed == 0:
+        return []
+
+    rng = random.Random(f"{world.seed}:{world.tick}:chaos_beast")
+    applied: list[str] = []
+    for _ in range(allowed):
+        beast = Beast(
+            id=f"beast_{_next_beast_index(world)}",
+            position=_random_map_edge_position(world, rng),
+            health=120.0,
+            damage=15.0,
+        )
+        world.beasts.append(beast)
+        _log_event(
+            world,
+            "chaos_event",
+            f"Chaos unleashed {beast.id} at the edge of the map",
+            severity="danger",
+            actor_id=beast.id,
+        )
+        applied.append(f"{beast.id} unleashed at the map edge.")
+    return applied
+
+
+def _apply_famine(world: WorldState) -> list[str]:
+    if world.famine_until >= world.tick:
+        return []
+
+    affected = 0
+    for node in world.resource_nodes:
+        if node.resource_type != "food":
+            continue
+        world.famine_saved_max[node.id] = node.max_amount
+        node.amount //= 2
+        node.max_amount = max(1, node.max_amount // 2)
+        affected += 1
+    if affected == 0:
+        return []
+
+    world.famine_until = world.tick + FAMINE_DURATION_TICKS
+    _log_event(
+        world,
+        "chaos_event",
+        f"Famine grips the land: {affected} food nodes halved for "
+        f"{FAMINE_DURATION_TICKS} ticks",
+        severity="danger",
+    )
+    return [f"Famine: {affected} food nodes halved for {FAMINE_DURATION_TICKS} ticks."]
+
+
+def end_famine_if_due(world: WorldState) -> None:
+    """Restore food node caps once the famine duration elapses."""
+    if world.famine_until < 0 or world.tick <= world.famine_until:
+        return
+    for node in world.resource_nodes:
+        saved = world.famine_saved_max.get(node.id)
+        if saved is not None:
+            node.max_amount = saved
+    world.famine_saved_max.clear()
+    world.famine_until = -1
+    _log_event(world, "chaos_event", "The famine has ended", severity="neutral")
+
+
+def _apply_maniac(world: WorldState) -> list[str]:
+    candidates = [npc for npc in world.npcs if is_alive(npc)]
+    if not candidates:
+        return []
+
+    rng = random.Random(f"{world.seed}:{world.tick}:chaos_maniac")
+    victim = rng.choice(candidates)
+    victim.god_directive = MANIAC_DIRECTIVE
+    victim.personality = "violent maniac"
+    _log_event(
+        world,
+        "chaos_event",
+        f"{victim.name} has gone mad and turned on the village!",
+        severity="danger",
+        actor_id=victim.id,
+    )
+    return [f"{victim.name} has gone mad and turned on the village."]

src/god_simulator/simulation/connectors/base.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Literal, Protocol, TypeAlias
+from typing import Any, Literal, Protocol, TypeAlias
 
 from god_simulator.domain import Vec3, WorldState
 
@@ -25,6 +25,10 @@ SurvivalActionKind: TypeAlias = Literal[
     "heal",
     "move_to_resource",
     "move_to",
+    "go_home",
+    "patrol",
+    "build",
+    "wander",
     "communicate",
     "transfer",
     "trade",
@@ -100,6 +104,7 @@ class ActionDebugTrace:
 class TickPlan:
     source: str
     directives: list[NpcDirective]
+    overseer: dict[str, Any] | None = None
 
 
 class WorldSimulator(Protocol):

src/god_simulator/simulation/connectors/openai_compatible.py

@@ -35,6 +35,7 @@ from god_simulator.simulation.memory import recent_meaningful_memories
 from god_simulator.simulation.perception import CitizenPerception
 from god_simulator.simulation.survival import (
     GOAL_ACTIONS,
+    allowed_actions_for_npc,
     build_memory_summary,
     build_perception,
     build_relationships_summary,
@@ -212,6 +213,45 @@ TOOL_DEFINITIONS: dict[str, dict[str, Any]] = {
             },
         },
     },
+    "go_home": {
+        "type": "function",
+        "function": {
+            "name": "go_home",
+            "description": "Move into the nearest completed house to regain safety.",
+            "parameters": {
+                "type": "object",
+                "properties": {},
+                "required": [],
+                "additionalProperties": False,
+            },
+        },
+    },
+    "patrol": {
+        "type": "function",
+        "function": {
+            "name": "patrol",
+            "description": "Guard action: patrol between village houses and intercept threats.",
+            "parameters": {
+                "type": "object",
+                "properties": {},
+                "required": [],
+                "additionalProperties": False,
+            },
+        },
+    },
+    "build": {
+        "type": "function",
+        "function": {
+            "name": "build",
+            "description": "Builder action: spend wood to start or continue building a house.",
+            "parameters": {
+                "type": "object",
+                "properties": {},
+                "required": [],
+                "additionalProperties": False,
+            },
+        },
+    },
     "transfer": {
         "type": "function",
         "function": {
@@ -274,6 +314,10 @@ TOOL_DEFINITIONS: dict[str, dict[str, Any]] = {
 
 def build_tool_list_for_goal(goal: str) -> list[dict[str, Any]]:
     allowed = GOAL_ACTIONS.get(goal, [])
+    return build_tool_list_for_actions(allowed)
+
+
+def build_tool_list_for_actions(allowed: Sequence[str]) -> list[dict[str, Any]]:
     return [TOOL_DEFINITIONS[action] for action in allowed[:7] if action in TOOL_DEFINITIONS]
 
 
@@ -502,9 +546,9 @@ class OpenAICompatibleWorldSimulator:
 
         if is_survival_world(world):
             survival_goal = select_survival_goal(npc, world)
-            allowed = GOAL_ACTIONS.get(survival_goal) or ["observe"]
+            allowed = allowed_actions_for_npc(world, npc, survival_goal)
             messages = _build_survival_messages(world, next_tick, npc, survival_goal, allowed)
-            tools = build_tool_list_for_goal(survival_goal)
+            tools = build_tool_list_for_actions(allowed)
             if not tools:
                 tools = _action_tools(cast(list[ActionKind], allowed))
         else:
@@ -642,15 +686,22 @@ def _build_survival_messages(
         "npc_id": npc.id,
         "tick": world.tick,
         "state": {
+            "role": npc.role,
             "health": round(npc.health),
             "hunger": round(npc.hunger),
             "fear": round(npc.fear),
+            "safety": round(npc.safety),
+            "age": npc.age,
+            "max_age": npc.max_age,
+            "reproduction_cooldown": npc.reproduction_cooldown,
+            "importance": npc.importance,
             "goal": goal,
         },
         "status": {
             "health": round(npc.health),
             "hunger": round(npc.hunger),
             "fear": round(npc.fear),
+            "safety": round(npc.safety),
         },
         "inventory": {
             "food": npc.inventory_food,
@@ -660,6 +711,17 @@ def _build_survival_messages(
         },
         "goal": goal,
         "allowed_actions": list(allowed_actions),
+        "role_rules": _role_rules_for_prompt(npc.role),
+        "houses": [
+            {
+                "id": house.id,
+                "state": house.state,
+                "hp": round(house.hp),
+                "position": {"x": house.position.x, "z": house.position.z},
+                "occupants": list(house.occupant_ids),
+            }
+            for house in world.houses
+        ],
         "perception": build_perception(npc, world),
         "memory": build_memory_summary(npc, last_n=3, current_tick=world.tick),
         "relationships": build_relationships_summary(npc, world),
@@ -681,6 +743,23 @@ def _build_survival_messages(
     ]
 
 
+def _role_rules_for_prompt(role: str) -> list[str]:
+    if role == "guard":
+        return [
+            "You are a guard: attack, defend, and patrol threats near the village.",
+            "Do not gather resources.",
+        ]
+    if role == "builder":
+        return [
+            "You are a builder: gather only wood and use build to construct houses.",
+            "Do not attack.",
+        ]
+    return [
+        "You are a gatherer: gather resources, transfer supplies, eat, heal, flee, and communicate.",
+        "Do not choose attack unless the engine has specifically exposed it for self-defense.",
+    ]
+
+
 def _npc_context(
     world: WorldState,
     npc: Npc,
@@ -915,6 +994,10 @@ def _action_kind(raw: object) -> ActionKind | None:
         "heal",
         "move_to_resource",
         "move_to",
+        "go_home",
+        "patrol",
+        "build",
+        "wander",
         "communicate",
         "transfer",
         "trade",

src/god_simulator/simulation/god_console.py

@@ -277,9 +277,9 @@ def apply_god_command_plan(world: WorldState, plan: GodCommandPlan) -> list[str]
                 if health is None:
                     continue
                 npc.health = health
-                if npc.health >= 0 and npc.intention == "dead":
+                if npc.health > 0 and npc.intention == "dead":
                     npc.intention = "idle"
-                if npc.health < 0:
+                if npc.health <= 0:
                     npc.intention = "dead"
                 applied.append(f"{npc.name} health set to {npc.health}.")
             case "set_npc_attack_damage":
@@ -319,6 +319,8 @@ def apply_god_command_plan(world: WorldState, plan: GodCommandPlan) -> list[str]
                 )
                 applied.append(f"{npc.name} moved.")
 
+    if applied:
+        world.chaos_intervention_until = max(world.chaos_intervention_until, world.tick + 100)
     return applied
 
 

src/god_simulator/simulation/mechanics.py

@@ -14,7 +14,7 @@ MAX_WALK_DISTANCE = 1.0 * BLOCK_SIZE
 
 
 def is_alive(npc: Npc) -> bool:
-    return npc.health >= 0
+    return npc.health > 0
 
 
 def distance_between(first: Npc, second: Npc) -> float:

src/god_simulator/simulation/overseer.py

@@ -0,0 +1,536 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+import os
+from pathlib import Path
+from typing import Any, Protocol, cast
+
+from god_simulator.config import ConnectorConfig, GameConfig, OverseerConfig
+from god_simulator.domain import Npc, WorldLogEvent, WorldState
+from god_simulator.simulation.connectors.base import NpcDirective, TickPlan
+from god_simulator.simulation.mechanics import is_alive, vec_distance
+from god_simulator.simulation.roles import normalize_role
+from god_simulator.simulation.survival import (
+    allowed_actions_for_npc,
+    nearest_beast,
+    nearest_house,
+    nearest_resource_for_npc,
+    select_goal,
+)
+
+PROMPT_PATH = Path(__file__).resolve().parents[3] / "prompts" / "overseer.md"
+
+
+@dataclass(frozen=True, slots=True)
+class OverseerDirective:
+    npc_id: str
+    directive: str
+
+
+@dataclass(frozen=True, slots=True)
+class OverseerDecision:
+    thoughts: str
+    directives: list[OverseerDirective]
+    priority_alert: str
+
+
+class OverseerClient(Protocol):
+    def decide(self, context: dict[str, Any]) -> OverseerDecision:
+        """Return one strict Overseer decision for the supplied compact context."""
+
+
+class OpenAICompatibleOverseerClient:
+    def __init__(
+        self,
+        config: ConnectorConfig,
+        *,
+        prompt_path: Path = PROMPT_PATH,
+    ) -> None:
+        self._config = config
+        self._prompt = prompt_path.read_text(encoding="utf-8")
+
+    def decide(self, context: dict[str, Any]) -> OverseerDecision:
+        if self._config.type != "openai_compatible":
+            raise ValueError("Overseer connector must be openai_compatible.")
+        if not self._config.model:
+            raise ValueError("Overseer connector requires a model.")
+        base_url = _resolve_base_url(self._config)
+        if not base_url:
+            raise ValueError("Overseer connector requires base_url or api_url.")
+
+        from openai import OpenAI
+
+        client = OpenAI(
+            api_key=_resolve_api_key(self._config),
+            base_url=base_url,
+            timeout=self._config.timeout_seconds,
+            max_retries=0,
+        )
+        request: dict[str, Any] = {
+            "model": self._config.model,
+            "messages": [
+                {"role": "system", "content": self._prompt},
+                {"role": "user", "content": json.dumps(context, ensure_ascii=False)},
+            ],
+            "temperature": self._config.temperature,
+            "top_p": self._config.top_p,
+            "max_tokens": self._config.max_tokens,
+        }
+        if self._config.extra_body:
+            request["extra_body"] = self._config.extra_body
+        completion = client.chat.completions.create(**request)
+        response = completion.model_dump()
+        content = response["choices"][0]["message"].get("content")
+        if not isinstance(content, str):
+            raise RuntimeError("Overseer response did not contain text content.")
+        return parse_overseer_decision(content)
+
+
+class ScriptedOverseerClient:
+    """Deterministic fake used by headless tests."""
+
+    def decide(self, context: dict[str, Any]) -> OverseerDecision:
+        npcs = context.get("npcs", [])
+        guard = _first_role(npcs, "guard")
+        builder = _first_role(npcs, "builder")
+        gatherer = _first_role(npcs, "gatherer")
+        directives: list[OverseerDirective] = []
+        if guard is not None:
+            directives.append(
+                OverseerDirective(npc_id=guard["id"], directive="attack the nearest beast")
+            )
+        if builder is not None:
+            directives.append(
+                OverseerDirective(
+                    npc_id=builder["id"],
+                    directive="attack beast_1 even though this should be validated",
+                )
+            )
+        if gatherer is not None:
+            directives.append(OverseerDirective(npc_id=gatherer["id"], directive="go home"))
+        return OverseerDecision(
+            thoughts="Mock Overseer: test guard attack, invalid builder command, and shelter order.",
+            directives=directives,
+            priority_alert="Mock directive validation check",
+        )
+
+
+@dataclass(slots=True)
+class OverseerController:
+    mode: str
+    cycle_ticks: int
+    max_directives: int
+    client: OverseerClient | None
+
+    def augment_plan(self, world: WorldState, next_tick: int, plan: TickPlan) -> TickPlan:
+        if self.mode == "off" or self.client is None:
+            return plan
+        if self.cycle_ticks <= 0 or next_tick % self.cycle_ticks != 0:
+            return plan
+
+        context = build_overseer_context(world, next_tick)
+        try:
+            decision = self.client.decide(context)
+        except Exception as exc:
+            metadata = {
+                "mode": self.mode,
+                "tick": next_tick,
+                "status": "skipped",
+                "skipped_reason": str(exc),
+                "thoughts": "",
+                "priority_alert": "",
+                "directives": [],
+            }
+            return TickPlan(
+                source=f"{plan.source}+overseer_skipped",
+                directives=plan.directives,
+                overseer=metadata,
+            )
+
+        raw_directives = decision.directives[: self.max_directives]
+        issued: list[dict[str, Any]] = []
+        converted: list[NpcDirective] = []
+        if self.mode == "autopilot":
+            for raw in raw_directives:
+                directive = _directive_to_engine(world, raw)
+                issued.append(
+                    {
+                        "npc_id": raw.npc_id,
+                        "directive": raw.directive,
+                        "applied": directive is not None,
+                        "action": directive.action if directive is not None else None,
+                    }
+                )
+                if directive is not None:
+                    converted.append(directive)
+        else:
+            issued = []
+
+        metadata = {
+            "mode": self.mode,
+            "tick": next_tick,
+            "status": "advisor"
+            if self.mode != "autopilot"
+            else ("applied" if converted else "no_directives"),
+            "thoughts": decision.thoughts,
+            "priority_alert": decision.priority_alert,
+            "directives": issued,
+        }
+        if self.mode != "autopilot":
+            return TickPlan(source=plan.source, directives=plan.directives, overseer=metadata)
+
+        merged = {directive.npc_id: directive for directive in plan.directives}
+        for directive in converted:
+            merged[directive.npc_id] = directive
+        return TickPlan(
+            source=f"{plan.source}+overseer",
+            directives=list(merged.values()),
+            overseer=metadata,
+        )
+
+
+def create_overseer(config: GameConfig) -> OverseerController | None:
+    overseer_config = config.overseer
+    if overseer_config.mode == "off":
+        return OverseerController(
+            mode="off",
+            cycle_ticks=overseer_config.cycle_ticks,
+            max_directives=overseer_config.max_directives,
+            client=None,
+        )
+    return OverseerController(
+        mode=overseer_config.mode,
+        cycle_ticks=overseer_config.cycle_ticks,
+        max_directives=overseer_config.max_directives,
+        client=_client_from_config(overseer_config),
+    )
+
+
+def scripted_overseer_controller(
+    *,
+    mode: str = "autopilot",
+    cycle_ticks: int = 1,
+    max_directives: int = 3,
+) -> OverseerController:
+    return OverseerController(
+        mode=mode,
+        cycle_ticks=cycle_ticks,
+        max_directives=max_directives,
+        client=ScriptedOverseerClient(),
+    )
+
+
+def build_overseer_context(world: WorldState, next_tick: int) -> dict[str, Any]:
+    alive = [npc for npc in world.npcs if is_alive(npc)]
+    role_counts: dict[str, int] = {"gatherer": 0, "guard": 0, "builder": 0}
+    for npc in alive:
+        role_counts[normalize_role(npc.role)] += 1
+    critical = sorted(
+        alive,
+        key=lambda npc: (
+            npc.health,
+            -npc.hunger,
+            -npc.importance,
+            0 if normalize_role(npc.role) == "builder" else 1,
+            npc.id,
+        ),
+    )[:10]
+    return {
+        "tick": world.tick,
+        "next_tick": next_tick,
+        "game_status": world.game_status,
+        "population": world.population,
+        "population_cap": world.population_cap,
+        "roles": role_counts,
+        "scoreboard": {
+            "overseer": world.overseer_score,
+            "chaos": world.chaos_score,
+        },
+        "npcs": [
+            {
+                "id": npc.id,
+                "name": npc.name,
+                "role": normalize_role(npc.role),
+                "hp": round(npc.health, 1),
+                "hunger": round(npc.hunger, 1),
+                "safety": round(npc.safety, 1),
+                "importance": npc.importance,
+                "goal": npc.survival_goal,
+                "inventory": {
+                    "food": npc.inventory_food,
+                    "herbs": npc.inventory_herbs,
+                    "wood": npc.inventory_wood,
+                    "weapon": npc.inventory_weapon,
+                },
+                "allowed_actions": allowed_actions_for_npc(world, npc, select_goal(npc, world)),
+                "position": {"x": npc.position.x, "z": npc.position.z},
+            }
+            for npc in critical
+        ],
+        "houses": [
+            {
+                "id": house.id,
+                "state": house.state,
+                "hp": round(house.hp, 1),
+                "capacity": house.capacity,
+                "occupants": list(house.occupant_ids),
+                "position": {"x": house.position.x, "z": house.position.z},
+            }
+            for house in world.houses
+        ],
+        "resources": _resource_totals(world),
+        "beasts": [
+            {
+                "id": beast.id,
+                "hp": round(beast.health, 1),
+                "state": beast.state,
+                "target_npc_id": beast.target_npc_id,
+                "target_house_id": beast.target_house_id,
+                "position": {"x": beast.position.x, "z": beast.position.z},
+            }
+            for beast in world.beasts
+            if beast.state != "dead"
+        ],
+        "current_threats": _current_threats(world),
+        "recent_events": [
+            {
+                "tick": event.tick,
+                "type": event.type,
+                "actor_id": event.actor_id,
+                "target_id": event.target_id,
+                "summary": event.summary,
+                "severity": event.severity,
+            }
+            for event in world.event_log[-20:]
+        ],
+    }
+
+
+def parse_overseer_decision(content: str) -> OverseerDecision:
+    raw = json.loads(content)
+    if not isinstance(raw, dict):
+        raise ValueError("Overseer JSON must be an object.")
+    thoughts = _short_text(raw.get("thoughts"), limit=500)
+    priority_alert = _short_text(raw.get("priority_alert"), limit=240)
+    directives_raw = raw.get("directives")
+    if not isinstance(directives_raw, list):
+        raise ValueError("Overseer JSON must include a directives array.")
+    directives: list[OverseerDirective] = []
+    for item in directives_raw[:3]:
+        if not isinstance(item, dict):
+            continue
+        npc_id = _short_text(item.get("npc_id"), limit=80)
+        directive = _short_text(item.get("directive"), limit=240)
+        if npc_id and directive:
+            directives.append(OverseerDirective(npc_id=npc_id, directive=directive))
+    return OverseerDecision(
+        thoughts=thoughts or "",
+        directives=directives,
+        priority_alert=priority_alert or "",
+    )
+
+
+def apply_overseer_metadata(world: WorldState, metadata: dict[str, Any] | None) -> None:
+    if metadata is None:
+        return
+    world.overseer_mode = str(metadata.get("mode") or world.overseer_mode)
+    world.overseer_last_tick = int(metadata.get("tick") or world.tick)
+    world.overseer_status = str(metadata.get("status") or "idle")
+    world.overseer_last_thoughts = _short_text(metadata.get("thoughts"), limit=500)
+    world.overseer_priority_alert = _short_text(metadata.get("priority_alert"), limit=240)
+    directives = metadata.get("directives")
+    world.overseer_last_directives = directives if isinstance(directives, list) else []
+
+    if world.overseer_status == "skipped":
+        reason = _short_text(metadata.get("skipped_reason"), limit=240) or "unknown error"
+        _append_log(
+            world,
+            "overseer_skipped",
+            f"Overseer skipped: {reason}",
+            severity="warning",
+        )
+        return
+
+    if world.overseer_last_thoughts:
+        _append_log(
+            world,
+            "overseer_thoughts",
+            world.overseer_last_thoughts,
+            severity="neutral",
+        )
+
+    npcs_by_id = {npc.id: npc for npc in world.npcs}
+    for directive in world.overseer_last_directives:
+        if not isinstance(directive, dict):
+            continue
+        npc_id = _short_text(directive.get("npc_id"), limit=80)
+        text = _short_text(directive.get("directive"), limit=240)
+        applied = directive.get("applied") is True
+        if not npc_id or not text:
+            continue
+        npc = npcs_by_id.get(npc_id)
+        if npc is not None and applied:
+            npc.god_directive = text
+        _append_log(
+            world,
+            "directive_issued",
+            f"Overseer {'applied' if applied else 'advised'} {npc_id}: {text}",
+            severity="good" if applied else "neutral",
+            actor_id="overseer",
+            target_id=npc_id,
+        )
+
+
+def _client_from_config(config: OverseerConfig) -> OverseerClient | None:
+    if config.connector.type == "deterministic":
+        return ScriptedOverseerClient()
+    if config.connector.type == "openai_compatible":
+        return OpenAICompatibleOverseerClient(config.connector)
+    return None
+
+
+def _directive_to_engine(world: WorldState, raw: OverseerDirective) -> NpcDirective | None:
+    npc = next((candidate for candidate in world.npcs if candidate.id == raw.npc_id), None)
+    if npc is None or not is_alive(npc):
+        return None
+    text = raw.directive.lower()
+    action = "go_home"
+    target_entity_id: str | None = None
+    resource_id: str | None = None
+    resource_type: str | None = None
+    communication_intent: str | None = None
+
+    if any(word in text for word in ("attack", "engage", "intercept", "fight")):
+        action = "attack"
+        beast = _mentioned_beast(world, text) or nearest_beast(world, npc.position)
+        target_entity_id = beast.id if beast is not None else None
+    elif "build" in text or "repair" in text:
+        action = "build"
+    elif "patrol" in text or "guard" in text:
+        action = "patrol" if normalize_role(npc.role) == "guard" else "go_home"
+    elif "defend" in text:
+        action = "defend"
+    elif "heal" in text:
+        action = "heal"
+    elif "eat" in text or "consume" in text or "food" in text and "gather" not in text:
+        action = "consume"
+    elif "wood" in text or "gather" in text or "resource" in text:
+        action = "move_to_resource"
+        if "wood" in text:
+            resource_type = "wood"
+        node = nearest_resource_for_npc(world, npc, resource_type=resource_type)
+        resource_id = node.id if node is not None else None
+    elif "help" in text or "warn" in text or "call" in text:
+        action = "communicate"
+        communication_intent = "help_request" if "help" in text else "warning"
+    elif "hide" in text or "home" in text or "house" in text or "inside" in text:
+        action = "go_home"
+
+    return NpcDirective(
+        npc_id=npc.id,
+        action=cast(Any, action),
+        target_entity_id=target_entity_id,
+        resource_id=resource_id,
+        resource_type=resource_type,
+        communication_intent=communication_intent,
+        message=raw.directive,
+        memory=f"Overseer directive: {raw.directive}",
+        intent="overseer_directive",
+        confidence=1.0,
+    )
+
+
+def _resource_totals(world: WorldState) -> dict[str, int]:
+    totals: dict[str, int] = {}
+    for node in world.resource_nodes:
+        totals[node.resource_type] = totals.get(node.resource_type, 0) + node.amount
+    return totals
+
+
+def _current_threats(world: WorldState) -> list[dict[str, Any]]:
+    threats: list[dict[str, Any]] = []
+    for beast in world.beasts:
+        if beast.state == "dead":
+            continue
+        nearest_npc = min(
+            (npc for npc in world.npcs if is_alive(npc)),
+            key=lambda npc: (vec_distance(beast.position, npc.position), npc.id),
+            default=None,
+        )
+        house = nearest_house(world, beast.position, completed_only=False)
+        threats.append(
+            {
+                "beast_id": beast.id,
+                "nearest_npc_id": nearest_npc.id if nearest_npc is not None else None,
+                "nearest_house_id": house.id if house is not None else None,
+                "state": beast.state,
+            }
+        )
+    return threats
+
+
+def _mentioned_beast(world: WorldState, text: str):
+    for beast in world.beasts:
+        if beast.id.lower() in text and beast.state != "dead":
+            return beast
+    return None
+
+
+def _first_role(npcs: object, role: str) -> dict[str, Any] | None:
+    if not isinstance(npcs, list):
+        return None
+    for npc in npcs:
+        if isinstance(npc, dict) and npc.get("role") == role:
+            return npc
+    return None
+
+
+def _append_log(
+    world: WorldState,
+    event_type: str,
+    summary: str,
+    *,
+    severity: str,
+    actor_id: str | None = None,
+    target_id: str | None = None,
+) -> None:
+    safe_severity = severity if severity in {"good", "neutral", "warning", "danger"} else "neutral"
+    world.event_log.append(
+        WorldLogEvent(
+            tick=world.tick,
+            type=event_type,
+            actor_id=actor_id,
+            target_id=target_id,
+            object_id=None,
+            summary=summary,
+            severity=cast(Any, safe_severity),
+        )
+    )
+
+
+def _short_text(raw: object, *, limit: int) -> str | None:
+    if not isinstance(raw, str):
+        return None
+    value = " ".join(raw.split())
+    if not value:
+        return None
+    return value[:limit]
+
+
+def _resolve_base_url(config: ConnectorConfig) -> str | None:
+    base_url = config.base_url or config.api_url
+    if not base_url:
+        return None
+    if base_url.endswith("/chat/completions"):
+        return base_url.removesuffix("/chat/completions")
+    return base_url
+
+
+def _resolve_api_key(config: ConnectorConfig) -> str:
+    if config.api_key_env:
+        api_key = os.getenv(config.api_key_env)
+        if api_key:
+            return api_key
+        raise ValueError(f"Missing Overseer API key environment variable: {config.api_key_env}")
+    return os.getenv("OPENAI_API_KEY") or "not-needed"

src/god_simulator/simulation/roles.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+VALID_ROLES = ("gatherer", "guard", "builder")
+
+_ROLE_ALIASES = {
+    "farmer": "gatherer",
+    "forager": "gatherer",
+    "scribe": "gatherer",
+}
+
+_ACTION_ALIASES = {
+    "eat": "consume",
+    "talk": "communicate",
+    "call_for_help": "communicate",
+    "request_trade": "communicate",
+    "trade": "transfer",
+    "wander": "move_to",
+}
+
+_ACTION_ORDER = [
+    "move_to_resource",
+    "gather",
+    "transfer",
+    "consume",
+    "heal",
+    "flee",
+    "communicate",
+    "go_home",
+    "move_to",
+    "steal",
+    "attack",
+    "defend",
+    "patrol",
+    "build",
+    "idle",
+]
+
+_SHARED_ACTIONS = {
+    "move_to_resource",
+    "consume",
+    "heal",
+    "flee",
+    "communicate",
+    "transfer",
+    "go_home",
+    "move_to",
+    "idle",
+}
+
+_ROLE_ACTIONS = {
+    "gatherer": _SHARED_ACTIONS | {"gather", "steal"},
+    "guard": (_SHARED_ACTIONS | {"attack", "defend", "patrol"}) - {"move_to_resource"},
+    "builder": _SHARED_ACTIONS | {"build", "gather"},
+}
+
+
+def normalize_role(role: str) -> str:
+    normalized = _ROLE_ALIASES.get(role, role)
+    return normalized if normalized in VALID_ROLES else "gatherer"
+
+
+def canonical_action(action: str) -> str:
+    return _ACTION_ALIASES.get(action, action)
+
+
+def actions_for_role(role: str) -> list[str]:
+    normalized = normalize_role(role)
+    allowed = _ROLE_ACTIONS[normalized]
+    return [action for action in _ACTION_ORDER if action in allowed]
+
+
+def filter_actions_for_role(actions: Iterable[str], role: str) -> list[str]:
+    role_actions = set(actions_for_role(role))
+    filtered: list[str] = []
+    for action in actions:
+        canonical = canonical_action(action)
+        if canonical in role_actions and canonical not in filtered:
+            filtered.append(canonical)
+    return filtered
+
+
+def action_allowed_for_role(
+    role: str,
+    action: str,
+    *,
+    resource_type: str | None = None,
+    self_defense: bool = False,
+) -> bool:
+    normalized_role = normalize_role(role)
+    canonical = canonical_action(action)
+    if canonical == "attack" and normalized_role == "gatherer" and self_defense:
+        return True
+    if canonical not in _ROLE_ACTIONS[normalized_role]:
+        return False
+    if canonical == "gather" and normalized_role == "builder":
+        return resource_type in (None, "wood")
+    return True

src/god_simulator/simulation/spawning.py

@@ -5,6 +5,7 @@ import random
 from god_simulator.config import GameConfig
 from god_simulator.domain import (
     Beast,
+    House,
     MemoryEntry,
     Npc,
     ResourceNode,
@@ -13,6 +14,7 @@ from god_simulator.domain import (
     WorldState,
 )
 from god_simulator.simulation.mechanics import BLOCK_SIZE, GRID_BLOCKS
+from god_simulator.simulation.roles import normalize_role
 
 _NAMES = [
     "Ada",
@@ -37,7 +39,7 @@ _NAMES = [
     "Vera",
 ]
 
-_ROLES = ["farmer", "builder", "forager", "guard", "scribe"]
+_ROLES = ["gatherer", "gatherer", "gatherer", "guard", "guard", "builder"]
 
 
 def create_world(config: GameConfig) -> WorldState:
@@ -47,13 +49,14 @@ def create_world(config: GameConfig) -> WorldState:
         width=config.world.width,
         depth=config.world.depth,
     )
-    npcs = [
-        _spawn_npc(index=index, config=config, rng=rng)
-        for index in range(config.npcs.count)
-    ]
+    npcs = [_spawn_npc(index=index, config=config, rng=rng) for index in range(config.npcs.count)]
+    houses = _spawn_houses(config)
     if config.world.survival:
         _seed_survival_relationships(npcs)
+        _assign_starting_homes(npcs, houses)
+        _initialize_importance(npcs)
 
+    population = sum(1 for npc in npcs if npc.health > 0)
     return WorldState(
         tick=0,
         seed=config.world.seed,
@@ -61,6 +64,11 @@ def create_world(config: GameConfig) -> WorldState:
         npcs=npcs,
         resource_nodes=_spawn_resource_nodes(config),
         beasts=_spawn_beasts(config),
+        houses=houses,
+        population=population,
+        peak_population=population,
+        overseer_mode=config.overseer.mode,
+        overseer_cycle_ticks=config.overseer.cycle_ticks,
     )
 
 
@@ -69,9 +77,21 @@ def _spawn_npc(*, index: int, config: GameConfig, rng: random.Random) -> Npc:
     half_depth = config.world.depth / 2
 
     name = _NAMES[index % len(_NAMES)]
-    role = _ROLES[index % len(_ROLES)]
-    x = _random_block_center(rng, half_width=half_width)
-    z = _random_block_center(rng, half_width=half_depth)
+    role = normalize_role(_ROLES[index % len(_ROLES)])
+    if config.world.survival:
+        ring = index % 6
+        offsets = [
+            (0.0, 0.0),
+            (1.2, 0.8),
+            (-1.0, -0.9),
+            (3.4, 0.0),
+            (-3.4, 0.0),
+            (0.0, 3.4),
+        ]
+        x, z = offsets[ring]
+    else:
+        x = _random_block_center(rng, half_width=half_width)
+        z = _random_block_center(rng, half_width=half_depth)
 
     npc = Npc(
         id=f"npc-{index + 1:03d}",
@@ -80,15 +100,21 @@ def _spawn_npc(*, index: int, config: GameConfig, rng: random.Random) -> Npc:
         position=Vec3(x=x, y=0.0, z=z),
         attack_damage=rng.randint(5, 15),
         memory=[MemoryEntry(tick=0, text=f"{name} arrived as a {role}.")],
+        age=60 if config.world.survival else 0,
+        max_age=_random_max_age(config.world.seed, index),
     )
 
     if config.world.survival:
         # Independent per-NPC RNG so survival inventory never perturbs the shared
         # position/damage stream (keeps non-survival spawning deterministic).
         inv_rng = random.Random(config.world.seed + index)
-        npc.inventory_food = inv_rng.randint(0, 2)
+        npc.hunger = 0.0 if index == 0 else 20.0 + inv_rng.randint(0, 10)
+        npc.safety = 100.0 if index == 0 else 0.0
+        npc.inventory_food = 2 if index == 0 else inv_rng.randint(0, 2)
         npc.inventory_herbs = inv_rng.randint(0, 1)
-        npc.inventory_weapon = 1 if index % 3 == 0 else 0
+        npc.inventory_weapon = 1 if role == "guard" else 0
+        if role == "builder" and index < 6:
+            npc.inventory_wood = 5
 
     return npc
 
@@ -97,7 +123,7 @@ def _spawn_resource_nodes(config: GameConfig) -> list[ResourceNode]:
     if not config.world.survival:
         return []
     rng = random.Random(f"{config.world.seed}:initial_resources")
-    counts = {"food": 5, "herbs": 3, "wood": 2, "weapon": 2}
+    counts = {"food": 4, "herbs": 2, "wood": 3, "weapon": 1}
     max_amounts = {"food": 5, "herbs": 4, "wood": 6, "weapon": 2}
     nodes: list[ResourceNode] = []
     for resource_type, count in counts.items():
@@ -122,15 +148,28 @@ def _spawn_resource_nodes(config: GameConfig) -> list[ResourceNode]:
 def _spawn_beasts(config: GameConfig) -> list[Beast]:
     if not config.world.survival:
         return []
-    rng = random.Random(f"{config.world.seed}:initial_beasts")
     return [
         Beast(
             "beast_1",
-            _random_world_position(
-                rng,
-                half_width=config.world.width / 2,
-                half_depth=config.world.depth / 2,
-            ),
+            Vec3(x=config.world.width / 2 - BLOCK_SIZE, y=0.0, z=0.0),
+            health=60.0,
+            damage=9.0,
+        )
+    ]
+
+
+def _spawn_houses(config: GameConfig) -> list[House]:
+    if not config.world.survival:
+        return []
+    return [
+        House(
+            id="house_001",
+            position=Vec3(x=0.0, y=0.0, z=0.0),
+            hp=60.0,
+            max_hp=60.0,
+            state="completed",
+            build_progress=10,
+            capacity=3,
         )
     ]
 
@@ -143,6 +182,28 @@ def _seed_survival_relationships(npcs: list[Npc]) -> None:
             npc.relationships[other.id] = 0.45
 
 
+def _assign_starting_homes(npcs: list[Npc], houses: list[House]) -> None:
+    if not houses:
+        return
+    home = houses[0]
+    for npc in npcs:
+        npc.home_house_id = home.id
+    home.occupant_ids = [npc.id for npc in npcs[: home.capacity]]
+
+
+def _initialize_importance(npcs: list[Npc]) -> None:
+    counts = {"gatherer": 0, "guard": 0, "builder": 0}
+    for npc in npcs:
+        counts[normalize_role(npc.role)] += 1
+    for npc in npcs:
+        role_count = max(1, counts[normalize_role(npc.role)])
+        npc.importance = round(1.0 + 2.0 * (1 / role_count), 3)
+
+
+def _random_max_age(seed: int, index: int) -> int:
+    return random.Random(f"{seed}:{index}:max_age").randint(320, 480)
+
+
 def _random_block_center(rng: random.Random, *, half_width: float) -> float:
     first_center = -half_width + (BLOCK_SIZE / 2)
     return first_center + (rng.randrange(GRID_BLOCKS) * BLOCK_SIZE)

src/god_simulator/simulation/survival.py

@@ -14,7 +14,18 @@ from __future__ import annotations
 import math
 import random
 
-from god_simulator.domain import Beast, MemoryEpisode, Npc, ResourceNode, Vec3, WorldEvent, WorldState
+from god_simulator.domain import (
+    Beast,
+    MemoryEntry,
+    House,
+    MemoryEpisode,
+    Npc,
+    ResourceNode,
+    Vec3,
+    WorldEvent,
+    WorldLogEvent,
+    WorldState,
+)
 from god_simulator.simulation.connectors.base import NpcDirective, TickPlan
 from god_simulator.simulation.mechanics import (
     BLOCK_SIZE,
@@ -25,53 +36,74 @@ from god_simulator.simulation.mechanics import (
     vec_distance,
 )
 from god_simulator.simulation.memory import remember
+from god_simulator.simulation.roles import (
+    action_allowed_for_role,
+    canonical_action,
+    filter_actions_for_role,
+    normalize_role,
+)
 
 TILE = BLOCK_SIZE
 
 # Hunger / health economy.
-HUNGER_RATE = 2.0
-HUNGER_DAMAGE = 3
-STARVATION_THRESHOLD = 80.0
+HUNGER_RATE = 0.8
+STARVATION_THRESHOLD = 70.0
+SEVERE_STARVATION_THRESHOLD = 90.0
+STARVATION_DAMAGE = 0.5
+SEVERE_STARVATION_DAMAGE = 1.5
 HUNGER_CAP = 150.0
 HEAL_GOAL_HEALTH = 40  # health < this (with herbs) -> heal_self
 FIND_HERBS_HEALTH = 50  # health < this (without herbs) -> find_herbs
+EAT_GOAL_HUNGER = 60.0
+REPRODUCTION_SNACK_HUNGER = 45.0
 
 # Awareness radii (world units).
 BEAST_ALERT_RADIUS = 6 * TILE
+BEAST_THREAT_RADIUS = 8 * TILE
+VILLAGE_THREAT_RADIUS = 10 * TILE
+HOUSE_THREAT_RADIUS = 12 * TILE
 ALLY_RADIUS = 5 * TILE
 WITNESS_RADIUS = 5 * TILE
-FEAR_DECAY_RADIUS = 8 * TILE
-GATHER_RADIUS = 2 * TILE
+FEAR_DECAY_RADIUS = 12 * TILE
+GATHER_RADIUS = 1.5 * TILE
 TRADE_RADIUS = 2 * TILE
 PERCEPTION_BEAST_RADIUS = 8 * TILE
 PERCEPTION_RESOURCE_RADIUS = 6 * TILE
 PERCEPTION_NPC_RADIUS = 6 * TILE
 HELP_RADIUS = 6 * TILE
+HOUSE_RADIUS = 2.5 * TILE
+HOUSE_BUILD_RADIUS = 2 * TILE
+HOUSE_MIN_DISTANCE = 4 * TILE
 
 # Fear dynamics.
-FEAR_ON_ATTACK = 40.0
+FEAR_ON_ATTACK = 60.0
 FEAR_ON_WITNESS = 20.0
-FEAR_DECAY = 5.0
+FEAR_DECAY = 2.0
+SAFETY_GAIN = 12.0
+SAFETY_DECAY = 8.0
 
 # Movement / combat (world units). Beasts are intentionally hard to solo and
 # damaging without instantly ending the village story.
 NPC_MOVE_STEP = 1 * TILE
 FLEE_STEP = 2 * TILE
 NPC_MELEE_REACH = 2 * TILE
-BASE_NPC_DAMAGE = 8
-WEAPON_DAMAGE_BONUS = 7
-BEAST_RETREAT_HEALTH = 35.0
+BASE_NPC_DAMAGE = 10
+WEAPON_DAMAGE_BONUS = 0
+GUARD_DAMAGE_MULTIPLIER = 1.5
+WEAK_DAMAGE_MULTIPLIER = 0.3
+BEAST_RETREAT_HEALTH = 20.0
+BEAST_DESPAWN_TICKS = 15
 
 # Deterministic world-system spawning. Positions and ids are random-looking but
 # stable for a world seed/tick pair.
 RESOURCE_SPAWN_INTERVAL = 7
 MAX_RESOURCE_NODES = 18
-BEAST_SPAWN_INTERVAL = 25
-MAX_BEASTS = 2
+BEAST_SPAWN_INTERVAL = 60
+MAX_BEASTS = 3
 
 # Resource regrowth: every node regrows +1 toward its cap on this cadence, so the
 # settlement is sustainable instead of starving once nodes are first depleted.
-RESOURCE_REGEN_INTERVAL = 2
+RESOURCE_REGEN_INTERVALS = {"food": 8, "herbs": 12, "wood": 10, "weapon": 40}
 RESOURCE_REGEN_AMOUNT = 1
 # How many of the nearest non-empty nodes foragers spread across (anti-clumping).
 SPREAD_NODE_CHOICES = 3
@@ -81,14 +113,17 @@ SHARE_FOOD_SURPLUS = 2
 # Goal -> allowed survival actions (the deterministic planner and any LLM both
 # choose from these sets; effects are resolved by the engine).
 GOAL_ACTIONS: dict[str, list[str]] = {
-    "survive_threat_fight": ["attack", "defend", "communicate", "flee"],
+    "engage_threat": ["attack", "defend", "communicate", "patrol"],
+    "survive_threat_fight": ["attack", "defend", "communicate", "flee", "go_home"],
     "survive_threat_flee": ["flee", "communicate", "defend"],
     "help_ally": ["attack", "defend", "communicate"],
     "heal_self": ["heal"],
     "eat_food": ["consume"],
     "find_food": ["move_to_resource", "gather", "communicate", "steal"],
     "find_herbs": ["move_to_resource", "gather", "communicate"],
-    "routine_life": ["gather", "move_to_resource", "transfer", "communicate"],
+    "settle": ["go_home", "consume", "communicate", "transfer"],
+    "work": ["gather", "move_to_resource", "transfer", "communicate", "build", "patrol"],
+    "routine_life": ["gather", "move_to_resource", "transfer", "communicate", "go_home", "build", "patrol"],
     "dead": [],
 }
 
@@ -101,6 +136,10 @@ VALID_SURVIVAL_ACTIONS = frozenset(
         "find_herbs",
         "idle",
         "move_to",
+        "go_home",
+        "patrol",
+        "build",
+        "wander",
         # Compatibility aliases accepted at validation boundaries.
         "eat",
         "talk",
@@ -303,6 +342,15 @@ def build_perception(npc: Npc, world: WorldState) -> str:
                 f"[{node.resource_type}={node.amount}]"
             )
 
+    for house in sorted(world.houses, key=lambda item: vec_distance(npc.position, item.position)):
+        distance = vec_distance(npc.position, house.position)
+        if distance <= PERCEPTION_RESOURCE_RADIUS:
+            lines.append(
+                f"- {house.id} is {_tiles(distance):.0f} tiles "
+                f"{_direction(npc.position, house.position)} "
+                f"[{house.state} hp={house.hp:.0f} occupants={len(house.occupant_ids)}/{house.capacity}]"
+            )
+
     for other in sorted(npcs_in_radius(world, npc.position, PERCEPTION_NPC_RADIUS, exclude_id=npc.id), key=lambda item: item.id):
         trust = npc.relationships.get(other.id, 0.0)
         label = _relationship_label(trust)
@@ -385,6 +433,26 @@ def nearest_alive_npc(
     return min(candidates, key=lambda other: (vec_distance(npc.position, other.position), other.id))
 
 
+def _nearest_role(
+    world: WorldState,
+    npc: Npc,
+    role: str,
+    *,
+    max_dist: float,
+) -> Npc | None:
+    candidates = [
+        other
+        for other in world.npcs
+        if other.id != npc.id
+        and is_alive(other)
+        and normalize_role(other.role) == role
+        and vec_distance(npc.position, other.position) <= max_dist
+    ]
+    if not candidates:
+        return None
+    return min(candidates, key=lambda other: (vec_distance(npc.position, other.position), other.id))
+
+
 def nearest_resource(
     world: WorldState,
     position: Vec3,
@@ -429,8 +497,57 @@ def count_alive_npcs_in_radius(world: WorldState, position: Vec3, radius: float)
     )
 
 
+def count_alive_population(world: WorldState) -> int:
+    return sum(1 for npc in world.npcs if is_alive(npc))
+
+
+def completed_houses(world: WorldState) -> list[House]:
+    return [house for house in world.houses if house.state == "completed" and house.hp > 0]
+
+
+def house_containing_npc(world: WorldState, npc: Npc) -> House | None:
+    for house in completed_houses(world):
+        if vec_distance(npc.position, house.position) <= HOUSE_RADIUS:
+            return house
+    return None
+
+
+def is_npc_inside_house(world: WorldState, npc: Npc) -> bool:
+    return house_containing_npc(world, npc) is not None
+
+
+def nearest_house(world: WorldState, position: Vec3, *, completed_only: bool = True) -> House | None:
+    houses = completed_houses(world) if completed_only else [house for house in world.houses if house.hp > 0]
+    if not houses:
+        return None
+    return min(houses, key=lambda house: (vec_distance(position, house.position), house.id))
+
+
+def nearest_resource_for_npc(
+    world: WorldState,
+    npc: Npc,
+    *,
+    resource_type: str | None = None,
+    max_dist: float | None = None,
+    require_amount: bool = True,
+) -> ResourceNode | None:
+    if normalize_role(npc.role) == "builder":
+        resource_type = "wood"
+    return nearest_resource(
+        world,
+        npc.position,
+        resource_type=resource_type,
+        max_dist=max_dist,
+        require_amount=require_amount,
+    )
+
+
 def apply_world_systems(world: WorldState) -> None:
     """Run deterministic environment systems before NPC decisions."""
+    # Local import: chaos.py reuses survival helpers at module level.
+    from god_simulator.simulation.chaos import end_famine_if_due
+
+    end_famine_if_due(world)
     if world.resource_nodes:
         _regrow_resource_nodes(world)
         _maybe_spawn_resource_node(world)
@@ -439,10 +556,9 @@ def apply_world_systems(world: WorldState) -> None:
 
 
 def _regrow_resource_nodes(world: WorldState) -> None:
-    if world.tick % RESOURCE_REGEN_INTERVAL != 0:
-        return
     for node in world.resource_nodes:
-        if node.max_amount > 0 and node.amount < node.max_amount:
+        interval = RESOURCE_REGEN_INTERVALS.get(node.resource_type, 10)
+        if world.tick % interval == 0 and node.max_amount > 0 and node.amount < node.max_amount:
             node.amount = min(node.max_amount, node.amount + RESOURCE_REGEN_AMOUNT)
 
 
@@ -475,18 +591,47 @@ def _maybe_spawn_beast(world: WorldState) -> None:
     living_beasts = [beast for beast in world.beasts if beast.state != "dead"]
     if len(living_beasts) >= MAX_BEASTS:
         return
-    if world.tick == 0 or world.tick % BEAST_SPAWN_INTERVAL != 0:
+    if count_alive_population(world) < 4:
+        return
+    cooldown = _natural_beast_spawn_interval(world)
+    if world.tick == 0 or world.tick % cooldown != 0:
         return
 
     rng = random.Random(f"{world.seed}:{world.tick}:beast_spawn")
-    world.beasts.append(
-        Beast(
-            id=f"beast_{_next_beast_index(world)}",
-            position=_random_map_position(world, rng),
-        )
+    beast = Beast(
+        id=f"beast_{_next_beast_index(world)}",
+        position=_random_map_edge_position(world, rng),
+        health=60.0,
+        damage=9.0,
+    )
+    world.beasts.append(beast)
+    _log_event(
+        world,
+        "beast_spawned",
+        f"{beast.id} appeared at the edge of the map",
+        severity="warning",
+        actor_id=beast.id,
     )
 
 
+def _natural_beast_spawn_interval(world: WorldState) -> int:
+    rng = random.Random(f"{world.seed}:beast_spawn_interval:{world.tick // BEAST_SPAWN_INTERVAL}")
+    return rng.randint(60, 90)
+
+
+def _random_map_edge_position(world: WorldState, rng: random.Random) -> Vec3:
+    half_width = world.terrain.width / 2
+    half_depth = world.terrain.depth / 2
+    side = rng.choice(["north", "south", "east", "west"])
+    if side == "north":
+        return Vec3(x=round(rng.uniform(-half_width, half_width), 3), y=0.0, z=half_depth)
+    if side == "south":
+        return Vec3(x=round(rng.uniform(-half_width, half_width), 3), y=0.0, z=-half_depth)
+    if side == "east":
+        return Vec3(x=half_width, y=0.0, z=round(rng.uniform(-half_depth, half_depth), 3))
+    return Vec3(x=-half_width, y=0.0, z=round(rng.uniform(-half_depth, half_depth), 3))
+
+
 def _next_resource_index(world: WorldState, resource_type: str) -> int:
     prefix = f"res_{resource_type}_"
     highest = 0
@@ -523,17 +668,34 @@ def _select_beast_target(world: WorldState, beast: Beast) -> Npc | None:
         npc
         for npc in world.npcs
         if is_alive(npc)
+        and not is_npc_inside_house(world, npc)
     ]
     if not candidates:
         return None
-    return min(
-        candidates,
-        key=lambda npc: (
-            vec_distance(beast.position, npc.position) + (max(0, npc.health) * 0.02),
-            npc.inventory_weapon,
-            npc.id,
-        ),
-    )
+    nearest_distance = min(vec_distance(beast.position, npc.position) for npc in candidates)
+    vulnerable = [
+        npc
+        for npc in candidates
+        if npc.health < 50 and vec_distance(beast.position, npc.position) <= nearest_distance * 1.3
+    ]
+    pool = vulnerable or candidates
+    return min(pool, key=lambda npc: (vec_distance(beast.position, npc.position), npc.health, npc.id))
+
+
+def _select_house_target(world: WorldState, beast: Beast) -> House | None:
+    houses = completed_houses(world)
+    if not houses:
+        return None
+    occupied_ids = set()
+    for npc in world.npcs:
+        if not is_alive(npc):
+            continue
+        house = house_containing_npc(world, npc)
+        if house is not None:
+            occupied_ids.add(house.id)
+    occupied = [house for house in houses if house.id in occupied_ids]
+    pool = occupied or houses
+    return min(pool, key=lambda house: (vec_distance(beast.position, house.position), house.id))
 
 
 def _record_world_event(
@@ -557,6 +719,31 @@ def _record_world_event(
     )
 
 
+def _log_event(
+    world: WorldState,
+    event_type: str,
+    summary: str,
+    *,
+    severity: str = "neutral",
+    actor_id: str | None = None,
+    target_id: str | None = None,
+    object_id: str | None = None,
+    tick: int | None = None,
+) -> None:
+    normalized_severity = severity if severity in {"good", "neutral", "warning", "danger"} else "neutral"
+    world.event_log.append(
+        WorldLogEvent(
+            tick=world.tick if tick is None else tick,
+            type=event_type,
+            actor_id=actor_id,
+            target_id=target_id,
+            object_id=object_id,
+            summary=summary,
+            severity=normalized_severity,  # type: ignore[arg-type]
+        )
+    )
+
+
 # --------------------------------------------------------------------------- #
 # Deterministic environment tick (no LLM)
 # --------------------------------------------------------------------------- #
@@ -575,118 +762,541 @@ def apply_survival_tick(world: WorldState) -> None:
 
     apply_world_systems(world)
 
-    if not world.beasts and not world.resource_nodes:
+    if not world.beasts and not world.resource_nodes and not world.houses:
         return
 
-    half_width = world.terrain.width / 2
-    half_depth = world.terrain.depth / 2
+    _refresh_house_occupants(world)
 
     for npc in world.npcs:
         if not is_alive(npc):
             continue
+        npc.age += 1
+        npc.reproduction_cooldown = max(0, npc.reproduction_cooldown - 1)
         npc.hunger = min(HUNGER_CAP, npc.hunger + HUNGER_RATE)
-        if npc.hunger > STARVATION_THRESHOLD:
-            npc.health -= HUNGER_DAMAGE
+        if npc.hunger >= SEVERE_STARVATION_THRESHOLD:
+            npc.health -= SEVERE_STARVATION_DAMAGE
+        elif npc.hunger >= STARVATION_THRESHOLD:
+            npc.health -= STARVATION_DAMAGE
+        if npc.health <= 0:
+            _kill_npc(world, npc, cause="starvation", actor_id=npc.id)
+            continue
+        if npc.age >= npc.max_age:
+            _kill_npc(world, npc, cause="old_age", actor_id=npc.id)
+
+    _apply_beast_system(world)
+    _refresh_house_occupants(world)
+
+    for npc in world.npcs:
+        if not is_alive(npc):
+            npc.survival_goal = "dead"
+            continue
+        _update_safety(world, npc)
+        if nearest_beast_distance(world, npc) > FEAR_DECAY_RADIUS:
+            npc.fear = max(0.0, npc.fear - FEAR_DECAY)
+        # Keep the live goal current for the snapshot, even when planning ran on a
+        # deep-copied world (the HTTP server path).
+        npc.survival_goal = select_goal(npc, world)
+        if world.tick > 0 and world.tick % 10 == 0:
+            compress_to_facts(npc)
+
+
+def apply_post_survival_tick(world: WorldState, next_tick: int) -> None:
+    """Run deterministic end-of-tick systems after NPC actions resolve."""
+    _refresh_house_occupants(world)
+    for npc in list(world.npcs):
+        if is_alive(npc):
+            _maybe_reproduce(world, npc, next_tick)
+    _refresh_house_occupants(world)
+    if next_tick % 10 == 0:
+        _recompute_importance(world)
+    _update_population_and_status(world, next_tick)
+
+
+def _apply_beast_system(world: WorldState) -> None:
+    half_width = world.terrain.width / 2
+    half_depth = world.terrain.depth / 2
 
     for beast in world.beasts:
         if beast.state == "dead":
             continue
+
         target = _select_beast_target(world, beast)
-        if target is None:
+        house_target = None if target is not None else _select_house_target(world, beast)
+        beast.target_npc_id = target.id if target is not None else None
+        beast.target_house_id = house_target.id if house_target is not None else None
+
+        target_position = target.position if target is not None else (
+            house_target.position if house_target is not None else None
+        )
+        if target_position is None:
             continue
-        beast.target_npc_id = target.id
 
-        distance = vec_distance(beast.position, target.position)
         step = beast.speed * TILE
         reach = beast.attack_range * TILE
 
         if beast.health < BEAST_RETREAT_HEALTH:
             beast.state = "retreating"
+            beast.retreat_ticks += 1
             beast.position = move_away(
                 beast.position,
-                target.position,
+                target_position,
                 step,
                 half_width=half_width,
                 half_depth=half_depth,
             )
+            if beast.retreat_ticks >= BEAST_DESPAWN_TICKS:
+                beast.state = "dead"
+                _log_event(
+                    world,
+                    "beast_retreat",
+                    f"{beast.id} fled the map",
+                    severity="neutral",
+                    actor_id=beast.id,
+                )
             continue
 
-        if distance <= reach:
-            beast.state = "attacking"
-            target.health -= int(beast.damage)
-            target.fear = min(100.0, target.fear + FEAR_ON_ATTACK)
-            add_episode(
-                target,
-                world.tick,
-                "attack",
-                beast.id,
-                f"{beast.id} attacked me",
-                target_id=target.id,
-                subject_kind="beast",
-                perspective="recipient",
-                tags=["danger", "beast"],
-                weight=1.0,
-            )
-            _record_world_event(
-                world,
-                "attack",
-                f"{beast.id} attacked {target.name}",
-                beast.position,
-                radius=WITNESS_RADIUS,
-                duration_ticks=4,
-            )
-            remember(target, world.tick, f"Beast {beast.id} attacked me at tick {world.tick}.")
-            if not is_alive(target):
-                target.intention = "dead"
-                add_episode(
-                    target,
-                    world.tick,
-                    "death",
-                    beast.id,
-                    f"{target.name} was killed by {beast.id}",
-                    target_id=target.id,
-                    subject_kind="beast",
-                    perspective="recipient",
-                    tags=["danger", "beast"],
-                    weight=1.0,
-                )
-                remember(target, world.tick, "You were killed by the beast.")
-            for witness in npcs_in_radius(world, beast.position, WITNESS_RADIUS, exclude_id=target.id):
-                witness.fear = min(100.0, witness.fear + FEAR_ON_WITNESS)
-                add_episode(
-                    witness,
-                    world.tick,
-                    "attack",
-                    beast.id,
-                    f"{beast.id} attacked {target.name} nearby",
-                    target_id=target.id,
-                    subject_kind="beast",
-                    perspective="witness",
-                    tags=["danger", "beast"],
-                    weight=0.8,
-                )
-                remember(witness, world.tick, f"The beast attacked {target.name} nearby.")
-        else:
+        beast.retreat_ticks = 0
+        distance = vec_distance(beast.position, target_position)
+        if distance > reach:
             beast.state = "hunting"
             beast.position = move_toward(
                 beast.position,
-                target.position,
+                target_position,
                 step,
                 half_width=half_width,
                 half_depth=half_depth,
             )
+            continue
 
+        beast.state = "attacking"
+        if target is not None:
+            _beast_attack_npc(world, beast, target)
+        elif house_target is not None:
+            _damage_house(world, house_target, beast, amount=5.0)
+
+
+def _beast_attack_npc(world: WorldState, beast: Beast, target: Npc) -> None:
+    if is_npc_inside_house(world, target):
+        house = house_containing_npc(world, target)
+        if house is not None:
+            _damage_house(world, house, beast, amount=5.0)
+        return
+
+    target.health -= beast.damage
+    target.fear = min(100.0, max(target.fear, FEAR_ON_ATTACK))
+    add_episode(
+        target,
+        world.tick,
+        "attack",
+        beast.id,
+        f"{beast.id} attacked me",
+        target_id=target.id,
+        subject_kind="beast",
+        perspective="recipient",
+        tags=["danger", "beast"],
+        weight=1.0,
+    )
+    _record_world_event(
+        world,
+        "beast_attack",
+        f"{beast.id} attacked {target.name}",
+        beast.position,
+        radius=WITNESS_RADIUS,
+        duration_ticks=4,
+    )
+    _log_event(
+        world,
+        "beast_attack",
+        f"{beast.id} attacked {target.name}",
+        severity="danger",
+        actor_id=beast.id,
+        target_id=target.id,
+    )
+    remember(target, world.tick, f"Beast {beast.id} attacked me at tick {world.tick}.")
+    if target.health <= 0:
+        _kill_npc(world, target, cause="beast", actor_id=beast.id)
+
+    for witness in npcs_in_radius(world, beast.position, WITNESS_RADIUS, exclude_id=target.id):
+        witness.fear = min(100.0, witness.fear + FEAR_ON_WITNESS)
+        add_episode(
+            witness,
+            world.tick,
+            "attack",
+            beast.id,
+            f"{beast.id} attacked {target.name} nearby",
+            target_id=target.id,
+            subject_kind="beast",
+            perspective="witness",
+            tags=["danger", "beast"],
+            weight=0.8,
+        )
+        remember(witness, world.tick, f"The beast attacked {target.name} nearby.")
+
+
+def _damage_house(world: WorldState, house: House, beast: Beast, *, amount: float) -> None:
+    house.hp = max(0.0, house.hp - amount)
+    _record_world_event(
+        world,
+        "house_damaged",
+        f"{beast.id} damaged {house.id}",
+        house.position,
+        radius=WITNESS_RADIUS,
+        duration_ticks=4,
+    )
+    _log_event(
+        world,
+        "house_damaged",
+        f"{beast.id} damaged {house.id}",
+        severity="warning",
+        actor_id=beast.id,
+        target_id=house.id,
+    )
+    if house.hp > 0:
+        return
+
+    house.state = "under_construction"
+    house.occupant_ids = []
+    if _chaos_points_active(world):
+        world.chaos_score += 2
+    _record_world_event(
+        world,
+        "house_destroyed",
+        f"{house.id} was destroyed",
+        house.position,
+        radius=WITNESS_RADIUS,
+        duration_ticks=6,
+    )
+    _log_event(
+        world,
+        "house_destroyed",
+        f"{house.id} was destroyed",
+        severity="danger",
+        actor_id=beast.id,
+        target_id=house.id,
+    )
+    for npc in npcs_in_radius(world, house.position, HOUSE_RADIUS):
+        npc.fear = max(npc.fear, 80.0)
+        npc.safety = 0.0
+        remember(npc, world.tick, f"{house.id} was destroyed around you.")
+
+
+def _kill_npc(world: WorldState, npc: Npc, *, cause: str, actor_id: str | None) -> None:
+    if npc.health <= 0 and npc.intention == "dead":
+        return
+    npc.health = min(npc.health, 0)
+    npc.intention = "dead"
+    npc.survival_goal = "dead"
+    world.deaths_by_cause[cause] = world.deaths_by_cause.get(cause, 0) + 1
+    if _chaos_points_active(world):
+        world.chaos_score += 3
+    add_episode(
+        npc,
+        world.tick,
+        "death",
+        actor_id or npc.id,
+        f"{npc.name} died of {cause}",
+        target_id=npc.id,
+        subject_kind="beast" if actor_id and actor_id.startswith("beast") else "npc",
+        perspective="recipient",
+        tags=["danger", "death", cause],
+        weight=1.0,
+    )
+    remember(npc, world.tick, "You died.")
+    _drop_inventory(world, npc)
+    _record_world_event(
+        world,
+        "npc_died",
+        f"{npc.name} died of {cause}",
+        npc.position,
+        radius=WITNESS_RADIUS,
+        duration_ticks=6,
+    )
+    _log_event(
+        world,
+        "npc_died",
+        f"{npc.name} died of {cause}",
+        severity="danger",
+        actor_id=actor_id,
+        target_id=npc.id,
+        object_id=cause,
+    )
+    for witness in npcs_in_radius(world, npc.position, WITNESS_RADIUS, exclude_id=npc.id):
+        witness.fear = min(100.0, witness.fear + FEAR_ON_WITNESS)
+        add_episode(
+            witness,
+            world.tick,
+            "death",
+            actor_id or npc.id,
+            f"{npc.name} died of {cause}",
+            target_id=npc.id,
+            subject_kind="npc",
+            perspective="witness",
+            tags=["danger", "death", cause],
+            weight=0.9,
+        )
+        remember(witness, world.tick, f"{npc.name} died of {cause}.")
+
+
+def _drop_inventory(world: WorldState, npc: Npc) -> None:
+    for resource_type, amount in (
+        ("food", npc.inventory_food),
+        ("herbs", npc.inventory_herbs),
+        ("wood", npc.inventory_wood),
+        ("weapon", npc.inventory_weapon),
+    ):
+        if amount <= 0:
+            continue
+        index = _next_resource_index(world, resource_type)
+        world.resource_nodes.append(
+            ResourceNode(
+                id=f"res_{resource_type}_{index}",
+                resource_type=resource_type,
+                position=npc.position,
+                amount=amount,
+                max_amount=max(amount, {"food": 5, "herbs": 4, "wood": 6, "weapon": 2}[resource_type]),
+            )
+        )
+    npc.inventory_food = 0
+    npc.inventory_herbs = 0
+    npc.inventory_wood = 0
+    npc.inventory_weapon = 0
+
+
+def _refresh_house_occupants(world: WorldState) -> None:
+    for house in world.houses:
+        if house.state != "completed" or house.hp <= 0:
+            house.occupant_ids = []
+            continue
+        house.occupant_ids = [
+            npc.id
+            for npc in world.npcs
+            if is_alive(npc) and vec_distance(npc.position, house.position) <= HOUSE_RADIUS
+        ][: house.capacity]
+
+
+def _update_safety(world: WorldState, npc: Npc) -> None:
+    house = house_containing_npc(world, npc)
+    if house is None:
+        npc.safety = max(0.0, npc.safety - SAFETY_DECAY)
+        npc.needs.safety = round(npc.safety)
+        return
+
+    threat_near_house = any(
+        beast.state != "dead" and vec_distance(beast.position, house.position) <= HOUSE_THREAT_RADIUS
+        for beast in world.beasts
+    ) or any(
+        other.id != npc.id
+        and is_alive(other)
+        and vec_distance(other.position, npc.position) <= 10 * TILE
+        and _has_hostile_directive_toward(other, npc)
+        for other in world.npcs
+    )
+    if not threat_near_house:
+        npc.safety = min(100.0, npc.safety + SAFETY_GAIN)
+    npc.needs.safety = round(npc.safety)
+
+
+def _has_hostile_directive_toward(actor: Npc, target: Npc) -> bool:
+    if not actor.god_directive:
+        return False
+    lowered = actor.god_directive.lower()
+    return "attack" in lowered or "kill" in lowered or target.name.lower() in lowered
+
+
+def _maybe_reproduce(world: WorldState, parent: Npc, next_tick: int) -> None:
+    house = house_containing_npc(world, parent)
+    if house is None:
+        return
+    if not _reproduction_conditions_met(world, parent):
+        return
+
+    role = _role_for_child(world, parent)
+    child_index = _next_npc_index(world)
+    child = Npc(
+        id=f"npc-{child_index:03d}",
+        name=_child_name(child_index),
+        role=role,
+        position=house.position,
+        health=70,
+        hunger=20.0,
+        fear=0.0,
+        safety=100.0 if not _house_has_threat(world, house) else 0.0,
+        age=0,
+        max_age=random.Random(f"{world.seed}:{next_tick}:{child_index}:max_age").randint(320, 480),
+        inventory_weapon=1 if role == "guard" else 0,
+        home_house_id=house.id,
+        memory=[MemoryEntry(tick=next_tick, text=f"Born in {house.id} as a {role}.")],
+    )
     for npc in world.npcs:
-        if not is_alive(npc):
-            npc.survival_goal = "dead"
+        if npc.id == child.id:
             continue
-        if nearest_beast_distance(world, npc) > FEAR_DECAY_RADIUS:
-            npc.fear = max(0.0, npc.fear - FEAR_DECAY)
-        # Keep the live goal current for the snapshot, even when planning ran on a
-        # deep-copied world (the HTTP server path).
-        npc.survival_goal = select_goal(npc, world)
-        if world.tick > 0 and world.tick % 10 == 0:
-            compress_to_facts(npc)
+        child.relationships[npc.id] = 0.45
+        npc.relationships[child.id] = 0.45
+    child.relationships[parent.id] = 0.6
+    parent.relationships[child.id] = 0.6
+    world.npcs.append(child)
+    parent.children_count += 1
+    parent.reproduction_cooldown = 100
+    parent.hunger = min(HUNGER_CAP, parent.hunger + 40.0)
+    world.total_births += 1
+    world.overseer_score += 3
+    add_episode(
+        parent,
+        next_tick,
+        "npc_born",
+        parent.id,
+        f"I had a child: {child.name}",
+        target_id=child.id,
+        subject_kind="npc",
+        perspective="self",
+        tags=["birth", "family"],
+        weight=0.8,
+    )
+    for witness in npcs_in_radius(world, house.position, HOUSE_RADIUS, exclude_id=parent.id):
+        add_episode(
+            witness,
+            next_tick,
+            "npc_born",
+            parent.id,
+            f"{parent.name} had a child: {child.name}",
+            target_id=child.id,
+            subject_kind="npc",
+            perspective="witness",
+            tags=["birth", "family"],
+            weight=0.6,
+        )
+    _log_event(
+        world,
+        "npc_born",
+        f"{parent.name} gave birth to {child.name}",
+        severity="good",
+        actor_id=parent.id,
+        target_id=child.id,
+        tick=next_tick,
+    )
+
+
+def _reproduction_conditions_met(world: WorldState, npc: Npc) -> bool:
+    return (
+        npc.health >= 95
+        and npc.hunger <= 5
+        and round(npc.safety) >= 100
+        and npc.age > 90
+        and npc.reproduction_cooldown == 0
+        and count_alive_population(world) < world.population_cap
+    )
+
+
+def _house_has_threat(world: WorldState, house: House) -> bool:
+    return any(
+        beast.state != "dead" and vec_distance(beast.position, house.position) <= HOUSE_THREAT_RADIUS
+        for beast in world.beasts
+    )
+
+
+def _role_for_child(world: WorldState, parent: Npc) -> str:
+    counts = {role: 0 for role in ("gatherer", "guard", "builder")}
+    for npc in world.npcs:
+        if is_alive(npc):
+            counts[normalize_role(npc.role)] += 1
+    total = max(1, sum(counts.values()))
+    targets = {"gatherer": 3 / 6, "guard": 2 / 6, "builder": 1 / 6}
+    scarcity = {
+        role: targets[role] - (counts[role] / total)
+        for role in counts
+    }
+    scarcest = max(scarcity, key=lambda role: (scarcity[role], -counts[role]))
+    if scarcity[scarcest] > 0.05:
+        return scarcest
+    return normalize_role(parent.role)
+
+
+def _next_npc_index(world: WorldState) -> int:
+    highest = 0
+    for npc in world.npcs:
+        suffix = npc.id.removeprefix("npc-")
+        if suffix.isdigit():
+            highest = max(highest, int(suffix))
+    return highest + 1
+
+
+def _child_name(index: int) -> str:
+    names = [
+        "Ada",
+        "Boris",
+        "Cora",
+        "Dima",
+        "Elena",
+        "Farid",
+        "Gita",
+        "Hana",
+        "Ivan",
+        "Juno",
+        "Kira",
+        "Lena",
+        "Mira",
+        "Niko",
+        "Oleg",
+        "Pavel",
+        "Raya",
+        "Sofia",
+        "Toma",
+        "Vera",
+    ]
+    return names[(index - 1) % len(names)]
+
+
+def _recompute_importance(world: WorldState) -> None:
+    counts = {role: 0 for role in ("gatherer", "guard", "builder")}
+    for npc in world.npcs:
+        if is_alive(npc):
+            counts[normalize_role(npc.role)] += 1
+    for npc in world.npcs:
+        role_count = max(1, counts.get(normalize_role(npc.role), 1))
+        role_scarcity = 1 / role_count
+        npc.importance = round(
+            1.0
+            + 2.0 * role_scarcity
+            + 0.5 * npc.beasts_killed
+            + 0.3 * npc.resources_transferred
+            + 0.4 * npc.children_count
+            + 0.5 * npc.houses_built,
+            3,
+        )
+
+
+def _update_population_and_status(world: WorldState, next_tick: int) -> None:
+    population = count_alive_population(world)
+    world.population = population
+    world.peak_population = max(world.peak_population, population)
+    if world.game_status != "running":
+        return
+    if population <= 0:
+        world.game_status = "lose"
+    elif population >= 12:
+        world.game_status = "win_population"
+    elif next_tick >= 600:
+        world.game_status = "win_survival"
+    if world.game_status != "running":
+        _log_event(
+            world,
+            "game_over",
+            _game_over_summary(world),
+            severity="good" if world.game_status.startswith("win") else "danger",
+            tick=next_tick,
+        )
+
+
+def _game_over_summary(world: WorldState) -> str:
+    return (
+        f"{world.game_status}: births={world.total_births}, deaths={sum(world.deaths_by_cause.values())}, "
+        f"houses_built={world.houses_built}, beasts_killed={world.beasts_killed}, "
+        f"peak_population={world.peak_population}, score={world.overseer_score}-{world.chaos_score}"
+    )
+
+
+def _chaos_points_active(world: WorldState) -> bool:
+    return world.tick <= world.chaos_intervention_until
 
 
 # --------------------------------------------------------------------------- #
@@ -696,41 +1306,88 @@ def select_goal(npc: Npc, world: WorldState) -> str:
     if not is_alive(npc):
         return "dead"
 
+    role = normalize_role(npc.role)
+
     if npc.help_target_id:
         target = _npc_by_id(world, npc.help_target_id)
         if (
             target is not None
             and is_alive(target)
-            and npc.inventory_weapon > 0
+            and role == "guard"
             and npc.relationships.get(target.id, 0.0) > 0.3
             and nearest_beast_distance(world, target) < BEAST_ALERT_RADIUS
         ):
             return "help_ally"
         npc.help_target_id = None
 
-    beast_nearby = nearest_beast_distance(world, npc) < BEAST_ALERT_RADIUS
-    has_weapon = npc.inventory_weapon > 0
-    allies_nearby = _has_trusted_ally_nearby(world, npc)
+    if role == "guard" and _beast_threatens_village(world):
+        return "engage_threat"
 
-    if beast_nearby and has_weapon and allies_nearby:
-        return "survive_threat_fight"
+    beast_nearby = nearest_beast_distance(world, npc) < BEAST_THREAT_RADIUS
+    if beast_nearby and role == "guard":
+        return "engage_threat"
     if beast_nearby:
         return "survive_threat_flee"
     if npc.health < HEAL_GOAL_HEALTH and npc.inventory_herbs > 0:
         return "heal_self"
-    if npc.hunger > STARVATION_THRESHOLD and npc.inventory_food > 0:
+    if (
+        _is_reproduction_candidate(npc)
+        and npc.inventory_food > 0
+        and 5 < npc.hunger <= REPRODUCTION_SNACK_HUNGER
+    ):
         return "eat_food"
-    if npc.hunger > STARVATION_THRESHOLD:
+    if npc.hunger >= EAT_GOAL_HUNGER and npc.inventory_food > 0:
+        return "eat_food"
+    if npc.hunger >= EAT_GOAL_HUNGER:
         return "find_food"
     if npc.health < FIND_HERBS_HEALTH and npc.inventory_herbs == 0:
         return "find_herbs"
-    return "routine_life"
+    if npc.health >= 80 and npc.hunger <= 30 and not _has_any_living_beast_near(world, npc.position, HOUSE_THREAT_RADIUS):
+        return "settle"
+    return "work"
 
 
 def allowed_actions_for_goal(goal: str) -> list[str]:
     return list(GOAL_ACTIONS.get(goal, []))
 
 
+def allowed_actions_for_npc(world: WorldState, npc: Npc, goal: str) -> list[str]:
+    _ = world
+    allowed = filter_actions_for_role(allowed_actions_for_goal(goal), npc.role)
+    if goal == "survive_threat_flee":
+        allowed = [action for action in allowed if action != "transfer"]
+    return allowed or ["idle"]
+
+
+def _beast_threatens_village(world: WorldState) -> bool:
+    for beast in world.beasts:
+        if beast.state == "dead":
+            continue
+        for house in completed_houses(world):
+            if vec_distance(beast.position, house.position) <= VILLAGE_THREAT_RADIUS:
+                return True
+        for npc in world.npcs:
+            if is_alive(npc) and vec_distance(beast.position, npc.position) <= VILLAGE_THREAT_RADIUS:
+                return True
+    return False
+
+
+def _has_any_living_beast_near(world: WorldState, position: Vec3, radius: float) -> bool:
+    return any(
+        beast.state != "dead" and vec_distance(beast.position, position) <= radius
+        for beast in world.beasts
+    )
+
+
+def _is_reproduction_candidate(npc: Npc) -> bool:
+    return (
+        npc.health >= 95
+        and npc.age > 90
+        and npc.reproduction_cooldown == 0
+        and round(npc.safety) >= 100
+    )
+
+
 def validate_survival_action(
     npc: Npc,
     action: str,
@@ -739,10 +1396,27 @@ def validate_survival_action(
 ) -> str:
     """Return a safe, executable action, repairing impossible requests."""
     action = _canonical_action(action)
+    if action not in VALID_SURVIVAL_ACTIONS:
+        return "idle"
+    resource_type = _resource_type_for_validation(world, npc, directive, action)
+    self_defense = (
+        action == "attack"
+        and nearest_beast_distance(world, npc) <= NPC_MELEE_REACH
+        and normalize_role(npc.role) == "gatherer"
+    )
+    if not action_allowed_for_role(
+        npc.role,
+        action,
+        resource_type=resource_type,
+        self_defense=self_defense,
+    ):
+        return _role_fallback_action(world, npc)
     if action == "gather":
         node = _resource_from_directive(world, directive, npc, max_dist=GATHER_RADIUS)
         if node is None or node.amount <= 0:
             return "move_to_resource"
+        if normalize_role(npc.role) == "builder" and node.resource_type != "wood":
+            return "move_to_resource"
         return "gather"
     if action == "consume":
         return "consume" if npc.inventory_food > 0 else "find_food"
@@ -753,6 +1427,18 @@ def validate_survival_action(
         if beast is None:
             return "defend"
         return "attack"  # apply_action_effects approaches when out of melee reach
+    if action == "build":
+        if normalize_role(npc.role) != "builder":
+            return _role_fallback_action(world, npc)
+        if npc.build_target_house_id:
+            house = _house_by_id(world, npc.build_target_house_id)
+            if house is not None and house.state == "under_construction":
+                return "build"
+        return "build" if npc.inventory_wood >= 5 else "move_to_resource"
+    if action == "go_home":
+        return "go_home" if nearest_house(world, npc.position) is not None else "move_to"
+    if action == "patrol":
+        return "patrol" if normalize_role(npc.role) == "guard" else _role_fallback_action(world, npc)
     if action == "steal":
         partner = nearest_alive_npc(world, npc, max_dist=TRADE_RADIUS, require_food=True)
         return "steal" if partner is not None else "move_to_resource"
@@ -763,19 +1449,43 @@ def validate_survival_action(
         if partner is None:
             partner = nearest_alive_npc(world, npc, max_dist=TRADE_RADIUS)
         return "transfer" if partner is not None else "communicate"
-    if action in VALID_SURVIVAL_ACTIONS:
-        return action
-    return "idle"
+    return action
 
 
 def _canonical_action(action: str) -> str:
-    if action == "eat":
+    return canonical_action(action)
+
+
+def _resource_type_for_validation(
+    world: WorldState,
+    npc: Npc,
+    directive: NpcDirective | None,
+    action: str,
+) -> str | None:
+    if directive is not None and directive.resource_type:
+        return directive.resource_type
+    if directive is not None and directive.resource_id:
+        node = next((node for node in world.resource_nodes if node.id == directive.resource_id), None)
+        return node.resource_type if node is not None else None
+    if action in {"gather", "move_to_resource"}:
+        node = nearest_resource_for_npc(world, npc)
+        return node.resource_type if node is not None else None
+    return None
+
+
+def _role_fallback_action(world: WorldState, npc: Npc) -> str:
+    role = normalize_role(npc.role)
+    if role == "guard":
+        if nearest_beast(world, npc.position) is not None:
+            return "attack"
+        return "patrol"
+    if role == "builder":
+        if npc.inventory_wood >= 5:
+            return "build"
+        return "move_to_resource"
+    if npc.inventory_food > 0 and npc.hunger >= EAT_GOAL_HUNGER:
         return "consume"
-    if action in {"talk", "call_for_help", "request_trade"}:
-        return "communicate"
-    if action == "trade":
-        return "transfer"
-    return action
+    return "move_to_resource"
 
 
 # --------------------------------------------------------------------------- #
@@ -823,6 +1533,13 @@ def apply_action_effects(
                 tags=["food"],
                 weight=0.2,
             )
+            _log_event(
+                world,
+                "consume",
+                f"{npc.name} ate food",
+                actor_id=npc.id,
+                object_id="food",
+            )
             return "eating food"
         return "searching for food"
 
@@ -830,12 +1547,22 @@ def apply_action_effects(
         if npc.inventory_herbs > 0:
             npc.inventory_herbs -= 1
             npc.health = min(100, npc.health + 25)
+            _log_event(
+                world,
+                "heal",
+                f"{npc.name} healed with herbs",
+                severity="good",
+                actor_id=npc.id,
+                object_id="herbs",
+            )
             return "healing with herbs"
         return "searching for herbs"
 
     if action == "gather":
         node = _resource_from_directive(world, directive, npc, max_dist=GATHER_RADIUS)
         if node is not None and node.amount > 0:
+            if normalize_role(npc.role) == "builder" and node.resource_type != "wood":
+                return "searching for wood"
             node.amount -= 1
             _add_to_inventory(npc, node.resource_type)
             add_episode(
@@ -851,6 +1578,13 @@ def apply_action_effects(
                 weight=0.3,
             )
             remember(npc, world.tick, f"You gathered {node.resource_type}.")
+            _log_event(
+                world,
+                "gather",
+                f"{npc.name} gathered {node.resource_type}",
+                actor_id=npc.id,
+                object_id=node.id,
+            )
             return f"gathering {node.resource_type}"
         return "searching for resources"
 
@@ -878,6 +1612,36 @@ def apply_action_effects(
         )
         return "wandering"
 
+    if action == "go_home":
+        house = nearest_house(world, npc.position)
+        if house is not None:
+            npc.home_house_id = house.id
+            npc.position = move_toward(
+                npc.position,
+                house.position,
+                NPC_MOVE_STEP,
+                half_width=half_width,
+                half_depth=half_depth,
+            )
+            return f"going home to {house.id}"
+        return "looking for home"
+
+    if action == "patrol":
+        target = _patrol_target(world, npc)
+        if target is not None:
+            npc.position = move_toward(
+                npc.position,
+                target,
+                NPC_MOVE_STEP,
+                half_width=half_width,
+                half_depth=half_depth,
+            )
+            return "patrolling"
+        return "standing guard"
+
+    if action == "build":
+        return _apply_build(npc, world)
+
     if action == "flee":
         beast = _beast_from_directive(world, npc, directive)
         if beast is not None:
@@ -896,7 +1660,7 @@ def apply_action_effects(
         if beast is None:
             return "defending"
         if vec_distance(npc.position, beast.position) <= NPC_MELEE_REACH:
-            damage = BASE_NPC_DAMAGE + (WEAPON_DAMAGE_BONUS if npc.inventory_weapon > 0 else 0)
+            damage = _npc_damage_against_beast(npc)
             beast.health -= damage
             npc.relationships[beast.id] = -1.0
             add_episode(
@@ -904,14 +1668,22 @@ def apply_action_effects(
                 world.tick,
                 "attack",
                 npc.id,
-                f"I struck {beast.id} for {damage} damage",
+                f"I struck {beast.id} for {damage:g} damage",
                 target_id=beast.id,
-                subject_kind="npc",
+                subject_kind="beast",
                 perspective="self",
                 tags=["danger", "beast"],
                 weight=0.8,
             )
-            remember(npc, world.tick, f"You struck {beast.id} for {damage} damage.")
+            remember(npc, world.tick, f"You struck {beast.id} for {damage:g} damage.")
+            _log_event(
+                world,
+                "npc_attack",
+                f"{npc.name} attacked {beast.id} for {damage:g}",
+                severity="warning",
+                actor_id=npc.id,
+                target_id=beast.id,
+            )
             if npc.help_target_id:
                 helped = _npc_by_id(world, npc.help_target_id)
                 if helped is not None and is_alive(helped):
@@ -929,14 +1701,25 @@ def apply_action_effects(
                     )
             if beast.health <= 0:
                 beast.state = "dead"
+                npc.beasts_killed += 1
+                world.beasts_killed += 1
+                world.overseer_score += 2
                 _record_world_event(
                     world,
-                    "death",
+                    "beast_killed",
                     f"{npc.name} killed {beast.id}",
                     beast.position,
                     radius=WITNESS_RADIUS,
                     duration_ticks=5,
                 )
+                _log_event(
+                    world,
+                    "beast_killed",
+                    f"{npc.name} killed {beast.id}",
+                    severity="good",
+                    actor_id=npc.id,
+                    target_id=beast.id,
+                )
                 remember(npc, world.tick, f"You killed {beast.id}!")
                 return "killed the beast"
             return "fighting the beast"
@@ -955,27 +1738,34 @@ def apply_action_effects(
         partner = _transfer_partner(world, npc, directive)
         resource_type = _resource_type_from_directive(directive, default="food")
         amount = _amount_from_directive(directive, default=1)
-        if (
-            partner is not None
-            and resource_type == "food"
+        can_transfer_food = (
+            resource_type == "food"
             and npc.inventory_food >= amount
+            and partner is not None
             and (npc.inventory_food >= SHARE_FOOD_SURPLUS or partner.hunger > npc.hunger)
             and partner.inventory_food < npc.inventory_food
-        ):
-            npc.inventory_food -= amount
-            partner.inventory_food += amount
+        )
+        can_transfer_nonfood = (
+            resource_type != "food"
+            and partner is not None
+            and _inventory_amount(npc, resource_type) >= amount
+        )
+        if partner is not None and (can_transfer_food or can_transfer_nonfood):
+            _remove_from_inventory(npc, resource_type, amount)
+            _add_to_inventory_amount(partner, resource_type, amount)
+            npc.resources_transferred += amount
             _adjust_relationship(npc, partner.id, 0.2)
             add_episode(
                 npc,
                 world.tick,
                 "transfer",
                 npc.id,
-                f"I gave {amount} food to {partner.name}",
+                f"I gave {amount} {resource_type} to {partner.name}",
                 target_id=partner.id,
-                object_id="food",
+                object_id=resource_type,
                 subject_kind="npc",
                 perspective="self",
-                tags=["food", "help", "trade"],
+                tags=[resource_type, "help", "trade"],
                 weight=0.5,
             )
             add_episode(
@@ -983,17 +1773,26 @@ def apply_action_effects(
                 world.tick,
                 "transfer",
                 npc.id,
-                f"{npc.name} gave me {amount} food",
+                f"{npc.name} gave me {amount} {resource_type}",
                 target_id=partner.id,
-                object_id="food",
+                object_id=resource_type,
                 subject_kind="npc",
                 perspective="recipient",
-                tags=["food", "help", "trade"],
+                tags=[resource_type, "help", "trade"],
                 weight=0.7,
             )
-            remember(npc, world.tick, f"Gave food to {partner.name}.")
-            remember(partner, world.tick, f"Received food from {npc.name}.")
-            return f"sharing food with {partner.name}"
+            remember(npc, world.tick, f"Gave {resource_type} to {partner.name}.")
+            remember(partner, world.tick, f"Received {resource_type} from {npc.name}.")
+            _log_event(
+                world,
+                "transfer",
+                f"{npc.name} gave {amount} {resource_type} to {partner.name}",
+                severity="good",
+                actor_id=npc.id,
+                target_id=partner.id,
+                object_id=resource_type,
+            )
+            return f"sharing {resource_type} with {partner.name}"
         return "looking for someone to trade with"
 
     if action == "steal":
@@ -1173,6 +1972,175 @@ def _apply_communicate(
     return "communicating"
 
 
+def _apply_build(npc: Npc, world: WorldState) -> str:
+    if normalize_role(npc.role) != "builder":
+        return "cannot build"
+
+    half_width = world.terrain.width / 2
+    half_depth = world.terrain.depth / 2
+    active_house = _house_by_id(world, npc.build_target_house_id or "")
+    if active_house is not None and active_house.state == "under_construction":
+        distance = vec_distance(npc.position, active_house.position)
+        if distance > HOUSE_BUILD_RADIUS:
+            npc.position = move_toward(
+                npc.position,
+                active_house.position,
+                NPC_MOVE_STEP,
+                half_width=half_width,
+                half_depth=half_depth,
+            )
+            return f"returning to build {active_house.id}"
+        active_house.build_progress += 1
+        if npc.id not in active_house.owner_ids:
+            active_house.owner_ids.append(npc.id)
+        if active_house.build_progress >= 10:
+            active_house.state = "completed"
+            active_house.hp = active_house.max_hp
+            npc.build_target_house_id = None
+            npc.houses_built += 1
+            world.houses_built += 1
+            world.overseer_score += 2
+            _record_world_event(
+                world,
+                "build_completed",
+                f"{npc.name} completed {active_house.id}",
+                active_house.position,
+                radius=WITNESS_RADIUS,
+                duration_ticks=6,
+            )
+            _log_event(
+                world,
+                "build_completed",
+                f"{npc.name} completed {active_house.id}",
+                severity="good",
+                actor_id=npc.id,
+                target_id=active_house.id,
+            )
+            remember(npc, world.tick, f"You completed {active_house.id}.")
+            return f"completed {active_house.id}"
+        return f"building {active_house.id}"
+
+    if npc.inventory_wood < 5:
+        return "needs wood to build"
+
+    if not _can_start_house(world, npc.position):
+        site = _preferred_build_site(world, npc)
+        npc.position = move_toward(
+            npc.position,
+            site,
+            NPC_MOVE_STEP,
+            half_width=half_width,
+            half_depth=half_depth,
+        )
+        return "moving to build site"
+
+    npc.inventory_wood -= 5
+    house = House(
+        id=f"house_{_next_house_index(world):03d}",
+        position=npc.position,
+        owner_ids=[npc.id],
+        hp=60.0,
+        max_hp=60.0,
+        state="under_construction",
+        build_progress=1,
+        capacity=3,
+    )
+    world.houses.append(house)
+    npc.build_target_house_id = house.id
+    _record_world_event(
+        world,
+        "build_started",
+        f"{npc.name} started {house.id}",
+        house.position,
+        radius=WITNESS_RADIUS,
+        duration_ticks=5,
+    )
+    _log_event(
+        world,
+        "build_started",
+        f"{npc.name} started {house.id}",
+        severity="good",
+        actor_id=npc.id,
+        target_id=house.id,
+    )
+    remember(npc, world.tick, f"You started building {house.id}.")
+    return f"building {house.id}"
+
+
+def _patrol_target(world: WorldState, npc: Npc) -> Vec3 | None:
+    threat = _nearest_village_threat(world, npc)
+    if threat is not None:
+        return threat.position
+    houses = completed_houses(world)
+    if not houses:
+        return Vec3(x=0.0, y=0.0, z=0.0)
+    houses = sorted(houses, key=lambda house: house.id)
+    if vec_distance(npc.position, houses[npc.patrol_index % len(houses)].position) <= NPC_MOVE_STEP:
+        npc.patrol_index = (npc.patrol_index + 1) % len(houses)
+    return houses[npc.patrol_index % len(houses)].position
+
+
+def _nearest_village_threat(world: WorldState, npc: Npc) -> Beast | None:
+    candidates = [
+        beast
+        for beast in world.beasts
+        if beast.state != "dead"
+        and (
+            any(vec_distance(beast.position, house.position) <= VILLAGE_THREAT_RADIUS for house in world.houses)
+            or any(
+                is_alive(other)
+                and vec_distance(beast.position, other.position) <= VILLAGE_THREAT_RADIUS
+                for other in world.npcs
+            )
+        )
+    ]
+    if not candidates:
+        return nearest_beast(world, npc.position)
+    return min(candidates, key=lambda beast: (vec_distance(npc.position, beast.position), beast.id))
+
+
+def _npc_damage_against_beast(npc: Npc) -> float:
+    damage = BASE_NPC_DAMAGE + (WEAPON_DAMAGE_BONUS if npc.inventory_weapon > 0 else 0)
+    role = normalize_role(npc.role)
+    if role == "guard":
+        return damage * GUARD_DAMAGE_MULTIPLIER
+    if role in {"gatherer", "builder"}:
+        return damage * WEAK_DAMAGE_MULTIPLIER
+    return float(damage)
+
+
+def _house_by_id(world: WorldState, house_id: str) -> House | None:
+    if not house_id:
+        return None
+    return next((house for house in world.houses if house.id == house_id), None)
+
+
+def _can_start_house(world: WorldState, position: Vec3) -> bool:
+    return all(vec_distance(position, house.position) >= HOUSE_MIN_DISTANCE for house in world.houses)
+
+
+def _preferred_build_site(world: WorldState, npc: Npc) -> Vec3:
+    half_width = world.terrain.width / 2
+    half_depth = world.terrain.depth / 2
+    angle = (len(world.houses) * 1.61803398875) % (2 * math.pi)
+    center = nearest_house(world, npc.position, completed_only=False)
+    origin = center.position if center is not None else Vec3(x=0.0, y=0.0, z=0.0)
+    return Vec3(
+        x=round(_clamp(origin.x + math.cos(angle) * (HOUSE_MIN_DISTANCE + TILE), -half_width, half_width), 3),
+        y=0.0,
+        z=round(_clamp(origin.z + math.sin(angle) * (HOUSE_MIN_DISTANCE + TILE), -half_depth, half_depth), 3),
+    )
+
+
+def _next_house_index(world: WorldState) -> int:
+    highest = 0
+    for house in world.houses:
+        suffix = house.id.removeprefix("house_")
+        if suffix.isdigit():
+            highest = max(highest, int(suffix))
+    return highest + 1
+
+
 def resolve_call_for_help(caller: Npc, world: WorldState) -> list[Npc]:
     helpers: list[Npc] = []
     for helper in npcs_in_radius(world, caller.position, HELP_RADIUS, exclude_id=caller.id):
@@ -1208,7 +2176,7 @@ def _resource_from_directive(
         node = next((node for node in world.resource_nodes if node.id == directive.resource_id), None)
         if node is not None and (max_dist is None or vec_distance(npc.position, node.position) <= max_dist):
             return node
-    return nearest_resource(world, npc.position, max_dist=max_dist)
+    return nearest_resource_for_npc(world, npc, max_dist=max_dist)
 
 
 def _beast_from_directive(
@@ -1299,26 +2267,55 @@ def _message_for_intent(intent: str) -> str:
 
 
 def _add_to_inventory(npc: Npc, resource_type: str) -> None:
+    _add_to_inventory_amount(npc, resource_type, 1)
+
+
+def _add_to_inventory_amount(npc: Npc, resource_type: str, amount: int) -> None:
+    if resource_type == "food":
+        npc.inventory_food += amount
+    elif resource_type == "herbs":
+        npc.inventory_herbs += amount
+    elif resource_type == "wood":
+        npc.inventory_wood += amount
+    elif resource_type == "weapon":
+        npc.inventory_weapon += amount
+
+
+def _remove_from_inventory(npc: Npc, resource_type: str, amount: int) -> None:
     if resource_type == "food":
-        npc.inventory_food += 1
+        npc.inventory_food = max(0, npc.inventory_food - amount)
     elif resource_type == "herbs":
-        npc.inventory_herbs += 1
+        npc.inventory_herbs = max(0, npc.inventory_herbs - amount)
     elif resource_type == "wood":
-        npc.inventory_wood += 1
+        npc.inventory_wood = max(0, npc.inventory_wood - amount)
     elif resource_type == "weapon":
-        npc.inventory_weapon += 1
+        npc.inventory_weapon = max(0, npc.inventory_weapon - amount)
+
+
+def _inventory_amount(npc: Npc, resource_type: str) -> int:
+    if resource_type == "food":
+        return npc.inventory_food
+    if resource_type == "herbs":
+        return npc.inventory_herbs
+    if resource_type == "wood":
+        return npc.inventory_wood
+    if resource_type == "weapon":
+        return npc.inventory_weapon
+    return 0
 
 
 def _resource_destination(world: WorldState, npc: Npc, action: str) -> Vec3 | None:
-    if action == "find_food":
+    if normalize_role(npc.role) == "builder":
+        resource_type: str | None = "wood"
+    elif action == "find_food":
         resource_type: str | None = "food"
     elif action == "find_herbs":
         resource_type = "herbs"
     else:
         resource_type = None
-    node = nearest_resource(world, npc.position, resource_type=resource_type)
+    node = nearest_resource_for_npc(world, npc, resource_type=resource_type)
     if node is None:
-        node = nearest_resource(world, npc.position)
+        node = nearest_resource_for_npc(world, npc)
     return node.position if node is not None else None
 
 
@@ -1334,6 +2331,8 @@ def _spread_resource(
     Spreading foragers across several nearby nodes stops the whole settlement from
     piling onto a single node and then starving together.
     """
+    if normalize_role(npc.role) == "builder":
+        resource_type = "wood"
     nodes = sorted(
         (
             node
@@ -1342,7 +2341,7 @@ def _spread_resource(
         ),
         key=lambda node: (vec_distance(npc.position, node.position), node.id),
     )
-    if not nodes and resource_type is not None:
+    if not nodes and resource_type is not None and normalize_role(npc.role) != "builder":
         nodes = sorted(
             (node for node in world.resource_nodes if node.amount > 0),
             key=lambda node: (vec_distance(npc.position, node.position), node.id),
@@ -1432,7 +2431,7 @@ def _clamp(value: float, minimum: float, maximum: float) -> float:
 # Deterministic survival planner + resolver
 # --------------------------------------------------------------------------- #
 def is_survival_world(world: WorldState) -> bool:
-    return bool(world.beasts or world.resource_nodes)
+    return bool(world.beasts or world.resource_nodes or world.houses)
 
 
 def survival_directive_for(world: WorldState, npc: Npc, next_tick: int) -> NpcDirective:
@@ -1483,6 +2482,8 @@ def apply_survival_plan(
                 directive.conversation_user,
                 directive.conversation_assistant,
             )
+        if directive.memory:
+            remember(npc, next_tick, directive.memory)
         if next_tick > 0 and next_tick % 10 == 0:
             compress_to_facts(npc)
         debug.append(
@@ -1535,6 +2536,14 @@ def _plan_directive(
             intent=f"survival:{goal}",
         )
 
+    role = normalize_role(npc.role)
+
+    if goal == "engage_threat":
+        beast = _nearest_village_threat(world, npc)
+        if beast is not None:
+            return directive("attack", target=beast.position, resource_id=None)
+        return directive("patrol")
+
     if goal == "survive_threat_fight":
         if (next_tick + index) % 3 == 0:
             return directive("communicate", communication_intent="help_request")
@@ -1556,6 +2565,16 @@ def _plan_directive(
 
     if goal in ("find_food", "find_herbs"):
         resource_type = "food" if goal == "find_food" else "herbs"
+        if role == "builder" and goal == "find_food":
+            partner = nearest_alive_npc(world, npc, max_dist=TRADE_RADIUS, require_food=True)
+            if partner is not None:
+                return directive(
+                    "communicate",
+                    target_npc_id=partner.id,
+                    resource_type="food",
+                    communication_intent="trade_request",
+                )
+            return directive("go_home")
         if goal == "find_food":
             partner = nearest_alive_npc(world, npc, max_dist=TRADE_RADIUS, require_food=True)
             if (
@@ -1577,7 +2596,49 @@ def _plan_directive(
             return directive("move_to_resource", target=node.position, resource_id=node.id)
         return directive("move_to")  # nothing to gather right now -> wander, don't freeze
 
-    # routine_life: socialise, share, forage, or wander -- and spread out.
+    if goal == "settle":
+        house = house_containing_npc(world, npc)
+        if (
+            house is not None
+            and _is_reproduction_candidate(npc)
+            and 5 < npc.hunger <= REPRODUCTION_SNACK_HUNGER
+            and npc.inventory_food > 0
+        ):
+            return directive("consume")
+        if house is None:
+            return directive("go_home")
+        if (next_tick + index) % 3 == 0:
+            neighbor = nearest_alive_npc(world, npc, max_dist=TALK_RADIUS)
+            if neighbor is not None:
+                return directive(
+                    "communicate",
+                    target_npc_id=neighbor.id,
+                    communication_intent="social",
+                )
+        return directive("go_home")
+
+    if goal == "work":
+        if role == "guard":
+            return directive("patrol")
+        if role == "builder":
+            if npc.build_target_house_id or npc.inventory_wood >= 5:
+                return directive("build")
+            node = _spread_resource(world, npc, index, resource_type="wood")
+            if node is not None and vec_distance(npc.position, node.position) <= GATHER_RADIUS:
+                return directive("gather", resource_id=node.id)
+            if node is not None:
+                return directive("move_to_resource", target=node.position, resource_id=node.id)
+            return directive("go_home")
+        builder = _nearest_role(world, npc, "builder", max_dist=TRADE_RADIUS)
+        if builder is not None and npc.inventory_wood > 0:
+            return directive(
+                "transfer",
+                target_npc_id=builder.id,
+                resource_type="wood",
+                amount=1,
+            )
+
+    # routine_life/work fallback: socialise, share, forage, or wander -- and spread out.
     neighbor = nearest_alive_npc(world, npc, max_dist=TALK_RADIUS)
     phase = (next_tick + index) % 4
     if (

src/god_simulator/simulation/tick.py

@@ -34,18 +34,24 @@ from god_simulator.simulation.mechanics import (
     walk_away_target,
 )
 from god_simulator.simulation.memory import remember
+from god_simulator.simulation.overseer import OverseerController, apply_overseer_metadata
 from god_simulator.simulation.perception import CitizenPerception, nearby_threat_npc
 from god_simulator.simulation.survival import (
     add_episode,
+    apply_post_survival_tick,
     apply_survival_plan,
     apply_survival_tick,
     is_survival_world,
 )
 
 
-def advance_world(world: WorldState, simulator: WorldSimulator | None = None) -> WorldState:
+def advance_world(
+    world: WorldState,
+    simulator: WorldSimulator | None = None,
+    overseer: OverseerController | None = None,
+) -> WorldState:
     """Advance world state by asking the configured simulator for a tick plan."""
-    next_tick, plan = plan_world_tick(world, simulator)
+    next_tick, plan = plan_world_tick(world, simulator, overseer=overseer)
     apply_tick_plan(world, next_tick, plan)
     return world
 
@@ -54,11 +60,15 @@ def plan_world_tick(
     world: WorldState,
     simulator: WorldSimulator | None = None,
     next_tick: int | None = None,
+    overseer: OverseerController | None = None,
 ) -> tuple[int, TickPlan]:
     """Build a tick plan without mutating the supplied world state."""
     planned_tick = next_tick if next_tick is not None else world.tick + 1
     active_simulator = simulator or DeterministicWorldSimulator()
-    return planned_tick, active_simulator.propose_tick(world, planned_tick)
+    plan = active_simulator.propose_tick(world, planned_tick)
+    if overseer is not None:
+        plan = overseer.augment_plan(world, planned_tick, plan)
+    return planned_tick, plan
 
 
 def apply_tick_plan(world: WorldState, next_tick: int, plan: TickPlan) -> None:
@@ -70,8 +80,10 @@ def apply_tick_plan(world: WorldState, next_tick: int, plan: TickPlan) -> None:
     # In a survival world all directives (deterministic or LLM) resolve through
     # the survival resolver so the engine owns hunger/health/position/inventory.
     if plan.source.startswith("survival") or is_survival_world(world):
-        debug = apply_survival_plan(world, next_tick, plan)
         world.tick = next_tick
+        apply_overseer_metadata(world, plan.overseer)
+        debug = apply_survival_plan(world, next_tick, plan)
+        apply_post_survival_tick(world, next_tick)
         world.last_tick_source = plan.source
         world.last_action_debug = debug
         return
@@ -145,6 +157,7 @@ def apply_tick_plan(world: WorldState, next_tick: int, plan: TickPlan) -> None:
             npc.intention = "dead"
 
     world.tick = next_tick
+    apply_overseer_metadata(world, plan.overseer)
     world.last_tick_source = plan.source
     world.last_action_debug = [_trace_to_dict(trace) for trace in resolved_traces]
 
@@ -170,7 +183,7 @@ def validate_tick_plan(
         )
         resolved_directives.append(validation.directive)
 
-    return TickPlan(source=plan.source, directives=resolved_directives), traces
+    return TickPlan(source=plan.source, directives=resolved_directives, overseer=plan.overseer), traces
 
 
 def validate_directive(

tests/test_claw3d_contract.py

@@ -38,7 +38,7 @@ def test_claw3d_snapshot_contains_terrain_and_entities() -> None:
     assert snapshot["entities"][0]["state"]["memory_count"] == 1
     assert snapshot["entities"][0]["state"]["memory_summary"] is None
     assert snapshot["entities"][0]["state"]["memories"] == [
-        {"tick": 0, "text": "Ada arrived as a farmer."}
+        {"tick": 0, "text": "Ada arrived as a gatherer."}
     ]
 
 

tests/test_npc_simulation_v2.py

@@ -249,12 +249,19 @@ def test_call_for_help_ignores_unarmed_or_low_trust_npcs() -> None:
 
 
 def test_armed_npc_with_trusted_ally_selects_fight() -> None:
-    fighter = _npc("npc-001", "Ada", x=8.0, inventory_weapon=1)
+    # Only guards engage threats (GAME_DESIGN 12); other roles flee.
+    fighter = Npc(
+        id="npc-001",
+        name="Ada",
+        role="guard",
+        position=Vec3(x=8.0, y=0.0, z=0.0),
+        inventory_weapon=1,
+    )
     ally = _npc("npc-002", "Boris", x=12.0)
     fighter.relationships[ally.id] = 0.8
     beast = Beast("beast_1", Vec3(0.0, 0.0, 0.0))
 
-    assert select_goal(fighter, _world([fighter, ally], beasts=[beast])) == "survive_threat_fight"
+    assert select_goal(fighter, _world([fighter, ally], beasts=[beast])) == "engage_threat"
 
 
 def test_armed_npc_with_low_trust_neighbor_selects_flee() -> None:

tests/test_openai_connector.py

@@ -92,7 +92,7 @@ def test_openai_connector_uses_tool_calls_for_npc_directives() -> None:
     assert world.npcs[0].position.z == 2
     assert world.npcs[0].intention == "walking"
     assert [memory.text for memory in world.npcs[0].memory] == [
-        "Ada arrived as a farmer."
+        "Ada arrived as a gatherer."
     ]
 
 
@@ -248,18 +248,17 @@ def test_openai_connector_sends_only_one_agent_state_per_request() -> None:
 
     advance_world(world, simulator)
 
-    assert [request["npc"]["id"] for request in requests] == [
-        "npc-001",
-        "npc-002",
-        "npc-003",
-    ]
+    # Agents are called in parallel, so request order is not deterministic.
+    requests_by_id = {request["npc"]["id"]: request for request in requests}
+    assert sorted(requests_by_id) == ["npc-001", "npc-002", "npc-003"]
     assert all("npcs" not in request for request in requests)
-    assert requests[0]["npc"]["visible_npcs"][0]["id"] == "npc-002"
-    assert "role" not in requests[0]["npc"]["visible_npcs"][0]
-    assert "attack_damage" not in requests[0]["npc"]["visible_npcs"][0]
-    assert "health" not in requests[0]["npc"]["visible_npcs"][0]
-    assert requests[0]["npc"]["visible_npcs"][0]["condition"] == "healthy"
-    assert requests[2]["npc"]["visible_npcs"] == []
+    first_request = requests_by_id["npc-001"]
+    assert first_request["npc"]["visible_npcs"][0]["id"] == "npc-002"
+    assert "role" not in first_request["npc"]["visible_npcs"][0]
+    assert "attack_damage" not in first_request["npc"]["visible_npcs"][0]
+    assert "health" not in first_request["npc"]["visible_npcs"][0]
+    assert first_request["npc"]["visible_npcs"][0]["condition"] == "healthy"
+    assert requests_by_id["npc-003"]["npc"]["visible_npcs"] == []
     assert {npc.intention for npc in world.npcs} == {"walking"}
     assert world.last_tick_source == "openai_compatible"
 

tests/test_survival_loop.py

@@ -19,10 +19,12 @@ from god_simulator.simulation.connectors.openai_compatible import (
     build_tool_list_for_goal,
 )
 from god_simulator.simulation.spawning import create_world
+import pytest
+
 from god_simulator.simulation.survival import (
-    BEAST_SPAWN_INTERVAL,
     GOAL_ACTIONS,
     MAX_BEASTS,
+    _natural_beast_spawn_interval,
     apply_action_effects,
     apply_survival_tick,
     select_goal,
@@ -62,16 +64,16 @@ def _survival_config(*, npc_count: int = 6) -> GameConfig:
     )
 
 
-# 1. hunger grows every tick
+# 1. hunger grows every tick (GAME_DESIGN: +0.8/tick)
 def test_hunger_increases_each_tick() -> None:
     npc = _npc(hunger=25.0)
     world = _world([npc], resource_nodes=[ResourceNode("r", "food", Vec3(30.0, 0.0, 30.0), 5)])
 
     apply_survival_tick(world)
-    assert npc.hunger == 27.0
+    assert npc.hunger == pytest.approx(25.8)
 
     apply_survival_tick(world)
-    assert npc.hunger == 29.0
+    assert npc.hunger == pytest.approx(26.6)
 
 
 # 2. hunger > 80 + food in inventory -> goal = eat_food
@@ -137,14 +139,14 @@ def test_nearby_beast_triggers_survive_threat_goal() -> None:
     assert goal.startswith("survive_threat")
 
 
-# 9. armed NPC with allies -> survive_threat_fight
+# 9. only guards engage threats (GAME_DESIGN 12); everyone else flees
 def test_armed_npc_with_allies_fights() -> None:
-    fighter = _npc("npc-001", "Ada", x=8.0, z=0.0, inventory_weapon=1)
+    fighter = _npc("npc-001", "Ada", x=8.0, z=0.0, role="guard", inventory_weapon=1)
     ally = _npc("npc-002", "Boris", x=10.0, z=0.0)
     fighter.relationships[ally.id] = 0.8
     beast = Beast("beast_1", Vec3(0.0, 0.0, 0.0))
 
-    assert select_goal(fighter, _world([fighter, ally], beasts=[beast])) == "survive_threat_fight"
+    assert select_goal(fighter, _world([fighter, ally], beasts=[beast])) == "engage_threat"
 
 
 # 10. unarmed loner -> survive_threat_flee
@@ -220,15 +222,15 @@ def test_resource_nodes_regrow_over_time() -> None:
     node = ResourceNode("r", "food", Vec3(40.0, 0.0, 40.0), amount=1, max_amount=5)
     world = _world([_npc(x=0.0, z=0.0)], resource_nodes=[node], tick=0)
 
-    apply_survival_tick(world)  # tick 0 % 2 == 0 -> +1
+    apply_survival_tick(world)  # food regrows every 8 ticks; tick 0 % 8 == 0 -> +1
     assert node.amount == 2
 
-    world.tick = 2
+    world.tick = 8
     apply_survival_tick(world)  # -> +1
     assert node.amount == 3
 
     node.amount = 5
-    world.tick = 4
+    world.tick = 16
     apply_survival_tick(world)  # never exceeds the cap
     assert node.amount == 5
 
@@ -248,27 +250,38 @@ def test_resources_spawn_randomly_but_deterministically_by_seed() -> None:
 
 
 def test_beast_random_spawn_respects_max_beasts_and_cooldown() -> None:
+    def villagers() -> list[Npc]:
+        # Natural beast spawns require population >= 4.
+        return [_npc(f"npc-{index}", f"Villager{index}", x=float(index)) for index in range(4)]
+
+    def find_spawn_tick() -> int:
+        probe = _world(villagers(), tick=0)
+        for tick in range(60, 2000):
+            probe.tick = tick
+            if tick % _natural_beast_spawn_interval(probe) == 0:
+                return tick
+        raise AssertionError("no natural beast spawn tick found for this seed")
+
+    spawn_tick = find_spawn_tick()
     node = ResourceNode("r", "food", Vec3(40.0, 0.0, 40.0), amount=1, max_amount=5)
-    cooldown_world = _world([_npc()], resource_nodes=[node], beasts=[], tick=BEAST_SPAWN_INTERVAL - 1)
 
+    cooldown_world = _world(villagers(), resource_nodes=[node], beasts=[], tick=1)
     apply_survival_tick(cooldown_world)
-
     assert cooldown_world.beasts == []
 
-    spawn_world = _world([_npc()], resource_nodes=[node], beasts=[], tick=BEAST_SPAWN_INTERVAL)
+    spawn_world = _world(villagers(), resource_nodes=[node], beasts=[], tick=spawn_tick)
     apply_survival_tick(spawn_world)
-
     assert len(spawn_world.beasts) == 1
     assert spawn_world.beasts[0].id == "beast_1"
 
     capped_world = _world(
-        [_npc()],
+        villagers(),
         resource_nodes=[node],
         beasts=[
             Beast(f"beast_{index}", Vec3(float(index), 0.0, 0.0))
             for index in range(1, MAX_BEASTS + 1)
         ],
-        tick=BEAST_SPAWN_INTERVAL,
+        tick=spawn_tick,
     )
     apply_survival_tick(capped_world)
 

tests/test_world_spawning.py

@@ -145,7 +145,7 @@ def test_memory_keeps_recent_entries_and_summarizes_older_events() -> None:
 
     assert len(speaker.memory) == 5
     assert speaker.memory_summary is not None
-    assert "Ada arrived as a farmer." in speaker.memory_summary
+    assert "Ada arrived as a gatherer." in speaker.memory_summary
     assert "Message 1." in speaker.memory_summary
     assert "Message 7." in speaker.memory[-1].text