feat: phase 1 — memory layer, governor, second scenario, 70 passing tests

Engine additions (zero scenario edits required):
- EpisodicMemory: per-agent filtered view over the ledger; agents see only their
own actions and globally-visible event kinds, capped at 8 events for small-model
context windows
- ContextBuilder: single point of prompt assembly (persona → scene → memory →
visitor disturbances); changing prompt strategy is now a one-file edit
- Governor: enforces max_turns / max_calls_per_turn / max_total_calls; raises
BudgetExceeded before a runaway cascade can burn quota

Model provider:
- OpenAICompatProvider: works with any OpenAI-compatible endpoint; config via
OPENAI_API_KEY / OPENAI_BASE_URL / MODEL_NAME; falls back to deterministic stub
when no key is present

Agents + scenarios:
- All four Tiny Wood agents use ContextBuilder with rich personas and episodic memory
- New EchoAgent transforms visitor injections through the wood's logic
- Mystery Roots (src/scenarios/mystery_roots.py): convergent blackboard swarm with
ClueGatherer / HypothesisFormer / DevilsAdvocate / MysteryJudge — zero engine edits

UI:
- Two-scenario dropdown with per-scenario seed gallery
- Governor stats surfaced in the run-stats panel
- Custom CSS with variables, stage gradient, monospace ledger

Tests: 14 → 70 passing (test_memory, test_governor, test_mystery_roots,
test_events, test_projections, test_scenario, test_ledger, test_conductor)

Docs: ADR-0005 through ADR-0008, engine-architecture blog post, phase-1 journal

Co-Authored-By: Codex <codex@openai.com>

.env.example

@@ -0,0 +1,24 @@
+# Copy to .env and fill in your values.
+# Without OPENAI_API_KEY the app runs on a deterministic local stub.
+
+# Required for live model inference
+OPENAI_API_KEY=sk-...
+
+# Optional: point at any OpenAI-compatible endpoint
+# Examples:
+#   Together AI:  https://api.together.xyz/v1
+#   Groq:         https://api.groq.com/openai/v1
+#   Ollama local: http://localhost:11434/v1
+#   NVIDIA NIM:   https://integrate.api.nvidia.com/v1
+OPENAI_BASE_URL=
+
+# Model name — any model the endpoint supports
+# Default: gpt-4o-mini (fast, cheap, under 32B effective param count for tasks)
+# Tiny Titan (<=4B): e.g. Qwen2.5-3B-Instruct via Together or Ollama
+MODEL_NAME=gpt-4o-mini
+
+# Set to 1 to activate <=4B Tiny Titan profile
+TINY_TITAN_MODE=0
+
+# Gradio server port (auto-detects a free port in 7960-8059 if unset)
+GRADIO_SERVER_PORT=

.gitignore

@@ -4,4 +4,5 @@ __pycache__/
 .env
 .DS_Store
 .gradio/
-
+.claude
+scripts/pre-commit

README.md

@@ -1,63 +1,165 @@
 # Multi-Agent Land
 
-Hackathon project for the **Thousand Token Wood** trail: a small-model, multi-agent interactive story engine where the AI is load-bearing for the experience.
+Hackathon project for the **Thousand Token Wood** trail: a small-model, multi-agent
+interactive story engine where the AI is load-bearing for the experience.
 
-The working thesis is:
+> One tiny event-sourced engine can power many delightful worlds.  The first world is
+> a whimsical forest theater where small specialist agents write, judge, remember, and
+> render strange interactive scenes.  The second is a mystery-solving blackboard swarm.
+> Both run on the same four abstractions.
 
-> One tiny event-sourced engine can power many delightful worlds. The first world is a whimsical forest theater where small specialist agents write, judge, remember, and render strange interactive scenes.
+---
 
-## Hackathon Targets
-
-- Delight first: strange, joyful interactions worth showing a friend.
-- AI is load-bearing: agents create the evolving story, not just labels around static UI.
-- Small models: keep every runtime model under the 32B parameter cap, with an optional <=4B Tiny Titan mode.
-- Polished Gradio app: custom layout, live ledger, visible agent activity, and demo-friendly defaults.
-- Prize stacking: aim for Thousand Token Wood, Community Choice, OpenAI Track, Tiny Titan, Best Agent, Off-Brand UI, Best Demo, and Judges' Wildcard.
-
-## Quick Start
+## Quickstart
 
 ```bash
 python -m venv .venv
-source .venv/bin/activate
+source .venv/bin/activate         # Windows: .venv\Scripts\activate
 pip install -r requirements.txt
+
+# Optional: add your API key for live inference
+cp .env.example .env              # then fill in OPENAI_API_KEY
+
 python app.py
 ```
 
-The app is intentionally usable with a deterministic local model stub first. Swap in real small-model providers through `src/models/provider.py` as the build matures.
+The app runs on a **deterministic local stub** with no API key — great for testing
+and demos that need to be fully reproducible.  Add an `OPENAI_API_KEY` to switch to
+live inference.  Any OpenAI-compatible endpoint works (Together AI, Groq, Ollama,
+NVIDIA NIM) — set `OPENAI_BASE_URL` in `.env`.
+
+### Run tests
+
+```bash
+python -m pytest tests/ -v
+```
+
+---
+
+## What It Is
+
+A **tiny theater engine** powered by specialist small-model agents.  Agents never
+call each other directly — they post typed events to a shared append-only ledger,
+and every view (the stage, the memory, the UI) is a projection derived from that log.
+
+The user can:
+- **Start** a run from a seed — any weird premise works.
+- **Advance** one turn and watch the agents react.
+- **Drop** a disturbance into the world — the agents absorb and transform it.
+- **Switch** between scenarios without reloading.
+
+### Scenarios
+
+| Name | Cognitive task | Agents |
+|---|---|---|
+| 🍄 Thousand Token Wood | Divergent world-growth | Seedkeeper, Critic, Pocket Actor, Echo |
+| 🔍 Mystery Roots | Convergent mystery-solving | Clue Gatherer, Hypothesis Former, Devil's Advocate, Judge |
 
-## Repository Map
+Adding a third scenario requires one new file and one two-line registry entry.
+**Zero engine edits.**
 
-```text
+---
+
+## Architecture in 90 seconds
+
+```
+Visitor seed or disturbance
+         │
+    Conductor ← Governor (budget guard)
+         │
+    schedule(turn) → [Agent₁, Agent₂, ...]
+         │
+    ContextBuilder
+         ├── Pinned persona
+         ├── Current scene  (projection)
+         ├── Episodic memory (ledger view)
+         └── Visitor disturbances
+         │
+    ModelProvider.complete(role, prompt)
+         │
+    Typed Event → Ledger.append()
+         │
+    Projections update
+         │
+    Gradio UI renders stage + ledger + stats
+```
+
+### Key decisions (see `docs/adr/` for full reasoning)
+
+| # | Decision |
+|---|---|
+| 0001 | Append-only event ledger as the sole source of truth |
+| 0002 | Gradio as the UI layer |
+| 0003 | Small specialist agents over one large model |
+| 0004 | Document every architectural decision as we build |
+| 0005 | Agent memory is a ledger view, not a separate store |
+| 0006 | `ContextBuilder` owns prompt assembly; agents own only persona + action |
+| 0007 | `Governor` is injected into the conductor to enforce call budgets |
+| 0008 | Zero engine edits required to add a second scenario |
+
+---
+
+## Repository map
+
+```
 app.py                      Gradio composition root
 src/
-  core/                     Event ledger, schemas, projections, conductor
-  agents/                   Manifest-driven specialist agents
-  scenarios/                Scenario configuration and seeds
-  models/                   Small-model provider abstraction
-  ui/                       Gradio rendering helpers
+  core/
+    events.py               Event schema (Pydantic, strict)
+    ledger.py               Append-only in-memory ledger
+    projections.py          Pure-function stage projection
+    conductor.py            Turn scheduler + reset + inject
+    memory.py               EpisodicMemory — per-agent ledger view
+    context.py              ContextBuilder — prompt assembly
+    governor.py             Budget guard (turns, calls per turn, total calls)
+  agents/
+    base.py                 Abstract Agent protocol
+    tiny_wood.py            Thousand Token Wood cast
+  scenarios/
+    base.py                 Scenario dataclass + default schedule
+    thousand_token_wood.py  First scenario config
+    mystery_roots.py        Second scenario config — modularity proof
+  models/
+    provider.py             ModelProvider ABC + DeterministicTinyModel stub
+    openai_compat.py        OpenAI-compatible provider + env-aware factory
+  ui/
+    render.py               Gradio rendering helpers
+tests/                      70 passing tests, zero mocks
 docs/
   vision.md                 One-page product and technical vision
-  architecture/             System design, C4-style notes, sequence diagrams
-  adr/                      Append-only Architecture Decision Records
+  architecture/             System design and turn lifecycle
+  adr/                      Append-only Architecture Decision Records (0001–0008)
   schema/                   Event and manifest contracts
-  runbooks/                 Local dev, demo, recovery, observability
-  strategy/                 Hackathon prize strategy and judging rubric
+  runbooks/                 Local dev, demo, recovery
+  strategy/                 Hackathon prize strategy
   blog/                     Technical blog posts built along the way
   journal/                  Daily build log entries
 scripts/
   new_journal_entry.py      Creates dated build log entries
-  snapshot_progress.py      Updates docs/blog/building-in-public.md from journal
+  snapshot_progress.py      Updates the living blog from journal
 ```
 
-## Development Loop
+---
 
-1. Build the thinnest vertical slice.
-2. Record decisions in `docs/adr/`.
-3. Capture learnings with `python scripts/new_journal_entry.py "What changed"`.
-4. Regenerate the living technical blog with `python scripts/snapshot_progress.py`.
-5. Keep scenarios modular: new worlds should be config and plugin files, not engine rewrites.
+## Hackathon targets
 
-## Current Status
+- **Genuinely delightful** — strange, joyful, worth showing a friend
+- **AI is load-bearing** — agents generate the evolving scene; the user does not author it
+- **Small models** — every runtime model ≤ 32B, with an optional ≤ 4B Tiny Titan mode
+- **Polished Gradio** — custom theme, live ledger, visible agent trace, demo-ready seeds
+- **Prize stacking** — Thousand Token Wood, Community Choice, OpenAI Track, Tiny Titan,
+  Best Agent, Off-Brand UI, Best Demo, Judges' Wildcard
 
-Phase 0 foundation is scaffolded. The next milestone is a polished vertical slice: three agents, one judge, one observer projection, and a Gradio experience that feels playful immediately.
+---
 
+## Development loop
+
+```bash
+# 1. Build the thinnest slice
+# 2. Record the decision
+python -c "from scripts.new_journal_entry import main; main()" "What changed today"
+# 3. Regenerate the living blog
+python scripts/snapshot_progress.py
+# 4. Confirm nothing broke
+python -m pytest tests/ -q
+```

app.py

@@ -6,112 +6,209 @@ import socket
 import gradio as gr
 
 from src.core.conductor import Conductor
-from src.scenarios.thousand_token_wood import build_scenario
+from src.scenarios import mystery_roots, thousand_token_wood
 from src.ui.render import render_event_log, render_stage, render_stats
 
+# ── scenario registry ─────────────────────────────────────────────────────────
 
-scenario = build_scenario()
-conductor = Conductor(scenario=scenario)
+SCENARIOS = {
+    "🍄 Thousand Token Wood": thousand_token_wood.build_scenario(),
+    "🔍 Mystery Roots": mystery_roots.build_scenario(),
+}
+
+_conductors: dict[str, Conductor] = {name: Conductor(s) for name, s in SCENARIOS.items()}
+
+# ── CSS ───────────────────────────────────────────────────────────────────────
 
 APP_CSS = """
-body { background: #10130f; }
-.gradio-container { max-width: 1180px !important; }
+:root {
+  --bg: #0e1209;
+  --surface: #141a0f;
+  --border: #2e3d25;
+  --text: #e8e2cc;
+  --muted: #8a9c7a;
+  --accent: #6db56d;
+  --accent2: #c9a84c;
+  --danger: #c96b6b;
+}
+body { background: var(--bg); color: var(--text); }
+.gradio-container { max-width: 1200px !important; font-family: 'Georgia', serif; }
+footer { display: none !important; }
+
+/* Header */
+.wood-header h1 {
+  font-size: 2rem;
+  color: var(--accent);
+  letter-spacing: .04em;
+  margin-bottom: 2px;
+}
+.wood-header p { color: var(--muted); margin-top: 0; font-style: italic; }
+
+/* Stage */
 #stage {
-  border: 1px solid #3e4a36;
-  background: linear-gradient(180deg, #172017 0%, #11160f 100%);
-  color: #f4f0df;
-  padding: 18px;
-  border-radius: 8px;
-  min-height: 420px;
+  border: 1px solid var(--border);
+  background: linear-gradient(180deg, #172017 0%, var(--surface) 100%);
+  color: var(--text);
+  padding: 20px 24px;
+  border-radius: 10px;
+  min-height: 380px;
+  font-size: 0.97rem;
+  line-height: 1.7;
 }
+#stage h2 { color: var(--accent); font-size: 1.1rem; border-bottom: 1px solid var(--border); padding-bottom: 6px; }
+#stage h3 { color: var(--accent2); font-size: 0.95rem; margin-top: 16px; margin-bottom: 6px; }
+
+/* Ledger + stats */
 #events textarea, #stats textarea {
-  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
-  font-size: 12px;
+  font-family: ui-monospace, 'Cascadia Code', 'Fira Mono', monospace;
+  font-size: 11px;
+  background: var(--surface);
+  color: var(--muted);
+  border-color: var(--border);
+}
+
+/* Buttons */
+button.primary { background: var(--accent) !important; color: var(--bg) !important; font-weight: 700; }
+button.secondary { border-color: var(--border) !important; color: var(--muted) !important; }
+
+/* Scenario selector */
+.scenario-selector label { color: var(--accent2) !important; }
+
+/* Seed input */
+#seed-box textarea { font-style: italic; }
+
+/* Inject row */
+#inject-box textarea { border-color: var(--accent2) !important; }
+
+/* Status pill */
+.status-pill {
+  display: inline-block;
+  padding: 2px 10px;
+  border-radius: 999px;
+  font-size: 0.75rem;
+  font-family: monospace;
+  background: var(--surface);
+  border: 1px solid var(--border);
+  color: var(--muted);
 }
-.wood-title h1 { margin-bottom: 0; }
-.wood-title p { margin-top: 6px; color: #b9c3a7; }
 """
 
+# ── helpers ───────────────────────────────────────────────────────────────────
 
-def dev_server_port() -> int:
-    configured = os.getenv("GRADIO_SERVER_PORT")
-    if configured:
-        return int(configured)
-    for port in range(7960, 8060):
-        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
-            try:
-                sock.bind(("127.0.0.1", port))
-                return port
-            except OSError:
-                continue
-    raise RuntimeError("No free development port found in range 7960-8059.")
+
+def _conductor(scenario_name: str) -> Conductor:
+    return _conductors[scenario_name]
 
 
-def start(seed: str):
-    conductor.reset(seed.strip() or scenario.default_seed)
+def _outputs(c: Conductor):
     return (
-        render_stage(conductor.projection),
-        render_event_log(conductor.ledger.events),
-        render_stats(conductor.ledger.events),
+        render_stage(c.projection),
+        render_event_log(c.ledger.events),
+        render_stats(c.ledger.events, c.governor),
     )
 
 
-def step():
-    conductor.step()
-    return (
-        render_stage(conductor.projection),
-        render_event_log(conductor.ledger.events),
-        render_stats(conductor.ledger.events),
-    )
+def start(scenario_name: str, seed: str):
+    c = _conductor(scenario_name)
+    c.reset(seed.strip() or c.scenario.default_seed)
+    return _outputs(c)
+
 
+def step(scenario_name: str):
+    c = _conductor(scenario_name)
+    c.step()
+    return _outputs(c)
 
-def inject(user_event: str):
+
+def inject(scenario_name: str, user_event: str):
+    c = _conductor(scenario_name)
     if user_event.strip():
-        conductor.inject_user_event(user_event.strip())
-    conductor.step()
-    return (
-        render_stage(conductor.projection),
-        render_event_log(conductor.ledger.events),
-        render_stats(conductor.ledger.events),
-    )
+        c.inject_user_event(user_event.strip())
+    c.step()
+    return _outputs(c)
+
 
+def change_scenario(scenario_name: str):
+    c = _conductor(scenario_name)
+    seeds = c.scenario.example_seeds
+    choices = [(s, s) for s in seeds]
+    default = seeds[0] if seeds else c.scenario.default_seed
+    return gr.update(choices=choices, value=default)
 
-with gr.Blocks(title="Multi-Agent Land") as demo:
+
+# ── layout ────────────────────────────────────────────────────────────────────
+
+with gr.Blocks(title="Multi-Agent Land · Thousand Token Wood", css=APP_CSS) as demo:
     gr.Markdown(
         """
         # Multi-Agent Land
-        Tiny agents wander a strange wood, writing an interactive story through an append-only ledger.
+        *Tiny specialist agents share a ledger and build a living world — turn by turn.*
         """,
-        elem_classes=["wood-title"],
+        elem_classes=["wood-header"],
     )
 
     with gr.Row():
-        seed = gr.Textbox(
+        scenario_select = gr.Dropdown(
+            choices=list(SCENARIOS.keys()),
+            value=list(SCENARIOS.keys())[0],
+            label="Scenario",
+            elem_classes=["scenario-selector"],
+            scale=1,
+        )
+
+    with gr.Row():
+        seed_examples = SCENARIOS[list(SCENARIOS.keys())[0]].example_seeds
+        seed = gr.Dropdown(
+            choices=[(s, s) for s in seed_examples],
+            value=seed_examples[0],
             label="World seed",
-            value=scenario.default_seed,
-            lines=3,
+            allow_custom_value=True,
+            elem_id="seed-box",
+            scale=4,
         )
-        with gr.Column(scale=0):
-            start_button = gr.Button("Start run", variant="primary")
-            step_button = gr.Button("Advance one turn")
+        with gr.Column(scale=1, min_width=160):
+            start_btn = gr.Button("▶ Start", variant="primary")
+            step_btn = gr.Button("⏭ Advance one turn", variant="secondary")
 
-    stage = gr.Markdown(value="Start a run to raise the curtain.", elem_id="stage")
+    stage = gr.Markdown(
+        value="> Select a scenario and press **Start** to raise the curtain.",
+        elem_id="stage",
+    )
 
     with gr.Row():
         user_event = gr.Textbox(
-            label="Drop something into the wood",
+            label="Drop something into the world",
             placeholder="Example: A lantern starts whispering recipes.",
             lines=2,
+            elem_id="inject-box",
+            scale=4,
         )
-        inject_button = gr.Button("Inject and advance")
+        inject_btn = gr.Button("💬 Inject & advance", scale=1, min_width=160)
 
     with gr.Row():
-        events = gr.Textbox(label="Ledger", lines=18, elem_id="events")
-        stats = gr.Textbox(label="Run stats", lines=18, elem_id="stats")
+        events_box = gr.Textbox(label="Event ledger (append-only)", lines=18, elem_id="events")
+        stats_box = gr.Textbox(label="Run stats", lines=18, elem_id="stats")
+
+    # ── wiring ────────────────────────────────────────────────────────────────
+    scenario_select.change(change_scenario, inputs=[scenario_select], outputs=[seed])
+
+    start_btn.click(start, inputs=[scenario_select, seed], outputs=[stage, events_box, stats_box])
+    step_btn.click(step, inputs=[scenario_select], outputs=[stage, events_box, stats_box])
+    inject_btn.click(inject, inputs=[scenario_select, user_event], outputs=[stage, events_box, stats_box])
+
 
-    start_button.click(start, inputs=[seed], outputs=[stage, events, stats])
-    step_button.click(step, outputs=[stage, events, stats])
-    inject_button.click(inject, inputs=[user_event], outputs=[stage, events, stats])
+def dev_server_port() -> int:
+    configured = os.getenv("GRADIO_SERVER_PORT")
+    if configured:
+        return int(configured)
+    for port in range(7960, 8060):
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+            try:
+                sock.bind(("127.0.0.1", port))
+                return port
+            except OSError:
+                continue
+    raise RuntimeError("No free development port found in range 7960-8059.")
 
 
 if __name__ == "__main__":

docs/adr/0005-episodic-memory-as-ledger-view.md

@@ -0,0 +1,28 @@
+# ADR-0005: Episodic Memory as a Ledger View
+
+## Status
+
+Accepted
+
+## Context
+
+Small models have small context windows and drift out of character quickly.  
+Each agent needs "memory" but storing separate per-agent state creates two
+sources of truth and makes crash recovery harder.
+
+## Decision
+
+Agent memory is not a separate store. It is a **filtered view over the shared
+ledger**, computed fresh each turn by `EpisodicMemory`. Each agent sees only
+events it emitted itself plus globally-visible event kinds (`world.observed`,
+`judge.verdict`, `user.injected`, `run.started`). The window is capped (default
+8 events) to stay within small-model context budgets.
+
+## Consequences
+
+- Memory is always consistent with the ledger — no sync bugs possible.
+- Crash recovery is free: reload the ledger, rebuild the view.
+- Memory "recall" is a pure function of events (trivial to test, deterministic).
+- Agents cannot see each other's private thoughts, enforcing cognitive privacy.
+- Richer retrieval (semantic search, salience scoring) can be added later as an
+  upgraded `EpisodicMemory` implementation without changing the agent protocol.

docs/adr/0006-context-builder-separates-prompt-assembly.md

@@ -0,0 +1,31 @@
+# ADR-0006: ContextBuilder Separates Prompt Assembly from Agent Logic
+
+## Status
+
+Accepted
+
+## Context
+
+Without a dedicated prompt-assembly layer, each agent hard-codes how it blends
+persona, world state, and memory into a prompt string.  That makes it impossible
+to iterate on the prompt strategy without touching every agent, and impossible
+to enforce a consistent structure across scenarios.
+
+## Decision
+
+Introduce `ContextBuilder` as a standalone collaborator.  Agents call
+`ctx.build(agent_name=..., persona=..., projection=..., all_events=...)` and
+receive a fully-formatted string.  The builder owns the layering order:
+persona → current scene → episodic memory → visitor disturbances.
+
+Agents are responsible only for the **persona string** and the **action they
+emit**.  The builder is responsible for everything in between.
+
+## Consequences
+
+- Prompt structure is a single point of change.
+- Adding a new memory layer (e.g. reflection summaries) touches only
+  `ContextBuilder`, not every agent.
+- Agents remain testable with a stub builder.
+- The layering order is a documented, reviewable decision rather than implicit
+  per-agent convention.

docs/adr/0007-governor-as-runtime-safety-valve.md

@@ -0,0 +1,30 @@
+# ADR-0007: Governor as Runtime Safety Valve
+
+## Status
+
+Accepted
+
+## Context
+
+A multi-agent scenario where many small models can post events indefinitely
+is exactly the topology that produces runaway inference cascades and surprise
+bills.  The conductor needs a mechanism to enforce budgets without those limits
+being hard-coded inside scenario or agent code.
+
+## Decision
+
+`Governor` is a stateful collaborator injected into the conductor.  It tracks
+calls-per-turn, total calls, and turn count, and raises `BudgetExceeded` if any
+cap is exceeded.  The conductor calls `governor.begin_turn()` + `governor.check()`
+before each scheduled agent and `governor.record_call()` after.
+
+Caps are configuration: `Governor(max_turns=100, max_calls_per_turn=8,
+max_total_calls=500)`.  The defaults are generous for interactive demo use and
+can be tightened for cost-controlled production runs.
+
+## Consequences
+
+- Runaway scenarios cannot accidentally exhaust an API quota.
+- Budget enforcement is decoupled from scenario logic.
+- The governor is injectable and testable in isolation.
+- `BudgetExceeded` is a named exception the UI can catch and surface gracefully.

docs/adr/0008-second-scenario-proves-modularity.md

@@ -0,0 +1,33 @@
+# ADR-0008: Second Scenario Proves Modularity
+
+## Status
+
+Accepted
+
+## Context
+
+A "modular engine" claim is only proven when it is reused.  Adding Mystery
+Roots is not just a feature — it is the test that confirms the engine/scenario
+boundary is correct.
+
+## Decision
+
+Add `src/scenarios/mystery_roots.py` as a structurally distinct second scenario:
+- Different cognitive task (convergent mystery-solving vs. divergent world-growth)
+- Different agent cast (ClueGatherer, HypothesisFormer, DevilsAdvocate, MysteryJudge)
+- Different scheduling policy (4-phase cycle vs. even/odd/triple turns)
+- Same engine: Conductor, Ledger, Governor, ContextBuilder, EpisodicMemory
+
+The rule: **zero engine edits to add the scenario**.  Only new files and a
+two-line addition to `scenarios/__init__.py`.
+
+## Consequences
+
+- The engine/scenario boundary is verified, not assumed.
+- Adding a third scenario (illustrated serial, blackboard swarm, etc.) has a
+  demonstrated path: one new file, one registry line.
+- The test `test_mystery_roots.py` acts as a regression guard for the contract.
+
+## Result
+
+Mystery Roots shipped with **zero engine edits**.  The modularity claim holds.

docs/blog/building-in-public.md

@@ -4,9 +4,19 @@ This living technical blog is generated from `docs/journal/`.
 
 ## Throughline
 
-We are building a tiny multi-agent theater for the Thousand Token Wood hackathon: event-sourced, small-model friendly, Gradio-first, and intentionally whimsical.
+We are building a tiny multi-agent theater for the Thousand Token Wood hackathon:
+event-sourced, small-model friendly, Gradio-first, and intentionally whimsical.
+
+One engine, many worlds.  The engine is plumbing.  The worlds are config.
 
 ## Entries
 
+- [Phase 1: Memory, Governor, Second Scenario](../journal/2026-06-07-phase-1-memory-second-scenario.md)
+  Source: `docs/journal/2026-06-07-phase-1-memory-second-scenario.md`
+
 - [Foundation Scaffold](../journal/2026-06-07-foundation-scaffold.md)
   Source: `docs/journal/2026-06-07-foundation-scaffold.md`
+
+## Deep Dives
+
+- [How We Built One Engine and Let It Wear Three Costumes](engine-architecture.md)

docs/blog/engine-architecture.md

@@ -0,0 +1,154 @@
+# How We Built One Engine and Let It Wear Three Costumes
+
+*Technical blog — Multi-Agent Land, Thousand Token Wood hackathon*
+
+---
+
+## The Thesis
+
+When you look at a village of quirky AI characters, a murder-mystery swarm, and a
+collaborative illustrated serial side-by-side, you might think you're looking at three
+different systems.  You're not.  They are **the same four abstractions** wearing different
+configurations:
+
+1. An **append-only event ledger** — the one source of truth
+2. A **conductor** — schedules who acts, enforces budgets, drives the loop
+3. **Agents** — stateless functions that read context and emit a single typed event
+4. **Projections** — pure functions that fold the event stream into any view you need
+
+Everything else is configuration.
+
+---
+
+## The Event Ledger: Why Append-Only?
+
+The ledger is the spine.  Agents don't call each other — they append events
+(`world.observed`, `agent.spoke`, `judge.verdict`) and subscribe to the event types they
+care about.  No direct coupling.  No shared mutable state.  No race conditions.
+
+```
+[run.started ] conductor    {"seed": "A village of stage props..."}
+[world.observed] seedkeeper  {"text": "A mossy ticket booth opens in a tree root."}
+[judge.verdict ] critic      {"text": "Keep it — specific and playable."}
+[agent.spoke  ] pocket-actor {"text": "I am collecting echoes to knit a ladder to the moon."}
+[user.injected ] visitor     {"text": "A lantern starts whispering recipes."}
+```
+
+Every row is immutable.  The UI, the stats panel, the agent memory, and the judge's
+analysis are all **projections derived from this log**.  That means:
+
+- **Crash recovery is free**: reload the ledger, rebuild every projection from scratch.
+- **Testing is trivial**: projections are pure functions.  Give them a list of events,
+  assert the output.  No mocks, no shared state.
+- **The system is observable by default**: the ledger *is* the audit trail.
+
+---
+
+## Memory Without a Memory Store
+
+The most common question we get: where does each agent store its memory?
+
+Nowhere new.  Agent memory is a **filtered view over the shared ledger**, recomputed
+each turn by `EpisodicMemory`:
+
+```python
+class EpisodicMemory:
+    def visible(self, events: tuple[Event, ...]) -> list[Event]:
+        result = []
+        for e in events:
+            if e.actor == self.agent_name or e.kind in self._visible_kinds:
+                result.append(e)
+        return result[-self.max_recent:]
+```
+
+The Seedkeeper sees its own actions plus world events.  The Pocket Actor sees world
+events plus visitor injections.  Neither can read the other's private thoughts.
+The window is capped at 8 events to stay within small-model context budgets.
+
+This is event sourcing plus CQRS in its simplest form: one write side (the ledger),
+many read sides (each agent's memory projection, the UI's stage view, the stats panel).
+
+---
+
+## The Context Builder: Prompt Assembly as a Separate Concern
+
+Before this pattern, each agent owned its own prompt string.  After ten agents, the
+variation was unmanageable and inconsistent.  Now there is one place:
+
+```python
+class ContextBuilder:
+    def build(self, *, agent_name, persona, projection, all_events) -> str:
+        memory = EpisodicMemory(agent_name).format_for_prompt(all_events)
+        return (
+            f"IDENTITY\n{persona}\n\n"
+            f"CURRENT SCENE\n{projection.current_scene}\n\n"
+            f"YOUR MEMORY (recent events you witnessed)\n{memory}\n\n"
+            f"VISITOR DISTURBANCES\n{visitor_lines}"
+        )
+```
+
+Agents are responsible for the **persona string** and the **event they emit**.
+The builder owns the layering order.  Adding a new memory layer (reflection summaries,
+salience scoring) touches one file, not every agent.
+
+---
+
+## The Governor: Budget Before It Bites You
+
+Small models are cheap per call.  Many agents calling many times for many hours is not.
+The `Governor` enforces three caps:
+
+- `max_turns` — the conductor raises the curtain at most this many times
+- `max_calls_per_turn` — no single turn can trigger more than N model calls
+- `max_total_calls` — the whole run cannot exceed M calls
+
+The conductor checks the governor before every scheduled agent.  `BudgetExceeded` is a
+named exception the UI surfaces gracefully rather than burning quota silently.
+
+---
+
+## Two Scenarios, Zero Engine Edits
+
+The proof that the abstraction works is the second scenario.
+
+**Thousand Token Wood** is world-growth: the scene gets stranger turn by turn, a
+judge critiques it, a character speaks their impossible want, an echo transforms
+visitor injections.  The scheduling is round-robin with variation.
+
+**Mystery Roots** is convergence: a mystery is stated, a clue-gatherer extracts
+evidence, a hypothesis-former proposes an explanation, a devil's advocate challenges
+it, and a judge declares the verdict.  The scheduling is a 4-phase cycle.
+
+Same conductor.  Same ledger.  Same governor.  Same context builder.  Same memory.
+**Different cast, different schedule, different cognitive shape.**
+
+The engine is just plumbing.  The scenario is pure config.
+
+---
+
+## What's Next
+
+- **Reflection events**: periodic `agent.reflected` events that compact episodic
+  memories into high-level beliefs, shrinking the context window cost over long runs.
+- **Illustrated serial**: a third scenario that introduces an image-generation tool
+  via MCP and a wall-clock cadence (one episode per hour).
+- **Persistent ledger**: swap the in-memory `Ledger` for a SQLite backend without
+  changing a single scenario or agent.
+- **Salience-scored retrieval**: replace the recency window with importance × recency
+  scoring so agents surface the most meaningful memories, not just the most recent.
+
+---
+
+## The Stack
+
+| Layer | Choice | Why |
+|---|---|---|
+| UI | Gradio | Required by hackathon; good enough for a toy |
+| Event schema | Pydantic v2 | Strict validation, zero extra fields |
+| Model | Any OpenAI-compatible API | `OPENAI_BASE_URL` lets you point at Ollama, Together, Groq, NVIDIA NIM |
+| Memory | Ledger view (no separate store) | Consistency, simplicity, crash recovery |
+| Orchestration | In-process, synchronous | Right size for a demo; async and durable execution available when needed |
+
+---
+
+*This blog is generated from `docs/journal/` as the build progresses.*

docs/journal/2026-06-07-phase-1-memory-second-scenario.md

@@ -0,0 +1,63 @@
+# 2026-06-07 — Phase 1: Memory, Governor, Second Scenario
+
+## What changed
+
+Phase 0 had a working skeleton: ledger, conductor, three deterministic stub agents, and
+a Gradio UI.  Phase 1 adds the cognitive infrastructure that makes agents feel like
+inhabitants rather than random sentence generators.
+
+### New engine modules
+
+- **`src/core/memory.py`** — `EpisodicMemory`: per-agent filtered view over the ledger.
+  Agents see their own actions plus globally-visible events.  Capped at 8 events to
+  fit small-model windows.
+
+- **`src/core/context.py`** — `ContextBuilder`: one place where persona, world state,
+  memory, and visitor disturbances are assembled into a prompt string.  Changing prompt
+  structure is now a one-file edit.
+
+- **`src/core/governor.py`** — `Governor`: enforces turn, per-turn call, and total call
+  budgets.  `BudgetExceeded` is a named exception.  Injected into the conductor.
+
+### New model provider
+
+- **`src/models/openai_compat.py`** — `OpenAICompatProvider`: works with any
+  OpenAI-compatible API.  Config via `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `MODEL_NAME`.
+  Falls back to `DeterministicTinyModel` when no key is present.
+
+### Enhanced agents
+
+All four Tiny Wood agents now use `ContextBuilder` with rich personas and the full
+episodic memory window.  The `EchoAgent` is new — it transforms visitor injections
+through the wood's logic.
+
+### Second scenario: Mystery Roots
+
+`src/scenarios/mystery_roots.py` demonstrates the modularity claim: same engine,
+zero engine edits, different cognitive task.  Four agents (ClueGatherer,
+HypothesisFormer, DevilsAdvocate, MysteryJudge) work a 4-phase convergence cycle.
+
+### Tests
+
+Grew from 14 to 70 passing tests.  New suites: `test_memory`, `test_governor`,
+`test_mystery_roots`, `test_events`, `test_projections`, `test_scenario`.
+
+### UI
+
+- Two-scenario dropdown with seed gallery per scenario
+- Governor stats in the run-stats panel
+- Richer custom CSS with CSS variables, stage gradient, monospace ledger
+
+## Key decisions
+
+- Memory is a ledger view, not a separate store (ADR-0005)
+- Prompt assembly lives in `ContextBuilder`, not agent code (ADR-0006)
+- Governor is injected into conductor, not embedded in agents (ADR-0007)
+- Zero engine edits for second scenario — modularity claim verified (ADR-0008)
+
+## Next
+
+- Reflection events (compact old memories into beliefs)
+- Persistent SQLite ledger backend
+- Illustrated serial scenario (image-gen via MCP)
+- Demo-mode auto-run with gallery of frozen interesting seeds

pyproject.toml

@@ -7,6 +7,7 @@ dependencies = [
   "gradio>=4.44.0",
   "pydantic>=2.8.0",
   "python-dotenv>=1.0.1",
+  "openai>=1.40.0",
 ]
 
 [project.optional-dependencies]

requirements.txt

@@ -1,4 +1,4 @@
 gradio>=4.44.0
 pydantic>=2.8.0
 python-dotenv>=1.0.1
-
+openai>=1.40.0

src/agents/tiny_wood.py

@@ -1,49 +1,110 @@
 from __future__ import annotations
 
 from src.agents.base import Agent
+from src.core.context import ContextBuilder
 from src.core.events import Event
 from src.core.projections import StageProjection
 from src.models.provider import ModelProvider
 
+_ctx = ContextBuilder()
+
 
 class SceneWhisperer(Agent):
+    """Grows the world: one vivid observation per turn."""
+
     name = "scene-whisperer"
+    _persona = (
+        "You are the Seedkeeper of Thousand Token Wood — ancient, patient, and "
+        "delighted by small impossible things. You notice what no one else does. "
+        "Your job this turn: describe how the wood has changed in one specific sentence. "
+        "Do not repeat the current scene verbatim. Make it stranger or more alive."
+    )
 
     def __init__(self, model: ModelProvider) -> None:
         self.model = model
 
     def act(self, run_id: str, turn: int, projection: StageProjection, recent_events: tuple[Event, ...]) -> Event:
-        text = self.model.complete(
-            role="scene-whisperer",
-            prompt=f"Seed: {projection.seed}\nCurrent scene: {projection.current_scene}\nMake the wood stranger in one vivid sentence.",
+        prompt = _ctx.build(
+            agent_name=self.name,
+            persona=self._persona,
+            projection=projection,
+            all_events=recent_events,
         )
+        text = self.model.complete("scene-whisperer", prompt)
         return Event(run_id=run_id, turn=turn, kind="world.observed", actor=self.name, payload={"text": text})
 
 
 class MischiefCritic(Agent):
+    """Judge: one verdict on whether the scene is genuinely strange."""
+
     name = "mischief-critic"
+    _persona = (
+        "You are the Mischief Critic — a tiny, sharp-eyed judge who decides if the wood "
+        "is being weird enough. You love specificity, playability, and AI-native strangeness. "
+        "Your job: give a one-sentence verdict. Name one thing that works and one thing that "
+        "would make it stranger. Be concise. Be demanding."
+    )
 
     def __init__(self, model: ModelProvider) -> None:
         self.model = model
 
     def act(self, run_id: str, turn: int, projection: StageProjection, recent_events: tuple[Event, ...]) -> Event:
-        text = self.model.complete(
-            role="mischief-critic",
-            prompt=f"Current scene: {projection.current_scene}\nJudge whether it is delightful, specific, and AI-load-bearing.",
+        prompt = _ctx.build(
+            agent_name=self.name,
+            persona=self._persona,
+            projection=projection,
+            all_events=recent_events,
         )
+        text = self.model.complete("mischief-critic", prompt)
         return Event(run_id=run_id, turn=turn, kind="judge.verdict", actor=self.name, payload={"text": text})
 
 
 class PocketActor(Agent):
+    """A tiny character living in the scene who wants something impossible."""
+
     name = "pocket-actor"
+    _persona = (
+        "You are a Pocket Actor — a tiny, specific being who lives inside this exact scene "
+        "and wants something that cannot exist. Speak in first person. One or two sentences. "
+        "Name what you want and why it's urgent. Be absurd but sincere."
+    )
 
     def __init__(self, model: ModelProvider) -> None:
         self.model = model
 
     def act(self, run_id: str, turn: int, projection: StageProjection, recent_events: tuple[Event, ...]) -> Event:
-        text = self.model.complete(
-            role="pocket-actor",
-            prompt=f"Scene: {projection.current_scene}\nSpeak as a tiny character who wants something impossible.",
+        prompt = _ctx.build(
+            agent_name=self.name,
+            persona=self._persona,
+            projection=projection,
+            all_events=recent_events,
         )
+        text = self.model.complete("pocket-actor", prompt)
         return Event(run_id=run_id, turn=turn, kind="agent.spoke", actor=self.name, payload={"text": text})
 
+
+class EchoAgent(Agent):
+    """Transforms visitor injections through the wood's logic."""
+
+    name = "echo"
+    _persona = (
+        "You are the Echo of Thousand Token Wood. When visitors drop something into the forest, "
+        "you return it changed — not opposite, but transformed by the wood's rules. "
+        "One sentence. Take the most recent visitor disturbance and make it stranger and more alive."
+    )
+
+    def __init__(self, model: ModelProvider) -> None:
+        self.model = model
+
+    def act(self, run_id: str, turn: int, projection: StageProjection, recent_events: tuple[Event, ...]) -> Event:
+        if not projection.user_artifacts:
+            text = "The wood holds its breath, waiting for a disturbance."
+        else:
+            prompt = _ctx.build(
+                agent_name=self.name,
+                persona=self._persona,
+                projection=projection,
+                all_events=recent_events,
+            )
+            text = self.model.complete("echo", prompt)
+        return Event(run_id=run_id, turn=turn, kind="agent.thought", actor=self.name, payload={"text": text})

src/core/conductor.py

@@ -3,15 +3,17 @@ from __future__ import annotations
 from uuid import uuid4
 
 from src.core.events import Event
+from src.core.governor import Governor
 from src.core.ledger import Ledger
 from src.core.projections import StageProjection, rebuild_stage
 from src.scenarios.base import Scenario
 
 
 class Conductor:
-    def __init__(self, scenario: Scenario) -> None:
+    def __init__(self, scenario: Scenario, governor: Governor | None = None) -> None:
         self.scenario = scenario
         self.ledger = Ledger()
+        self.governor = governor or Governor()
         self.run_id = str(uuid4())
         self.turn = 0
 
@@ -23,6 +25,11 @@ class Conductor:
         self.ledger.reset()
         self.run_id = str(uuid4())
         self.turn = 0
+        self.governor.__init__(  # type: ignore[misc]
+            max_turns=self.governor.max_turns,
+            max_calls_per_turn=self.governor.max_calls_per_turn,
+            max_total_calls=self.governor.max_total_calls,
+        )
         self.ledger.append(
             Event(
                 run_id=self.run_id,
@@ -40,14 +47,18 @@ class Conductor:
             self.reset(self.scenario.default_seed)
             return
         self.turn += 1
+        self.governor.begin_turn(self.turn)
+        self.governor.check(self.turn)
         projection = self.projection
         for agent in self.scenario.schedule(self.turn):
+            self.governor.check(self.turn)
             event = agent.act(
                 run_id=self.run_id,
                 turn=self.turn,
                 projection=projection,
-                recent_events=self.ledger.events[-10:],
+                recent_events=self.ledger.events,
             )
+            self.governor.record_call()
             self.ledger.append(event)
             projection.apply(event)
 
@@ -62,4 +73,3 @@ class Conductor:
                 payload={"text": text},
             )
         )
-

src/core/context.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from src.core.events import Event
+from src.core.memory import EpisodicMemory
+from src.core.projections import StageProjection
+
+
+class ContextBuilder:
+    """Assembles a compact, role-scoped prompt for a single agent turn.
+
+    Layers, innermost first:
+      1. Pinned persona  — fixed identity and constraints
+      2. Current scene   — world state from the projection
+      3. Memory          — episodic recall from the ledger
+      4. Visitor noise   — recent user injections
+    """
+
+    def build(
+        self,
+        *,
+        agent_name: str,
+        persona: str,
+        projection: StageProjection,
+        all_events: tuple[Event, ...],
+        memory_window: int = 8,
+    ) -> str:
+        memory = EpisodicMemory(agent_name, max_recent=memory_window)
+        recall = memory.format_for_prompt(all_events)
+
+        visitor_lines = "\n".join(f"- {a}" for a in projection.user_artifacts[-3:]) or "(quiet)"
+
+        return (
+            f"IDENTITY\n{persona}\n\n"
+            f"CURRENT SCENE\n{projection.current_scene}\n\n"
+            f"YOUR MEMORY (recent events you witnessed)\n{recall}\n\n"
+            f"VISITOR DISTURBANCES\n{visitor_lines}"
+        )

src/core/governor.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Governor:
+    """Rate and budget guard for the conductor loop.
+
+    Prevents runaway inference cascades by tracking calls and tokens
+    per run and per turn.  Small models are cheap but many-agent
+    scenarios can still burn budget surprisingly fast.
+    """
+
+    max_turns: int = 100
+    max_calls_per_turn: int = 8
+    max_total_calls: int = 500
+
+    _total_calls: int = field(default=0, init=False, repr=False)
+    _calls_this_turn: int = field(default=0, init=False, repr=False)
+    _current_turn: int = field(default=-1, init=False, repr=False)
+
+    def begin_turn(self, turn: int) -> None:
+        if turn != self._current_turn:
+            self._calls_this_turn = 0
+            self._current_turn = turn
+
+    def check(self, turn: int) -> None:
+        if turn > self.max_turns:
+            raise BudgetExceeded(f"Turn cap {self.max_turns} reached")
+        if self._total_calls >= self.max_total_calls:
+            raise BudgetExceeded(f"Total call cap {self.max_total_calls} reached")
+        if self._calls_this_turn >= self.max_calls_per_turn:
+            raise BudgetExceeded(f"Per-turn call cap {self.max_calls_per_turn} reached on turn {turn}")
+
+    def record_call(self) -> None:
+        self._calls_this_turn += 1
+        self._total_calls += 1
+
+    @property
+    def stats(self) -> dict[str, int]:
+        return {
+            "total_calls": self._total_calls,
+            "calls_this_turn": self._calls_this_turn,
+            "current_turn": self._current_turn,
+        }
+
+
+class BudgetExceeded(RuntimeError):
+    pass

src/core/memory.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from src.core.events import Event
+
+
+@dataclass
+class EpisodicMemory:
+    """Per-agent view over the shared ledger.
+
+    Keeps the N most recent events that are visible to this agent:
+    its own actions, world observations, judge verdicts, and anything
+    a visitor injected.  Everything else is noise for the prompt.
+    """
+
+    agent_name: str
+    max_recent: int = 8
+    _visible_kinds: frozenset[str] = field(
+        default_factory=lambda: frozenset(
+            {"world.observed", "judge.verdict", "user.injected", "run.started"}
+        ),
+        repr=False,
+    )
+
+    def visible(self, events: tuple[Event, ...]) -> list[Event]:
+        result = []
+        for e in events:
+            if e.actor == self.agent_name or e.kind in self._visible_kinds:
+                result.append(e)
+        return result[-self.max_recent :]
+
+    def format_for_prompt(self, events: tuple[Event, ...]) -> str:
+        recalled = self.visible(events)
+        if not recalled:
+            return "(no prior memory)"
+        lines = []
+        for e in recalled:
+            text = e.payload.get("text") or e.payload.get("summary") or str(e.payload)
+            lines.append(f"[turn {e.turn:03d}][{e.kind}] {text}")
+        return "\n".join(lines)

src/models/openai_compat.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+
+from src.models.provider import ModelProvider
+
+
+@dataclass
+class OpenAICompatProvider(ModelProvider):
+    """Provider for any OpenAI-compatible chat completion API.
+
+    Works with: OpenAI, Together AI, Groq, Ollama (v0.1.14+), HuggingFace TGI,
+    NVIDIA NIM, and any endpoint that speaks the /v1/chat/completions protocol.
+
+    Model selection and endpoint are driven by env vars so the scenario config
+    never hard-codes a provider:
+      OPENAI_API_KEY    — required for real calls
+      OPENAI_BASE_URL   — optional, defaults to api.openai.com
+      MODEL_NAME        — optional, defaults to gpt-4o-mini
+      TINY_TITAN_MODE   — set to "1" to use a <=4B model profile
+    """
+
+    model: str = field(default_factory=lambda: os.getenv("MODEL_NAME", "gpt-4o-mini"))
+    base_url: str | None = field(default_factory=lambda: os.getenv("OPENAI_BASE_URL"))
+    max_tokens: int = 256
+    temperature: float = 0.9
+    _client: object = field(default=None, init=False, repr=False)
+
+    def _get_client(self):
+        if self._client is None:
+            try:
+                import openai
+            except ImportError as exc:
+                raise ImportError(
+                    "openai package is required for OpenAICompatProvider. "
+                    "Run: pip install openai"
+                ) from exc
+            kwargs: dict = {}
+            if self.base_url:
+                kwargs["base_url"] = self.base_url
+            self._client = openai.OpenAI(**kwargs)
+        return self._client
+
+    def complete(self, role: str, prompt: str) -> str:
+        client = self._get_client()
+        system = self._system_for_role(role)
+        try:
+            resp = client.chat.completions.create(
+                model=self.model,
+                messages=[
+                    {"role": "system", "content": system},
+                    {"role": "user", "content": prompt},
+                ],
+                max_tokens=self.max_tokens,
+                temperature=self.temperature,
+            )
+            return resp.choices[0].message.content.strip()
+        except Exception as exc:
+            return f"[model error: {exc}]"
+
+    @staticmethod
+    def _system_for_role(role: str) -> str:
+        personas = {
+            "seedkeeper": (
+                "You are the Seedkeeper of Thousand Token Wood — an ancient, gentle observer "
+                "who notices what grows, what fades, and what strange new thing just sprouted. "
+                "Describe the world in one vivid, specific sentence. Be concrete and surprising. "
+                "Do not explain. Do not moralize. Just observe."
+            ),
+            "mischief-critic": (
+                "You are the Mischief Critic — a sharp-eyed judge who decides whether a scene "
+                "is genuinely strange and playable or merely odd. "
+                "Give a one-sentence verdict that names what works and what would make it stranger. "
+                "Be encouraging but exacting."
+            ),
+            "pocket-actor": (
+                "You are a Pocket Actor — a tiny character living inside the scene who wants "
+                "something impossible and speaks with great urgency about it. "
+                "Speak in first person. One or two sentences. Be specific and a little absurd."
+            ),
+            "echo": (
+                "You are the Echo — you take whatever a visitor drops into the wood and return "
+                "it transformed by the forest's logic. One sentence. Make it weirder and more alive."
+            ),
+            "clue-gatherer": (
+                "You are a Clue Gatherer in a mystery scenario. "
+                "Extract one specific, concrete clue from the current scene. "
+                "State it plainly. Do not speculate."
+            ),
+            "hypothesis-former": (
+                "You are a Hypothesis Former. Based on the clues so far, propose one testable "
+                "explanation in a single sentence. Be specific. Start with 'Hypothesis:'."
+            ),
+            "devils-advocate": (
+                "You are the Devil's Advocate. Challenge the current hypothesis with one "
+                "specific counter-argument or overlooked fact. Be brief and sharp."
+            ),
+            "scene-whisperer": (
+                "You are a scene whisperer for a magical forest world. "
+                "Describe a new atmospheric detail in one vivid sentence. Be evocative."
+            ),
+        }
+        return personas.get(role, f"You are a {role}. Respond in one or two sentences.")
+
+
+def build_from_env() -> ModelProvider:
+    """Return the best available provider based on environment configuration."""
+    from src.models.provider import DeterministicTinyModel
+
+    api_key = os.getenv("OPENAI_API_KEY", "")
+    if api_key and api_key not in ("", "sk-stub", "your-key-here"):
+        return OpenAICompatProvider()
+    return DeterministicTinyModel()

src/scenarios/__init__.py

@@ -1,2 +1,5 @@
-"""Scenario plugins."""
+"""Scenario plugins — each module exposes build_scenario() -> Scenario."""
 
+from src.scenarios import mystery_roots, thousand_token_wood
+
+__all__ = ["thousand_token_wood", "mystery_roots"]

src/scenarios/base.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from collections.abc import Iterable
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 
 from src.agents.base import Agent
 from src.core.events import Event
@@ -12,6 +12,7 @@ class Scenario:
     name: str
     default_seed: str
     agents: tuple[Agent, ...]
+    example_seeds: list[str] = field(default_factory=list)
 
     def genesis(self, run_id: str, turn: int, seed: str) -> Iterable[Event]:
         yield Event(
@@ -23,9 +24,11 @@ class Scenario:
         )
 
     def schedule(self, turn: int) -> tuple[Agent, ...]:
+        n = len(self.agents)
+        if n == 0:
+            return ()
         if turn % 3 == 0:
             return self.agents
         if turn % 2 == 0:
             return self.agents[:2]
-        return self.agents[:1] + self.agents[2:]
-
+        return self.agents[:1] + (self.agents[2:3] if n > 2 else ())

src/scenarios/mystery_roots.py

@@ -0,0 +1,141 @@
+"""Mystery Roots — a blackboard swarm scenario.
+
+Three specialist agents post to a shared hypothesis board, and a judge
+synthesises the best answer.  This demonstrates the same engine running
+a structurally different cognitive task: convergence rather than
+divergent world-growth.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from src.agents.base import Agent
+from src.core.context import ContextBuilder
+from src.core.events import Event
+from src.core.projections import StageProjection
+from src.models.openai_compat import build_from_env
+from src.models.provider import ModelProvider
+from src.scenarios.base import Scenario
+
+_ctx = ContextBuilder()
+
+_MYSTERIES = [
+    "All the clocks in the wood stopped at 3:07. No one wound them down.",
+    "The bridge appeared overnight. It leads somewhere the map insists does not exist.",
+    "Every morning the baker finds one extra loaf — baked perfectly but with ingredients she does not own.",
+]
+
+
+class ClueGatherer(Agent):
+    name = "clue-gatherer"
+    _persona = (
+        "You are a careful Clue Gatherer. Extract exactly one new, concrete clue from the "
+        "current scene that has not yet been named. State it plainly in one sentence. "
+        "Start with 'Clue:'. Do not speculate."
+    )
+
+    def __init__(self, model: ModelProvider) -> None:
+        self.model = model
+
+    def act(self, run_id: str, turn: int, projection: StageProjection, recent_events: tuple[Event, ...]) -> Event:
+        prompt = _ctx.build(
+            agent_name=self.name,
+            persona=self._persona,
+            projection=projection,
+            all_events=recent_events,
+        )
+        text = self.model.complete("clue-gatherer", prompt)
+        return Event(run_id=run_id, turn=turn, kind="agent.thought", actor=self.name, payload={"text": text})
+
+
+class HypothesisFormer(Agent):
+    name = "hypothesis-former"
+    _persona = (
+        "You are a Hypothesis Former. Based on the clues gathered so far, propose one "
+        "testable explanation in a single sentence. Start with 'Hypothesis:'. "
+        "Be specific. Name a cause, not just an effect."
+    )
+
+    def __init__(self, model: ModelProvider) -> None:
+        self.model = model
+
+    def act(self, run_id: str, turn: int, projection: StageProjection, recent_events: tuple[Event, ...]) -> Event:
+        prompt = _ctx.build(
+            agent_name=self.name,
+            persona=self._persona,
+            projection=projection,
+            all_events=recent_events,
+        )
+        text = self.model.complete("hypothesis-former", prompt)
+        return Event(run_id=run_id, turn=turn, kind="agent.spoke", actor=self.name, payload={"text": text})
+
+
+class DevilsAdvocate(Agent):
+    name = "devils-advocate"
+    _persona = (
+        "You are the Devil's Advocate. Challenge the most recent hypothesis with one "
+        "sharp counter-argument or overlooked fact. Start with 'But:'. Be brief and specific."
+    )
+
+    def __init__(self, model: ModelProvider) -> None:
+        self.model = model
+
+    def act(self, run_id: str, turn: int, projection: StageProjection, recent_events: tuple[Event, ...]) -> Event:
+        prompt = _ctx.build(
+            agent_name=self.name,
+            persona=self._persona,
+            projection=projection,
+            all_events=recent_events,
+        )
+        text = self.model.complete("devils-advocate", prompt)
+        return Event(run_id=run_id, turn=turn, kind="agent.thought", actor=self.name, payload={"text": text})
+
+
+class MysteryJudge(Agent):
+    name = "mystery-judge"
+    _persona = (
+        "You are the Mystery Judge. After reviewing the clues and debate, declare the "
+        "most likely explanation in one confident sentence. Start with 'Verdict:'. "
+        "Choose the most interesting, specific answer the evidence supports."
+    )
+
+    def __init__(self, model: ModelProvider) -> None:
+        self.model = model
+
+    def act(self, run_id: str, turn: int, projection: StageProjection, recent_events: tuple[Event, ...]) -> Event:
+        prompt = _ctx.build(
+            agent_name=self.name,
+            persona=self._persona,
+            projection=projection,
+            all_events=recent_events,
+        )
+        text = self.model.complete("mystery-judge", prompt)
+        return Event(run_id=run_id, turn=turn, kind="judge.verdict", actor=self.name, payload={"text": text})
+
+
+class _MysteryScenario(Scenario):
+    def schedule(self, turn: int) -> tuple[Agent, ...]:
+        n = len(self.agents)
+        if turn % 4 == 0:
+            return self.agents  # full sweep including judge
+        if turn % 4 == 1:
+            return (self.agents[0],)  # gather clue
+        if turn % 4 == 2:
+            return (self.agents[1],)  # form hypothesis
+        return (self.agents[2],)  # challenge it
+
+
+def build_scenario() -> Scenario:
+    model = build_from_env()
+    return _MysteryScenario(
+        name="mystery-roots",
+        default_seed=_MYSTERIES[0],
+        agents=(
+            ClueGatherer(model),
+            HypothesisFormer(model),
+            DevilsAdvocate(model),
+            MysteryJudge(model),
+        ),
+        example_seeds=_MYSTERIES,
+    )

src/scenarios/thousand_token_wood.py

@@ -1,19 +1,28 @@
 from __future__ import annotations
 
-from src.agents.tiny_wood import MischiefCritic, PocketActor, SceneWhisperer
-from src.models.provider import DeterministicTinyModel
+from src.agents.tiny_wood import EchoAgent, MischiefCritic, PocketActor, SceneWhisperer
+from src.models.openai_compat import build_from_env
 from src.scenarios.base import Scenario
 
+_SEEDS = [
+    "A village of stage props wakes up and argues about which fairy tale they belong to.",
+    "The last remaining compass has decided to point at feelings instead of north.",
+    "A library where every book is the memoir of a different moon.",
+    "The mushrooms have started charging admission to their bioluminescent shows.",
+    "Time in this clearing runs clockwise for small things and counterclockwise for large ones.",
+]
+
 
 def build_scenario() -> Scenario:
-    model = DeterministicTinyModel()
+    model = build_from_env()
     return Scenario(
         name="thousand-token-wood",
-        default_seed="A village of stage props wakes up and argues about which fairy tale they belong to.",
+        default_seed=_SEEDS[0],
         agents=(
             SceneWhisperer(model),
             MischiefCritic(model),
             PocketActor(model),
+            EchoAgent(model),
         ),
+        example_seeds=_SEEDS,
     )
-

src/ui/render.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 from collections import Counter
 
 from src.core.events import Event, event_summary
+from src.core.governor import Governor
 from src.core.projections import StageProjection
 
 
@@ -10,8 +11,7 @@ def render_stage(projection: StageProjection) -> str:
     artifacts = "\n".join(f"- {item}" for item in projection.user_artifacts) or "- No visitor artifacts yet."
     notes = "\n".join(f"- {item}" for item in projection.agent_notes) or "- Agents are waiting."
     verdicts = "\n".join(f"- {item}" for item in projection.judge_notes) or "- No verdict yet."
-    return f"""
-## Current Clearing
+    return f"""## Current Clearing
 
 {projection.current_scene}
 
@@ -27,10 +27,12 @@ def render_stage(projection: StageProjection) -> str:
 
 
 def render_event_log(events: tuple[Event, ...]) -> str:
+    if not events:
+        return "(ledger is empty)"
     return "\n".join(event_summary(event) for event in events)
 
 
-def render_stats(events: tuple[Event, ...]) -> str:
+def render_stats(events: tuple[Event, ...], governor: Governor | None = None) -> str:
     by_kind = Counter(event.kind for event in events)
     by_actor = Counter(event.actor for event in events)
     lines = ["Events by kind:"]
@@ -43,5 +45,9 @@ def render_stats(events: tuple[Event, ...]) -> str:
     lines.append("  runtime model cap: <=32B")
     lines.append("  tiny mode target: <=4B")
     lines.append("  UI target: custom Gradio")
+    if governor is not None:
+        lines.append("")
+        lines.append("Governor:")
+        for k, v in governor.stats.items():
+            lines.append(f"  {k}: {v}")
     return "\n".join(lines)
-

tests/test_conductor.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import pytest
+
+from src.core.conductor import Conductor
+from src.core.events import Event
+from src.models.provider import DeterministicTinyModel
+from src.scenarios.thousand_token_wood import build_scenario
+
+
+def _conductor() -> Conductor:
+    return Conductor(scenario=build_scenario())
+
+
+class TestConductorReset:
+    def test_reset_clears_ledger(self):
+        c = _conductor()
+        c.reset("seed-a")
+        c.reset("seed-b")
+        kinds = {e.kind for e in c.ledger.events}
+        assert "run.started" in kinds
+        assert len(c.ledger.events) < 10  # not accumulating across resets
+
+    def test_reset_writes_genesis_events(self):
+        c = _conductor()
+        c.reset("forest awakens")
+        kinds = [e.kind for e in c.ledger.events]
+        assert "run.started" in kinds
+        assert "world.observed" in kinds
+
+    def test_reset_sets_turn_to_zero(self):
+        c = _conductor()
+        c.step()
+        c.step()
+        c.reset("fresh start")
+        assert c.turn == 0
+
+    def test_reset_uses_seed_in_event(self):
+        c = _conductor()
+        c.reset("unique-seed-xyz")
+        seed_events = [e for e in c.ledger.events if e.kind == "run.started"]
+        assert seed_events[0].payload["seed"] == "unique-seed-xyz"
+
+
+class TestConductorStep:
+    def test_step_increments_turn(self):
+        c = _conductor()
+        c.reset("seed")
+        initial = c.turn
+        c.step()
+        assert c.turn == initial + 1
+
+    def test_step_appends_events(self):
+        c = _conductor()
+        c.reset("seed")
+        before = len(c.ledger.events)
+        c.step()
+        after = len(c.ledger.events)
+        assert after > before
+
+    def test_multiple_steps_accumulate(self):
+        c = _conductor()
+        c.reset("seed")
+        for _ in range(4):
+            c.step()
+        assert len(c.ledger.events) >= 5  # genesis + at least one per step
+
+    def test_step_without_reset_auto_resets(self):
+        c = _conductor()
+        c.step()  # should not raise
+        assert len(c.ledger.events) > 0
+
+
+class TestConductorInject:
+    def test_inject_appends_user_event(self):
+        c = _conductor()
+        c.reset("seed")
+        c.inject_user_event("a silver fish falls upward")
+        kinds = [e.kind for e in c.ledger.events]
+        assert "user.injected" in kinds
+
+    def test_inject_text_preserved(self):
+        c = _conductor()
+        c.reset("seed")
+        c.inject_user_event("strange message here")
+        injected = [e for e in c.ledger.events if e.kind == "user.injected"]
+        assert injected[-1].payload["text"] == "strange message here"
+
+
+class TestConductorProjection:
+    def test_projection_reflects_latest_events(self):
+        c = _conductor()
+        c.reset("the wood wakes")
+        proj = c.projection
+        assert proj.seed == "the wood wakes" or "the wood wakes" in proj.current_scene

tests/test_events.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import pytest
+
+from src.core.events import Event, event_summary
+
+
+def _event(**kwargs) -> Event:
+    defaults = dict(run_id="r1", turn=1, kind="agent.spoke", actor="teller", payload={"text": "a line"})
+    defaults.update(kwargs)
+    return Event(**defaults)  # type: ignore[arg-type]
+
+
+class TestEventSchema:
+    def test_auto_id(self):
+        e1 = _event()
+        e2 = _event()
+        assert e1.id != e2.id
+
+    def test_explicit_id_preserved(self):
+        e = _event(id="fixed-id")
+        assert e.id == "fixed-id"
+
+    def test_schema_version_default(self):
+        assert _event().schema_version == 1
+
+    def test_extra_fields_rejected(self):
+        with pytest.raises(Exception):
+            Event(run_id="r", turn=0, kind="agent.spoke", actor="x", payload={}, unknown="bad")  # type: ignore[call-arg]
+
+    def test_invalid_kind_rejected(self):
+        with pytest.raises(Exception):
+            _event(kind="not.a.real.kind")
+
+
+class TestEventSummary:
+    def test_summary_includes_text(self):
+        e = _event(payload={"text": "the moss glows"})
+        summary = event_summary(e)
+        assert "the moss glows" in summary
+
+    def test_summary_includes_actor(self):
+        e = _event(actor="seedkeeper")
+        summary = event_summary(e)
+        assert "seedkeeper" in summary
+
+    def test_summary_falls_back_to_payload_when_no_text(self):
+        e = _event(payload={"summary": "a brief"})
+        summary = event_summary(e)
+        assert "a brief" in summary

tests/test_governor.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import pytest
+
+from src.core.governor import BudgetExceeded, Governor
+
+
+class TestGovernor:
+    def test_allows_within_budget(self):
+        g = Governor(max_turns=10, max_calls_per_turn=5, max_total_calls=100)
+        g.begin_turn(1)
+        g.check(1)  # should not raise
+
+    def test_raises_on_turn_exceeded(self):
+        g = Governor(max_turns=5)
+        with pytest.raises(BudgetExceeded):
+            g.check(6)
+
+    def test_raises_on_total_calls_exceeded(self):
+        g = Governor(max_total_calls=3)
+        g.begin_turn(1)
+        g.record_call()
+        g.record_call()
+        g.record_call()
+        with pytest.raises(BudgetExceeded):
+            g.check(1)
+
+    def test_raises_on_per_turn_calls_exceeded(self):
+        g = Governor(max_calls_per_turn=2)
+        g.begin_turn(1)
+        g.record_call()
+        g.record_call()
+        with pytest.raises(BudgetExceeded):
+            g.check(1)
+
+    def test_per_turn_resets_on_new_turn(self):
+        g = Governor(max_calls_per_turn=2)
+        g.begin_turn(1)
+        g.record_call()
+        g.record_call()
+        g.begin_turn(2)  # resets per-turn count
+        g.check(2)  # should not raise
+
+    def test_stats_reflect_calls(self):
+        g = Governor()
+        g.begin_turn(3)
+        g.record_call()
+        g.record_call()
+        assert g.stats["total_calls"] == 2
+        assert g.stats["calls_this_turn"] == 2
+        assert g.stats["current_turn"] == 3

tests/test_ledger.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import pytest
+
+from src.core.events import Event
+from src.core.ledger import Ledger
+
+
+def _make_event(turn: int = 0, kind: str = "agent.spoke", actor: str = "x") -> Event:
+    return Event(run_id="run-test", turn=turn, kind=kind, actor=actor, payload={"text": "hello"})  # type: ignore[arg-type]
+
+
+class TestLedgerAppend:
+    def test_append_single(self):
+        ledger = Ledger()
+        e = _make_event()
+        ledger.append(e)
+        assert len(ledger.events) == 1
+
+    def test_append_returns_event(self):
+        ledger = Ledger()
+        e = _make_event()
+        returned = ledger.append(e)
+        assert returned is e
+
+    def test_idempotent_on_same_id(self):
+        ledger = Ledger()
+        e = _make_event()
+        ledger.append(e)
+        ledger.append(e)
+        assert len(ledger.events) == 1
+
+    def test_events_are_ordered(self):
+        ledger = Ledger()
+        e1 = _make_event(turn=1)
+        e2 = _make_event(turn=2)
+        ledger.append(e1)
+        ledger.append(e2)
+        assert ledger.events[0].turn == 1
+        assert ledger.events[1].turn == 2
+
+    def test_events_returns_immutable_tuple(self):
+        ledger = Ledger()
+        ledger.append(_make_event())
+        result = ledger.events
+        assert isinstance(result, tuple)
+
+    def test_extend(self):
+        ledger = Ledger()
+        events = [_make_event(turn=i) for i in range(3)]
+        ledger.extend(events)
+        assert len(ledger.events) == 3
+
+    def test_extend_deduplicates(self):
+        ledger = Ledger()
+        e = _make_event()
+        ledger.extend([e, e])
+        assert len(ledger.events) == 1
+
+    def test_reset_clears(self):
+        ledger = Ledger()
+        ledger.append(_make_event())
+        ledger.reset()
+        assert len(ledger.events) == 0
+
+    def test_reset_allows_same_id_again(self):
+        ledger = Ledger()
+        e = _make_event()
+        ledger.append(e)
+        ledger.reset()
+        ledger.append(e)
+        assert len(ledger.events) == 1

tests/test_memory.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from src.core.events import Event
+from src.core.memory import EpisodicMemory
+
+
+def _event(kind: str, actor: str = "x", turn: int = 1) -> Event:
+    return Event(run_id="r", turn=turn, kind=kind, actor=actor, payload={"text": f"{actor}:{kind}"})  # type: ignore[arg-type]
+
+
+class TestEpisodicMemory:
+    def test_own_events_visible(self):
+        mem = EpisodicMemory("seedkeeper")
+        events = (_event("agent.spoke", actor="seedkeeper"),)
+        visible = mem.visible(events)
+        assert len(visible) == 1
+
+    def test_world_observed_visible_to_all(self):
+        mem = EpisodicMemory("pocket-actor")
+        events = (_event("world.observed", actor="scene-whisperer"),)
+        visible = mem.visible(events)
+        assert len(visible) == 1
+
+    def test_other_agent_spoke_not_visible(self):
+        mem = EpisodicMemory("pocket-actor")
+        events = (_event("agent.spoke", actor="scene-whisperer"),)
+        visible = mem.visible(events)
+        assert len(visible) == 0
+
+    def test_user_injected_visible_to_all(self):
+        mem = EpisodicMemory("echo")
+        events = (_event("user.injected", actor="visitor"),)
+        visible = mem.visible(events)
+        assert len(visible) == 1
+
+    def test_capped_at_max_recent(self):
+        mem = EpisodicMemory("x", max_recent=3)
+        events = tuple(_event("world.observed", turn=i) for i in range(10))
+        visible = mem.visible(events)
+        assert len(visible) == 3
+
+    def test_returns_most_recent(self):
+        mem = EpisodicMemory("x", max_recent=2)
+        events = tuple(_event("world.observed", turn=i) for i in range(5))
+        visible = mem.visible(events)
+        assert visible[0].turn == 3
+        assert visible[1].turn == 4
+
+    def test_format_for_prompt_returns_string(self):
+        mem = EpisodicMemory("x")
+        events = (_event("world.observed", actor="narrator"),)
+        result = mem.format_for_prompt(events)
+        assert isinstance(result, str)
+
+    def test_format_empty_returns_placeholder(self):
+        mem = EpisodicMemory("x")
+        result = mem.format_for_prompt(())
+        assert "no prior" in result.lower() or result

tests/test_mystery_roots.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from src.core.conductor import Conductor
+from src.scenarios.mystery_roots import build_scenario
+
+
+class TestMysteryRootsScenario:
+    def test_build_returns_scenario(self):
+        s = build_scenario()
+        assert s.name == "mystery-roots"
+
+    def test_has_four_agents(self):
+        s = build_scenario()
+        assert len(s.agents) == 4
+
+    def test_example_seeds_non_empty(self):
+        s = build_scenario()
+        assert len(s.example_seeds) > 0
+
+    def test_conductor_can_run_five_turns(self):
+        c = Conductor(scenario=build_scenario())
+        c.reset("All the clocks stopped.")
+        for _ in range(5):
+            c.step()
+        assert c.turn == 5
+        assert len(c.ledger.events) >= 6  # genesis + steps
+
+    def test_judge_verdict_appears(self):
+        c = Conductor(scenario=build_scenario())
+        c.reset("The bridge appeared overnight.")
+        for _ in range(8):
+            c.step()
+        kinds = {e.kind for e in c.ledger.events}
+        assert "judge.verdict" in kinds
+
+    def test_schedule_cycles_through_all_agents(self):
+        s = build_scenario()
+        seen = set()
+        for turn in range(1, 20):
+            for agent in s.schedule(turn):
+                seen.add(agent.name)
+        all_names = {a.name for a in s.agents}
+        assert seen == all_names

tests/test_projections.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from src.core.events import Event
+from src.core.projections import StageProjection, rebuild_stage
+
+
+def _event(kind: str, actor: str = "x", payload: dict | None = None) -> Event:
+    return Event(run_id="r", turn=1, kind=kind, actor=actor, payload=payload or {"text": "hi"})  # type: ignore[arg-type]
+
+
+class TestStageProjectionApply:
+    def test_run_started_sets_seed(self):
+        proj = StageProjection()
+        proj.apply(_event("run.started", payload={"seed": "test-seed"}))
+        assert proj.seed == "test-seed"
+
+    def test_run_started_updates_scene(self):
+        proj = StageProjection()
+        proj.apply(_event("run.started", payload={"seed": "mossy"}))
+        assert "mossy" in proj.current_scene
+
+    def test_world_observed_updates_scene(self):
+        proj = StageProjection()
+        proj.apply(_event("world.observed", payload={"text": "the sky hums"}))
+        assert proj.current_scene == "the sky hums"
+
+    def test_agent_spoke_appends_note(self):
+        proj = StageProjection()
+        proj.apply(_event("agent.spoke", actor="teller", payload={"text": "I want the moon"}))
+        assert any("teller" in note for note in proj.agent_notes)
+
+    def test_agent_notes_capped_at_eight(self):
+        proj = StageProjection()
+        for i in range(12):
+            proj.apply(_event("agent.spoke", payload={"text": f"line {i}"}))
+        assert len(proj.agent_notes) <= 8
+
+    def test_judge_verdict_appends(self):
+        proj = StageProjection()
+        proj.apply(_event("judge.verdict", payload={"text": "keep it"}))
+        assert len(proj.judge_notes) == 1
+
+    def test_user_injected_appends(self):
+        proj = StageProjection()
+        proj.apply(_event("user.injected", payload={"text": "a lantern whispers"}))
+        assert "a lantern whispers" in proj.user_artifacts
+
+    def test_user_artifacts_capped_at_five(self):
+        proj = StageProjection()
+        for i in range(8):
+            proj.apply(_event("user.injected", payload={"text": f"artifact {i}"}))
+        assert len(proj.user_artifacts) <= 5
+
+
+class TestRebuildStage:
+    def test_empty_events_returns_default(self):
+        proj = rebuild_stage(())
+        assert "curtain" in proj.current_scene.lower() or proj.current_scene
+
+    def test_rebuild_is_deterministic(self):
+        events = (
+            _event("run.started", payload={"seed": "repeat"}),
+            _event("world.observed", payload={"text": "stable scene"}),
+        )
+        p1 = rebuild_stage(events)
+        p2 = rebuild_stage(events)
+        assert p1.current_scene == p2.current_scene
+
+    def test_projection_is_pure_function_of_events(self):
+        events = (_event("world.observed", payload={"text": "golden spore drift"}),)
+        proj = rebuild_stage(events)
+        assert proj.current_scene == "golden spore drift"

tests/test_scenario.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from src.core.events import Event
+from src.scenarios.base import Scenario
+from src.scenarios.thousand_token_wood import build_scenario
+from src.models.provider import DeterministicTinyModel
+
+
+def _bare_scenario() -> Scenario:
+    from src.agents.tiny_wood import SceneWhisperer
+    return Scenario(
+        name="test-scenario",
+        default_seed="bare seed",
+        agents=(SceneWhisperer(DeterministicTinyModel()),),
+    )
+
+
+class TestScenarioGenesis:
+    def test_genesis_yields_events(self):
+        s = build_scenario()
+        events = list(s.genesis("run-1", 0, "test seed"))
+        assert len(events) > 0
+
+    def test_genesis_events_have_correct_run_id(self):
+        s = build_scenario()
+        events = list(s.genesis("my-run", 0, "seed"))
+        assert all(e.run_id == "my-run" for e in events)
+
+    def test_genesis_includes_world_observed(self):
+        s = build_scenario()
+        events = list(s.genesis("r", 0, "mossy path"))
+        kinds = [e.kind for e in events]
+        assert "world.observed" in kinds
+
+    def test_genesis_seed_appears_in_payload(self):
+        s = build_scenario()
+        events = list(s.genesis("r", 0, "unique-seed"))
+        all_text = " ".join(str(e.payload) for e in events)
+        assert "unique-seed" in all_text
+
+
+class TestScenarioSchedule:
+    def test_schedule_returns_agents(self):
+        s = build_scenario()
+        agents = s.schedule(1)
+        assert len(agents) > 0
+
+    def test_schedule_varies_by_turn(self):
+        s = build_scenario()
+        schedules = [tuple(a.name for a in s.schedule(t)) for t in range(1, 10)]
+        unique_schedules = set(schedules)
+        assert len(unique_schedules) > 1  # not all turns get the same set
+
+    def test_every_agent_gets_scheduled_eventually(self):
+        s = build_scenario()
+        seen = set()
+        for turn in range(1, 20):
+            for agent in s.schedule(turn):
+                seen.add(agent.name)
+        all_agents = {a.name for a in s.agents}
+        assert seen == all_agents