[claude] Add web_fetch tool (trafilatura) for full-page content extraction (#973) (#1004)

Co-authored-by: Alexander Whitestone <alexpaynex@gmail.com>
Co-committed-by: Alexander Whitestone <alexpaynex@gmail.com>

.gitignore

@@ -73,7 +73,6 @@ morning_briefing.txt
 markdown_report.md
 data/timmy_soul.jsonl
 scripts/migrate_to_zeroclaw.py
-src/infrastructure/db_pool.py
 workspace/
 
 # Loop orchestration state

config/matrix.yaml

@@ -0,0 +1,33 @@
+# Matrix World Configuration
+# Serves lighting, environment, and feature settings to the Matrix frontend.
+
+lighting:
+  ambient_color: "#FFAA55"  # Warm amber (Workshop warmth)
+  ambient_intensity: 0.5
+  point_lights:
+    - color: "#FFAA55"      # Warm amber (Workshop center light)
+      intensity: 1.2
+      position: { x: 0, y: 5, z: 0 }
+    - color: "#3B82F6"      # Cool blue (Matrix accent)
+      intensity: 0.8
+      position: { x: -5, y: 3, z: -5 }
+    - color: "#A855F7"      # Purple accent
+      intensity: 0.6
+      position: { x: 5, y: 3, z: 5 }
+
+environment:
+  rain_enabled: false
+  starfield_enabled: true     # Cool blue starfield (Matrix feel)
+  fog_color: "#0f0f23"
+  fog_density: 0.02
+
+features:
+  chat_enabled: true
+  visitor_avatars: true
+  pip_familiar: true
+  workshop_portal: true
+
+agents:
+  default_count: 5
+  max_count: 20
+  agents: []

config/quests.yaml

@@ -0,0 +1,178 @@
+# ── Token Quest System Configuration ─────────────────────────────────────────
+#
+# Quests are special objectives that agents (and humans) can complete for
+# bonus tokens. Each quest has:
+#   - id: Unique identifier
+#   - name: Display name
+#   - description: What the quest requires
+#   - reward_tokens: Number of tokens awarded on completion
+#   - criteria: Detection rules for completion
+#   - enabled: Whether this quest is active
+#   - repeatable: Whether this quest can be completed multiple times
+#   - cooldown_hours: Minimum hours between completions (if repeatable)
+#
+# Quest Types:
+#   - issue_count: Complete when N issues matching criteria are closed
+#   - issue_reduce: Complete when open issue count drops by N
+#   - docs_update: Complete when documentation files are updated
+#   - test_improve: Complete when test coverage/cases improve
+#   - daily_run: Complete Daily Run session objectives
+#   - custom: Special quests with manual completion
+#
+# ── Active Quests ─────────────────────────────────────────────────────────────
+
+quests:
+  # ── Daily Run & Test Improvement Quests ───────────────────────────────────
+  
+  close_flaky_tests:
+    id: close_flaky_tests
+    name: Flaky Test Hunter
+    description: Close 3 issues labeled "flaky-test"
+    reward_tokens: 150
+    type: issue_count
+    enabled: true
+    repeatable: true
+    cooldown_hours: 24
+    criteria:
+      issue_labels:
+        - flaky-test
+      target_count: 3
+      issue_state: closed
+      lookback_days: 7
+    notification_message: "Quest Complete! You closed 3 flaky-test issues and earned {tokens} tokens."
+
+  reduce_p1_issues:
+    id: reduce_p1_issues
+    name: Priority Firefighter
+    description: Reduce open P1 Daily Run issues by 2
+    reward_tokens: 200
+    type: issue_reduce
+    enabled: true
+    repeatable: true
+    cooldown_hours: 48
+    criteria:
+      issue_labels:
+        - layer:triage
+        - P1
+      target_reduction: 2
+      lookback_days: 3
+    notification_message: "Quest Complete! You reduced P1 issues by 2 and earned {tokens} tokens."
+
+  improve_test_coverage:
+    id: improve_test_coverage
+    name: Coverage Champion
+    description: Improve test coverage by 5% or add 10 new test cases
+    reward_tokens: 300
+    type: test_improve
+    enabled: true
+    repeatable: false
+    criteria:
+      coverage_increase_percent: 5
+      min_new_tests: 10
+    notification_message: "Quest Complete! You improved test coverage and earned {tokens} tokens."
+
+  complete_daily_run_session:
+    id: complete_daily_run_session
+    name: Daily Runner
+    description: Successfully complete 5 Daily Run sessions in a week
+    reward_tokens: 250
+    type: daily_run
+    enabled: true
+    repeatable: true
+    cooldown_hours: 168  # 1 week
+    criteria:
+      min_sessions: 5
+      lookback_days: 7
+    notification_message: "Quest Complete! You completed 5 Daily Run sessions and earned {tokens} tokens."
+
+  # ── Documentation & Maintenance Quests ────────────────────────────────────
+
+  improve_automation_docs:
+    id: improve_automation_docs
+    name: Documentation Hero
+    description: Improve documentation for automations (update 3+ doc files)
+    reward_tokens: 100
+    type: docs_update
+    enabled: true
+    repeatable: true
+    cooldown_hours: 72
+    criteria:
+      file_patterns:
+        - "docs/**/*.md"
+        - "**/README.md"
+        - "timmy_automations/**/*.md"
+      min_files_changed: 3
+      lookback_days: 7
+    notification_message: "Quest Complete! You improved automation docs and earned {tokens} tokens."
+
+  close_micro_fixes:
+    id: close_micro_fixes
+    name: Micro Fix Master
+    description: Close 5 issues labeled "layer:micro-fix"
+    reward_tokens: 125
+    type: issue_count
+    enabled: true
+    repeatable: true
+    cooldown_hours: 24
+    criteria:
+      issue_labels:
+        - layer:micro-fix
+      target_count: 5
+      issue_state: closed
+      lookback_days: 7
+    notification_message: "Quest Complete! You closed 5 micro-fix issues and earned {tokens} tokens."
+
+  # ── Special Achievements ──────────────────────────────────────────────────
+
+  first_contribution:
+    id: first_contribution
+    name: First Steps
+    description: Make your first contribution (close any issue)
+    reward_tokens: 50
+    type: issue_count
+    enabled: true
+    repeatable: false
+    criteria:
+      target_count: 1
+      issue_state: closed
+      lookback_days: 30
+    notification_message: "Welcome! You completed your first contribution and earned {tokens} tokens."
+
+  bug_squasher:
+    id: bug_squasher
+    name: Bug Squasher
+    description: Close 10 issues labeled "bug"
+    reward_tokens: 500
+    type: issue_count
+    enabled: true
+    repeatable: true
+    cooldown_hours: 168  # 1 week
+    criteria:
+      issue_labels:
+        - bug
+      target_count: 10
+      issue_state: closed
+      lookback_days: 7
+    notification_message: "Quest Complete! You squashed 10 bugs and earned {tokens} tokens."
+
+# ── Quest System Settings ───────────────────────────────────────────────────
+
+settings:
+  # Enable/disable quest notifications
+  notifications_enabled: true
+  
+  # Maximum number of concurrent active quests per agent
+  max_concurrent_quests: 5
+  
+  # Auto-detect quest completions on Daily Run metrics update
+  auto_detect_on_daily_run: true
+  
+  # Gitea issue labels that indicate quest-related work
+  quest_work_labels:
+    - layer:triage
+    - layer:micro-fix
+    - layer:tests
+    - layer:economy
+    - flaky-test
+    - bug
+    - documentation

docs/research/openclaw-architecture-deployment-guide.md

@@ -0,0 +1,912 @@
+# OpenClaw Architecture, Deployment Modes, and Ollama Integration
+
+## Research Report for Timmy Time Dashboard Project
+
+**Issue:** #721 — [Kimi Research] OpenClaw architecture, deployment modes, and Ollama integration  
+**Date:** 2026-03-21  
+**Author:** Kimi (Moonshot AI)  
+**Status:** Complete
+
+---
+
+## Executive Summary
+
+OpenClaw is an open-source AI agent framework that bridges messaging platforms (WhatsApp, Telegram, Slack, Discord, iMessage) to AI coding agents through a centralized gateway. Originally known as Clawdbot and Moltbot, it was rebranded to OpenClaw in early 2026. This report provides a comprehensive analysis of OpenClaw's architecture, deployment options, Ollama integration capabilities, and suitability for deployment on resource-constrained VPS environments like the Hermes DigitalOcean droplet (2GB RAM / 1 vCPU).
+
+**Key Finding:** Running OpenClaw with local LLMs on a 2GB RAM VPS is **not recommended**. The absolute minimum for a text-only agent with external API models is 4GB RAM. For local model inference via Ollama, 8-16GB RAM is the practical minimum. A hybrid approach using OpenRouter as the primary provider with Ollama as fallback is the most viable configuration for small VPS deployments.
+
+---
+
+## 1. Architecture Overview
+
+### 1.1 Core Components
+
+OpenClaw follows a **hub-and-spoke (轴辐式)** architecture optimized for multi-agent task execution:
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         OPENCLAW ARCHITECTURE                           │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                         │
+│  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐            │
+│  │  WhatsApp    │     │   Telegram   │     │   Discord    │            │
+│  │   Channel    │     │   Channel    │     │   Channel    │            │
+│  └──────┬───────┘     └──────┬───────┘     └──────┬───────┘            │
+│         │                    │                    │                     │
+│         └────────────────────┼────────────────────┘                     │
+│                              ▼                                         │
+│                    ┌──────────────────┐                                │
+│                    │     Gateway      │◄─────── WebSocket/API         │
+│                    │   (Port 18789)   │         Control Plane         │
+│                    └────────┬─────────┘                                │
+│                             │                                          │
+│              ┌──────────────┼──────────────┐                          │
+│              ▼              ▼              ▼                          │
+│       ┌──────────┐   ┌──────────┐   ┌──────────┐                     │
+│       │ Agent A  │   │ Agent B  │   │  Pi Agent│                     │
+│       │ (main)   │   │ (coder)  │   │(delegate)│                     │
+│       └────┬─────┘   └────┬─────┘   └────┬─────┘                     │
+│            │              │              │                           │
+│            └──────────────┼──────────────┘                           │
+│                           ▼                                          │
+│              ┌────────────────────────┐                              │
+│              │     LLM Router         │                              │
+│              │  (Primary/Fallback)    │                              │
+│              └───────────┬────────────┘                              │
+│                          │                                           │
+│        ┌─────────────────┼─────────────────┐                         │
+│        ▼                 ▼                 ▼                         │
+│   ┌─────────┐      ┌─────────┐      ┌─────────┐                     │
+│   │ Ollama  │      │ OpenAI  │      │Anthropic│                     │
+│   │(local)  │      │(cloud)  │      │(cloud)  │                     │
+│   └─────────┘      └─────────┘      └─────────┘                     │
+│        │                                                    ┌─────┐ │
+│        └────────────────────────────────────────────────────►│ MCP │ │
+│                                                              │Tools│ │
+│                                                              └─────┘ │
+│                                                                         │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐                  │
+│  │   Memory     │  │   Skills     │  │  Workspace   │                  │
+│  │   (SOUL.md)  │  │  (SKILL.md)  │  │  (sessions)  │                  │
+│  └──────────────┘  └──────────────┘  └──────────────┘                  │
+│                                                                         │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### 1.2 Component Deep Dive
+
+| Component | Purpose | Configuration File |
+|-----------|---------|-------------------|
+| **Gateway** | Central control plane, WebSocket/API server, session management | `gateway` section in `openclaw.json` |
+| **Pi Agent** | Core agent runner, "指挥中心" - schedules LLM calls, tool execution, error handling | `agents` section in `openclaw.json` |
+| **Channels** | Messaging platform integrations (Telegram, WhatsApp, Slack, Discord, iMessage) | `channels` section in `openclaw.json` |
+| **SOUL.md** | Agent persona definition - personality, communication style, behavioral guidelines | `~/.openclaw/workspace/SOUL.md` |
+| **AGENTS.md** | Multi-agent configuration, routing rules, agent specialization definitions | `~/.openclaw/workspace/AGENTS.md` |
+| **Workspace** | File system for agent state, session data, temporary files | `~/.openclaw/workspace/` |
+| **Skills** | Bundled tools, prompts, configurations that teach agents specific tasks | `~/.openclaw/workspace/skills/` |
+| **Sessions** | Conversation history, context persistence between interactions | `~/.openclaw/agents/<agent>/sessions/` |
+| **MCP Tools** | Model Context Protocol integration for external tool access | Via `mcporter` or native MCP |
+
+### 1.3 Agent Runner Execution Flow
+
+According to OpenClaw documentation, a complete agent run follows these stages:
+
+1. **Queuing** - Session-level queue (serializes same-session requests) → Global queue (controls total concurrency)
+2. **Preparation** - Parse workspace, provider/model, thinking level parameters
+3. **Plugin Loading** - Load relevant skills based on task context
+4. **Memory Retrieval** - Fetch relevant context from SOUL.md and conversation history
+5. **LLM Inference** - Send prompt to configured provider with tool definitions
+6. **Tool Execution** - Execute any tool calls returned by the LLM
+7. **Response Generation** - Format and return final response to the channel
+8. **Memory Storage** - Persist conversation and results to session storage
+
+---
+
+## 2. Deployment Modes
+
+### 2.1 Comparison Matrix
+
+| Deployment Mode | Best For | Setup Complexity | Resource Overhead | Stability |
+|----------------|----------|------------------|-------------------|-----------|
+| **npm global** | Development, quick testing | Low | Minimal (~200MB) | Moderate |
+| **Docker** | Production, isolation, reproducibility | Medium | Higher (~2.5GB base image) | High |
+| **Docker Compose** | Multi-service stacks, complex setups | Medium-High | Higher | High |
+| **Bare metal/systemd** | Maximum performance, dedicated hardware | High | Minimal | Moderate |
+
+### 2.2 NPM Global Installation (Recommended for Quick Start)
+
+```bash
+# One-line installer
+curl -fsSL https://openclaw.ai/install.sh | bash
+
+# Or manual npm install
+npm install -g openclaw
+
+# Initialize configuration
+openclaw onboard
+
+# Start gateway
+openclaw gateway
+```
+
+**Pros:**
+- Fastest setup (~30 seconds)
+- Direct access to host resources
+- Easy updates via `npm update -g openclaw`
+
+**Cons:**
+- Node.js 22+ dependency required
+- No process isolation
+- Manual dependency management
+
+### 2.3 Docker Deployment (Recommended for Production)
+
+```bash
+# Pull and run
+docker pull openclaw/openclaw:latest
+docker run -d \
+  --name openclaw \
+  -p 127.0.0.1:18789:18789 \
+  -v ~/.openclaw:/root/.openclaw \
+  -e ANTHROPIC_API_KEY=sk-ant-... \
+  openclaw/openclaw:latest
+
+# Or with Docker Compose
+docker compose -f compose.yml --env-file .env up -d --build
+```
+
+**Docker Compose Configuration (production-ready):**
+
+```yaml
+version: '3.8'
+services:
+  openclaw:
+    image: openclaw/openclaw:latest
+    container_name: openclaw
+    restart: unless-stopped
+    ports:
+      - "127.0.0.1:18789:18789"  # Never expose to 0.0.0.0
+    volumes:
+      - ./openclaw-data:/root/.openclaw
+      - ./workspace:/root/.openclaw/workspace
+    environment:
+      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
+      - OPENROUTER_API_KEY=${OPENROUTER_API_KEY}
+      - OLLAMA_API_KEY=ollama-local
+    networks:
+      - openclaw-net
+    # Resource limits for small VPS
+    deploy:
+      resources:
+        limits:
+          cpus: '1.5'
+          memory: 3G
+        reservations:
+          cpus: '0.5'
+          memory: 1G
+
+networks:
+  openclaw-net:
+    driver: bridge
+```
+
+### 2.4 Bare Metal / Systemd Installation
+
+For running as a system service on Linux:
+
+```bash
+# Create systemd service
+sudo tee /etc/systemd/system/openclaw.service > /dev/null <<EOF
+[Unit]
+Description=OpenClaw Gateway
+After=network.target
+
+[Service]
+Type=simple
+User=openclaw
+Group=openclaw
+WorkingDirectory=/home/openclaw
+Environment="PATH=/usr/local/bin:/usr/bin:/bin"
+Environment="NODE_ENV=production"
+Environment="ANTHROPIC_API_KEY=sk-ant-..."
+ExecStart=/usr/local/bin/openclaw gateway
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+sudo systemctl daemon-reload
+sudo systemctl enable openclaw
+sudo systemctl start openclaw
+```
+
+### 2.5 Recommended Deployment for 2GB RAM VPS
+
+**⚠️ Critical Finding:** OpenClaw's official minimum is 4GB RAM. On a 2GB VPS:
+
+1. **Do NOT run local LLMs** - Use external API providers exclusively
+2. **Use npm installation** - Docker overhead is too heavy
+3. **Disable browser automation** - Chromium requires 2-4GB alone
+4. **Enable swap** - Critical for preventing OOM kills
+5. **Use OpenRouter** - Cheap/free tier models reduce costs
+
+**Setup script for 2GB VPS:**
+
+```bash
+#!/bin/bash
+# openclaw-minimal-vps.sh
+# Setup for 2GB RAM VPS - EXTERNAL API ONLY
+
+# Create 4GB swap
+sudo fallocate -l 4G /swapfile
+sudo chmod 600 /swapfile
+sudo mkswap /swapfile
+sudo swapon /swapfile
+echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
+
+# Install Node.js 22
+curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash -
+sudo apt-get install -y nodejs
+
+# Install OpenClaw
+npm install -g openclaw
+
+# Configure for minimal resource usage
+mkdir -p ~/.openclaw
+cat > ~/.openclaw/openclaw.json <<'EOF'
+{
+  "gateway": {
+    "bind": "127.0.0.1",
+    "port": 18789,
+    "mode": "local"
+  },
+  "agents": {
+    "defaults": {
+      "model": {
+        "primary": "openrouter/google/gemma-3-4b-it:free",
+        "fallbacks": [
+          "openrouter/meta/llama-3.1-8b-instruct:free"
+        ]
+      },
+      "maxIterations": 15,
+      "timeout": 120
+    }
+  },
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "dmPolicy": "pairing"
+    }
+  }
+}
+EOF
+
+# Set OpenRouter API key
+export OPENROUTER_API_KEY="sk-or-v1-..."
+
+# Start gateway
+openclaw gateway &
+```
+
+---
+
+## 3. Ollama Integration
+
+### 3.1 Architecture
+
+OpenClaw integrates with Ollama through its native `/api/chat` endpoint, supporting both streaming responses and tool calling simultaneously:
+
+```
+┌──────────────┐      HTTP/JSON      ┌──────────────┐      GGUF/CPU/GPU     ┌──────────┐
+│   OpenClaw   │◄───────────────────►│    Ollama    │◄────────────────────►│  Local   │
+│   Gateway    │   /api/chat         │   Server     │   Model inference    │   LLM    │
+│              │   Port 11434        │  Port 11434  │                      │          │
+└──────────────┘                     └──────────────┘                      └──────────┘
+```
+
+### 3.2 Configuration
+
+**Basic Ollama Setup:**
+
+```bash
+# Install Ollama
+curl -fsSL https://ollama.com/install.sh | sh
+
+# Start server
+ollama serve
+
+# Pull a tool-capable model
+ollama pull qwen2.5-coder:7b
+ollama pull llama3.1:8b
+
+# Configure OpenClaw
+export OLLAMA_API_KEY="ollama-local"  # Any non-empty string works
+```
+
+**OpenClaw Configuration for Ollama:**
+
+```json
+{
+  "models": {
+    "providers": {
+      "ollama": {
+        "baseUrl": "http://localhost:11434",
+        "apiKey": "ollama-local",
+        "api": "ollama",
+        "models": [
+          {
+            "id": "qwen2.5-coder:7b",
+            "name": "Qwen 2.5 Coder 7B",
+            "contextWindow": 32768,
+            "maxTokens": 8192,
+            "cost": { "input": 0, "output": 0 }
+          },
+          {
+            "id": "llama3.1:8b",
+            "name": "Llama 3.1 8B",
+            "contextWindow": 128000,
+            "maxTokens": 8192,
+            "cost": { "input": 0, "output": 0 }
+          }
+        ]
+      }
+    }
+  },
+  "agents": {
+    "defaults": {
+      "model": {
+        "primary": "ollama/qwen2.5-coder:7b",
+        "fallbacks": ["ollama/llama3.1:8b"]
+      }
+    }
+  }
+}
+```
+
+### 3.3 Context Window Requirements
+
+**⚠️ Critical Requirement:** OpenClaw requires a minimum **64K token context window** for reliable multi-step task execution.
+
+| Model | Parameters | Context Window | Tool Support | OpenClaw Compatible |
+|-------|-----------|----------------|--------------|---------------------|
+| **llama3.1** | 8B | 128K | ✅ Yes | ✅ Yes |
+| **qwen2.5-coder** | 7B | 32K | ✅ Yes | ⚠️ Below minimum |
+| **qwen2.5-coder** | 32B | 128K | ✅ Yes | ✅ Yes |
+| **gpt-oss** | 20B | 128K | ✅ Yes | ✅ Yes |
+| **glm-4.7-flash** | - | 128K | ✅ Yes | ✅ Yes |
+| **deepseek-coder-v2** | 33B | 128K | ✅ Yes | ✅ Yes |
+| **mistral-small3.1** | - | 128K | ✅ Yes | ✅ Yes |
+
+**Context Window Configuration:**
+
+For models that don't report context window via Ollama's API:
+
+```bash
+# Create custom Modelfile with extended context
+cat > ~/qwen-custom.modelfile <<EOF
+FROM qwen2.5-coder:7b
+PARAMETER num_ctx 65536
+PARAMETER temperature 0.7
+EOF
+
+# Create custom model
+ollama create qwen2.5-coder-64k -f ~/qwen-custom.modelfile
+```
+
+### 3.4 Models for Small VPS (≤8B Parameters)
+
+For resource-constrained environments (2-4GB RAM):
+
+| Model | Quantization | RAM Required | VRAM Required | Performance |
+|-------|-------------|--------------|---------------|-------------|
+| **Llama 3.1 8B** | Q4_K_M | ~5GB | ~6GB | Good |
+| **Llama 3.2 3B** | Q4_K_M | ~2.5GB | ~3GB | Basic |
+| **Qwen 2.5 7B** | Q4_K_M | ~5GB | ~6GB | Good |
+| **Qwen 2.5 3B** | Q4_K_M | ~2.5GB | ~3GB | Basic |
+| **DeepSeek 7B** | Q4_K_M | ~5GB | ~6GB | Good |
+| **Phi-4 4B** | Q4_K_M | ~3GB | ~4GB | Moderate |
+
+**⚠️ Verdict for 2GB VPS:** Running local LLMs is **NOT viable**. Use external APIs only.
+
+---
+
+## 4. OpenRouter Integration (Fallback Strategy)
+
+### 4.1 Overview
+
+OpenRouter provides a unified API gateway to multiple LLM providers, enabling:
+- Single API key access to 200+ models
+- Automatic failover between providers
+- Free tier models for cost-conscious deployments
+- Unified billing and usage tracking
+
+### 4.2 Configuration
+
+**Environment Variable Setup:**
+
+```bash
+export OPENROUTER_API_KEY="sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+```
+
+**OpenClaw Configuration:**
+
+```json
+{
+  "models": {
+    "providers": {
+      "openrouter": {
+        "apiKey": "${OPENROUTER_API_KEY}",
+        "baseUrl": "https://openrouter.ai/api/v1"
+      }
+    }
+  },
+  "agents": {
+    "defaults": {
+      "model": {
+        "primary": "openrouter/anthropic/claude-sonnet-4-6",
+        "fallbacks": [
+          "openrouter/google/gemini-3.1-pro",
+          "openrouter/meta/llama-3.3-70b-instruct",
+          "openrouter/google/gemma-3-4b-it:free"
+        ]
+      }
+    }
+  }
+}
+```
+
+### 4.3 Recommended Free/Cheap Models on OpenRouter
+
+For cost-conscious VPS deployments:
+
+| Model | Cost | Context | Best For |
+|-------|------|---------|----------|
+| **google/gemma-3-4b-it:free** | Free | 128K | General tasks, simple automation |
+| **meta/llama-3.1-8b-instruct:free** | Free | 128K | General tasks, longer contexts |
+| **deepseek/deepseek-chat-v3.2** | $0.53/M | 64K | Code generation, reasoning |
+| **xiaomi/mimo-v2-flash** | $0.40/M | 128K | Fast responses, basic tasks |
+| **qwen/qwen3-coder-next** | $1.20/M | 128K | Code-focused tasks |
+
+### 4.4 Hybrid Configuration (Recommended for Timmy)
+
+A production-ready configuration for the Hermes VPS:
+
+```json
+{
+  "models": {
+    "providers": {
+      "openrouter": {
+        "apiKey": "${OPENROUTER_API_KEY}",
+        "models": [
+          {
+            "id": "google/gemma-3-4b-it:free",
+            "name": "Gemma 3 4B (Free)",
+            "contextWindow": 131072,
+            "maxTokens": 8192,
+            "cost": { "input": 0, "output": 0 }
+          },
+          {
+            "id": "deepseek/deepseek-chat-v3.2",
+            "name": "DeepSeek V3.2",
+            "contextWindow": 64000,
+            "maxTokens": 8192,
+            "cost": { "input": 0.00053, "output": 0.00053 }
+          }
+        ]
+      },
+      "ollama": {
+        "baseUrl": "http://localhost:11434",
+        "apiKey": "ollama-local",
+        "models": [
+          {
+            "id": "llama3.2:3b",
+            "name": "Llama 3.2 3B (Local Fallback)",
+            "contextWindow": 128000,
+            "maxTokens": 4096,
+            "cost": { "input": 0, "output": 0 }
+          }
+        ]
+      }
+    }
+  },
+  "agents": {
+    "defaults": {
+      "model": {
+        "primary": "openrouter/google/gemma-3-4b-it:free",
+        "fallbacks": [
+          "openrouter/deepseek/deepseek-chat-v3.2",
+          "ollama/llama3.2:3b"
+        ]
+      },
+      "maxIterations": 10,
+      "timeout": 90
+    }
+  }
+}
+```
+
+---
+
+## 5. Hardware Constraints & VPS Viability
+
+### 5.1 System Requirements Summary
+
+| Component | Minimum | Recommended | Notes |
+|-----------|---------|-------------|-------|
+| **CPU** | 2 vCPU | 4 vCPU | Dedicated preferred over shared |
+| **RAM** | 4 GB | 8 GB | 2GB causes OOM with external APIs |
+| **Storage** | 40 GB SSD | 80 GB NVMe | Docker images are ~10-15GB |
+| **Network** | 100 Mbps | 1 Gbps | For API calls and model downloads |
+| **OS** | Ubuntu 22.04/Debian 12 | Ubuntu 24.04 LTS | Linux required for production |
+
+### 5.2 2GB RAM VPS Analysis
+
+**Can it work?** Yes, with severe limitations:
+
+✅ **What works:**
+- Text-only agents with external API providers
+- Single Telegram/Discord channel
+- Basic file operations and shell commands
+- No browser automation
+
+❌ **What doesn't work:**
+- Local LLM inference via Ollama
+- Browser automation (Chromium needs 2-4GB)
+- Multiple concurrent channels
+- Python environment-heavy skills
+
+**Required mitigations for 2GB VPS:**
+
+```bash
+# 1. Create substantial swap
+sudo fallocate -l 4G /swapfile
+sudo chmod 600 /swapfile
+sudo mkswap /swapfile
+sudo swapon /swapfile
+
+# 2. Configure swappiness
+echo 'vm.swappiness=60' | sudo tee -a /etc/sysctl.conf
+sudo sysctl -p
+
+# 3. Limit Node.js memory
+export NODE_OPTIONS="--max-old-space-size=1536"
+
+# 4. Use external APIs only - NO OLLAMA
+# 5. Disable browser skills
+# 6. Set conservative concurrency limits
+```
+
+### 5.3 4-bit Quantization Viability
+
+**Qwen 2.5 7B Q4_K_M on 2GB VPS:**
+- Model size: ~4.5GB
+- RAM required at runtime: ~5-6GB
+- **Verdict:** Will cause immediate OOM on 2GB VPS
+- **Even with 4GB VPS:** Marginal, heavy swap usage, poor performance
+
+**Viable models for 4GB VPS with Ollama:**
+- Llama 3.2 3B Q4_K_M (~2.5GB RAM)
+- Qwen 2.5 3B Q4_K_M (~2.5GB RAM)
+- Phi-4 4B Q4_K_M (~3GB RAM)
+
+---
+
+## 6. Security Configuration
+
+### 6.1 Network Ports
+
+| Port | Purpose | Exposure |
+|------|---------|----------|
+| **18789/tcp** | OpenClaw Gateway (WebSocket/HTTP) | **NEVER expose to internet** |
+| **11434/tcp** | Ollama API (if running locally) | Localhost only |
+| **22/tcp** | SSH | Restrict to known IPs |
+
+**⚠️ CRITICAL:** Never expose port 18789 to the public internet. Use Tailscale or SSH tunnels for remote access.
+
+### 6.2 Tailscale Integration
+
+Tailscale provides zero-configuration VPN mesh for secure remote access:
+
+```bash
+# Install Tailscale
+curl -fsSL https://tailscale.com/install.sh | sh
+sudo tailscale up
+
+# Get Tailscale IP
+tailscale ip
+# Returns: 100.x.y.z
+
+# Configure OpenClaw to bind to Tailscale
+cat > ~/.openclaw/openclaw.json <<EOF
+{
+  "gateway": {
+    "bind": "tailnet",
+    "port": 18789
+  },
+  "tailscale": {
+    "mode": "on",
+    "resetOnExit": false
+  }
+}
+EOF
+```
+
+**Tailscale vs SSH Tunnel:**
+
+| Feature | Tailscale | SSH Tunnel |
+|---------|-----------|------------|
+| Setup | Very easy | Moderate |
+| Persistence | Automatic | Requires autossh |
+| Multiple devices | Built-in | One tunnel per connection |
+| NAT traversal | Works | Requires exposed SSH |
+| Access control | Tailscale ACL | SSH keys |
+
+### 6.3 Firewall Configuration (UFW)
+
+```bash
+# Default deny
+sudo ufw default deny incoming
+sudo ufw default allow outgoing
+
+# Allow SSH
+sudo ufw allow 22/tcp
+
+# Allow Tailscale only (if using)
+sudo ufw allow in on tailscale0 to any port 18789
+
+# Block public access to OpenClaw
+# (bind is 127.0.0.1, so this is defense in depth)
+
+sudo ufw enable
+```
+
+### 6.4 Authentication Configuration
+
+```json
+{
+  "gateway": {
+    "bind": "127.0.0.1",
+    "port": 18789,
+    "auth": {
+      "mode": "token",
+      "token": "your-64-char-hex-token-here"
+    },
+    "controlUi": {
+      "allowedOrigins": [
+        "http://localhost:18789",
+        "https://your-domain.tailnet-name.ts.net"
+      ],
+      "allowInsecureAuth": false,
+      "dangerouslyDisableDeviceAuth": false
+    }
+  }
+}
+```
+
+**Generate secure token:**
+
+```bash
+openssl rand -hex 32
+```
+
+### 6.5 Sandboxing Considerations
+
+OpenClaw executes arbitrary shell commands and file operations by default. For production:
+
+1. **Run as non-root user:**
+```bash
+sudo useradd -r -s /bin/false openclaw
+sudo mkdir -p /home/openclaw/.openclaw
+sudo chown -R openclaw:openclaw /home/openclaw
+```
+
+2. **Use Docker for isolation:**
+```bash
+docker run --security-opt=no-new-privileges \
+  --cap-drop=ALL \
+  --read-only \
+  --tmpfs /tmp:noexec,nosuid,size=100m \
+  openclaw/openclaw:latest
+```
+
+3. **Enable dmPolicy for channels:**
+```json
+{
+  "channels": {
+    "telegram": {
+      "dmPolicy": "pairing"  // Require one-time code for new contacts
+    }
+  }
+}
+```
+
+---
+
+## 7. MCP (Model Context Protocol) Tools
+
+### 7.1 Overview
+
+MCP is an open standard created by Anthropic (donated to Linux Foundation in Dec 2025) that lets AI applications connect to external tools through a universal interface. Think of it as "USB-C for AI."
+
+### 7.2 MCP vs OpenClaw Skills
+
+| Aspect | MCP | OpenClaw Skills |
+|--------|-----|-----------------|
+| **Protocol** | Standardized (Anthropic) | OpenClaw-specific |
+| **Isolation** | Process-isolated | Runs in agent context |
+| **Security** | Higher (sandboxed) | Lower (full system access) |
+| **Discovery** | Automatic via protocol | Manual via SKILL.md |
+| **Ecosystem** | 10,000+ servers | 5400+ skills |
+
+**Note:** OpenClaw currently has limited native MCP support. Use `mcporter` tool for MCP integration.
+
+### 7.3 Using MCPorter (MCP Bridge)
+
+```bash
+# Install mcporter
+clawhub install mcporter
+
+# Configure MCP server
+mcporter config add github \
+  --url "https://api.github.com/mcp" \
+  --token "ghp_..."
+
+# List available tools
+mcporter list
+
+# Call MCP tool
+mcporter call github.list_repos --owner "rockachopa"
+```
+
+### 7.4 Popular MCP Servers
+
+| Server | Purpose | Integration |
+|--------|---------|-------------|
+| **GitHub** | Repo management, PRs, issues | `mcp-github` |
+| **Slack** | Messaging, channel management | `mcp-slack` |
+| **PostgreSQL** | Database queries | `mcp-postgres` |
+| **Filesystem** | File operations (sandboxed) | `mcp-filesystem` |
+| **Brave Search** | Web search | `mcp-brave` |
+
+---
+
+## 8. Recommendations for Timmy Time Dashboard
+
+### 8.1 Deployment Strategy for Hermes VPS (2GB RAM)
+
+Given the hardware constraints, here's the recommended approach:
+
+**Option A: External API Only (Recommended)**
+```
+┌─────────────────────────────────────────┐
+│         Hermes VPS (2GB RAM)            │
+│  ┌─────────────────────────────────┐    │
+│  │     OpenClaw Gateway            │    │
+│  │     (npm global install)        │    │
+│  └─────────────┬───────────────────┘    │
+│                │                        │
+│                ▼                        │
+│  ┌─────────────────────────────────┐    │
+│  │   OpenRouter API (Free Tier)    │    │
+│  │   google/gemma-3-4b-it:free     │    │
+│  └─────────────────────────────────┘    │
+│                                         │
+│  NO OLLAMA - insufficient RAM          │
+└─────────────────────────────────────────┘
+```
+
+**Option B: Hybrid with External Ollama**
+```
+┌──────────────────────┐      ┌──────────────────────────┐
+│   Hermes VPS (2GB)   │      │   Separate Ollama Host   │
+│  ┌────────────────┐  │      │  ┌────────────────────┐  │
+│  │ OpenClaw       │  │◄────►│  │ Ollama Server      │  │
+│  │ (external API) │  │      │  │ (8GB+ RAM required)│  │
+│  └────────────────┘  │      │  └────────────────────┘  │
+└──────────────────────┘      └──────────────────────────┘
+```
+
+### 8.2 Configuration Summary
+
+```json
+{
+  "gateway": {
+    "bind": "127.0.0.1",
+    "port": 18789,
+    "auth": {
+      "mode": "token",
+      "token": "GENERATE_WITH_OPENSSL_RAND"
+    }
+  },
+  "models": {
+    "providers": {
+      "openrouter": {
+        "apiKey": "${OPENROUTER_API_KEY}",
+        "models": [
+          {
+            "id": "google/gemma-3-4b-it:free",
+            "contextWindow": 131072,
+            "maxTokens": 4096
+          }
+        ]
+      }
+    }
+  },
+  "agents": {
+    "defaults": {
+      "model": {
+        "primary": "openrouter/google/gemma-3-4b-it:free"
+      },
+      "maxIterations": 10,
+      "timeout": 90,
+      "maxConcurrent": 2
+    }
+  },
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "dmPolicy": "pairing"
+    }
+  }
+}
+```
+
+### 8.3 Migration Path (Future)
+
+When upgrading to a larger VPS (4-8GB RAM):
+
+1. **Phase 1:** Enable Ollama with Llama 3.2 3B as fallback
+2. **Phase 2:** Add browser automation skills (requires 4GB+ RAM)
+3. **Phase 3:** Enable multi-agent routing with specialized agents
+4. **Phase 4:** Add MCP server integration for external tools
+
+---
+
+## 9. References
+
+1. OpenClaw Official Documentation: https://docs.openclaw.ai
+2. Ollama Integration Guide: https://docs.ollama.com/integrations/openclaw
+3. OpenRouter Documentation: https://openrouter.ai/docs
+4. MCP Specification: https://modelcontextprotocol.io
+5. OpenClaw Community Discord: https://discord.gg/openclaw
+6. GitHub Repository: https://github.com/openclaw/openclaw
+
+---
+
+## 10. Appendix: Quick Command Reference
+
+```bash
+# Installation
+curl -fsSL https://openclaw.ai/install.sh | bash
+
+# Configuration
+openclaw onboard                    # Interactive setup
+openclaw configure                  # Edit config
+openclaw config set <key> <value>   # Set specific value
+
+# Gateway management
+openclaw gateway                    # Start gateway
+openclaw gateway --verbose          # Start with logs
+openclaw gateway status             # Check status
+openclaw gateway restart            # Restart gateway
+openclaw gateway stop               # Stop gateway
+
+# Model management
+openclaw models list                # List available models
+openclaw models set <model>         # Set default model
+openclaw models status              # Check model status
+
+# Diagnostics
+openclaw doctor                     # System health check
+openclaw doctor --repair            # Auto-fix issues
+openclaw security audit             # Security check
+
+# Dashboard
+openclaw dashboard                  # Open web UI
+```
+
+---
+
+*End of Research Report*

pyproject.toml

@@ -20,6 +20,7 @@ packages = [
     { include = "spark", from = "src" },
     { include = "timmy", from = "src" },
     { include = "timmy_serve", from = "src" },
+    { include = "timmyctl", from = "src" },
 ]
 
 [tool.poetry.dependencies]
@@ -49,6 +50,7 @@ sounddevice = { version = ">=0.4.6", optional = true }
 sentence-transformers = { version = ">=2.0.0", optional = true }
 numpy = { version = ">=1.24.0", optional = true }
 requests = { version = ">=2.31.0", optional = true }
+trafilatura = { version = ">=1.6.0", optional = true }
 GitPython = { version = ">=3.1.40", optional = true }
 pytest = { version = ">=8.0.0", optional = true }
 pytest-asyncio = { version = ">=0.24.0", optional = true }
@@ -66,6 +68,7 @@ voice = ["pyttsx3", "openai-whisper", "piper-tts", "sounddevice"]
 celery = ["celery"]
 embeddings = ["sentence-transformers", "numpy"]
 git = ["GitPython"]
+research = ["requests", "trafilatura"]
 dev = ["pytest", "pytest-asyncio", "pytest-cov", "pytest-timeout", "pytest-randomly", "pytest-xdist", "selenium"]
 
 [tool.poetry.group.dev.dependencies]
@@ -82,6 +85,7 @@ mypy = ">=1.0.0"
 [tool.poetry.scripts]
 timmy = "timmy.cli:main"
 timmy-serve = "timmy_serve.cli:main"
+timmyctl = "timmyctl.cli:main"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

scripts/backfill_retro.py

@@ -17,8 +17,23 @@ REPO_ROOT = Path(__file__).resolve().parent.parent
 RETRO_FILE = REPO_ROOT / ".loop" / "retro" / "cycles.jsonl"
 SUMMARY_FILE = REPO_ROOT / ".loop" / "retro" / "summary.json"
 
-GITEA_API = "http://localhost:3000/api/v1"
-REPO_SLUG = "rockachopa/Timmy-time-dashboard"
+
+def _get_gitea_api() -> str:
+    """Read Gitea API URL from env var, then ~/.hermes/gitea_api file, then default."""
+    # Check env vars first (TIMMY_GITEA_API is preferred, GITEA_API for compatibility)
+    api_url = os.environ.get("TIMMY_GITEA_API") or os.environ.get("GITEA_API")
+    if api_url:
+        return api_url
+    # Check ~/.hermes/gitea_api file
+    api_file = Path.home() / ".hermes" / "gitea_api"
+    if api_file.exists():
+        return api_file.read_text().strip()
+    # Default fallback
+    return "http://localhost:3000/api/v1"
+
+
+GITEA_API = _get_gitea_api()
+REPO_SLUG = os.environ.get("REPO_SLUG", "rockachopa/Timmy-time-dashboard")
 TOKEN_FILE = Path.home() / ".hermes" / "gitea_token"
 
 TAG_RE = re.compile(r"\[([^\]]+)\]")

scripts/cycle_retro.py

@@ -277,6 +277,8 @@ def main() -> None:
             args.tests_passed = int(cr["tests_passed"])
         if not args.notes and cr.get("notes"):
             args.notes = cr["notes"]
+        # Consume-once: delete after reading so stale results don't poison future cycles
+        CYCLE_RESULT_FILE.unlink(missing_ok=True)
 
     # Auto-detect issue from branch when not explicitly provided
     if args.issue is None:

scripts/gitea_backup.sh

@@ -0,0 +1,83 @@
+#!/bin/bash
+# Gitea backup script — run on the VPS before any hardening changes.
+# Usage: sudo bash scripts/gitea_backup.sh [off-site-dest]
+#
+# off-site-dest: optional rsync/scp destination for off-site copy
+#   e.g. user@backup-host:/backups/gitea/
+#
+# Refs: #971, #990
+
+set -euo pipefail
+
+BACKUP_DIR="/opt/gitea/backups"
+TIMESTAMP=$(date +"%Y%m%d_%H%M%S")
+GITEA_CONF="/etc/gitea/app.ini"
+GITEA_WORK_DIR="/var/lib/gitea"
+OFFSITE_DEST="${1:-}"
+
+echo "=== Gitea Backup — $TIMESTAMP ==="
+
+# Ensure backup directory exists
+mkdir -p "$BACKUP_DIR"
+cd "$BACKUP_DIR"
+
+# Run the dump
+echo "[1/4] Running gitea dump..."
+gitea dump -c "$GITEA_CONF"
+
+# Find the newest zip (gitea dump names it gitea-dump-*.zip)
+BACKUP_FILE=$(ls -t "$BACKUP_DIR"/gitea-dump-*.zip 2>/dev/null | head -1)
+
+if [ -z "$BACKUP_FILE" ]; then
+    echo "ERROR: No backup zip found in $BACKUP_DIR"
+    exit 1
+fi
+
+BACKUP_SIZE=$(stat -c%s "$BACKUP_FILE" 2>/dev/null || stat -f%z "$BACKUP_FILE")
+echo "[2/4] Backup created: $BACKUP_FILE ($BACKUP_SIZE bytes)"
+
+if [ "$BACKUP_SIZE" -eq 0 ]; then
+    echo "ERROR: Backup file is 0 bytes"
+    exit 1
+fi
+
+# Lock down permissions
+chmod 600 "$BACKUP_FILE"
+
+# Verify contents
+echo "[3/4] Verifying backup contents..."
+CONTENTS=$(unzip -l "$BACKUP_FILE" 2>/dev/null || true)
+
+check_component() {
+    if echo "$CONTENTS" | grep -q "$1"; then
+        echo "  OK: $2"
+    else
+        echo "  WARN: $2 not found in backup"
+    fi
+}
+
+check_component "gitea-db.sql"    "Database dump"
+check_component "gitea-repo"      "Repositories"
+check_component "custom"          "Custom config"
+check_component "app.ini"         "app.ini"
+
+# Off-site copy
+if [ -n "$OFFSITE_DEST" ]; then
+    echo "[4/4] Copying to off-site: $OFFSITE_DEST"
+    rsync -avz "$BACKUP_FILE" "$OFFSITE_DEST"
+    echo "  Off-site copy complete."
+else
+    echo "[4/4] No off-site destination provided. Skipping."
+    echo "  To copy later: scp $BACKUP_FILE user@backup-host:/backups/gitea/"
+fi
+
+echo ""
+echo "=== Backup complete ==="
+echo "File: $BACKUP_FILE"
+echo "Size: $BACKUP_SIZE bytes"
+echo ""
+echo "To verify restore on a clean instance:"
+echo "  1. Copy zip to test machine"
+echo "  2. unzip $BACKUP_FILE"
+echo "  3. gitea restore --from <extracted-dir> -c /etc/gitea/app.ini"
+echo "  4. Verify repos and DB are intact"

scripts/loop_guard.py

@@ -27,11 +27,30 @@ from pathlib import Path
 REPO_ROOT = Path(__file__).resolve().parent.parent
 QUEUE_FILE = REPO_ROOT / ".loop" / "queue.json"
 IDLE_STATE_FILE = REPO_ROOT / ".loop" / "idle_state.json"
+CYCLE_RESULT_FILE = REPO_ROOT / ".loop" / "cycle_result.json"
 TOKEN_FILE = Path.home() / ".hermes" / "gitea_token"
 
-GITEA_API = os.environ.get("GITEA_API", "http://localhost:3000/api/v1")
+
+def _get_gitea_api() -> str:
+    """Read Gitea API URL from env var, then ~/.hermes/gitea_api file, then default."""
+    # Check env vars first (TIMMY_GITEA_API is preferred, GITEA_API for compatibility)
+    api_url = os.environ.get("TIMMY_GITEA_API") or os.environ.get("GITEA_API")
+    if api_url:
+        return api_url
+    # Check ~/.hermes/gitea_api file
+    api_file = Path.home() / ".hermes" / "gitea_api"
+    if api_file.exists():
+        return api_file.read_text().strip()
+    # Default fallback
+    return "http://localhost:3000/api/v1"
+
+
+GITEA_API = _get_gitea_api()
 REPO_SLUG = os.environ.get("REPO_SLUG", "rockachopa/Timmy-time-dashboard")
 
+# Default cycle duration in seconds (5 min); stale threshold = 2× this
+CYCLE_DURATION = int(os.environ.get("CYCLE_DURATION", "300"))
+
 # Backoff sequence: 60s, 120s, 240s, 600s max
 BACKOFF_BASE = 60
 BACKOFF_MAX = 600
@@ -77,6 +96,89 @@ def _fetch_open_issue_numbers() -> set[int] | None:
         return None
 
 
+def _load_cycle_result() -> dict:
+    """Read cycle_result.json, handling markdown-fenced JSON."""
+    if not CYCLE_RESULT_FILE.exists():
+        return {}
+    try:
+        raw = CYCLE_RESULT_FILE.read_text().strip()
+        if raw.startswith("```"):
+            lines = raw.splitlines()
+            lines = [ln for ln in lines if not ln.startswith("```")]
+            raw = "\n".join(lines)
+        return json.loads(raw)
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def _is_issue_open(issue_number: int) -> bool | None:
+    """Check if a single issue is open. Returns None on API failure."""
+    token = _get_token()
+    if not token:
+        return None
+    try:
+        url = f"{GITEA_API}/repos/{REPO_SLUG}/issues/{issue_number}"
+        req = urllib.request.Request(
+            url,
+            headers={
+                "Authorization": f"token {token}",
+                "Accept": "application/json",
+            },
+        )
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            data = json.loads(resp.read())
+        return data.get("state") == "open"
+    except Exception:
+        return None
+
+
+def validate_cycle_result() -> bool:
+    """Pre-cycle validation: remove stale or invalid cycle_result.json.
+
+    Checks:
+    1. Age — if older than 2× CYCLE_DURATION, delete it.
+    2. Issue — if the referenced issue is closed, delete it.
+
+    Returns True if the file was removed, False otherwise.
+    """
+    if not CYCLE_RESULT_FILE.exists():
+        return False
+
+    # Age check
+    try:
+        age = time.time() - CYCLE_RESULT_FILE.stat().st_mtime
+    except OSError:
+        return False
+    stale_threshold = CYCLE_DURATION * 2
+    if age > stale_threshold:
+        print(
+            f"[loop-guard] cycle_result.json is {int(age)}s old "
+            f"(threshold {stale_threshold}s) — removing stale file"
+        )
+        CYCLE_RESULT_FILE.unlink(missing_ok=True)
+        return True
+
+    # Issue check
+    cr = _load_cycle_result()
+    issue_num = cr.get("issue")
+    if issue_num is not None:
+        try:
+            issue_num = int(issue_num)
+        except (ValueError, TypeError):
+            return False
+        is_open = _is_issue_open(issue_num)
+        if is_open is False:
+            print(
+                f"[loop-guard] cycle_result.json references closed "
+                f"issue #{issue_num} — removing"
+            )
+            CYCLE_RESULT_FILE.unlink(missing_ok=True)
+            return True
+        # is_open is None (API failure) or True — keep file
+
+    return False
+
+
 def load_queue() -> list[dict]:
     """Load queue.json and return ready items, filtering out closed issues."""
     if not QUEUE_FILE.exists():
@@ -100,7 +202,11 @@ def load_queue() -> list[dict]:
                 # Persist the cleaned queue so stale entries don't recur
                 _save_cleaned_queue(data, open_numbers)
         return ready
-    except (json.JSONDecodeError, OSError):
+    except json.JSONDecodeError as exc:
+        print(f"[loop-guard] WARNING: Corrupt queue.json ({exc}) — returning empty queue")
+        return []
+    except OSError as exc:
+        print(f"[loop-guard] WARNING: Cannot read queue.json ({exc}) — returning empty queue")
         return []
 
 
@@ -150,6 +256,9 @@ def main() -> int:
         }, indent=2))
         return 0
 
+    # Pre-cycle validation: remove stale cycle_result.json
+    validate_cycle_result()
+
     ready = load_queue()
 
     if ready:

scripts/triage_score.py

@@ -20,11 +20,28 @@ from datetime import datetime, timezone
 from pathlib import Path
 
 # ── Config ──────────────────────────────────────────────────────────────
-GITEA_API = os.environ.get("GITEA_API", "http://localhost:3000/api/v1")
+
+
+def _get_gitea_api() -> str:
+    """Read Gitea API URL from env var, then ~/.hermes/gitea_api file, then default."""
+    # Check env vars first (TIMMY_GITEA_API is preferred, GITEA_API for compatibility)
+    api_url = os.environ.get("TIMMY_GITEA_API") or os.environ.get("GITEA_API")
+    if api_url:
+        return api_url
+    # Check ~/.hermes/gitea_api file
+    api_file = Path.home() / ".hermes" / "gitea_api"
+    if api_file.exists():
+        return api_file.read_text().strip()
+    # Default fallback
+    return "http://localhost:3000/api/v1"
+
+
+GITEA_API = _get_gitea_api()
 REPO_SLUG = os.environ.get("REPO_SLUG", "rockachopa/Timmy-time-dashboard")
 TOKEN_FILE = Path.home() / ".hermes" / "gitea_token"
 REPO_ROOT = Path(__file__).resolve().parent.parent
 QUEUE_FILE = REPO_ROOT / ".loop" / "queue.json"
+QUEUE_BACKUP_FILE = REPO_ROOT / ".loop" / "queue.json.bak"
 RETRO_FILE = REPO_ROOT / ".loop" / "retro" / "triage.jsonl"
 QUARANTINE_FILE = REPO_ROOT / ".loop" / "quarantine.json"
 CYCLE_RETRO_FILE = REPO_ROOT / ".loop" / "retro" / "cycles.jsonl"
@@ -326,9 +343,38 @@ def run_triage() -> list[dict]:
     ready = [s for s in scored if s["ready"]]
     not_ready = [s for s in scored if not s["ready"]]
 
+    # Save backup before writing (if current file exists and is valid)
+    if QUEUE_FILE.exists():
+        try:
+            json.loads(QUEUE_FILE.read_text())  # Validate current file
+            QUEUE_BACKUP_FILE.write_text(QUEUE_FILE.read_text())
+        except (json.JSONDecodeError, OSError):
+            pass  # Current file is corrupt, don't overwrite backup
+
+    # Write new queue file
     QUEUE_FILE.parent.mkdir(parents=True, exist_ok=True)
     QUEUE_FILE.write_text(json.dumps(ready, indent=2) + "\n")
 
+    # Validate the write by re-reading and parsing
+    try:
+        json.loads(QUEUE_FILE.read_text())
+    except (json.JSONDecodeError, OSError) as exc:
+        print(f"[triage] ERROR: queue.json validation failed: {exc}", file=sys.stderr)
+        # Restore from backup if available
+        if QUEUE_BACKUP_FILE.exists():
+            try:
+                backup_data = QUEUE_BACKUP_FILE.read_text()
+                json.loads(backup_data)  # Validate backup
+                QUEUE_FILE.write_text(backup_data)
+                print(f"[triage] Restored queue.json from backup")
+            except (json.JSONDecodeError, OSError) as restore_exc:
+                print(f"[triage] ERROR: Backup restore failed: {restore_exc}", file=sys.stderr)
+                # Write empty list as last resort
+                QUEUE_FILE.write_text("[]\n")
+        else:
+            # No backup, write empty list
+            QUEUE_FILE.write_text("[]\n")
+
     # Write retro entry
     retro_entry = {
         "timestamp": datetime.now(timezone.utc).isoformat(),

skills/research/architecture_spike.md

@@ -0,0 +1,67 @@
+---
+name: Architecture Spike
+type: research
+typical_query_count: 2-4
+expected_output_length: 600-1200 words
+cascade_tier: groq_preferred
+description: >
+  Investigate how to connect two systems or components. Produces an integration
+  architecture with sequence diagram, key decisions, and a proof-of-concept outline.
+---
+
+# Architecture Spike: Connect {system_a} to {system_b}
+
+## Context
+
+We need to integrate **{system_a}** with **{system_b}** in the context of
+**{project_context}**. This spike answers: what is the best way to wire them
+together, and what are the trade-offs?
+
+## Constraints
+
+- Prefer approaches that avoid adding new infrastructure dependencies.
+- The integration should be **{sync_or_async}** (synchronous / asynchronous).
+- Must work within: {environment_constraints}.
+
+## Research Steps
+
+1. Identify the APIs / protocols exposed by both systems.
+2. List all known integration patterns (direct API, message queue, webhook, SDK, etc.).
+3. Evaluate each pattern for complexity, reliability, and latency.
+4. Select the recommended approach and outline a proof-of-concept.
+
+## Output Format
+
+### Integration Options
+
+| Pattern | Complexity | Reliability | Latency | Notes |
+|---------|-----------|-------------|---------|-------|
+| ...     | ...       | ...         | ...     | ...   |
+
+### Recommended Approach
+
+**Pattern:** {pattern_name}
+
+**Why:** One paragraph explaining the choice.
+
+### Sequence Diagram
+
+```
+{system_a} -> {middleware} -> {system_b}
+```
+
+Describe the data flow step by step:
+
+1. {system_a} does X...
+2. {middleware} transforms / routes...
+3. {system_b} receives Y...
+
+### Proof-of-Concept Outline
+
+- Files to create or modify
+- Key libraries / dependencies needed
+- Estimated effort: {effort_estimate}
+
+### Open Questions
+
+Bullet list of decisions that need human input before proceeding.

skills/research/competitive_scan.md

@@ -0,0 +1,74 @@
+---
+name: Competitive Scan
+type: research
+typical_query_count: 3-5
+expected_output_length: 800-1500 words
+cascade_tier: groq_preferred
+description: >
+  Compare a project against its alternatives. Produces a feature matrix,
+  strengths/weaknesses analysis, and positioning summary.
+---
+
+# Competitive Scan: {project} vs Alternatives
+
+## Context
+
+Compare **{project}** against **{alternatives}** (comma-separated list of
+competitors). The goal is to understand where {project} stands and identify
+differentiation opportunities.
+
+## Constraints
+
+- Comparison date: {date}.
+- Focus areas: {focus_areas} (e.g., features, pricing, community, performance).
+- Perspective: {perspective} (user, developer, business).
+
+## Research Steps
+
+1. Gather key facts about {project} (features, pricing, community size, release cadence).
+2. Gather the same data for each alternative in {alternatives}.
+3. Build a feature comparison matrix.
+4. Identify strengths and weaknesses for each entry.
+5. Summarize positioning and recommend next steps.
+
+## Output Format
+
+### Overview
+
+One paragraph: what space does {project} compete in, and who are the main players?
+
+### Feature Matrix
+
+| Feature / Attribute | {project} | {alt_1} | {alt_2} | {alt_3} |
+|--------------------|-----------|---------|---------|---------|
+| {feature_1}        | ...       | ...     | ...     | ...     |
+| {feature_2}        | ...       | ...     | ...     | ...     |
+| Pricing            | ...       | ...     | ...     | ...     |
+| License            | ...       | ...     | ...     | ...     |
+| Community Size     | ...       | ...     | ...     | ...     |
+| Last Major Release | ...       | ...     | ...     | ...     |
+
+### Strengths & Weaknesses
+
+#### {project}
+- **Strengths:** ...
+- **Weaknesses:** ...
+
+#### {alt_1}
+- **Strengths:** ...
+- **Weaknesses:** ...
+
+_(Repeat for each alternative)_
+
+### Positioning Map
+
+Describe where each project sits along the key dimensions (e.g., simplicity
+vs power, free vs paid, niche vs general).
+
+### Recommendations
+
+Bullet list of actions based on the competitive landscape:
+
+- **Differentiate on:** {differentiator}
+- **Watch out for:** {threat}
+- **Consider adopting from {alt}:** {feature_or_approach}

skills/research/game_analysis.md

@@ -0,0 +1,68 @@
+---
+name: Game Analysis
+type: research
+typical_query_count: 2-3
+expected_output_length: 600-1000 words
+cascade_tier: local_ok
+description: >
+  Evaluate a game for AI agent playability. Assesses API availability,
+  observation/action spaces, and existing bot ecosystems.
+---
+
+# Game Analysis: {game}
+
+## Context
+
+Evaluate **{game}** to determine whether an AI agent can play it effectively.
+Focus on programmatic access, observation space, action space, and existing
+bot/AI ecosystems.
+
+## Constraints
+
+- Platform: {platform} (PC, console, mobile, browser).
+- Agent type: {agent_type} (reinforcement learning, rule-based, LLM-driven, hybrid).
+- Budget for API/licenses: {budget}.
+
+## Research Steps
+
+1. Identify official APIs, modding support, or programmatic access methods for {game}.
+2. Characterize the observation space (screen pixels, game state JSON, memory reading, etc.).
+3. Characterize the action space (keyboard/mouse, API calls, controller inputs).
+4. Survey existing bots, AI projects, or research papers for {game}.
+5. Assess feasibility and difficulty for the target agent type.
+
+## Output Format
+
+### Game Profile
+
+| Property          | Value                  |
+|-------------------|------------------------|
+| Game              | {game}                 |
+| Genre             | {genre}                |
+| Platform          | {platform}             |
+| API Available     | Yes / No / Partial     |
+| Mod Support       | Yes / No / Limited     |
+| Existing AI Work  | Extensive / Some / None|
+
+### Observation Space
+
+Describe what data the agent can access and how (API, screen capture, memory hooks, etc.).
+
+### Action Space
+
+Describe how the agent can interact with the game (input methods, timing constraints, etc.).
+
+### Existing Ecosystem
+
+List known bots, frameworks, research papers, or communities working on AI for {game}.
+
+### Feasibility Assessment
+
+- **Difficulty:** Easy / Medium / Hard / Impractical
+- **Best approach:** {recommended_agent_type}
+- **Key challenges:** Bullet list
+- **Estimated time to MVP:** {time_estimate}
+
+### Recommendation
+
+One paragraph: should we proceed, and if so, what is the first step?

skills/research/integration_guide.md

@@ -0,0 +1,79 @@
+---
+name: Integration Guide
+type: research
+typical_query_count: 3-5
+expected_output_length: 1000-2000 words
+cascade_tier: groq_preferred
+description: >
+  Step-by-step guide to wire a specific tool into an existing stack,
+  complete with code samples, configuration, and testing steps.
+---
+
+# Integration Guide: Wire {tool} into {stack}
+
+## Context
+
+Integrate **{tool}** into our **{stack}** stack. The goal is to
+**{integration_goal}** (e.g., "add vector search to the dashboard",
+"send notifications via Telegram").
+
+## Constraints
+
+- Must follow existing project conventions (see CLAUDE.md).
+- No new cloud AI dependencies unless explicitly approved.
+- Environment config via `pydantic-settings` / `config.py`.
+
+## Research Steps
+
+1. Review {tool}'s official documentation for installation and setup.
+2. Identify the minimal dependency set required.
+3. Map {tool}'s API to our existing patterns (singletons, graceful degradation).
+4. Write integration code with proper error handling.
+5. Define configuration variables and their defaults.
+
+## Output Format
+
+### Prerequisites
+
+- Dependencies to install (with versions)
+- External services or accounts required
+- Environment variables to configure
+
+### Configuration
+
+```python
+# In config.py — add these fields to Settings:
+{config_fields}
+```
+
+### Implementation
+
+```python
+# {file_path}
+{implementation_code}
+```
+
+### Graceful Degradation
+
+Describe how the integration behaves when {tool} is unavailable:
+
+| Scenario              | Behavior           | Log Level |
+|-----------------------|--------------------|-----------|
+| {tool} not installed  | {fallback}         | WARNING   |
+| {tool} unreachable    | {fallback}         | WARNING   |
+| Invalid credentials   | {fallback}         | ERROR     |
+
+### Testing
+
+```python
+# tests/unit/test_{tool_snake}.py
+{test_code}
+```
+
+### Verification Checklist
+
+- [ ] Dependency added to pyproject.toml
+- [ ] Config fields added with sensible defaults
+- [ ] Graceful degradation tested (service down)
+- [ ] Unit tests pass (`tox -e unit`)
+- [ ] No new linting errors (`tox -e lint`)

skills/research/state_of_art.md

@@ -0,0 +1,67 @@
+---
+name: State of the Art
+type: research
+typical_query_count: 4-6
+expected_output_length: 1000-2000 words
+cascade_tier: groq_preferred
+description: >
+  Comprehensive survey of what currently exists in a given field or domain.
+  Produces a structured landscape overview with key players, trends, and gaps.
+---
+
+# State of the Art: {field} (as of {date})
+
+## Context
+
+Survey the current landscape of **{field}**. Identify key players, recent
+developments, dominant approaches, and notable gaps. This is a point-in-time
+snapshot intended to inform decision-making.
+
+## Constraints
+
+- Focus on developments from the last {timeframe} (e.g., 12 months, 2 years).
+- Prioritize {priority} (open-source, commercial, academic, or all).
+- Target audience: {audience} (technical team, leadership, general).
+
+## Research Steps
+
+1. Identify the major categories or sub-domains within {field}.
+2. For each category, list the leading projects, companies, or research groups.
+3. Note recent milestones, releases, or breakthroughs.
+4. Identify emerging trends and directions.
+5. Highlight gaps — things that don't exist yet but should.
+
+## Output Format
+
+### Executive Summary
+
+Two to three sentences: what is the state of {field} right now?
+
+### Landscape Map
+
+| Category       | Key Players              | Maturity    | Trend       |
+|---------------|--------------------------|-------------|-------------|
+| {category_1}  | {player_a}, {player_b}   | Early / GA  | Growing / Stable / Declining |
+| {category_2}  | {player_c}, {player_d}   | Early / GA  | Growing / Stable / Declining |
+
+### Recent Milestones
+
+Chronological list of notable events in the last {timeframe}:
+
+- **{date_1}:** {event_description}
+- **{date_2}:** {event_description}
+
+### Trends
+
+Numbered list of the top 3-5 trends shaping {field}:
+
+1. **{trend_name}** — {one-line description}
+2. **{trend_name}** — {one-line description}
+
+### Gaps & Opportunities
+
+Bullet list of things that are missing, underdeveloped, or ripe for innovation.
+
+### Implications for Us
+
+One paragraph: what does this mean for our project? What should we do next?

skills/research/tool_evaluation.md

@@ -0,0 +1,52 @@
+---
+name: Tool Evaluation
+type: research
+typical_query_count: 3-5
+expected_output_length: 800-1500 words
+cascade_tier: groq_preferred
+description: >
+  Discover and evaluate all shipping tools/libraries/services in a given domain.
+  Produces a ranked comparison table with pros, cons, and recommendation.
+---
+
+# Tool Evaluation: {domain}
+
+## Context
+
+You are researching tools, libraries, and services for **{domain}**.
+The goal is to find everything that is currently shipping (not vaporware)
+and produce a structured comparison.
+
+## Constraints
+
+- Only include tools that have public releases or hosted services available today.
+- If a tool is in beta/preview, note that clearly.
+- Focus on {focus_criteria} when evaluating (e.g., cost, ease of integration, community size).
+
+## Research Steps
+
+1. Identify all actively-maintained tools in the **{domain}** space.
+2. For each tool, gather: name, URL, license/pricing, last release date, language/platform.
+3. Evaluate each tool against the focus criteria.
+4. Rank by overall fit for the use case: **{use_case}**.
+
+## Output Format
+
+### Summary
+
+One paragraph: what the landscape looks like and the top recommendation.
+
+### Comparison Table
+
+| Tool | License / Price | Last Release | Language | {focus_criteria} Score | Notes |
+|------|----------------|--------------|----------|----------------------|-------|
+| ...  | ...            | ...          | ...      | ...                  | ...   |
+
+### Top Pick
+
+- **Recommended:** {tool_name} — {one-line reason}
+- **Runner-up:** {tool_name} — {one-line reason}
+
+### Risks & Gaps
+
+Bullet list of things to watch out for (missing features, vendor lock-in, etc.).

src/config.py

@@ -87,8 +87,12 @@ class Settings(BaseSettings):
     xai_base_url: str = "https://api.x.ai/v1"
     grok_default_model: str = "grok-3-fast"
     grok_max_sats_per_query: int = 200
+    grok_sats_hard_cap: int = 100  # Absolute ceiling on sats per Grok query
     grok_free: bool = False  # Skip Lightning invoice when user has own API key
 
+    # ── Database ──────────────────────────────────────────────────────────
+    db_busy_timeout_ms: int = 5000  # SQLite PRAGMA busy_timeout (ms)
+
     # ── Claude (Anthropic) — cloud fallback backend ────────────────────────
     # Used when Ollama is offline and local inference isn't available.
     # Set ANTHROPIC_API_KEY to enable.  Default model is Haiku (fast + cheap).
@@ -149,6 +153,18 @@ class Settings(BaseSettings):
         "http://127.0.0.1:8000",
     ]
 
+    # ── Matrix Frontend Integration ────────────────────────────────────────
+    # URL of the Matrix frontend (Replit/Tailscale) for CORS.
+    # When set, this origin is added to CORS allowed_origins.
+    # Example: "http://100.124.176.28:8080" or "https://alexanderwhitestone.com"
+    matrix_frontend_url: str = ""  # Empty = disabled
+
+    # WebSocket authentication token for Matrix connections.
+    # When set, clients must provide this token via ?token= query param
+    # or in the first message as {"type": "auth", "token": "..."}.
+    # Empty/unset = auth disabled (dev mode).
+    matrix_ws_token: str = ""
+
     # Trusted hosts for the Host header check (TrustedHostMiddleware).
     # Set TRUSTED_HOSTS as a comma-separated list. Wildcards supported (e.g. "*.ts.net").
     # Defaults include localhost + Tailscale MagicDNS. Add your Tailscale IP if needed.
@@ -318,6 +334,13 @@ class Settings(BaseSettings):
     autoresearch_max_iterations: int = 100
     autoresearch_metric: str = "val_bpb"  # metric to optimise (lower = better)
 
+    # ── Weekly Narrative Summary ───────────────────────────────────────
+    # Generates a human-readable weekly summary of development activity.
+    # Disabling this will stop the weekly narrative generation.
+    weekly_narrative_enabled: bool = True
+    weekly_narrative_lookback_days: int = 7
+    weekly_narrative_output_dir: str = ".loop"
+
     # ── Local Hands (Shell + Git) ──────────────────────────────────────
     # Enable local shell/git execution hands.
     hands_shell_enabled: bool = True

src/dashboard/app.py

@@ -10,6 +10,7 @@ Key improvements:
 import asyncio
 import json
 import logging
+import re
 from contextlib import asynccontextmanager
 from pathlib import Path
 
@@ -23,6 +24,7 @@ from config import settings
 
 # Import dedicated middleware
 from dashboard.middleware.csrf import CSRFMiddleware
+from dashboard.middleware.rate_limit import RateLimitMiddleware
 from dashboard.middleware.request_logging import RequestLoggingMiddleware
 from dashboard.middleware.security_headers import SecurityHeadersMiddleware
 from dashboard.routes.agents import router as agents_router
@@ -30,6 +32,7 @@ from dashboard.routes.briefing import router as briefing_router
 from dashboard.routes.calm import router as calm_router
 from dashboard.routes.chat_api import router as chat_api_router
 from dashboard.routes.chat_api_v1 import router as chat_api_v1_router
+from dashboard.routes.daily_run import router as daily_run_router
 from dashboard.routes.db_explorer import router as db_explorer_router
 from dashboard.routes.discord import router as discord_router
 from dashboard.routes.experiments import router as experiments_router
@@ -40,6 +43,8 @@ from dashboard.routes.memory import router as memory_router
 from dashboard.routes.mobile import router as mobile_router
 from dashboard.routes.models import api_router as models_api_router
 from dashboard.routes.models import router as models_router
+from dashboard.routes.quests import router as quests_router
+from dashboard.routes.scorecards import router as scorecards_router
 from dashboard.routes.spark import router as spark_router
 from dashboard.routes.system import router as system_router
 from dashboard.routes.tasks import router as tasks_router
@@ -49,6 +54,7 @@ from dashboard.routes.tools import router as tools_router
 from dashboard.routes.tower import router as tower_router
 from dashboard.routes.voice import router as voice_router
 from dashboard.routes.work_orders import router as work_orders_router
+from dashboard.routes.world import matrix_router
 from dashboard.routes.world import router as world_router
 from timmy.workshop_state import PRESENCE_FILE
 
@@ -519,25 +525,55 @@ app = FastAPI(
 
 
 def _get_cors_origins() -> list[str]:
-    """Get CORS origins from settings, rejecting wildcards in production."""
-    origins = settings.cors_origins
+    """Get CORS origins from settings, rejecting wildcards in production.
+
+    Adds matrix_frontend_url when configured. Always allows Tailscale IPs
+    (100.x.x.x range) for development convenience.
+    """
+    origins = list(settings.cors_origins)
+
+    # Strip wildcards in production (security)
     if "*" in origins and not settings.debug:
         logger.warning(
             "Wildcard '*' in CORS_ORIGINS stripped in production — "
             "set explicit origins via CORS_ORIGINS env var"
         )
         origins = [o for o in origins if o != "*"]
+
+    # Add Matrix frontend URL if configured
+    if settings.matrix_frontend_url:
+        url = settings.matrix_frontend_url.strip()
+        if url and url not in origins:
+            origins.append(url)
+            logger.debug("Added Matrix frontend to CORS: %s", url)
+
     return origins
 
 
+# Pattern to match Tailscale IPs (100.x.x.x) for CORS origin regex
+_TAILSCALE_IP_PATTERN = re.compile(r"^https?://100\.\d{1,3}\.\d{1,3}\.\d{1,3}(?::\d+)?$")
+
+
+def _is_tailscale_origin(origin: str) -> bool:
+    """Check if origin is a Tailscale IP (100.x.x.x range)."""
+    return bool(_TAILSCALE_IP_PATTERN.match(origin))
+
+
 # Add dedicated middleware in correct order
 # 1. Logging (outermost to capture everything)
 app.add_middleware(RequestLoggingMiddleware, skip_paths=["/health"])
 
-# 2. Security Headers
+# 2. Rate Limiting (before security to prevent abuse early)
+app.add_middleware(
+    RateLimitMiddleware,
+    path_prefixes=["/api/matrix/"],
+    requests_per_minute=30,
+)
+
+# 3. Security Headers
 app.add_middleware(SecurityHeadersMiddleware, production=not settings.debug)
 
-# 3. CSRF Protection
+# 4. CSRF Protection
 app.add_middleware(CSRFMiddleware)
 
 # 4. Standard FastAPI middleware
@@ -551,6 +587,7 @@ app.add_middleware(
 app.add_middleware(
     CORSMiddleware,
     allow_origins=_get_cors_origins(),
+    allow_origin_regex=r"https?://100\.\d{1,3}\.\d{1,3}\.\d{1,3}(:\d+)?",
     allow_credentials=True,
     allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"],
     allow_headers=["Content-Type", "Authorization"],
@@ -589,7 +626,11 @@ app.include_router(system_router)
 app.include_router(experiments_router)
 app.include_router(db_explorer_router)
 app.include_router(world_router)
+app.include_router(matrix_router)
 app.include_router(tower_router)
+app.include_router(daily_run_router)
+app.include_router(quests_router)
+app.include_router(scorecards_router)
 
 
 @app.websocket("/ws")

src/dashboard/middleware/__init__.py

@@ -1,6 +1,7 @@
 """Dashboard middleware package."""
 
 from .csrf import CSRFMiddleware, csrf_exempt, generate_csrf_token, validate_csrf_token
+from .rate_limit import RateLimiter, RateLimitMiddleware
 from .request_logging import RequestLoggingMiddleware
 from .security_headers import SecurityHeadersMiddleware
 
@@ -9,6 +10,8 @@ __all__ = [
     "csrf_exempt",
     "generate_csrf_token",
     "validate_csrf_token",
+    "RateLimiter",
+    "RateLimitMiddleware",
     "SecurityHeadersMiddleware",
     "RequestLoggingMiddleware",
 ]

src/dashboard/middleware/csrf.py

@@ -131,7 +131,6 @@ class CSRFMiddleware(BaseHTTPMiddleware):
         For safe methods: Set a CSRF token cookie if not present.
         For unsafe methods: Validate the CSRF token or check if exempt.
         """
-        # Bypass CSRF if explicitly disabled (e.g. in tests)
         from config import settings
 
         if settings.timmy_disable_csrf:
@@ -141,52 +140,55 @@ class CSRFMiddleware(BaseHTTPMiddleware):
         if request.headers.get("upgrade", "").lower() == "websocket":
             return await call_next(request)
 
-        # Get existing CSRF token from cookie
         csrf_cookie = request.cookies.get(self.cookie_name)
 
-        # For safe methods, just ensure a token exists
         if request.method in self.SAFE_METHODS:
-            response = await call_next(request)
+            return await self._handle_safe_method(request, call_next, csrf_cookie)
 
-            # Set CSRF token cookie if not present
-            if not csrf_cookie:
-                new_token = generate_csrf_token()
-                response.set_cookie(
-                    key=self.cookie_name,
-                    value=new_token,
-                    httponly=False,  # Must be readable by JavaScript
-                    secure=settings.csrf_cookie_secure,
-                    samesite="Lax",
-                    max_age=86400,  # 24 hours
-                )
+        return await self._handle_unsafe_method(request, call_next, csrf_cookie)
 
-            return response
+    async def _handle_safe_method(
+        self, request: Request, call_next, csrf_cookie: str | None
+    ) -> Response:
+        """Handle safe HTTP methods (GET, HEAD, OPTIONS, TRACE).
 
-        # For unsafe methods, we need to validate or check if exempt
-        # First, try to validate the CSRF token
-        if await self._validate_request(request, csrf_cookie):
-            # Token is valid, allow the request
-            return await call_next(request)
+        Forwards the request and sets a CSRF token cookie if not present.
+        """
+        from config import settings
 
-        # Token validation failed, check if the path is exempt
-        path = request.url.path
-        if self._is_likely_exempt(path):
-            # Path is exempt, allow the request
-            return await call_next(request)
-
-        # Token validation failed and path is not exempt
-        # We still need to call the app to check if the endpoint is decorated
-        # with @csrf_exempt, so we'll let it through and check after routing
         response = await call_next(request)
 
-        # After routing, check if the endpoint is marked as exempt
-        endpoint = request.scope.get("endpoint")
-        if endpoint and is_csrf_exempt(endpoint):
-            # Endpoint is marked as exempt, allow the response
-            return response
+        if not csrf_cookie:
+            new_token = generate_csrf_token()
+            response.set_cookie(
+                key=self.cookie_name,
+                value=new_token,
+                httponly=False,  # Must be readable by JavaScript
+                secure=settings.csrf_cookie_secure,
+                samesite="Lax",
+                max_age=86400,  # 24 hours
+            )
+
+        return response
+
+    async def _handle_unsafe_method(
+        self, request: Request, call_next, csrf_cookie: str | None
+    ) -> Response:
+        """Handle unsafe HTTP methods (POST, PUT, DELETE, PATCH).
+
+        Validates the CSRF token, checks path and endpoint exemptions,
+        or returns a 403 error.
+        """
+        if await self._validate_request(request, csrf_cookie):
+            return await call_next(request)
+
+        if self._is_likely_exempt(request.url.path):
+            return await call_next(request)
+
+        endpoint = self._resolve_endpoint(request)
+        if endpoint and is_csrf_exempt(endpoint):
+            return await call_next(request)
 
-        # Endpoint is not exempt and token validation failed
-        # Return 403 error
         return JSONResponse(
             status_code=403,
             content={
@@ -196,6 +198,41 @@ class CSRFMiddleware(BaseHTTPMiddleware):
             },
         )
 
+    def _resolve_endpoint(self, request: Request) -> Callable | None:
+        """Resolve the route endpoint without executing it.
+
+        Walks the Starlette/FastAPI router to find which endpoint function
+        handles this request, so we can check @csrf_exempt before any
+        side effects occur.
+
+        Returns:
+            The endpoint callable, or None if no route matched.
+        """
+        # If routing already happened (endpoint in scope), use it
+        endpoint = request.scope.get("endpoint")
+        if endpoint:
+            return endpoint
+
+        # Walk the middleware/app chain to find something with routes
+        from starlette.routing import Match
+
+        app = self.app
+        while app is not None:
+            if hasattr(app, "routes"):
+                for route in app.routes:
+                    match, _ = route.matches(request.scope)
+                    if match == Match.FULL:
+                        return getattr(route, "endpoint", None)
+            # Try .router (FastAPI stores routes on app.router)
+            if hasattr(app, "router") and hasattr(app.router, "routes"):
+                for route in app.router.routes:
+                    match, _ = route.matches(request.scope)
+                    if match == Match.FULL:
+                        return getattr(route, "endpoint", None)
+            app = getattr(app, "app", None)
+
+        return None
+
     def _is_likely_exempt(self, path: str) -> bool:
         """Check if a path is likely to be CSRF exempt.
 

src/dashboard/middleware/rate_limit.py

@@ -0,0 +1,209 @@
+"""Rate limiting middleware for FastAPI.
+
+Simple in-memory rate limiter for API endpoints. Tracks requests per IP
+with configurable limits and automatic cleanup of stale entries.
+"""
+
+import logging
+import time
+from collections import deque
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+
+logger = logging.getLogger(__name__)
+
+
+class RateLimiter:
+    """In-memory rate limiter for tracking requests per IP.
+
+    Stores request timestamps in a dict keyed by client IP.
+    Automatically cleans up stale entries every 60 seconds.
+
+    Attributes:
+        requests_per_minute: Maximum requests allowed per minute per IP.
+        cleanup_interval_seconds: How often to clean stale entries.
+    """
+
+    def __init__(
+        self,
+        requests_per_minute: int = 30,
+        cleanup_interval_seconds: int = 60,
+    ):
+        self.requests_per_minute = requests_per_minute
+        self.cleanup_interval_seconds = cleanup_interval_seconds
+        self._storage: dict[str, deque[float]] = {}
+        self._last_cleanup: float = time.time()
+        self._window_seconds: float = 60.0  # 1 minute window
+
+    def _get_client_ip(self, request: Request) -> str:
+        """Extract client IP from request, respecting X-Forwarded-For header.
+
+        Args:
+            request: The incoming request.
+
+        Returns:
+            Client IP address string.
+        """
+        # Check for forwarded IP (when behind proxy/load balancer)
+        forwarded = request.headers.get("x-forwarded-for")
+        if forwarded:
+            # Take the first IP in the chain
+            return forwarded.split(",")[0].strip()
+
+        real_ip = request.headers.get("x-real-ip")
+        if real_ip:
+            return real_ip
+
+        # Fall back to direct connection
+        if request.client:
+            return request.client.host
+
+        return "unknown"
+
+    def _cleanup_if_needed(self) -> None:
+        """Remove stale entries older than the cleanup interval."""
+        now = time.time()
+        if now - self._last_cleanup < self.cleanup_interval_seconds:
+            return
+
+        cutoff = now - self._window_seconds
+        stale_ips: list[str] = []
+
+        for ip, timestamps in self._storage.items():
+            # Remove timestamps older than the window
+            while timestamps and timestamps[0] < cutoff:
+                timestamps.popleft()
+            # Mark IP for removal if no recent requests
+            if not timestamps:
+                stale_ips.append(ip)
+
+        # Remove stale IP entries
+        for ip in stale_ips:
+            del self._storage[ip]
+
+        self._last_cleanup = now
+        if stale_ips:
+            logger.debug("Rate limiter cleanup: removed %d stale IPs", len(stale_ips))
+
+    def is_allowed(self, client_ip: str) -> tuple[bool, float]:
+        """Check if a request from the given IP is allowed.
+
+        Args:
+            client_ip: The client's IP address.
+
+        Returns:
+            Tuple of (allowed: bool, retry_after: float).
+            retry_after is seconds until next allowed request, 0 if allowed now.
+        """
+        now = time.time()
+        cutoff = now - self._window_seconds
+
+        # Get or create timestamp deque for this IP
+        if client_ip not in self._storage:
+            self._storage[client_ip] = deque()
+
+        timestamps = self._storage[client_ip]
+
+        # Remove timestamps outside the window
+        while timestamps and timestamps[0] < cutoff:
+            timestamps.popleft()
+
+        # Check if limit exceeded
+        if len(timestamps) >= self.requests_per_minute:
+            # Calculate retry after time
+            oldest = timestamps[0]
+            retry_after = self._window_seconds - (now - oldest)
+            return False, max(0.0, retry_after)
+
+        # Record this request
+        timestamps.append(now)
+        return True, 0.0
+
+    def check_request(self, request: Request) -> tuple[bool, float]:
+        """Check if the request is allowed under rate limits.
+
+        Args:
+            request: The incoming request.
+
+        Returns:
+            Tuple of (allowed: bool, retry_after: float).
+        """
+        self._cleanup_if_needed()
+        client_ip = self._get_client_ip(request)
+        return self.is_allowed(client_ip)
+
+
+class RateLimitMiddleware(BaseHTTPMiddleware):
+    """Middleware to apply rate limiting to specific routes.
+
+    Usage:
+        # Apply to all routes (not recommended for public static files)
+        app.add_middleware(RateLimitMiddleware)
+
+        # Apply only to specific paths
+        app.add_middleware(
+            RateLimitMiddleware,
+            path_prefixes=["/api/matrix/"],
+            requests_per_minute=30,
+        )
+
+    Attributes:
+        path_prefixes: List of URL path prefixes to rate limit.
+                       If empty, applies to all paths.
+        requests_per_minute: Maximum requests per minute per IP.
+    """
+
+    def __init__(
+        self,
+        app,
+        path_prefixes: list[str] | None = None,
+        requests_per_minute: int = 30,
+    ):
+        super().__init__(app)
+        self.path_prefixes = path_prefixes or []
+        self.limiter = RateLimiter(requests_per_minute=requests_per_minute)
+
+    def _should_rate_limit(self, path: str) -> bool:
+        """Check if the given path should be rate limited.
+
+        Args:
+            path: The request URL path.
+
+        Returns:
+            True if path matches any configured prefix.
+        """
+        if not self.path_prefixes:
+            return True
+        return any(path.startswith(prefix) for prefix in self.path_prefixes)
+
+    async def dispatch(self, request: Request, call_next) -> Response:
+        """Apply rate limiting to configured paths.
+
+        Args:
+            request: The incoming request.
+            call_next: Callable to get the response from downstream.
+
+        Returns:
+            Response from downstream, or 429 if rate limited.
+        """
+        # Skip if path doesn't match configured prefixes
+        if not self._should_rate_limit(request.url.path):
+            return await call_next(request)
+
+        # Check rate limit
+        allowed, retry_after = self.limiter.check_request(request)
+
+        if not allowed:
+            return JSONResponse(
+                status_code=429,
+                content={
+                    "error": "Rate limit exceeded. Try again later.",
+                    "retry_after": int(retry_after) + 1,
+                },
+                headers={"Retry-After": str(int(retry_after) + 1)},
+            )
+
+        # Process the request
+        return await call_next(request)

src/dashboard/middleware/request_logging.py

@@ -42,6 +42,114 @@ class RequestLoggingMiddleware(BaseHTTPMiddleware):
         self.skip_paths = set(skip_paths or [])
         self.log_level = log_level
 
+    def _should_skip_path(self, path: str) -> bool:
+        """Check if the request path should be skipped from logging.
+
+        Args:
+            path: The request URL path.
+
+        Returns:
+            True if the path should be skipped, False otherwise.
+        """
+        return path in self.skip_paths
+
+    def _prepare_request_context(self, request: Request) -> tuple[str, float]:
+        """Prepare context for request processing.
+
+        Generates a correlation ID and records the start time.
+
+        Args:
+            request: The incoming request.
+
+        Returns:
+            Tuple of (correlation_id, start_time).
+        """
+        correlation_id = str(uuid.uuid4())[:8]
+        request.state.correlation_id = correlation_id
+        start_time = time.time()
+        return correlation_id, start_time
+
+    def _get_duration_ms(self, start_time: float) -> float:
+        """Calculate the request duration in milliseconds.
+
+        Args:
+            start_time: The start time from time.time().
+
+        Returns:
+            Duration in milliseconds.
+        """
+        return (time.time() - start_time) * 1000
+
+    def _log_success(
+        self,
+        request: Request,
+        response: Response,
+        correlation_id: str,
+        duration_ms: float,
+        client_ip: str,
+        user_agent: str,
+    ) -> None:
+        """Log a successful request.
+
+        Args:
+            request: The incoming request.
+            response: The response from downstream.
+            correlation_id: The request correlation ID.
+            duration_ms: Request duration in milliseconds.
+            client_ip: Client IP address.
+            user_agent: User-Agent header value.
+        """
+        self._log_request(
+            method=request.method,
+            path=request.url.path,
+            status_code=response.status_code,
+            duration_ms=duration_ms,
+            client_ip=client_ip,
+            user_agent=user_agent,
+            correlation_id=correlation_id,
+        )
+
+    def _log_error(
+        self,
+        request: Request,
+        exc: Exception,
+        correlation_id: str,
+        duration_ms: float,
+        client_ip: str,
+    ) -> None:
+        """Log a failed request and capture the error.
+
+        Args:
+            request: The incoming request.
+            exc: The exception that was raised.
+            correlation_id: The request correlation ID.
+            duration_ms: Request duration in milliseconds.
+            client_ip: Client IP address.
+        """
+        logger.error(
+            f"[{correlation_id}] {request.method} {request.url.path} "
+            f"- ERROR - {duration_ms:.2f}ms - {client_ip} - {str(exc)}"
+        )
+
+        # Auto-escalate: create bug report task from unhandled exception
+        try:
+            from infrastructure.error_capture import capture_error
+
+            capture_error(
+                exc,
+                source="http",
+                context={
+                    "method": request.method,
+                    "path": request.url.path,
+                    "correlation_id": correlation_id,
+                    "client_ip": client_ip,
+                    "duration_ms": f"{duration_ms:.0f}",
+                },
+            )
+        except Exception:
+            logger.warning("Escalation logging error: capture failed")
+            # never let escalation break the request
+
     async def dispatch(self, request: Request, call_next) -> Response:
         """Log the request and response details.
 
@@ -52,74 +160,23 @@ class RequestLoggingMiddleware(BaseHTTPMiddleware):
         Returns:
             The response from downstream.
         """
-        # Check if we should skip logging this path
-        if request.url.path in self.skip_paths:
+        if self._should_skip_path(request.url.path):
             return await call_next(request)
 
-        # Generate correlation ID
-        correlation_id = str(uuid.uuid4())[:8]
-        request.state.correlation_id = correlation_id
-
-        # Record start time
-        start_time = time.time()
-
-        # Get client info
+        correlation_id, start_time = self._prepare_request_context(request)
         client_ip = self._get_client_ip(request)
         user_agent = request.headers.get("user-agent", "-")
 
         try:
-            # Process the request
             response = await call_next(request)
-
-            # Calculate duration
-            duration_ms = (time.time() - start_time) * 1000
-
-            # Log the request
-            self._log_request(
-                method=request.method,
-                path=request.url.path,
-                status_code=response.status_code,
-                duration_ms=duration_ms,
-                client_ip=client_ip,
-                user_agent=user_agent,
-                correlation_id=correlation_id,
-            )
-
-            # Add correlation ID to response headers
+            duration_ms = self._get_duration_ms(start_time)
+            self._log_success(request, response, correlation_id, duration_ms, client_ip, user_agent)
             response.headers["X-Correlation-ID"] = correlation_id
-
             return response
 
         except Exception as exc:
-            # Calculate duration even for failed requests
-            duration_ms = (time.time() - start_time) * 1000
-
-            # Log the error
-            logger.error(
-                f"[{correlation_id}] {request.method} {request.url.path} "
-                f"- ERROR - {duration_ms:.2f}ms - {client_ip} - {str(exc)}"
-            )
-
-            # Auto-escalate: create bug report task from unhandled exception
-            try:
-                from infrastructure.error_capture import capture_error
-
-                capture_error(
-                    exc,
-                    source="http",
-                    context={
-                        "method": request.method,
-                        "path": request.url.path,
-                        "correlation_id": correlation_id,
-                        "client_ip": client_ip,
-                        "duration_ms": f"{duration_ms:.0f}",
-                    },
-                )
-            except Exception as exc:
-                logger.debug("Escalation logging error: %s", exc)
-                pass  # never let escalation break the request
-
-            # Re-raise the exception
+            duration_ms = self._get_duration_ms(start_time)
+            self._log_error(request, exc, correlation_id, duration_ms, client_ip)
             raise
 
     def _get_client_ip(self, request: Request) -> str:

src/dashboard/routes/daily_run.py

@@ -0,0 +1,435 @@
+"""Daily Run metrics routes — dashboard card for triage and session metrics."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from urllib.error import HTTPError, URLError
+from urllib.request import Request as UrlRequest
+from urllib.request import urlopen
+
+from fastapi import APIRouter, Request
+from fastapi.responses import HTMLResponse, JSONResponse
+
+from config import settings
+from dashboard.templating import templates
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(tags=["daily-run"])
+
+REPO_ROOT = Path(settings.repo_root)
+CONFIG_PATH = REPO_ROOT / "timmy_automations" / "config" / "daily_run.json"
+
+DEFAULT_CONFIG = {
+    "gitea_api": "http://localhost:3000/api/v1",
+    "repo_slug": "rockachopa/Timmy-time-dashboard",
+    "token_file": "~/.hermes/gitea_token",
+    "layer_labels_prefix": "layer:",
+}
+
+LAYER_LABELS = ["layer:triage", "layer:micro-fix", "layer:tests", "layer:economy"]
+
+
+def _load_config() -> dict:
+    """Load configuration from config file with fallback to defaults."""
+    config = DEFAULT_CONFIG.copy()
+    if CONFIG_PATH.exists():
+        try:
+            file_config = json.loads(CONFIG_PATH.read_text())
+            if "orchestrator" in file_config:
+                config.update(file_config["orchestrator"])
+        except (json.JSONDecodeError, OSError) as exc:
+            logger.debug("Could not load daily_run config: %s", exc)
+
+    # Environment variable overrides
+    if os.environ.get("TIMMY_GITEA_API"):
+        config["gitea_api"] = os.environ.get("TIMMY_GITEA_API")
+    if os.environ.get("TIMMY_REPO_SLUG"):
+        config["repo_slug"] = os.environ.get("TIMMY_REPO_SLUG")
+    if os.environ.get("TIMMY_GITEA_TOKEN"):
+        config["token"] = os.environ.get("TIMMY_GITEA_TOKEN")
+
+    return config
+
+
+def _get_token(config: dict) -> str | None:
+    """Get Gitea token from environment or file."""
+    if "token" in config:
+        return config["token"]
+
+    token_file = Path(config["token_file"]).expanduser()
+    if token_file.exists():
+        return token_file.read_text().strip()
+
+    return None
+
+
+class GiteaClient:
+    """Simple Gitea API client with graceful degradation."""
+
+    def __init__(self, config: dict, token: str | None):
+        self.api_base = config["gitea_api"].rstrip("/")
+        self.repo_slug = config["repo_slug"]
+        self.token = token
+        self._available: bool | None = None
+
+    def _headers(self) -> dict:
+        headers = {"Accept": "application/json"}
+        if self.token:
+            headers["Authorization"] = f"token {self.token}"
+        return headers
+
+    def _api_url(self, path: str) -> str:
+        return f"{self.api_base}/repos/{self.repo_slug}/{path}"
+
+    def is_available(self) -> bool:
+        """Check if Gitea API is reachable."""
+        if self._available is not None:
+            return self._available
+
+        try:
+            req = UrlRequest(
+                f"{self.api_base}/version",
+                headers=self._headers(),
+                method="GET",
+            )
+            with urlopen(req, timeout=5) as resp:
+                self._available = resp.status == 200
+                return self._available
+        except (HTTPError, URLError, TimeoutError):
+            self._available = False
+            return False
+
+    def get_paginated(self, path: str, params: dict | None = None) -> list:
+        """Fetch all pages of a paginated endpoint."""
+        all_items = []
+        page = 1
+        limit = 50
+
+        while True:
+            url = self._api_url(path)
+            query_parts = [f"limit={limit}", f"page={page}"]
+            if params:
+                for key, val in params.items():
+                    query_parts.append(f"{key}={val}")
+            url = f"{url}?{'&'.join(query_parts)}"
+
+            req = UrlRequest(url, headers=self._headers(), method="GET")
+            with urlopen(req, timeout=15) as resp:
+                batch = json.loads(resp.read())
+
+            if not batch:
+                break
+
+            all_items.extend(batch)
+            if len(batch) < limit:
+                break
+            page += 1
+
+        return all_items
+
+
+@dataclass
+class LayerMetrics:
+    """Metrics for a single layer."""
+
+    name: str
+    label: str
+    current_count: int
+    previous_count: int
+
+    @property
+    def trend(self) -> str:
+        """Return trend indicator."""
+        if self.previous_count == 0:
+            return "→" if self.current_count == 0 else "↑"
+        diff = self.current_count - self.previous_count
+        pct = (diff / self.previous_count) * 100
+        if pct > 20:
+            return "↑↑"
+        elif pct > 5:
+            return "↑"
+        elif pct < -20:
+            return "↓↓"
+        elif pct < -5:
+            return "↓"
+        return "→"
+
+    @property
+    def trend_color(self) -> str:
+        """Return color for trend (CSS variable name)."""
+        trend = self.trend
+        if trend in ("↑↑", "↑"):
+            return "var(--green)"  # More work = positive
+        elif trend in ("↓↓", "↓"):
+            return "var(--amber)"  # Less work = caution
+        return "var(--text-dim)"
+
+
+@dataclass
+class DailyRunMetrics:
+    """Complete Daily Run metrics."""
+
+    sessions_completed: int
+    sessions_previous: int
+    layers: list[LayerMetrics]
+    total_touched_current: int
+    total_touched_previous: int
+    lookback_days: int
+    generated_at: str
+
+    @property
+    def sessions_trend(self) -> str:
+        """Return sessions trend indicator."""
+        if self.sessions_previous == 0:
+            return "→" if self.sessions_completed == 0 else "↑"
+        diff = self.sessions_completed - self.sessions_previous
+        pct = (diff / self.sessions_previous) * 100
+        if pct > 20:
+            return "↑↑"
+        elif pct > 5:
+            return "↑"
+        elif pct < -20:
+            return "↓↓"
+        elif pct < -5:
+            return "↓"
+        return "→"
+
+    @property
+    def sessions_trend_color(self) -> str:
+        """Return color for sessions trend."""
+        trend = self.sessions_trend
+        if trend in ("↑↑", "↑"):
+            return "var(--green)"
+        elif trend in ("↓↓", "↓"):
+            return "var(--amber)"
+        return "var(--text-dim)"
+
+
+def _extract_layer(labels: list[dict]) -> str | None:
+    """Extract layer label from issue labels."""
+    for label in labels:
+        name = label.get("name", "")
+        if name.startswith("layer:"):
+            return name.replace("layer:", "")
+    return None
+
+
+def _load_cycle_data(days: int = 14) -> dict:
+    """Load cycle retrospective data for session counting."""
+    retro_file = REPO_ROOT / ".loop" / "retro" / "cycles.jsonl"
+    if not retro_file.exists():
+        return {"current": 0, "previous": 0}
+
+    try:
+        entries = []
+        for line in retro_file.read_text().strip().splitlines():
+            try:
+                entries.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue
+
+        now = datetime.now(UTC)
+        current_cutoff = now - timedelta(days=days)
+        previous_cutoff = now - timedelta(days=days * 2)
+
+        current_count = 0
+        previous_count = 0
+
+        for entry in entries:
+            ts_str = entry.get("timestamp", "")
+            if not ts_str:
+                continue
+            try:
+                ts = datetime.fromisoformat(ts_str.replace("Z", "+00:00"))
+                if ts >= current_cutoff:
+                    if entry.get("success", False):
+                        current_count += 1
+                elif ts >= previous_cutoff:
+                    if entry.get("success", False):
+                        previous_count += 1
+            except (ValueError, TypeError):
+                continue
+
+        return {"current": current_count, "previous": previous_count}
+    except (OSError, ValueError) as exc:
+        logger.debug("Failed to load cycle data: %s", exc)
+        return {"current": 0, "previous": 0}
+
+
+def _fetch_layer_metrics(
+    client: GiteaClient, lookback_days: int = 7
+) -> tuple[list[LayerMetrics], int, int]:
+    """Fetch metrics for each layer from Gitea issues."""
+    now = datetime.now(UTC)
+    current_cutoff = now - timedelta(days=lookback_days)
+    previous_cutoff = now - timedelta(days=lookback_days * 2)
+
+    layers = []
+    total_current = 0
+    total_previous = 0
+
+    for layer_label in LAYER_LABELS:
+        layer_name = layer_label.replace("layer:", "")
+        try:
+            # Fetch all issues with this layer label (both open and closed)
+            issues = client.get_paginated(
+                "issues",
+                {"state": "all", "labels": layer_label, "limit": 100},
+            )
+
+            current_count = 0
+            previous_count = 0
+
+            for issue in issues:
+                updated_at = issue.get("updated_at", "")
+                if not updated_at:
+                    continue
+                try:
+                    updated = datetime.fromisoformat(updated_at.replace("Z", "+00:00"))
+                    if updated >= current_cutoff:
+                        current_count += 1
+                    elif updated >= previous_cutoff:
+                        previous_count += 1
+                except (ValueError, TypeError):
+                    continue
+
+            layers.append(
+                LayerMetrics(
+                    name=layer_name,
+                    label=layer_label,
+                    current_count=current_count,
+                    previous_count=previous_count,
+                )
+            )
+            total_current += current_count
+            total_previous += previous_count
+
+        except (HTTPError, URLError) as exc:
+            logger.debug("Failed to fetch issues for %s: %s", layer_label, exc)
+            layers.append(
+                LayerMetrics(
+                    name=layer_name,
+                    label=layer_label,
+                    current_count=0,
+                    previous_count=0,
+                )
+            )
+
+    return layers, total_current, total_previous
+
+
+def _get_metrics(lookback_days: int = 7) -> DailyRunMetrics | None:
+    """Get Daily Run metrics from Gitea API."""
+    config = _load_config()
+    token = _get_token(config)
+    client = GiteaClient(config, token)
+
+    if not client.is_available():
+        logger.debug("Gitea API not available for Daily Run metrics")
+        return None
+
+    try:
+        # Get layer metrics from issues
+        layers, total_current, total_previous = _fetch_layer_metrics(client, lookback_days)
+
+        # Get session data from cycle retrospectives
+        cycle_data = _load_cycle_data(days=lookback_days)
+
+        return DailyRunMetrics(
+            sessions_completed=cycle_data["current"],
+            sessions_previous=cycle_data["previous"],
+            layers=layers,
+            total_touched_current=total_current,
+            total_touched_previous=total_previous,
+            lookback_days=lookback_days,
+            generated_at=datetime.now(UTC).isoformat(),
+        )
+    except Exception as exc:
+        logger.debug("Error fetching Daily Run metrics: %s", exc)
+        return None
+
+
+@router.get("/daily-run/metrics", response_class=JSONResponse)
+async def daily_run_metrics_api(lookback_days: int = 7):
+    """Return Daily Run metrics as JSON API."""
+    metrics = _get_metrics(lookback_days)
+    if not metrics:
+        return JSONResponse(
+            {"error": "Gitea API unavailable", "status": "unavailable"},
+            status_code=503,
+        )
+
+    # Check for quest completions based on Daily Run metrics
+    quest_rewards = []
+    try:
+        from dashboard.routes.quests import check_daily_run_quests
+
+        quest_rewards = await check_daily_run_quests(agent_id="system")
+    except Exception as exc:
+        logger.debug("Quest checking failed: %s", exc)
+
+    return JSONResponse(
+        {
+            "status": "ok",
+            "lookback_days": metrics.lookback_days,
+            "sessions": {
+                "completed": metrics.sessions_completed,
+                "previous": metrics.sessions_previous,
+                "trend": metrics.sessions_trend,
+            },
+            "layers": [
+                {
+                    "name": layer.name,
+                    "label": layer.label,
+                    "current": layer.current_count,
+                    "previous": layer.previous_count,
+                    "trend": layer.trend,
+                }
+                for layer in metrics.layers
+            ],
+            "totals": {
+                "current": metrics.total_touched_current,
+                "previous": metrics.total_touched_previous,
+            },
+            "generated_at": metrics.generated_at,
+            "quest_rewards": quest_rewards,
+        }
+    )
+
+
+@router.get("/daily-run/panel", response_class=HTMLResponse)
+async def daily_run_panel(request: Request, lookback_days: int = 7):
+    """Return Daily Run metrics panel HTML for HTMX polling."""
+    metrics = _get_metrics(lookback_days)
+
+    # Build Gitea URLs for filtered issue lists
+    config = _load_config()
+    repo_slug = config.get("repo_slug", "rockachopa/Timmy-time-dashboard")
+    gitea_base = config.get("gitea_api", "http://localhost:3000/api/v1").replace("/api/v1", "")
+
+    # Logbook URL (link to issues with any layer label)
+    layer_labels = ",".join(LAYER_LABELS)
+    logbook_url = f"{gitea_base}/{repo_slug}/issues?labels={layer_labels}&state=all"
+
+    # Layer-specific URLs
+    layer_urls = {
+        layer: f"{gitea_base}/{repo_slug}/issues?labels=layer:{layer}&state=all"
+        for layer in ["triage", "micro-fix", "tests", "economy"]
+    }
+
+    return templates.TemplateResponse(
+        request,
+        "partials/daily_run_panel.html",
+        {
+            "metrics": metrics,
+            "logbook_url": logbook_url,
+            "layer_urls": layer_urls,
+            "gitea_available": metrics is not None,
+        },
+    )

src/dashboard/routes/db_explorer.py

@@ -75,6 +75,7 @@ def _query_database(db_path: str) -> dict:
                         "truncated": count > MAX_ROWS,
                     }
                 except Exception as exc:
+                    logger.exception("Failed to query table %s", table_name)
                     result["tables"][table_name] = {
                         "error": str(exc),
                         "columns": [],
@@ -83,6 +84,7 @@ def _query_database(db_path: str) -> dict:
                         "truncated": False,
                     }
     except Exception as exc:
+        logger.exception("Failed to query database %s", db_path)
         result["error"] = str(exc)
 
     return result

src/dashboard/routes/grok.py

@@ -135,6 +135,7 @@ def _run_grok_query(message: str) -> dict:
         result = backend.run(message)
         return {"response": f"**[Grok]{invoice_note}:** {result.content}", "error": None}
     except Exception as exc:
+        logger.exception("Grok query failed")
         return {"response": None, "error": f"Grok error: {exc}"}
 
 
@@ -193,6 +194,7 @@ async def grok_stats():
             "model": settings.grok_default_model,
         }
     except Exception as exc:
+        logger.exception("Failed to load Grok stats")
         return {"error": str(exc)}
 
 

src/dashboard/routes/health.py

@@ -148,6 +148,7 @@ def _check_sqlite() -> DependencyStatus:
             details={"path": str(db_path)},
         )
     except Exception as exc:
+        logger.exception("SQLite health check failed")
         return DependencyStatus(
             name="SQLite Database",
             status="unavailable",
@@ -274,3 +275,54 @@ async def component_status():
         },
         "timestamp": datetime.now(UTC).isoformat(),
     }
+
+
+@router.get("/health/snapshot")
+async def health_snapshot():
+    """Quick health snapshot before coding.
+
+    Returns a concise status summary including:
+    - CI pipeline status (pass/fail/unknown)
+    - Critical issues count (P0/P1)
+    - Test flakiness rate
+    - Token economy temperature
+
+    Fast execution (< 5 seconds) for pre-work checks.
+    Refs: #710
+    """
+    import sys
+    from pathlib import Path
+
+    # Import the health snapshot module
+    snapshot_path = Path(settings.repo_root) / "timmy_automations" / "daily_run"
+    if str(snapshot_path) not in sys.path:
+        sys.path.insert(0, str(snapshot_path))
+
+    try:
+        from health_snapshot import generate_snapshot, get_token, load_config
+
+        config = load_config()
+        token = get_token(config)
+
+        # Run the health snapshot (in thread to avoid blocking)
+        snapshot = await asyncio.to_thread(generate_snapshot, config, token)
+
+        return snapshot.to_dict()
+    except Exception as exc:
+        logger.warning("Health snapshot failed: %s", exc)
+        # Return graceful fallback
+        return {
+            "timestamp": datetime.now(UTC).isoformat(),
+            "overall_status": "unknown",
+            "error": str(exc),
+            "ci": {"status": "unknown", "message": "Snapshot failed"},
+            "issues": {"count": 0, "p0_count": 0, "p1_count": 0, "issues": []},
+            "flakiness": {
+                "status": "unknown",
+                "recent_failures": 0,
+                "recent_cycles": 0,
+                "failure_rate": 0.0,
+                "message": "Snapshot failed",
+            },
+            "tokens": {"status": "unknown", "message": "Snapshot failed"},
+        }

src/dashboard/routes/quests.py

@@ -0,0 +1,377 @@
+"""Quest system routes for agent token rewards.
+
+Provides API endpoints for:
+- Listing quests and their status
+- Claiming quest rewards
+- Getting quest leaderboard
+- Quest progress tracking
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from fastapi import APIRouter, Request
+from fastapi.responses import HTMLResponse, JSONResponse
+from pydantic import BaseModel
+
+from dashboard.templating import templates
+from timmy.quest_system import (
+    QuestStatus,
+    auto_evaluate_all_quests,
+    claim_quest_reward,
+    evaluate_quest_progress,
+    get_active_quests,
+    get_agent_quests_status,
+    get_quest_definition,
+    get_quest_leaderboard,
+    load_quest_config,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/quests", tags=["quests"])
+
+
+class ClaimQuestRequest(BaseModel):
+    """Request to claim a quest reward."""
+
+    agent_id: str
+    quest_id: str
+
+
+class EvaluateQuestRequest(BaseModel):
+    """Request to manually evaluate quest progress."""
+
+    agent_id: str
+    quest_id: str
+
+
+# ---------------------------------------------------------------------------
+# API Endpoints
+# ---------------------------------------------------------------------------
+
+
+@router.get("/api/definitions")
+async def get_quest_definitions_api() -> JSONResponse:
+    """Get all quest definitions.
+
+    Returns:
+        JSON list of all quest definitions with their criteria.
+    """
+    definitions = get_active_quests()
+    return JSONResponse(
+        {
+            "quests": [
+                {
+                    "id": q.id,
+                    "name": q.name,
+                    "description": q.description,
+                    "reward_tokens": q.reward_tokens,
+                    "type": q.quest_type.value,
+                    "repeatable": q.repeatable,
+                    "cooldown_hours": q.cooldown_hours,
+                    "criteria": q.criteria,
+                }
+                for q in definitions
+            ]
+        }
+    )
+
+
+@router.get("/api/status/{agent_id}")
+async def get_agent_quest_status(agent_id: str) -> JSONResponse:
+    """Get quest status for a specific agent.
+
+    Returns:
+        Complete quest status including progress, completion counts,
+        and tokens earned.
+    """
+    status = get_agent_quests_status(agent_id)
+    return JSONResponse(status)
+
+
+@router.post("/api/claim")
+async def claim_quest_reward_api(request: ClaimQuestRequest) -> JSONResponse:
+    """Claim a quest reward for an agent.
+
+    The quest must be completed but not yet claimed.
+    """
+    reward = claim_quest_reward(request.quest_id, request.agent_id)
+
+    if not reward:
+        return JSONResponse(
+            {
+                "success": False,
+                "error": "Quest not completed, already claimed, or on cooldown",
+            },
+            status_code=400,
+        )
+
+    return JSONResponse(
+        {
+            "success": True,
+            "reward": reward,
+        }
+    )
+
+
+@router.post("/api/evaluate")
+async def evaluate_quest_api(request: EvaluateQuestRequest) -> JSONResponse:
+    """Manually evaluate quest progress with provided context.
+
+    This is useful for testing or when the quest completion
+    needs to be triggered manually.
+    """
+    quest = get_quest_definition(request.quest_id)
+    if not quest:
+        return JSONResponse(
+            {"success": False, "error": "Quest not found"},
+            status_code=404,
+        )
+
+    # Build evaluation context based on quest type
+    context = await _build_evaluation_context(quest)
+
+    progress = evaluate_quest_progress(request.quest_id, request.agent_id, context)
+
+    if not progress:
+        return JSONResponse(
+            {"success": False, "error": "Failed to evaluate quest"},
+            status_code=500,
+        )
+
+    # Auto-claim if completed
+    reward = None
+    if progress.status == QuestStatus.COMPLETED:
+        reward = claim_quest_reward(request.quest_id, request.agent_id)
+
+    return JSONResponse(
+        {
+            "success": True,
+            "progress": progress.to_dict(),
+            "reward": reward,
+            "completed": progress.status == QuestStatus.COMPLETED,
+        }
+    )
+
+
+@router.get("/api/leaderboard")
+async def get_leaderboard_api() -> JSONResponse:
+    """Get the quest completion leaderboard.
+
+    Returns agents sorted by total tokens earned.
+    """
+    leaderboard = get_quest_leaderboard()
+    return JSONResponse(
+        {
+            "leaderboard": leaderboard,
+        }
+    )
+
+
+@router.post("/api/reload")
+async def reload_quest_config_api() -> JSONResponse:
+    """Reload quest configuration from quests.yaml.
+
+    Useful for applying quest changes without restarting.
+    """
+    definitions, quest_settings = load_quest_config()
+    return JSONResponse(
+        {
+            "success": True,
+            "quests_loaded": len(definitions),
+            "settings": quest_settings,
+        }
+    )
+
+
+# ---------------------------------------------------------------------------
+# Dashboard UI Endpoints
+# ---------------------------------------------------------------------------
+
+
+@router.get("", response_class=HTMLResponse)
+async def quests_dashboard(request: Request) -> HTMLResponse:
+    """Main quests dashboard page."""
+    return templates.TemplateResponse(
+        request,
+        "quests.html",
+        {"agent_id": "current_user"},
+    )
+
+
+@router.get("/panel/{agent_id}", response_class=HTMLResponse)
+async def quests_panel(request: Request, agent_id: str) -> HTMLResponse:
+    """Quest panel for HTMX partial updates."""
+    status = get_agent_quests_status(agent_id)
+    return templates.TemplateResponse(
+        request,
+        "partials/quests_panel.html",
+        {
+            "agent_id": agent_id,
+            "quests": status["quests"],
+            "total_tokens": status["total_tokens_earned"],
+            "completed_count": status["total_quests_completed"],
+        },
+    )
+
+
+# ---------------------------------------------------------------------------
+# Internal Functions
+# ---------------------------------------------------------------------------
+
+
+async def _build_evaluation_context(quest) -> dict[str, Any]:
+    """Build evaluation context for a quest based on its type."""
+    context: dict[str, Any] = {}
+
+    if quest.quest_type.value == "issue_count":
+        # Fetch closed issues with relevant labels
+        context["closed_issues"] = await _fetch_closed_issues(
+            quest.criteria.get("issue_labels", [])
+        )
+
+    elif quest.quest_type.value == "issue_reduce":
+        # Fetch current and previous issue counts
+        labels = quest.criteria.get("issue_labels", [])
+        context["current_issue_count"] = await _fetch_open_issue_count(labels)
+        context["previous_issue_count"] = await _fetch_previous_issue_count(
+            labels, quest.criteria.get("lookback_days", 7)
+        )
+
+    elif quest.quest_type.value == "daily_run":
+        # Fetch Daily Run metrics
+        metrics = await _fetch_daily_run_metrics()
+        context["sessions_completed"] = metrics.get("sessions_completed", 0)
+
+    return context
+
+
+async def _fetch_closed_issues(labels: list[str]) -> list[dict]:
+    """Fetch closed issues matching the given labels."""
+    try:
+        from dashboard.routes.daily_run import GiteaClient, _load_config
+
+        config = _load_config()
+        token = _get_gitea_token(config)
+        client = GiteaClient(config, token)
+
+        if not client.is_available():
+            return []
+
+        # Build label filter
+        label_filter = ",".join(labels) if labels else ""
+
+        issues = client.get_paginated(
+            "issues",
+            {"state": "closed", "labels": label_filter, "limit": 100},
+        )
+
+        return issues
+    except Exception as exc:
+        logger.debug("Failed to fetch closed issues: %s", exc)
+        return []
+
+
+async def _fetch_open_issue_count(labels: list[str]) -> int:
+    """Fetch count of open issues with given labels."""
+    try:
+        from dashboard.routes.daily_run import GiteaClient, _load_config
+
+        config = _load_config()
+        token = _get_gitea_token(config)
+        client = GiteaClient(config, token)
+
+        if not client.is_available():
+            return 0
+
+        label_filter = ",".join(labels) if labels else ""
+
+        issues = client.get_paginated(
+            "issues",
+            {"state": "open", "labels": label_filter, "limit": 100},
+        )
+
+        return len(issues)
+    except Exception as exc:
+        logger.debug("Failed to fetch open issue count: %s", exc)
+        return 0
+
+
+async def _fetch_previous_issue_count(labels: list[str], lookback_days: int) -> int:
+    """Fetch previous issue count (simplified - uses current for now)."""
+    # This is a simplified implementation
+    # In production, you'd query historical data
+    return await _fetch_open_issue_count(labels)
+
+
+async def _fetch_daily_run_metrics() -> dict[str, Any]:
+    """Fetch Daily Run metrics."""
+    try:
+        from dashboard.routes.daily_run import _get_metrics
+
+        metrics = _get_metrics(lookback_days=7)
+        if metrics:
+            return {
+                "sessions_completed": metrics.sessions_completed,
+                "sessions_previous": metrics.sessions_previous,
+            }
+    except Exception as exc:
+        logger.debug("Failed to fetch Daily Run metrics: %s", exc)
+
+    return {"sessions_completed": 0, "sessions_previous": 0}
+
+
+def _get_gitea_token(config: dict) -> str | None:
+    """Get Gitea token from config."""
+    if "token" in config:
+        return config["token"]
+
+    from pathlib import Path
+
+    token_file = Path(config.get("token_file", "~/.hermes/gitea_token")).expanduser()
+    if token_file.exists():
+        return token_file.read_text().strip()
+
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Daily Run Integration
+# ---------------------------------------------------------------------------
+
+
+async def check_daily_run_quests(agent_id: str = "system") -> list[dict]:
+    """Check and award Daily Run related quests.
+
+    Called by the Daily Run system when metrics are updated.
+
+    Returns:
+        List of rewards awarded
+    """
+    # Check if auto-detect is enabled
+    _, quest_settings = load_quest_config()
+    if not quest_settings.get("auto_detect_on_daily_run", True):
+        return []
+
+    # Build context from Daily Run metrics
+    metrics = await _fetch_daily_run_metrics()
+    context = {
+        "sessions_completed": metrics.get("sessions_completed", 0),
+        "sessions_previous": metrics.get("sessions_previous", 0),
+    }
+
+    # Add closed issues for issue_count quests
+    active_quests = get_active_quests()
+    for quest in active_quests:
+        if quest.quest_type.value == "issue_count":
+            labels = quest.criteria.get("issue_labels", [])
+            context["closed_issues"] = await _fetch_closed_issues(labels)
+            break  # Only need to fetch once
+
+    # Evaluate all quests
+    rewards = auto_evaluate_all_quests(agent_id, context)
+
+    return rewards

src/dashboard/routes/scorecards.py

@@ -0,0 +1,353 @@
+"""Agent scorecard routes — API endpoints for generating and viewing scorecards."""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+
+from fastapi import APIRouter, Query, Request
+from fastapi.responses import HTMLResponse, JSONResponse
+
+from dashboard.services.scorecard_service import (
+    PeriodType,
+    generate_all_scorecards,
+    generate_scorecard,
+    get_tracked_agents,
+)
+from dashboard.templating import templates
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/scorecards", tags=["scorecards"])
+
+
+def _format_period_label(period_type: PeriodType) -> str:
+    """Format a period type for display."""
+    return "Daily" if period_type == PeriodType.daily else "Weekly"
+
+
+@router.get("/api/agents")
+async def list_tracked_agents() -> dict[str, list[str]]:
+    """Return the list of tracked agent IDs.
+
+    Returns:
+        Dict with "agents" key containing list of agent IDs
+    """
+    return {"agents": get_tracked_agents()}
+
+
+@router.get("/api/{agent_id}")
+async def get_agent_scorecard(
+    agent_id: str,
+    period: str = Query(default="daily", description="Period type: 'daily' or 'weekly'"),
+) -> JSONResponse:
+    """Generate a scorecard for a specific agent.
+
+    Args:
+        agent_id: The agent ID (e.g., 'kimi', 'claude')
+        period: 'daily' or 'weekly' (default: daily)
+
+    Returns:
+        JSON response with scorecard data
+    """
+    try:
+        period_type = PeriodType(period.lower())
+    except ValueError:
+        return JSONResponse(
+            status_code=400,
+            content={"error": f"Invalid period '{period}'. Use 'daily' or 'weekly'."},
+        )
+
+    try:
+        scorecard = generate_scorecard(agent_id, period_type)
+
+        if scorecard is None:
+            return JSONResponse(
+                status_code=404,
+                content={"error": f"No scorecard found for agent '{agent_id}'"},
+            )
+
+        return JSONResponse(content=scorecard.to_dict())
+
+    except Exception as exc:
+        logger.error("Failed to generate scorecard for %s: %s", agent_id, exc)
+        return JSONResponse(
+            status_code=500,
+            content={"error": f"Failed to generate scorecard: {str(exc)}"},
+        )
+
+
+@router.get("/api")
+async def get_all_scorecards(
+    period: str = Query(default="daily", description="Period type: 'daily' or 'weekly'"),
+) -> JSONResponse:
+    """Generate scorecards for all tracked agents.
+
+    Args:
+        period: 'daily' or 'weekly' (default: daily)
+
+    Returns:
+        JSON response with list of scorecard data
+    """
+    try:
+        period_type = PeriodType(period.lower())
+    except ValueError:
+        return JSONResponse(
+            status_code=400,
+            content={"error": f"Invalid period '{period}'. Use 'daily' or 'weekly'."},
+        )
+
+    try:
+        scorecards = generate_all_scorecards(period_type)
+        return JSONResponse(
+            content={
+                "period": period_type.value,
+                "scorecards": [s.to_dict() for s in scorecards],
+                "count": len(scorecards),
+            }
+        )
+
+    except Exception as exc:
+        logger.error("Failed to generate scorecards: %s", exc)
+        return JSONResponse(
+            status_code=500,
+            content={"error": f"Failed to generate scorecards: {str(exc)}"},
+        )
+
+
+@router.get("", response_class=HTMLResponse)
+async def scorecards_page(request: Request) -> HTMLResponse:
+    """Render the scorecards dashboard page.
+
+    Returns:
+        HTML page with scorecard interface
+    """
+    agents = get_tracked_agents()
+    return templates.TemplateResponse(
+        request,
+        "scorecards.html",
+        {
+            "agents": agents,
+            "periods": ["daily", "weekly"],
+        },
+    )
+
+
+@router.get("/panel/{agent_id}", response_class=HTMLResponse)
+async def agent_scorecard_panel(
+    request: Request,
+    agent_id: str,
+    period: str = Query(default="daily"),
+) -> HTMLResponse:
+    """Render an individual agent scorecard panel (for HTMX).
+
+    Args:
+        request: The request object
+        agent_id: The agent ID
+        period: 'daily' or 'weekly'
+
+    Returns:
+        HTML panel with scorecard content
+    """
+    try:
+        period_type = PeriodType(period.lower())
+    except ValueError:
+        period_type = PeriodType.daily
+
+    try:
+        scorecard = generate_scorecard(agent_id, period_type)
+
+        if scorecard is None:
+            return HTMLResponse(
+                content=f"""
+                <div class="card mc-panel">
+                    <h5 class="card-title">{agent_id.title()}</h5>
+                    <p class="text-muted">No activity recorded for this period.</p>
+                </div>
+                """,
+                status_code=200,
+            )
+
+        data = scorecard.to_dict()
+
+        # Build patterns HTML
+        patterns_html = ""
+        if data["patterns"]:
+            patterns_list = "".join([f"<li>{p}</li>" for p in data["patterns"]])
+            patterns_html = f"""
+            <div class="mt-3">
+                <h6>Patterns</h6>
+                <ul class="list-unstyled text-info">
+                    {patterns_list}
+                </ul>
+            </div>
+            """
+
+        # Build bullets HTML
+        bullets_html = "".join([f"<li>{b}</li>" for b in data["narrative_bullets"]])
+
+        # Build metrics summary
+        metrics = data["metrics"]
+
+        html_content = f"""
+        <div class="card mc-panel">
+            <div class="card-header d-flex justify-content-between align-items-center">
+                <h5 class="card-title mb-0">{agent_id.title()}</h5>
+                <span class="badge bg-secondary">{_format_period_label(period_type)}</span>
+            </div>
+            <div class="card-body">
+                <ul class="list-unstyled mb-3">
+                    {bullets_html}
+                </ul>
+                
+                <div class="row text-center small">
+                    <div class="col">
+                        <div class="text-muted">PRs</div>
+                        <div class="fw-bold">{metrics["prs_opened"]}/{metrics["prs_merged"]}</div>
+                        <div class="text-muted" style="font-size: 0.75rem;">
+                            {int(metrics["pr_merge_rate"] * 100)}% merged
+                        </div>
+                    </div>
+                    <div class="col">
+                        <div class="text-muted">Issues</div>
+                        <div class="fw-bold">{metrics["issues_touched"]}</div>
+                    </div>
+                    <div class="col">
+                        <div class="text-muted">Tests</div>
+                        <div class="fw-bold">{metrics["tests_affected"]}</div>
+                    </div>
+                    <div class="col">
+                        <div class="text-muted">Tokens</div>
+                        <div class="fw-bold {"text-success" if metrics["token_net"] >= 0 else "text-danger"}">
+                            {"+" if metrics["token_net"] > 0 else ""}{metrics["token_net"]}
+                        </div>
+                    </div>
+                </div>
+                
+                {patterns_html}
+            </div>
+        </div>
+        """
+
+        return HTMLResponse(content=html_content)
+
+    except Exception as exc:
+        logger.error("Failed to render scorecard panel for %s: %s", agent_id, exc)
+        return HTMLResponse(
+            content=f"""
+            <div class="card mc-panel border-danger">
+                <h5 class="card-title">{agent_id.title()}</h5>
+                <p class="text-danger">Error loading scorecard: {str(exc)}</p>
+            </div>
+            """,
+            status_code=200,
+        )
+
+
+@router.get("/all/panels", response_class=HTMLResponse)
+async def all_scorecard_panels(
+    request: Request,
+    period: str = Query(default="daily"),
+) -> HTMLResponse:
+    """Render all agent scorecard panels (for HTMX).
+
+    Args:
+        request: The request object
+        period: 'daily' or 'weekly'
+
+    Returns:
+        HTML with all scorecard panels
+    """
+    try:
+        period_type = PeriodType(period.lower())
+    except ValueError:
+        period_type = PeriodType.daily
+
+    try:
+        scorecards = generate_all_scorecards(period_type)
+
+        panels: list[str] = []
+        for scorecard in scorecards:
+            data = scorecard.to_dict()
+
+            # Build patterns HTML
+            patterns_html = ""
+            if data["patterns"]:
+                patterns_list = "".join([f"<li>{p}</li>" for p in data["patterns"]])
+                patterns_html = f"""
+                <div class="mt-3">
+                    <h6>Patterns</h6>
+                    <ul class="list-unstyled text-info">
+                        {patterns_list}
+                    </ul>
+                </div>
+                """
+
+            # Build bullets HTML
+            bullets_html = "".join([f"<li>{b}</li>" for b in data["narrative_bullets"]])
+            metrics = data["metrics"]
+
+            panel_html = f"""
+            <div class="col-md-6 col-lg-4 mb-3">
+                <div class="card mc-panel">
+                    <div class="card-header d-flex justify-content-between align-items-center">
+                        <h5 class="card-title mb-0">{scorecard.agent_id.title()}</h5>
+                        <span class="badge bg-secondary">{_format_period_label(period_type)}</span>
+                    </div>
+                    <div class="card-body">
+                        <ul class="list-unstyled mb-3">
+                            {bullets_html}
+                        </ul>
+                        
+                        <div class="row text-center small">
+                            <div class="col">
+                                <div class="text-muted">PRs</div>
+                                <div class="fw-bold">{metrics["prs_opened"]}/{metrics["prs_merged"]}</div>
+                                <div class="text-muted" style="font-size: 0.75rem;">
+                                    {int(metrics["pr_merge_rate"] * 100)}% merged
+                                </div>
+                            </div>
+                            <div class="col">
+                                <div class="text-muted">Issues</div>
+                                <div class="fw-bold">{metrics["issues_touched"]}</div>
+                            </div>
+                            <div class="col">
+                                <div class="text-muted">Tests</div>
+                                <div class="fw-bold">{metrics["tests_affected"]}</div>
+                            </div>
+                            <div class="col">
+                                <div class="text-muted">Tokens</div>
+                                <div class="fw-bold {"text-success" if metrics["token_net"] >= 0 else "text-danger"}">
+                                    {"+" if metrics["token_net"] > 0 else ""}{metrics["token_net"]}
+                                </div>
+                            </div>
+                        </div>
+                        
+                        {patterns_html}
+                    </div>
+                </div>
+            </div>
+            """
+            panels.append(panel_html)
+
+        html_content = f"""
+        <div class="row">
+            {"".join(panels)}
+        </div>
+        <div class="text-muted small mt-2">
+            Generated: {datetime.now().strftime("%Y-%m-%d %H:%M:%S UTC")}
+        </div>
+        """
+
+        return HTMLResponse(content=html_content)
+
+    except Exception as exc:
+        logger.error("Failed to render all scorecard panels: %s", exc)
+        return HTMLResponse(
+            content=f"""
+            <div class="alert alert-danger">
+                Error loading scorecards: {str(exc)}
+            </div>
+            """,
+            status_code=200,
+        )

src/dashboard/routes/system.py

@@ -56,11 +56,13 @@ async def self_modify_queue(request: Request):
 
 @router.get("/swarm/mission-control", response_class=HTMLResponse)
 async def mission_control(request: Request):
+    """Render the swarm mission control dashboard page."""
     return templates.TemplateResponse(request, "mission_control.html", {})
 
 
 @router.get("/bugs", response_class=HTMLResponse)
 async def bugs_page(request: Request):
+    """Render the bug tracking page."""
     return templates.TemplateResponse(
         request,
         "bugs.html",
@@ -75,16 +77,19 @@ async def bugs_page(request: Request):
 
 @router.get("/self-coding", response_class=HTMLResponse)
 async def self_coding(request: Request):
+    """Render the self-coding automation status page."""
     return templates.TemplateResponse(request, "self_coding.html", {"stats": {}})
 
 
 @router.get("/hands", response_class=HTMLResponse)
 async def hands_page(request: Request):
+    """Render the hands (automation executions) page."""
     return templates.TemplateResponse(request, "hands.html", {"executions": []})
 
 
 @router.get("/creative/ui", response_class=HTMLResponse)
 async def creative_ui(request: Request):
+    """Render the creative UI playground page."""
     return templates.TemplateResponse(request, "creative.html", {})
 
 

src/dashboard/routes/tasks.py

@@ -145,6 +145,7 @@ async def tasks_page(request: Request):
 
 @router.get("/tasks/pending", response_class=HTMLResponse)
 async def tasks_pending(request: Request):
+    """Return HTMX partial for pending approval tasks."""
     with _get_db() as db:
         rows = db.execute(
             "SELECT * FROM tasks WHERE status='pending_approval' ORDER BY created_at DESC"
@@ -164,6 +165,7 @@ async def tasks_pending(request: Request):
 
 @router.get("/tasks/active", response_class=HTMLResponse)
 async def tasks_active(request: Request):
+    """Return HTMX partial for active (approved/running/paused) tasks."""
     with _get_db() as db:
         rows = db.execute(
             "SELECT * FROM tasks WHERE status IN ('approved','running','paused') ORDER BY created_at DESC"
@@ -183,6 +185,7 @@ async def tasks_active(request: Request):
 
 @router.get("/tasks/completed", response_class=HTMLResponse)
 async def tasks_completed(request: Request):
+    """Return HTMX partial for completed/vetoed/failed tasks (last 50)."""
     with _get_db() as db:
         rows = db.execute(
             "SELECT * FROM tasks WHERE status IN ('completed','vetoed','failed') ORDER BY completed_at DESC LIMIT 50"
@@ -241,26 +244,31 @@ async def create_task_form(
 
 @router.post("/tasks/{task_id}/approve", response_class=HTMLResponse)
 async def approve_task(request: Request, task_id: str):
+    """Approve a pending task and move it to active queue."""
     return await _set_status(request, task_id, "approved")
 
 
 @router.post("/tasks/{task_id}/veto", response_class=HTMLResponse)
 async def veto_task(request: Request, task_id: str):
+    """Veto a task, marking it as rejected."""
     return await _set_status(request, task_id, "vetoed")
 
 
 @router.post("/tasks/{task_id}/pause", response_class=HTMLResponse)
 async def pause_task(request: Request, task_id: str):
+    """Pause a running or approved task."""
     return await _set_status(request, task_id, "paused")
 
 
 @router.post("/tasks/{task_id}/cancel", response_class=HTMLResponse)
 async def cancel_task(request: Request, task_id: str):
+    """Cancel a task (marks as vetoed)."""
     return await _set_status(request, task_id, "vetoed")
 
 
 @router.post("/tasks/{task_id}/retry", response_class=HTMLResponse)
 async def retry_task(request: Request, task_id: str):
+    """Retry a failed/vetoed task by moving it back to approved."""
     return await _set_status(request, task_id, "approved")
 
 
@@ -271,6 +279,7 @@ async def modify_task(
     title: str = Form(...),
     description: str = Form(""),
 ):
+    """Update task title and description."""
     with _get_db() as db:
         db.execute(
             "UPDATE tasks SET title=?, description=? WHERE id=?",

src/dashboard/routes/voice.py

@@ -59,6 +59,7 @@ async def tts_speak(text: str = Form(...)):
         voice_tts.speak(text)
         return {"spoken": True, "text": text}
     except Exception as exc:
+        logger.exception("TTS speak failed")
         return {"spoken": False, "reason": str(exc)}
 
 

src/dashboard/routes/world.py

@@ -17,16 +17,221 @@ or missing.
 import asyncio
 import json
 import logging
+import math
 import re
 import time
 from collections import deque
 from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
 
-from fastapi import APIRouter, WebSocket
+import yaml
+from fastapi import APIRouter, Request, WebSocket
 from fastapi.responses import JSONResponse
+from pydantic import BaseModel
 
+from config import settings
+from infrastructure.presence import produce_bark, serialize_presence
+from timmy.memory_system import search_memories
 from timmy.workshop_state import PRESENCE_FILE
 
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/world", tags=["world"])
+matrix_router = APIRouter(prefix="/api/matrix", tags=["matrix"])
+
+# ---------------------------------------------------------------------------
+# Matrix Bark Endpoint — HTTP fallback for bark messages
+# ---------------------------------------------------------------------------
+
+# Rate limiting: 1 request per 3 seconds per visitor_id
+_BARK_RATE_LIMIT_SECONDS = 3
+_bark_last_request: dict[str, float] = {}
+
+
+class BarkRequest(BaseModel):
+    """Request body for POST /api/matrix/bark."""
+
+    text: str
+    visitor_id: str
+
+
+@matrix_router.post("/bark")
+async def post_matrix_bark(request: BarkRequest) -> JSONResponse:
+    """Generate a bark response for a visitor message.
+
+    HTTP fallback for when WebSocket isn't available. The Matrix frontend
+    can POST a message and get Timmy's bark response back as JSON.
+
+    Rate limited to 1 request per 3 seconds per visitor_id.
+
+    Request body:
+        - text: The visitor's message text
+        - visitor_id: Unique identifier for the visitor (used for rate limiting)
+
+    Returns:
+        - 200: Bark message in produce_bark() format
+        - 429: Rate limit exceeded (try again later)
+        - 422: Invalid request (missing/invalid fields)
+    """
+    # Validate inputs
+    text = request.text.strip() if request.text else ""
+    visitor_id = request.visitor_id.strip() if request.visitor_id else ""
+
+    if not text:
+        return JSONResponse(
+            status_code=422,
+            content={"error": "text is required"},
+        )
+
+    if not visitor_id:
+        return JSONResponse(
+            status_code=422,
+            content={"error": "visitor_id is required"},
+        )
+
+    # Rate limiting check
+    now = time.time()
+    last_request = _bark_last_request.get(visitor_id, 0)
+    time_since_last = now - last_request
+
+    if time_since_last < _BARK_RATE_LIMIT_SECONDS:
+        retry_after = _BARK_RATE_LIMIT_SECONDS - time_since_last
+        return JSONResponse(
+            status_code=429,
+            content={"error": "Rate limit exceeded. Try again later."},
+            headers={"Retry-After": str(int(retry_after) + 1)},
+        )
+
+    # Record this request
+    _bark_last_request[visitor_id] = now
+
+    # Generate bark response
+    try:
+        reply = await _generate_bark(text)
+    except Exception as exc:
+        logger.warning("Bark generation failed: %s", exc)
+        reply = "Hmm, my thoughts are a bit tangled right now."
+
+    # Build bark response using produce_bark format
+    bark = produce_bark(agent_id="timmy", text=reply, style="speech")
+
+    return JSONResponse(
+        content=bark,
+        headers={"Cache-Control": "no-cache, no-store"},
+    )
+
+
+# ---------------------------------------------------------------------------
+# Matrix Agent Registry — serves agents to the Matrix visualization
+# ---------------------------------------------------------------------------
+
+# Agent color mapping — consistent with Matrix visual identity
+_AGENT_COLORS: dict[str, str] = {
+    "timmy": "#FFD700",  # Gold
+    "orchestrator": "#FFD700",  # Gold
+    "perplexity": "#3B82F6",  # Blue
+    "replit": "#F97316",  # Orange
+    "kimi": "#06B6D4",  # Cyan
+    "claude": "#A855F7",  # Purple
+    "researcher": "#10B981",  # Emerald
+    "coder": "#EF4444",  # Red
+    "writer": "#EC4899",  # Pink
+    "memory": "#8B5CF6",  # Violet
+    "experimenter": "#14B8A6",  # Teal
+    "forge": "#EF4444",  # Red (coder alias)
+    "seer": "#10B981",  # Emerald (researcher alias)
+    "quill": "#EC4899",  # Pink (writer alias)
+    "echo": "#8B5CF6",  # Violet (memory alias)
+    "lab": "#14B8A6",  # Teal (experimenter alias)
+}
+
+# Agent shape mapping for 3D visualization
+_AGENT_SHAPES: dict[str, str] = {
+    "timmy": "sphere",
+    "orchestrator": "sphere",
+    "perplexity": "cube",
+    "replit": "cylinder",
+    "kimi": "dodecahedron",
+    "claude": "octahedron",
+    "researcher": "icosahedron",
+    "coder": "cube",
+    "writer": "cone",
+    "memory": "torus",
+    "experimenter": "tetrahedron",
+    "forge": "cube",
+    "seer": "icosahedron",
+    "quill": "cone",
+    "echo": "torus",
+    "lab": "tetrahedron",
+}
+
+# Default fallback values
+_DEFAULT_COLOR = "#9CA3AF"  # Gray
+_DEFAULT_SHAPE = "sphere"
+_DEFAULT_STATUS = "available"
+
+
+def _get_agent_color(agent_id: str) -> str:
+    """Get the Matrix color for an agent."""
+    return _AGENT_COLORS.get(agent_id.lower(), _DEFAULT_COLOR)
+
+
+def _get_agent_shape(agent_id: str) -> str:
+    """Get the Matrix shape for an agent."""
+    return _AGENT_SHAPES.get(agent_id.lower(), _DEFAULT_SHAPE)
+
+
+def _compute_circular_positions(count: int, radius: float = 3.0) -> list[dict[str, float]]:
+    """Compute circular positions for agents in the Matrix.
+
+    Agents are arranged in a circle on the XZ plane at y=0.
+    """
+    positions = []
+    for i in range(count):
+        angle = (2 * math.pi * i) / count
+        x = radius * math.cos(angle)
+        z = radius * math.sin(angle)
+        positions.append({"x": round(x, 2), "y": 0.0, "z": round(z, 2)})
+    return positions
+
+
+def _build_matrix_agents_response() -> list[dict[str, Any]]:
+    """Build the Matrix agent registry response.
+
+    Reads from agents.yaml and returns agents with Matrix-compatible
+    formatting including colors, shapes, and positions.
+    """
+    try:
+        from timmy.agents.loader import list_agents
+
+        agents = list_agents()
+        if not agents:
+            return []
+
+        positions = _compute_circular_positions(len(agents))
+
+        result = []
+        for i, agent in enumerate(agents):
+            agent_id = agent.get("id", "")
+            result.append(
+                {
+                    "id": agent_id,
+                    "display_name": agent.get("name", agent_id.title()),
+                    "role": agent.get("role", "general"),
+                    "color": _get_agent_color(agent_id),
+                    "position": positions[i],
+                    "shape": _get_agent_shape(agent_id),
+                    "status": agent.get("status", _DEFAULT_STATUS),
+                }
+            )
+
+        return result
+    except Exception as exc:
+        logger.warning("Failed to load agents for Matrix: %s", exc)
+        return []
+
+
 logger = logging.getLogger(__name__)
 
 router = APIRouter(prefix="/api/world", tags=["world"])
@@ -149,21 +354,7 @@ def _read_presence_file() -> dict | None:
 
 def _build_world_state(presence: dict) -> dict:
     """Transform presence dict into the world/state API response."""
-    return {
-        "timmyState": {
-            "mood": presence.get("mood", "calm"),
-            "activity": presence.get("current_focus", "idle"),
-            "energy": presence.get("energy", 0.5),
-            "confidence": presence.get("confidence", 0.7),
-        },
-        "familiar": presence.get("familiar"),
-        "activeThreads": presence.get("active_threads", []),
-        "recentEvents": presence.get("recent_events", []),
-        "concerns": presence.get("concerns", []),
-        "visitorPresent": False,
-        "updatedAt": presence.get("liveness", datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")),
-        "version": presence.get("version", 1),
-    }
+    return serialize_presence(presence)
 
 
 def _get_current_state() -> dict:
@@ -224,6 +415,50 @@ async def _heartbeat(websocket: WebSocket) -> None:
         logger.debug("Heartbeat stopped — connection gone")
 
 
+async def _authenticate_ws(websocket: WebSocket) -> bool:
+    """Authenticate WebSocket connection using matrix_ws_token.
+
+    Checks for token in query param ?token= first. If no query param,
+    accepts the connection and waits for first message with
+    {"type": "auth", "token": "..."}.
+
+    Returns True if authenticated (or if auth is disabled).
+    Returns False and closes connection with code 4001 if invalid.
+    """
+    token_setting = settings.matrix_ws_token
+
+    # Auth disabled in dev mode (empty/unset token)
+    if not token_setting:
+        return True
+
+    # Check query param first (can validate before accept)
+    query_token = websocket.query_params.get("token", "")
+    if query_token:
+        if query_token == token_setting:
+            return True
+        # Invalid token in query param - we need to accept to close properly
+        await websocket.accept()
+        await websocket.close(code=4001, reason="Invalid token")
+        return False
+
+    # No query token - accept and wait for auth message
+    await websocket.accept()
+
+    # Wait for auth message as first message
+    try:
+        raw = await websocket.receive_text()
+        data = json.loads(raw)
+        if data.get("type") == "auth" and data.get("token") == token_setting:
+            return True
+        # Invalid auth message
+        await websocket.close(code=4001, reason="Invalid token")
+        return False
+    except (json.JSONDecodeError, TypeError):
+        # Non-JSON first message without valid token
+        await websocket.close(code=4001, reason="Authentication required")
+        return False
+
+
 @router.websocket("/ws")
 async def world_ws(websocket: WebSocket) -> None:
     """Accept a Workshop client and keep it alive for state broadcasts.
@@ -232,8 +467,28 @@ async def world_ws(websocket: WebSocket) -> None:
     client never starts from a blank slate.  Incoming frames are parsed
     as JSON — ``visitor_message`` triggers a bark response.  A background
     heartbeat ping runs every 15 s to detect dead connections early.
+
+    Authentication:
+        - If matrix_ws_token is configured, clients must provide it via
+          ?token= query param or in the first message as
+          {"type": "auth", "token": "..."}.
+        - Invalid token results in close code 4001.
+        - Valid token receives a connection_ack message.
     """
-    await websocket.accept()
+    # Authenticate (may accept connection internally)
+    is_authed = await _authenticate_ws(websocket)
+    if not is_authed:
+        logger.info("World WS connection rejected — invalid token")
+        return
+
+    # Auth passed - accept if not already accepted
+    if websocket.client_state.name != "CONNECTED":
+        await websocket.accept()
+
+    # Send connection_ack if auth was required
+    if settings.matrix_ws_token:
+        await websocket.send_text(json.dumps({"type": "connection_ack"}))
+
     _ws_clients.append(websocket)
     logger.info("World WS connected — %d clients", len(_ws_clients))
 
@@ -383,3 +638,428 @@ async def _generate_bark(visitor_text: str) -> str:
     except Exception as exc:
         logger.warning("Bark generation failed: %s", exc)
         return "Hmm, my thoughts are a bit tangled right now."
+
+
+# ---------------------------------------------------------------------------
+# Matrix Configuration Endpoint
+# ---------------------------------------------------------------------------
+
+# Default Matrix configuration (fallback when matrix.yaml is missing/corrupt)
+_DEFAULT_MATRIX_CONFIG: dict[str, Any] = {
+    "lighting": {
+        "ambient_color": "#1a1a2e",
+        "ambient_intensity": 0.4,
+        "point_lights": [
+            {"color": "#FFD700", "intensity": 1.2, "position": {"x": 0, "y": 5, "z": 0}},
+            {"color": "#3B82F6", "intensity": 0.8, "position": {"x": -5, "y": 3, "z": -5}},
+            {"color": "#A855F7", "intensity": 0.6, "position": {"x": 5, "y": 3, "z": 5}},
+        ],
+    },
+    "environment": {
+        "rain_enabled": False,
+        "starfield_enabled": True,
+        "fog_color": "#0f0f23",
+        "fog_density": 0.02,
+    },
+    "features": {
+        "chat_enabled": True,
+        "visitor_avatars": True,
+        "pip_familiar": True,
+        "workshop_portal": True,
+    },
+}
+
+
+def _load_matrix_config() -> dict[str, Any]:
+    """Load Matrix world configuration from matrix.yaml with fallback to defaults.
+
+    Returns a dict with sections: lighting, environment, features.
+    If the config file is missing or invalid, returns sensible defaults.
+    """
+    try:
+        config_path = Path(settings.repo_root) / "config" / "matrix.yaml"
+        if not config_path.exists():
+            logger.debug("matrix.yaml not found, using default config")
+            return _DEFAULT_MATRIX_CONFIG.copy()
+
+        raw = config_path.read_text()
+        config = yaml.safe_load(raw)
+        if not isinstance(config, dict):
+            logger.warning("matrix.yaml invalid format, using defaults")
+            return _DEFAULT_MATRIX_CONFIG.copy()
+
+        # Merge with defaults to ensure all required fields exist
+        result: dict[str, Any] = {
+            "lighting": {
+                **_DEFAULT_MATRIX_CONFIG["lighting"],
+                **config.get("lighting", {}),
+            },
+            "environment": {
+                **_DEFAULT_MATRIX_CONFIG["environment"],
+                **config.get("environment", {}),
+            },
+            "features": {
+                **_DEFAULT_MATRIX_CONFIG["features"],
+                **config.get("features", {}),
+            },
+        }
+
+        # Ensure point_lights is a list
+        if "point_lights" in config.get("lighting", {}):
+            result["lighting"]["point_lights"] = config["lighting"]["point_lights"]
+        else:
+            result["lighting"]["point_lights"] = _DEFAULT_MATRIX_CONFIG["lighting"]["point_lights"]
+
+        return result
+    except Exception as exc:
+        logger.warning("Failed to load matrix config: %s, using defaults", exc)
+        return _DEFAULT_MATRIX_CONFIG.copy()
+
+
+@matrix_router.get("/config")
+async def get_matrix_config() -> JSONResponse:
+    """Return Matrix world configuration.
+
+    Serves lighting presets, environment settings, and feature flags
+    to the Matrix frontend so it can be config-driven rather than
+    hardcoded. Reads from config/matrix.yaml with sensible defaults.
+
+    Response structure:
+    - lighting: ambient_color, ambient_intensity, point_lights[]
+    - environment: rain_enabled, starfield_enabled, fog_color, fog_density
+    - features: chat_enabled, visitor_avatars, pip_familiar, workshop_portal
+    """
+    config = _load_matrix_config()
+    return JSONResponse(
+        content=config,
+        headers={"Cache-Control": "no-cache, no-store"},
+    )
+
+
+# ---------------------------------------------------------------------------
+# Matrix Agent Registry Endpoint
+# ---------------------------------------------------------------------------
+
+
+@matrix_router.get("/agents")
+async def get_matrix_agents() -> JSONResponse:
+    """Return the agent registry for Matrix visualization.
+
+    Serves agents from agents.yaml with Matrix-compatible formatting:
+    - id: agent identifier
+    - display_name: human-readable name
+    - role: functional role
+    - color: hex color code for visualization
+    - position: {x, y, z} coordinates in 3D space
+    - shape: 3D shape type
+    - status: availability status
+
+    Agents are arranged in a circular layout by default.
+    Returns 200 with empty list if no agents configured.
+    """
+    agents = _build_matrix_agents_response()
+    return JSONResponse(
+        content=agents,
+        headers={"Cache-Control": "no-cache, no-store"},
+    )
+
+
+# ---------------------------------------------------------------------------
+# Matrix Thoughts Endpoint — Timmy's recent thought stream for Matrix display
+# ---------------------------------------------------------------------------
+
+_MAX_THOUGHT_LIMIT = 50  # Maximum thoughts allowed per request
+_DEFAULT_THOUGHT_LIMIT = 10  # Default number of thoughts to return
+_MAX_THOUGHT_TEXT_LEN = 500  # Max characters for thought text
+
+
+def _build_matrix_thoughts_response(limit: int = _DEFAULT_THOUGHT_LIMIT) -> list[dict[str, Any]]:
+    """Build the Matrix thoughts response from the thinking engine.
+
+    Returns recent thoughts formatted for Matrix display:
+    - id: thought UUID
+    - text: thought content (truncated to 500 chars)
+    - created_at: ISO-8601 timestamp
+    - chain_id: parent thought ID (or null if root thought)
+
+    Returns empty list if thinking engine is disabled or fails.
+    """
+    try:
+        from timmy.thinking import thinking_engine
+
+        thoughts = thinking_engine.get_recent_thoughts(limit=limit)
+        return [
+            {
+                "id": t.id,
+                "text": t.content[:_MAX_THOUGHT_TEXT_LEN],
+                "created_at": t.created_at,
+                "chain_id": t.parent_id,
+            }
+            for t in thoughts
+        ]
+    except Exception as exc:
+        logger.warning("Failed to load thoughts for Matrix: %s", exc)
+        return []
+
+
+@matrix_router.get("/thoughts")
+async def get_matrix_thoughts(limit: int = _DEFAULT_THOUGHT_LIMIT) -> JSONResponse:
+    """Return Timmy's recent thoughts formatted for Matrix display.
+
+    This is the REST companion to the thought WebSocket messages,
+    allowing the Matrix frontend to display what Timmy is actually
+    thinking about rather than canned contextual lines.
+
+    Query params:
+        - limit: Number of thoughts to return (default 10, max 50)
+
+    Response: JSON array of thought objects:
+        - id: thought UUID
+        - text: thought content (truncated to 500 chars)
+        - created_at: ISO-8601 timestamp
+        - chain_id: parent thought ID (null if root thought)
+
+    Returns empty array if thinking engine is disabled or fails.
+    """
+    # Clamp limit to valid range
+    if limit < 1:
+        limit = 1
+    elif limit > _MAX_THOUGHT_LIMIT:
+        limit = _MAX_THOUGHT_LIMIT
+
+    thoughts = _build_matrix_thoughts_response(limit=limit)
+    return JSONResponse(
+        content=thoughts,
+        headers={"Cache-Control": "no-cache, no-store"},
+    )
+
+
+# ---------------------------------------------------------------------------
+# Matrix Health Endpoint — backend capability discovery
+# ---------------------------------------------------------------------------
+
+# Health check cache (5-second TTL for capability checks)
+_health_cache: dict | None = None
+_health_cache_ts: float = 0.0
+_HEALTH_CACHE_TTL = 5.0
+
+
+def _check_capability_thinking() -> bool:
+    """Check if thinking engine is available."""
+    try:
+        from timmy.thinking import thinking_engine
+
+        # Check if the engine has been initialized (has a db path)
+        return hasattr(thinking_engine, "_db") and thinking_engine._db is not None
+    except Exception:
+        return False
+
+
+def _check_capability_memory() -> bool:
+    """Check if memory system is available."""
+    try:
+        from timmy.memory_system import HOT_MEMORY_PATH
+
+        return HOT_MEMORY_PATH.exists()
+    except Exception:
+        return False
+
+
+def _check_capability_bark() -> bool:
+    """Check if bark production is available."""
+    try:
+        from infrastructure.presence import produce_bark
+
+        return callable(produce_bark)
+    except Exception:
+        return False
+
+
+def _check_capability_familiar() -> bool:
+    """Check if familiar (Pip) is available."""
+    try:
+        from timmy.familiar import pip_familiar
+
+        return pip_familiar is not None
+    except Exception:
+        return False
+
+
+def _check_capability_lightning() -> bool:
+    """Check if Lightning payments are available."""
+    # Lightning is currently disabled per health.py
+    # Returns False until properly re-implemented
+    return False
+
+
+def _build_matrix_health_response() -> dict[str, Any]:
+    """Build the Matrix health response with capability checks.
+
+    Performs lightweight checks (<100ms total) to determine which features
+    are available. Returns 200 even if some capabilities are degraded.
+    """
+    capabilities = {
+        "thinking": _check_capability_thinking(),
+        "memory": _check_capability_memory(),
+        "bark": _check_capability_bark(),
+        "familiar": _check_capability_familiar(),
+        "lightning": _check_capability_lightning(),
+    }
+
+    # Status is ok if core capabilities (thinking, memory, bark) are available
+    core_caps = ["thinking", "memory", "bark"]
+    core_available = all(capabilities[c] for c in core_caps)
+    status = "ok" if core_available else "degraded"
+
+    return {
+        "status": status,
+        "version": "1.0.0",
+        "capabilities": capabilities,
+    }
+
+
+@matrix_router.get("/health")
+async def get_matrix_health() -> JSONResponse:
+    """Return health status and capability availability for Matrix frontend.
+
+        This endpoint allows the Matrix frontend to discover what backend
+    capabilities are available so it can show/hide UI elements:
+        - thinking: Show thought bubbles if enabled
+        - memory: Show crystal ball memory search if available
+        - bark: Enable visitor chat responses
+        - familiar: Show Pip the familiar
+        - lightning: Enable payment features
+
+        Response time is <100ms (no heavy checks). Returns 200 even if
+        some capabilities are degraded.
+
+        Response:
+            - status: "ok" or "degraded"
+            - version: API version string
+            - capabilities: dict of feature:bool
+    """
+    response = _build_matrix_health_response()
+    status_code = 200  # Always 200, even if degraded
+
+    return JSONResponse(
+        content=response,
+        status_code=status_code,
+        headers={"Cache-Control": "no-cache, no-store"},
+    )
+
+
+# ---------------------------------------------------------------------------
+# Matrix Memory Search Endpoint — visitors query Timmy's memory
+# ---------------------------------------------------------------------------
+
+# Rate limiting: 1 search per 5 seconds per IP
+_MEMORY_SEARCH_RATE_LIMIT_SECONDS = 5
+_memory_search_last_request: dict[str, float] = {}
+_MAX_MEMORY_RESULTS = 5
+_MAX_MEMORY_TEXT_LENGTH = 200
+
+
+def _get_client_ip(request) -> str:
+    """Extract client IP from request, respecting X-Forwarded-For header."""
+    # Check for forwarded IP (when behind proxy)
+    forwarded = request.headers.get("X-Forwarded-For")
+    if forwarded:
+        # Take the first IP in the chain
+        return forwarded.split(",")[0].strip()
+    # Fall back to direct client IP
+    if request.client:
+        return request.client.host
+    return "unknown"
+
+
+def _build_matrix_memory_response(
+    memories: list,
+) -> list[dict[str, Any]]:
+    """Build the Matrix memory search response.
+
+    Formats memory entries for Matrix display:
+    - text: truncated to 200 characters
+    - relevance: 0-1 score from relevance_score
+    - created_at: ISO-8601 timestamp
+    - context_type: the memory type
+
+    Results are capped at _MAX_MEMORY_RESULTS.
+    """
+    results = []
+    for mem in memories[:_MAX_MEMORY_RESULTS]:
+        text = mem.content
+        if len(text) > _MAX_MEMORY_TEXT_LENGTH:
+            text = text[:_MAX_MEMORY_TEXT_LENGTH] + "..."
+
+        results.append(
+            {
+                "text": text,
+                "relevance": round(mem.relevance_score or 0.0, 4),
+                "created_at": mem.timestamp,
+                "context_type": mem.context_type,
+            }
+        )
+    return results
+
+
+@matrix_router.get("/memory/search")
+async def get_matrix_memory_search(request: Request, q: str | None = None) -> JSONResponse:
+    """Search Timmy's memory for relevant snippets.
+
+    Allows Matrix visitors to query Timmy's memory ("what do you remember
+    about sovereignty?"). Results appear as floating crystal-ball text
+    in the Workshop room.
+
+    Query params:
+        - q: Search query text (required)
+
+    Response: JSON array of memory objects:
+        - text: Memory content (truncated to 200 chars)
+        - relevance: Similarity score 0-1
+        - created_at: ISO-8601 timestamp
+        - context_type: Memory type (conversation, fact, etc.)
+
+    Rate limited to 1 search per 5 seconds per IP.
+
+    Returns:
+        - 200: JSON array of memory results (max 5)
+        - 400: Missing or empty query parameter
+        - 429: Rate limit exceeded
+    """
+    # Validate query parameter
+    query = q.strip() if q else ""
+    if not query:
+        return JSONResponse(
+            status_code=400,
+            content={"error": "Query parameter 'q' is required"},
+        )
+
+    # Rate limiting check by IP
+    client_ip = _get_client_ip(request)
+    now = time.time()
+    last_request = _memory_search_last_request.get(client_ip, 0)
+    time_since_last = now - last_request
+
+    if time_since_last < _MEMORY_SEARCH_RATE_LIMIT_SECONDS:
+        retry_after = _MEMORY_SEARCH_RATE_LIMIT_SECONDS - time_since_last
+        return JSONResponse(
+            status_code=429,
+            content={"error": "Rate limit exceeded. Try again later."},
+            headers={"Retry-After": str(int(retry_after) + 1)},
+        )
+
+    # Record this request
+    _memory_search_last_request[client_ip] = now
+
+    # Search memories
+    try:
+        memories = search_memories(query, limit=_MAX_MEMORY_RESULTS)
+        results = _build_matrix_memory_response(memories)
+    except Exception as exc:
+        logger.warning("Memory search failed: %s", exc)
+        results = []
+
+    return JSONResponse(
+        content=results,
+        headers={"Cache-Control": "no-cache, no-store"},
+    )

src/dashboard/services/__init__.py

@@ -0,0 +1,17 @@
+"""Dashboard services for business logic."""
+
+from dashboard.services.scorecard_service import (
+    PeriodType,
+    ScorecardSummary,
+    generate_all_scorecards,
+    generate_scorecard,
+    get_tracked_agents,
+)
+
+__all__ = [
+    "PeriodType",
+    "ScorecardSummary",
+    "generate_all_scorecards",
+    "generate_scorecard",
+    "get_tracked_agents",
+]

src/dashboard/services/scorecard_service.py

@@ -0,0 +1,515 @@
+"""Agent scorecard service — track and summarize agent performance.
+
+Generates daily/weekly scorecards showing:
+- Issues touched, PRs opened/merged
+- Tests affected, tokens earned/spent
+- Pattern highlights (merge rate, activity quality)
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
+from enum import StrEnum
+from typing import Any
+
+from infrastructure.events.bus import Event, get_event_bus
+
+logger = logging.getLogger(__name__)
+
+# Bot/agent usernames to track
+TRACKED_AGENTS = frozenset({"hermes", "kimi", "manus", "claude", "gemini"})
+
+
+class PeriodType(StrEnum):
+    daily = "daily"
+    weekly = "weekly"
+
+
+@dataclass
+class AgentMetrics:
+    """Raw metrics collected for an agent over a period."""
+
+    agent_id: str
+    issues_touched: set[int] = field(default_factory=set)
+    prs_opened: set[int] = field(default_factory=set)
+    prs_merged: set[int] = field(default_factory=set)
+    tests_affected: set[str] = field(default_factory=set)
+    tokens_earned: int = 0
+    tokens_spent: int = 0
+    commits: int = 0
+    comments: int = 0
+
+    @property
+    def pr_merge_rate(self) -> float:
+        """Calculate PR merge rate (0.0 - 1.0)."""
+        opened = len(self.prs_opened)
+        if opened == 0:
+            return 0.0
+        return len(self.prs_merged) / opened
+
+
+@dataclass
+class ScorecardSummary:
+    """A generated scorecard with narrative summary."""
+
+    agent_id: str
+    period_type: PeriodType
+    period_start: datetime
+    period_end: datetime
+    metrics: AgentMetrics
+    narrative_bullets: list[str] = field(default_factory=list)
+    patterns: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert scorecard to dictionary for JSON serialization."""
+        return {
+            "agent_id": self.agent_id,
+            "period_type": self.period_type.value,
+            "period_start": self.period_start.isoformat(),
+            "period_end": self.period_end.isoformat(),
+            "metrics": {
+                "issues_touched": len(self.metrics.issues_touched),
+                "prs_opened": len(self.metrics.prs_opened),
+                "prs_merged": len(self.metrics.prs_merged),
+                "pr_merge_rate": round(self.metrics.pr_merge_rate, 2),
+                "tests_affected": len(self.tests_affected),
+                "commits": self.metrics.commits,
+                "comments": self.metrics.comments,
+                "tokens_earned": self.metrics.tokens_earned,
+                "tokens_spent": self.metrics.tokens_spent,
+                "token_net": self.metrics.tokens_earned - self.metrics.tokens_spent,
+            },
+            "narrative_bullets": self.narrative_bullets,
+            "patterns": self.patterns,
+        }
+
+    @property
+    def tests_affected(self) -> set[str]:
+        """Alias for metrics.tests_affected."""
+        return self.metrics.tests_affected
+
+
+def _get_period_bounds(
+    period_type: PeriodType, reference_date: datetime | None = None
+) -> tuple[datetime, datetime]:
+    """Calculate start and end timestamps for a period.
+
+    Args:
+        period_type: daily or weekly
+        reference_date: The date to calculate from (defaults to now)
+
+    Returns:
+        Tuple of (period_start, period_end) in UTC
+    """
+    if reference_date is None:
+        reference_date = datetime.now(UTC)
+
+    # Normalize to start of day
+    end = reference_date.replace(hour=0, minute=0, second=0, microsecond=0)
+
+    if period_type == PeriodType.daily:
+        start = end - timedelta(days=1)
+    else:  # weekly
+        start = end - timedelta(days=7)
+
+    return start, end
+
+
+def _collect_events_for_period(
+    start: datetime, end: datetime, agent_id: str | None = None
+) -> list[Event]:
+    """Collect events from the event bus for a time period.
+
+    Args:
+        start: Period start time
+        end: Period end time
+        agent_id: Optional agent filter
+
+    Returns:
+        List of matching events
+    """
+    bus = get_event_bus()
+    events: list[Event] = []
+
+    # Query persisted events for relevant types
+    event_types = [
+        "gitea.push",
+        "gitea.issue.opened",
+        "gitea.issue.comment",
+        "gitea.pull_request",
+        "agent.task.completed",
+        "test.execution",
+    ]
+
+    for event_type in event_types:
+        try:
+            type_events = bus.replay(
+                event_type=event_type,
+                source=agent_id,
+                limit=1000,
+            )
+            events.extend(type_events)
+        except Exception as exc:
+            logger.debug("Failed to replay events for %s: %s", event_type, exc)
+
+    # Filter by timestamp
+    filtered = []
+    for event in events:
+        try:
+            event_time = datetime.fromisoformat(event.timestamp.replace("Z", "+00:00"))
+            if start <= event_time < end:
+                filtered.append(event)
+        except (ValueError, AttributeError):
+            continue
+
+    return filtered
+
+
+def _extract_actor_from_event(event: Event) -> str:
+    """Extract the actor/agent from an event."""
+    # Try data fields first
+    if "actor" in event.data:
+        return event.data["actor"]
+    if "agent_id" in event.data:
+        return event.data["agent_id"]
+    # Fall back to source
+    return event.source
+
+
+def _is_tracked_agent(actor: str) -> bool:
+    """Check if an actor is a tracked agent."""
+    return actor.lower() in TRACKED_AGENTS
+
+
+def _aggregate_metrics(events: list[Event]) -> dict[str, AgentMetrics]:
+    """Aggregate metrics from events grouped by agent.
+
+    Args:
+        events: List of events to process
+
+    Returns:
+        Dict mapping agent_id -> AgentMetrics
+    """
+    metrics_by_agent: dict[str, AgentMetrics] = {}
+
+    for event in events:
+        actor = _extract_actor_from_event(event)
+
+        # Skip non-agent events unless they explicitly have an agent_id
+        if not _is_tracked_agent(actor) and "agent_id" not in event.data:
+            continue
+
+        if actor not in metrics_by_agent:
+            metrics_by_agent[actor] = AgentMetrics(agent_id=actor)
+
+        metrics = metrics_by_agent[actor]
+
+        # Process based on event type
+        event_type = event.type
+
+        if event_type == "gitea.push":
+            metrics.commits += event.data.get("num_commits", 1)
+
+        elif event_type == "gitea.issue.opened":
+            issue_num = event.data.get("issue_number", 0)
+            if issue_num:
+                metrics.issues_touched.add(issue_num)
+
+        elif event_type == "gitea.issue.comment":
+            metrics.comments += 1
+            issue_num = event.data.get("issue_number", 0)
+            if issue_num:
+                metrics.issues_touched.add(issue_num)
+
+        elif event_type == "gitea.pull_request":
+            pr_num = event.data.get("pr_number", 0)
+            action = event.data.get("action", "")
+            merged = event.data.get("merged", False)
+
+            if pr_num:
+                if action == "opened":
+                    metrics.prs_opened.add(pr_num)
+                elif action == "closed" and merged:
+                    metrics.prs_merged.add(pr_num)
+                    # Also count as touched issue for tracking
+                    metrics.issues_touched.add(pr_num)
+
+        elif event_type == "agent.task.completed":
+            # Extract test files from task data
+            affected = event.data.get("tests_affected", [])
+            for test in affected:
+                metrics.tests_affected.add(test)
+
+            # Token rewards from task completion
+            reward = event.data.get("token_reward", 0)
+            if reward:
+                metrics.tokens_earned += reward
+
+        elif event_type == "test.execution":
+            # Track test files that were executed
+            test_files = event.data.get("test_files", [])
+            for test in test_files:
+                metrics.tests_affected.add(test)
+
+    return metrics_by_agent
+
+
+def _query_token_transactions(agent_id: str, start: datetime, end: datetime) -> tuple[int, int]:
+    """Query the lightning ledger for token transactions.
+
+    Args:
+        agent_id: The agent to query for
+        start: Period start
+        end: Period end
+
+    Returns:
+        Tuple of (tokens_earned, tokens_spent)
+    """
+    try:
+        from lightning.ledger import get_transactions
+
+        transactions = get_transactions(limit=1000)
+
+        earned = 0
+        spent = 0
+
+        for tx in transactions:
+            # Filter by agent if specified
+            if tx.agent_id and tx.agent_id != agent_id:
+                continue
+
+            # Filter by timestamp
+            try:
+                tx_time = datetime.fromisoformat(tx.created_at.replace("Z", "+00:00"))
+                if not (start <= tx_time < end):
+                    continue
+            except (ValueError, AttributeError):
+                continue
+
+            if tx.tx_type.value == "incoming":
+                earned += tx.amount_sats
+            else:
+                spent += tx.amount_sats
+
+        return earned, spent
+
+    except Exception as exc:
+        logger.debug("Failed to query token transactions: %s", exc)
+        return 0, 0
+
+
+def _generate_narrative_bullets(metrics: AgentMetrics, period_type: PeriodType) -> list[str]:
+    """Generate narrative summary bullets for a scorecard.
+
+    Args:
+        metrics: The agent's metrics
+        period_type: daily or weekly
+
+    Returns:
+        List of narrative bullet points
+    """
+    bullets: list[str] = []
+    period_label = "day" if period_type == PeriodType.daily else "week"
+
+    # Activity summary
+    activities = []
+    if metrics.commits:
+        activities.append(f"{metrics.commits} commit{'s' if metrics.commits != 1 else ''}")
+    if len(metrics.prs_opened):
+        activities.append(
+            f"{len(metrics.prs_opened)} PR{'s' if len(metrics.prs_opened) != 1 else ''} opened"
+        )
+    if len(metrics.prs_merged):
+        activities.append(
+            f"{len(metrics.prs_merged)} PR{'s' if len(metrics.prs_merged) != 1 else ''} merged"
+        )
+    if len(metrics.issues_touched):
+        activities.append(
+            f"{len(metrics.issues_touched)} issue{'s' if len(metrics.issues_touched) != 1 else ''} touched"
+        )
+    if metrics.comments:
+        activities.append(f"{metrics.comments} comment{'s' if metrics.comments != 1 else ''}")
+
+    if activities:
+        bullets.append(f"Active across {', '.join(activities)} this {period_label}.")
+
+    # Test activity
+    if len(metrics.tests_affected):
+        bullets.append(
+            f"Affected {len(metrics.tests_affected)} test file{'s' if len(metrics.tests_affected) != 1 else ''}."
+        )
+
+    # Token summary
+    net_tokens = metrics.tokens_earned - metrics.tokens_spent
+    if metrics.tokens_earned or metrics.tokens_spent:
+        if net_tokens > 0:
+            bullets.append(
+                f"Net earned {net_tokens} tokens ({metrics.tokens_earned} earned, {metrics.tokens_spent} spent)."
+            )
+        elif net_tokens < 0:
+            bullets.append(
+                f"Net spent {abs(net_tokens)} tokens ({metrics.tokens_earned} earned, {metrics.tokens_spent} spent)."
+            )
+        else:
+            bullets.append(
+                f"Balanced token flow ({metrics.tokens_earned} earned, {metrics.tokens_spent} spent)."
+            )
+
+    # Handle empty case
+    if not bullets:
+        bullets.append(f"No recorded activity this {period_label}.")
+
+    return bullets
+
+
+def _detect_patterns(metrics: AgentMetrics) -> list[str]:
+    """Detect interesting patterns in agent behavior.
+
+    Args:
+        metrics: The agent's metrics
+
+    Returns:
+        List of pattern descriptions
+    """
+    patterns: list[str] = []
+
+    pr_opened = len(metrics.prs_opened)
+    merge_rate = metrics.pr_merge_rate
+
+    # Merge rate patterns
+    if pr_opened >= 3:
+        if merge_rate >= 0.8:
+            patterns.append("High merge rate with few failures — code quality focus.")
+        elif merge_rate <= 0.3:
+            patterns.append("Lots of noisy PRs, low merge rate — may need review support.")
+
+    # Activity patterns
+    if metrics.commits > 10 and pr_opened == 0:
+        patterns.append("High commit volume without PRs — working directly on main?")
+
+    if len(metrics.issues_touched) > 5 and metrics.comments == 0:
+        patterns.append("Touching many issues but low comment volume — silent worker.")
+
+    if metrics.comments > len(metrics.issues_touched) * 2:
+        patterns.append("Highly communicative — lots of discussion relative to work items.")
+
+    # Token patterns
+    net_tokens = metrics.tokens_earned - metrics.tokens_spent
+    if net_tokens > 100:
+        patterns.append("Strong token accumulation — high value delivery.")
+    elif net_tokens < -50:
+        patterns.append("High token spend — may be in experimentation phase.")
+
+    return patterns
+
+
+def generate_scorecard(
+    agent_id: str,
+    period_type: PeriodType = PeriodType.daily,
+    reference_date: datetime | None = None,
+) -> ScorecardSummary | None:
+    """Generate a scorecard for a single agent.
+
+    Args:
+        agent_id: The agent to generate scorecard for
+        period_type: daily or weekly
+        reference_date: The date to calculate from (defaults to now)
+
+    Returns:
+        ScorecardSummary or None if agent has no activity
+    """
+    start, end = _get_period_bounds(period_type, reference_date)
+
+    # Collect events
+    events = _collect_events_for_period(start, end, agent_id)
+
+    # Aggregate metrics
+    all_metrics = _aggregate_metrics(events)
+
+    # Get metrics for this specific agent
+    if agent_id not in all_metrics:
+        # Create empty metrics - still generate a scorecard
+        metrics = AgentMetrics(agent_id=agent_id)
+    else:
+        metrics = all_metrics[agent_id]
+
+    # Augment with token data from ledger
+    tokens_earned, tokens_spent = _query_token_transactions(agent_id, start, end)
+    metrics.tokens_earned = max(metrics.tokens_earned, tokens_earned)
+    metrics.tokens_spent = max(metrics.tokens_spent, tokens_spent)
+
+    # Generate narrative and patterns
+    narrative = _generate_narrative_bullets(metrics, period_type)
+    patterns = _detect_patterns(metrics)
+
+    return ScorecardSummary(
+        agent_id=agent_id,
+        period_type=period_type,
+        period_start=start,
+        period_end=end,
+        metrics=metrics,
+        narrative_bullets=narrative,
+        patterns=patterns,
+    )
+
+
+def generate_all_scorecards(
+    period_type: PeriodType = PeriodType.daily,
+    reference_date: datetime | None = None,
+) -> list[ScorecardSummary]:
+    """Generate scorecards for all tracked agents.
+
+    Args:
+        period_type: daily or weekly
+        reference_date: The date to calculate from (defaults to now)
+
+    Returns:
+        List of ScorecardSummary for all agents with activity
+    """
+    start, end = _get_period_bounds(period_type, reference_date)
+
+    # Collect all events
+    events = _collect_events_for_period(start, end)
+
+    # Aggregate metrics for all agents
+    all_metrics = _aggregate_metrics(events)
+
+    # Include tracked agents even if no activity
+    for agent_id in TRACKED_AGENTS:
+        if agent_id not in all_metrics:
+            all_metrics[agent_id] = AgentMetrics(agent_id=agent_id)
+
+    # Generate scorecards
+    scorecards: list[ScorecardSummary] = []
+
+    for agent_id, metrics in all_metrics.items():
+        # Augment with token data
+        tokens_earned, tokens_spent = _query_token_transactions(agent_id, start, end)
+        metrics.tokens_earned = max(metrics.tokens_earned, tokens_earned)
+        metrics.tokens_spent = max(metrics.tokens_spent, tokens_spent)
+
+        narrative = _generate_narrative_bullets(metrics, period_type)
+        patterns = _detect_patterns(metrics)
+
+        scorecard = ScorecardSummary(
+            agent_id=agent_id,
+            period_type=period_type,
+            period_start=start,
+            period_end=end,
+            metrics=metrics,
+            narrative_bullets=narrative,
+            patterns=patterns,
+        )
+        scorecards.append(scorecard)
+
+    # Sort by agent_id for consistent ordering
+    scorecards.sort(key=lambda s: s.agent_id)
+
+    return scorecards
+
+
+def get_tracked_agents() -> list[str]:
+    """Return the list of tracked agent IDs."""
+    return sorted(TRACKED_AGENTS)

src/dashboard/templates/base.html

@@ -51,6 +51,7 @@
           <a href="/thinking" class="mc-test-link mc-link-thinking">THINKING</a>
           <a href="/swarm/mission-control" class="mc-test-link">MISSION CTRL</a>
           <a href="/swarm/live" class="mc-test-link">SWARM</a>
+          <a href="/scorecards" class="mc-test-link">SCORECARDS</a>
           <a href="/bugs" class="mc-test-link mc-link-bugs">BUGS</a>
         </div>
       </div>
@@ -123,6 +124,7 @@
     <a href="/thinking" class="mc-mobile-link">THINKING</a>
     <a href="/swarm/mission-control" class="mc-mobile-link">MISSION CONTROL</a>
     <a href="/swarm/live" class="mc-mobile-link">SWARM</a>
+    <a href="/scorecards" class="mc-mobile-link">SCORECARDS</a>
     <a href="/bugs" class="mc-mobile-link">BUGS</a>
     <div class="mc-mobile-section-label">INTELLIGENCE</div>
     <a href="/spark/ui" class="mc-mobile-link">SPARK</a>

src/dashboard/templates/index.html

@@ -21,6 +21,11 @@
         </div>
       {% endcall %}
 
+      <!-- Daily Run Metrics (HTMX polled) -->
+      {% call panel("DAILY RUN", hx_get="/daily-run/panel", hx_trigger="every 60s") %}
+        <div class="mc-loading-placeholder">LOADING...</div>
+      {% endcall %}
+
     </div>
 
     <!-- Main panel — swappable via HTMX; defaults to Timmy on load -->

src/dashboard/templates/partials/daily_run_panel.html

@@ -0,0 +1,54 @@
+<div class="card-header mc-panel-header">// DAILY RUN METRICS</div>
+<div class="card-body p-3">
+  {% if not gitea_available %}
+  <div class="mc-muted" style="font-size: 0.85rem; padding: 8px 0;">
+    <span style="color: var(--amber);">⚠</span> Gitea API unavailable
+  </div>
+  {% else %}
+  {% set m = metrics %}
+
+  <!-- Sessions summary -->
+  <div class="dr-section" style="margin-bottom: 16px;">
+    <div class="dr-row" style="display: flex; justify-content: space-between; align-items: center; margin-bottom: 8px;">
+      <span class="dr-label" style="font-size: 0.85rem; color: var(--text-dim);">Sessions ({{ m.lookback_days }}d)</span>
+      <a href="{{ logbook_url }}" target="_blank" class="dr-link" style="font-size: 0.75rem; color: var(--green); text-decoration: none;">
+        Logbook →
+      </a>
+    </div>
+    <div class="dr-stat" style="display: flex; align-items: baseline; gap: 8px;">
+      <span class="dr-value" style="font-size: 1.5rem; font-weight: 600; color: var(--text-bright);">{{ m.sessions_completed }}</span>
+      <span class="dr-trend" style="font-size: 0.9rem; color: {{ m.sessions_trend_color }};">{{ m.sessions_trend }}</span>
+      <span class="dr-prev" style="font-size: 0.75rem; color: var(--text-dim);">vs {{ m.sessions_previous }} prev</span>
+    </div>
+  </div>
+
+  <!-- Layer breakdown -->
+  <div class="dr-section">
+    <div class="dr-label" style="font-size: 0.85rem; color: var(--text-dim); margin-bottom: 8px;">Issues by Layer</div>
+    <div class="dr-layers" style="display: flex; flex-direction: column; gap: 6px;">
+      {% for layer in m.layers %}
+      <div class="dr-layer-row" style="display: flex; justify-content: space-between; align-items: center;">
+        <a href="{{ layer_urls[layer.name] }}" target="_blank" class="dr-layer-name" style="font-size: 0.8rem; color: var(--text); text-decoration: none; text-transform: capitalize;">
+          {{ layer.name.replace('-', ' ') }}
+        </a>
+        <div class="dr-layer-stat" style="display: flex; align-items: center; gap: 6px;">
+          <span class="dr-layer-value" style="font-size: 0.9rem; font-weight: 500; color: var(--text-bright);">{{ layer.current_count }}</span>
+          <span class="dr-layer-trend" style="font-size: 0.75rem; color: {{ layer.trend_color }}; width: 18px; text-align: center;">{{ layer.trend }}</span>
+        </div>
+      </div>
+      {% endfor %}
+    </div>
+  </div>
+
+  <!-- Total touched -->
+  <div class="dr-section" style="margin-top: 12px; padding-top: 12px; border-top: 1px solid var(--border);">
+    <div class="dr-row" style="display: flex; justify-content: space-between; align-items: center;">
+      <span class="dr-label" style="font-size: 0.8rem; color: var(--text-dim);">Total Issues Touched</span>
+      <div class="dr-total-stat" style="display: flex; align-items: center; gap: 6px;">
+        <span class="dr-total-value" style="font-size: 1rem; font-weight: 600; color: var(--text-bright);">{{ m.total_touched_current }}</span>
+        <span class="dr-total-prev" style="font-size: 0.7rem; color: var(--text-dim);">/ {{ m.total_touched_previous }} prev</span>
+      </div>
+    </div>
+  </div>
+  {% endif %}
+</div>

src/dashboard/templates/partials/quests_panel.html

@@ -0,0 +1,80 @@
+{% from "macros.html" import panel %}
+
+<div class="quests-summary mb-4">
+    <div class="row">
+        <div class="col-md-4">
+            <div class="stat-card">
+                <div class="stat-value">{{ total_tokens }}</div>
+                <div class="stat-label">Tokens Earned</div>
+            </div>
+        </div>
+        <div class="col-md-4">
+            <div class="stat-card">
+                <div class="stat-value">{{ completed_count }}</div>
+                <div class="stat-label">Quests Completed</div>
+            </div>
+        </div>
+        <div class="col-md-4">
+            <div class="stat-card">
+                <div class="stat-value">{{ quests|selectattr('enabled', 'equalto', true)|list|length }}</div>
+                <div class="stat-label">Active Quests</div>
+            </div>
+        </div>
+    </div>
+</div>
+
+<div class="quests-list">
+    {% for quest in quests %}
+    {% if quest.enabled %}
+    <div class="quest-card quest-status-{{ quest.status }}">
+        <div class="quest-header">
+            <h5 class="quest-name">{{ quest.name }}</h5>
+            <span class="quest-reward">+{{ quest.reward_tokens }} ⚡</span>
+        </div>
+        <p class="quest-description">{{ quest.description }}</p>
+
+        <div class="quest-progress">
+            {% if quest.status == 'completed' %}
+            <div class="progress">
+                <div class="progress-bar bg-success" style="width: 100%"></div>
+            </div>
+            <span class="quest-status-badge completed">Completed</span>
+            {% elif quest.status == 'claimed' %}
+            <div class="progress">
+                <div class="progress-bar bg-success" style="width: 100%"></div>
+            </div>
+            <span class="quest-status-badge claimed">Reward Claimed</span>
+            {% elif quest.on_cooldown %}
+            <div class="progress">
+                <div class="progress-bar bg-secondary" style="width: 100%"></div>
+            </div>
+            <span class="quest-status-badge cooldown">
+                Cooldown: {{ quest.cooldown_hours_remaining }}h remaining
+            </span>
+            {% else %}
+            <div class="progress">
+                <div class="progress-bar" style="width: {{ (quest.current_value / quest.target_value * 100)|int }}%"></div>
+            </div>
+            <span class="quest-progress-text">{{ quest.current_value }} / {{ quest.target_value }}</span>
+            {% endif %}
+        </div>
+
+        <div class="quest-meta">
+            <span class="quest-type">{{ quest.type }}</span>
+            {% if quest.repeatable %}
+            <span class="quest-repeatable">↻ Repeatable</span>
+            {% endif %}
+            {% if quest.completion_count > 0 %}
+            <span class="quest-completions">Completed {{ quest.completion_count }} time{% if quest.completion_count != 1 %}s{% endif %}</span>
+            {% endif %}
+        </div>
+    </div>
+    {% endif %}
+    {% endfor %}
+</div>
+
+{% if not quests|selectattr('enabled', 'equalto', true)|list|length %}
+<div class="alert alert-info">
+    No active quests available. Check back later or contact an administrator.
+</div>
+{% endif %}

src/dashboard/templates/quests.html

@@ -0,0 +1,50 @@
+{% extends "base.html" %}
+
+{% block title %}Quests — Mission Control{% endblock %}
+
+{% block content %}
+<div class="container-fluid">
+    <div class="row">
+        <div class="col-12">
+            <h1 class="mc-title">Token Quests</h1>
+            <p class="mc-subtitle">Complete quests to earn bonus tokens</p>
+        </div>
+    </div>
+
+    <div class="row mt-4">
+        <div class="col-md-8">
+            <div id="quests-panel" hx-get="/quests/panel/{{ agent_id }}" hx-trigger="load, every 30s">
+                <div class="mc-loading">Loading quests...</div>
+            </div>
+        </div>
+
+        <div class="col-md-4">
+            <div class="card mc-panel">
+                <div class="card-header">
+                    <h5 class="mb-0">Leaderboard</h5>
+                </div>
+                <div class="card-body">
+                    <div id="leaderboard" hx-get="/quests/api/leaderboard" hx-trigger="load, every 60s">
+                        <div class="mc-loading">Loading leaderboard...</div>
+                    </div>
+                </div>
+            </div>
+
+            <div class="card mc-panel mt-4">
+                <div class="card-header">
+                    <h5 class="mb-0">About Quests</h5>
+                </div>
+                <div class="card-body">
+                    <p class="mb-2">Quests are special objectives that reward tokens upon completion.</p>
+                    <ul class="mc-list mb-0">
+                        <li>Complete Daily Run sessions</li>
+                        <li>Close flaky-test issues</li>
+                        <li>Reduce P1 issue backlog</li>
+                        <li>Improve documentation</li>
+                    </ul>
+                </div>
+            </div>
+        </div>
+    </div>
+</div>
+{% endblock %}

src/dashboard/templates/scorecards.html

@@ -0,0 +1,113 @@
+{% extends "base.html" %}
+
+{% block title %}Agent Scorecards - Timmy Time{% endblock %}
+
+{% block extra_styles %}{% endblock %}
+
+{% block content %}
+<div class="container-fluid py-4">
+  <!-- Header -->
+  <div class="d-flex justify-content-between align-items-center mb-4">
+    <div>
+      <h1 class="h3 mb-0">AGENT SCORECARDS</h1>
+      <p class="text-muted small mb-0">Track agent performance across issues, PRs, tests, and tokens</p>
+    </div>
+    <div class="d-flex gap-2">
+      <select id="period-select" class="form-select form-select-sm" style="width: auto;">
+        <option value="daily" selected>Daily</option>
+        <option value="weekly">Weekly</option>
+      </select>
+      <button class="btn btn-sm btn-primary" onclick="refreshScorecards()">
+        <span>Refresh</span>
+      </button>
+    </div>
+  </div>
+
+  <!-- Scorecards Grid -->
+  <div id="scorecards-container"
+       hx-get="/scorecards/all/panels?period=daily"
+       hx-trigger="load"
+       hx-swap="innerHTML">
+    <div class="text-center py-5">
+      <div class="spinner-border text-secondary" role="status">
+        <span class="visually-hidden">Loading...</span>
+      </div>
+      <p class="text-muted mt-2">Loading scorecards...</p>
+    </div>
+  </div>
+
+  <!-- API Reference -->
+  <div class="mt-5 pt-4 border-top">
+    <h5 class="text-muted">API Reference</h5>
+    <div class="row g-3">
+      <div class="col-md-6">
+        <div class="card mc-panel">
+          <div class="card-body">
+            <h6 class="card-title">List Tracked Agents</h6>
+            <code>GET /scorecards/api/agents</code>
+            <p class="small text-muted mt-2">Returns all tracked agent IDs</p>
+          </div>
+        </div>
+      </div>
+      <div class="col-md-6">
+        <div class="card mc-panel">
+          <div class="card-body">
+            <h6 class="card-title">Get All Scorecards</h6>
+            <code>GET /scorecards/api?period=daily|weekly</code>
+            <p class="small text-muted mt-2">Returns scorecards for all agents</p>
+          </div>
+        </div>
+      </div>
+      <div class="col-md-6">
+        <div class="card mc-panel">
+          <div class="card-body">
+            <h6 class="card-title">Get Agent Scorecard</h6>
+            <code>GET /scorecards/api/{agent_id}?period=daily|weekly</code>
+            <p class="small text-muted mt-2">Returns scorecard for a specific agent</p>
+          </div>
+        </div>
+      </div>
+      <div class="col-md-6">
+        <div class="card mc-panel">
+          <div class="card-body">
+            <h6 class="card-title">HTML Panel (HTMX)</h6>
+            <code>GET /scorecards/panel/{agent_id}?period=daily|weekly</code>
+            <p class="small text-muted mt-2">Returns HTML panel for embedding</p>
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>
+
+<script>
+// Period selector change handler
+document.getElementById('period-select').addEventListener('change', function() {
+  refreshScorecards();
+});
+
+function refreshScorecards() {
+  var period = document.getElementById('period-select').value;
+  var container = document.getElementById('scorecards-container');
+  
+  // Show loading state
+  container.innerHTML = `
+    <div class="text-center py-5">
+      <div class="spinner-border text-secondary" role="status">
+        <span class="visually-hidden">Loading...</span>
+      </div>
+      <p class="text-muted mt-2">Loading scorecards...</p>
+    </div>
+  `;
+  
+  // Trigger HTMX request
+  htmx.ajax('GET', '/scorecards/all/panels?period=' + period, {
+    target: '#scorecards-container',
+    swap: 'innerHTML'
+  });
+}
+
+// Auto-refresh every 5 minutes
+setInterval(refreshScorecards, 300000);
+</script>
+{% endblock %}

src/infrastructure/db_pool.py

@@ -0,0 +1,84 @@
+"""Thread-local SQLite connection pool.
+
+Provides a ConnectionPool class that manages SQLite connections per thread,
+with support for context managers and automatic cleanup.
+"""
+
+import sqlite3
+import threading
+from collections.abc import Generator
+from contextlib import contextmanager
+from pathlib import Path
+
+
+class ConnectionPool:
+    """Thread-local SQLite connection pool.
+
+    Each thread gets its own connection, which is reused for subsequent
+    requests from the same thread. Connections are automatically cleaned
+    up when close_connection() is called or the context manager exits.
+    """
+
+    def __init__(self, db_path: Path | str) -> None:
+        """Initialize the connection pool.
+
+        Args:
+            db_path: Path to the SQLite database file.
+        """
+        self._db_path = Path(db_path)
+        self._local = threading.local()
+
+    def _ensure_db_exists(self) -> None:
+        """Ensure the database directory exists."""
+        self._db_path.parent.mkdir(parents=True, exist_ok=True)
+
+    def get_connection(self) -> sqlite3.Connection:
+        """Get a connection for the current thread.
+
+        Creates a new connection if one doesn't exist for this thread,
+        otherwise returns the existing connection.
+
+        Returns:
+            A sqlite3 Connection object.
+        """
+        if not hasattr(self._local, "conn") or self._local.conn is None:
+            self._ensure_db_exists()
+            self._local.conn = sqlite3.connect(str(self._db_path), check_same_thread=False)
+            self._local.conn.row_factory = sqlite3.Row
+        return self._local.conn
+
+    def close_connection(self) -> None:
+        """Close the connection for the current thread.
+
+        Cleans up the thread-local storage. Safe to call even if
+        no connection exists for this thread.
+        """
+        if hasattr(self._local, "conn") and self._local.conn is not None:
+            self._local.conn.close()
+            self._local.conn = None
+
+    @contextmanager
+    def connection(self) -> Generator[sqlite3.Connection, None, None]:
+        """Context manager for getting and automatically closing a connection.
+
+        Yields:
+            A sqlite3 Connection object.
+
+        Example:
+            with pool.connection() as conn:
+                cursor = conn.execute("SELECT 1")
+                result = cursor.fetchone()
+        """
+        conn = self.get_connection()
+        try:
+            yield conn
+        finally:
+            self.close_connection()
+
+    def close_all(self) -> None:
+        """Close all connections (useful for testing).
+
+        Note: This only closes the connection for the current thread.
+        In a multi-threaded environment, each thread must close its own.
+        """
+        self.close_connection()

src/infrastructure/matrix_config.py

@@ -0,0 +1,266 @@
+"""Matrix configuration loader utility.
+
+Provides a typed dataclass for Matrix world configuration and a loader
+that fetches settings from YAML with sensible defaults.
+"""
+
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class PointLight:
+    """A single point light in the Matrix world."""
+
+    color: str = "#FFFFFF"
+    intensity: float = 1.0
+    position: dict[str, float] = field(default_factory=lambda: {"x": 0, "y": 0, "z": 0})
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "PointLight":
+        """Create a PointLight from a dictionary with defaults."""
+        return cls(
+            color=data.get("color", "#FFFFFF"),
+            intensity=data.get("intensity", 1.0),
+            position=data.get("position", {"x": 0, "y": 0, "z": 0}),
+        )
+
+
+def _default_point_lights_factory() -> list[PointLight]:
+    """Factory function for default point lights."""
+    return [
+        PointLight(
+            color="#FFAA55",  # Warm amber (Workshop)
+            intensity=1.2,
+            position={"x": 0, "y": 5, "z": 0},
+        ),
+        PointLight(
+            color="#3B82F6",  # Cool blue (Matrix)
+            intensity=0.8,
+            position={"x": -5, "y": 3, "z": -5},
+        ),
+        PointLight(
+            color="#A855F7",  # Purple accent
+            intensity=0.6,
+            position={"x": 5, "y": 3, "z": 5},
+        ),
+    ]
+
+
+@dataclass
+class LightingConfig:
+    """Lighting configuration for the Matrix world."""
+
+    ambient_color: str = "#FFAA55"  # Warm amber (Workshop warmth)
+    ambient_intensity: float = 0.5
+    point_lights: list[PointLight] = field(default_factory=_default_point_lights_factory)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> "LightingConfig":
+        """Create a LightingConfig from a dictionary with defaults."""
+        if data is None:
+            data = {}
+
+        point_lights_data = data.get("point_lights", [])
+        point_lights = (
+            [PointLight.from_dict(pl) for pl in point_lights_data]
+            if point_lights_data
+            else _default_point_lights_factory()
+        )
+
+        return cls(
+            ambient_color=data.get("ambient_color", "#FFAA55"),
+            ambient_intensity=data.get("ambient_intensity", 0.5),
+            point_lights=point_lights,
+        )
+
+
+@dataclass
+class EnvironmentConfig:
+    """Environment settings for the Matrix world."""
+
+    rain_enabled: bool = False
+    starfield_enabled: bool = True
+    fog_color: str = "#0f0f23"
+    fog_density: float = 0.02
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> "EnvironmentConfig":
+        """Create an EnvironmentConfig from a dictionary with defaults."""
+        if data is None:
+            data = {}
+        return cls(
+            rain_enabled=data.get("rain_enabled", False),
+            starfield_enabled=data.get("starfield_enabled", True),
+            fog_color=data.get("fog_color", "#0f0f23"),
+            fog_density=data.get("fog_density", 0.02),
+        )
+
+
+@dataclass
+class FeaturesConfig:
+    """Feature toggles for the Matrix world."""
+
+    chat_enabled: bool = True
+    visitor_avatars: bool = True
+    pip_familiar: bool = True
+    workshop_portal: bool = True
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> "FeaturesConfig":
+        """Create a FeaturesConfig from a dictionary with defaults."""
+        if data is None:
+            data = {}
+        return cls(
+            chat_enabled=data.get("chat_enabled", True),
+            visitor_avatars=data.get("visitor_avatars", True),
+            pip_familiar=data.get("pip_familiar", True),
+            workshop_portal=data.get("workshop_portal", True),
+        )
+
+
+@dataclass
+class AgentConfig:
+    """Configuration for a single Matrix agent."""
+
+    name: str = ""
+    role: str = ""
+    enabled: bool = True
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "AgentConfig":
+        """Create an AgentConfig from a dictionary with defaults."""
+        return cls(
+            name=data.get("name", ""),
+            role=data.get("role", ""),
+            enabled=data.get("enabled", True),
+        )
+
+
+@dataclass
+class AgentsConfig:
+    """Agent registry configuration."""
+
+    default_count: int = 5
+    max_count: int = 20
+    agents: list[AgentConfig] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> "AgentsConfig":
+        """Create an AgentsConfig from a dictionary with defaults."""
+        if data is None:
+            data = {}
+
+        agents_data = data.get("agents", [])
+        agents = [AgentConfig.from_dict(a) for a in agents_data] if agents_data else []
+
+        return cls(
+            default_count=data.get("default_count", 5),
+            max_count=data.get("max_count", 20),
+            agents=agents,
+        )
+
+
+@dataclass
+class MatrixConfig:
+    """Complete Matrix world configuration.
+
+    Combines lighting, environment, features, and agent settings
+    into a single configuration object.
+    """
+
+    lighting: LightingConfig = field(default_factory=LightingConfig)
+    environment: EnvironmentConfig = field(default_factory=EnvironmentConfig)
+    features: FeaturesConfig = field(default_factory=FeaturesConfig)
+    agents: AgentsConfig = field(default_factory=AgentsConfig)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> "MatrixConfig":
+        """Create a MatrixConfig from a dictionary with defaults for missing sections."""
+        if data is None:
+            data = {}
+        return cls(
+            lighting=LightingConfig.from_dict(data.get("lighting")),
+            environment=EnvironmentConfig.from_dict(data.get("environment")),
+            features=FeaturesConfig.from_dict(data.get("features")),
+            agents=AgentsConfig.from_dict(data.get("agents")),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert the configuration to a plain dictionary."""
+        return {
+            "lighting": {
+                "ambient_color": self.lighting.ambient_color,
+                "ambient_intensity": self.lighting.ambient_intensity,
+                "point_lights": [
+                    {
+                        "color": pl.color,
+                        "intensity": pl.intensity,
+                        "position": pl.position,
+                    }
+                    for pl in self.lighting.point_lights
+                ],
+            },
+            "environment": {
+                "rain_enabled": self.environment.rain_enabled,
+                "starfield_enabled": self.environment.starfield_enabled,
+                "fog_color": self.environment.fog_color,
+                "fog_density": self.environment.fog_density,
+            },
+            "features": {
+                "chat_enabled": self.features.chat_enabled,
+                "visitor_avatars": self.features.visitor_avatars,
+                "pip_familiar": self.features.pip_familiar,
+                "workshop_portal": self.features.workshop_portal,
+            },
+            "agents": {
+                "default_count": self.agents.default_count,
+                "max_count": self.agents.max_count,
+                "agents": [
+                    {"name": a.name, "role": a.role, "enabled": a.enabled}
+                    for a in self.agents.agents
+                ],
+            },
+        }
+
+
+def load_from_yaml(path: str | Path) -> MatrixConfig:
+    """Load Matrix configuration from a YAML file.
+
+    Missing keys are filled with sensible defaults. If the file
+    cannot be read or parsed, returns a fully default configuration.
+
+    Args:
+        path: Path to the YAML configuration file.
+
+    Returns:
+        A MatrixConfig instance with loaded or default values.
+    """
+    path = Path(path)
+
+    if not path.exists():
+        logger.warning("Matrix config file not found: %s, using defaults", path)
+        return MatrixConfig()
+
+    try:
+        with open(path, encoding="utf-8") as f:
+            raw_data = yaml.safe_load(f)
+
+        if not isinstance(raw_data, dict):
+            logger.warning("Matrix config invalid format, using defaults")
+            return MatrixConfig()
+
+        return MatrixConfig.from_dict(raw_data)
+
+    except yaml.YAMLError as exc:
+        logger.warning("Matrix config YAML parse error: %s, using defaults", exc)
+        return MatrixConfig()
+    except OSError as exc:
+        logger.warning("Matrix config read error: %s, using defaults", exc)
+        return MatrixConfig()

src/infrastructure/presence.py

@@ -0,0 +1,333 @@
+"""Presence state serializer — transforms ADR-023 presence dicts for consumers.
+
+Converts the raw presence schema (version, liveness, mood, energy, etc.)
+into the camelCase world-state payload consumed by the Workshop 3D renderer
+and WebSocket gateway.
+"""
+
+import logging
+import time
+from datetime import UTC, datetime
+
+logger = logging.getLogger(__name__)
+
+# Default Pip familiar state (used when familiar module unavailable)
+DEFAULT_PIP_STATE = {
+    "name": "Pip",
+    "mood": "sleepy",
+    "energy": 0.5,
+    "color": "0x00b450",  # emerald green
+    "trail_color": "0xdaa520",  # gold
+}
+
+
+def _get_familiar_state() -> dict:
+    """Get Pip familiar state from familiar module, with graceful fallback.
+
+    Returns a dict with name, mood, energy, color, and trail_color.
+    Falls back to default state if familiar module unavailable or raises.
+    """
+    try:
+        from timmy.familiar import pip_familiar
+
+        snapshot = pip_familiar.snapshot()
+        # Map PipSnapshot fields to the expected agent_state format
+        return {
+            "name": snapshot.name,
+            "mood": snapshot.state,
+            "energy": DEFAULT_PIP_STATE["energy"],  # Pip doesn't track energy yet
+            "color": DEFAULT_PIP_STATE["color"],
+            "trail_color": DEFAULT_PIP_STATE["trail_color"],
+        }
+    except Exception as exc:
+        logger.warning("Familiar state unavailable, using default: %s", exc)
+        return DEFAULT_PIP_STATE.copy()
+
+
+# Valid bark styles for Matrix protocol
+BARK_STYLES = {"speech", "thought", "whisper", "shout"}
+
+
+def produce_bark(agent_id: str, text: str, reply_to: str = None, style: str = "speech") -> dict:
+    """Format a chat response as a Matrix bark message.
+
+    Barks appear as floating text above agents in the Matrix 3D world with
+    typing animation. This function formats the text for the Matrix protocol.
+
+    Parameters
+    ----------
+    agent_id:
+        Unique identifier for the agent (e.g. ``"timmy"``).
+    text:
+        The chat response text to display as a bark.
+    reply_to:
+        Optional message ID or reference this bark is replying to.
+    style:
+        Visual style of the bark. One of: "speech" (default), "thought",
+        "whisper", "shout". Invalid styles fall back to "speech".
+
+    Returns
+    -------
+    dict
+        Bark message with keys ``type``, ``agent_id``, ``data`` (containing
+        ``text``, ``reply_to``, ``style``), and ``ts``.
+
+    Examples
+    --------
+    >>> produce_bark("timmy", "Hello world!")
+    {
+        "type": "bark",
+        "agent_id": "timmy",
+        "data": {"text": "Hello world!", "reply_to": None, "style": "speech"},
+        "ts": 1742529600,
+    }
+    """
+    # Validate and normalize style
+    if style not in BARK_STYLES:
+        style = "speech"
+
+    # Truncate text to 280 characters (bark, not essay)
+    truncated_text = text[:280] if text else ""
+
+    return {
+        "type": "bark",
+        "agent_id": agent_id,
+        "data": {
+            "text": truncated_text,
+            "reply_to": reply_to,
+            "style": style,
+        },
+        "ts": int(time.time()),
+    }
+
+
+def produce_thought(
+    agent_id: str, thought_text: str, thought_id: int, chain_id: str = None
+) -> dict:
+    """Format a thinking engine thought as a Matrix thought message.
+
+    Thoughts appear as subtle floating text in the 3D world, streaming from
+    Timmy's thinking engine (/thinking/api). This function wraps thoughts in
+    Matrix protocol format.
+
+    Parameters
+    ----------
+    agent_id:
+        Unique identifier for the agent (e.g. ``"timmy"``).
+    thought_text:
+        The thought text to display. Truncated to 500 characters.
+    thought_id:
+        Unique identifier for this thought (sequence number).
+    chain_id:
+        Optional chain identifier grouping related thoughts.
+
+    Returns
+    -------
+    dict
+        Thought message with keys ``type``, ``agent_id``, ``data`` (containing
+        ``text``, ``thought_id``, ``chain_id``), and ``ts``.
+
+    Examples
+    --------
+    >>> produce_thought("timmy", "Considering the options...", 42, "chain-123")
+    {
+        "type": "thought",
+        "agent_id": "timmy",
+        "data": {"text": "Considering the options...", "thought_id": 42, "chain_id": "chain-123"},
+        "ts": 1742529600,
+    }
+    """
+    # Truncate text to 500 characters (thoughts can be longer than barks)
+    truncated_text = thought_text[:500] if thought_text else ""
+
+    return {
+        "type": "thought",
+        "agent_id": agent_id,
+        "data": {
+            "text": truncated_text,
+            "thought_id": thought_id,
+            "chain_id": chain_id,
+        },
+        "ts": int(time.time()),
+    }
+
+
+def serialize_presence(presence: dict) -> dict:
+    """Transform an ADR-023 presence dict into the world-state API shape.
+
+    Parameters
+    ----------
+    presence:
+        Raw presence dict as written by
+        :func:`~timmy.workshop_state.get_state_dict` or read from
+        ``~/.timmy/presence.json``.
+
+    Returns
+    -------
+    dict
+        CamelCase world-state payload with ``timmyState``, ``familiar``,
+        ``activeThreads``, ``recentEvents``, ``concerns``, ``visitorPresent``,
+        ``updatedAt``, and ``version`` keys.
+    """
+    return {
+        "timmyState": {
+            "mood": presence.get("mood", "calm"),
+            "activity": presence.get("current_focus", "idle"),
+            "energy": presence.get("energy", 0.5),
+            "confidence": presence.get("confidence", 0.7),
+        },
+        "familiar": presence.get("familiar"),
+        "activeThreads": presence.get("active_threads", []),
+        "recentEvents": presence.get("recent_events", []),
+        "concerns": presence.get("concerns", []),
+        "visitorPresent": False,
+        "updatedAt": presence.get("liveness", datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")),
+        "version": presence.get("version", 1),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Status mapping: ADR-023 current_focus → Matrix agent status
+# ---------------------------------------------------------------------------
+_STATUS_KEYWORDS: dict[str, str] = {
+    "thinking": "thinking",
+    "speaking": "speaking",
+    "talking": "speaking",
+    "idle": "idle",
+}
+
+
+def _derive_status(current_focus: str) -> str:
+    """Map a free-text current_focus value to a Matrix status enum.
+
+    Returns one of: online, idle, thinking, speaking.
+    """
+    focus_lower = current_focus.lower()
+    for keyword, status in _STATUS_KEYWORDS.items():
+        if keyword in focus_lower:
+            return status
+    if current_focus and current_focus != "idle":
+        return "online"
+    return "idle"
+
+
+def produce_agent_state(agent_id: str, presence: dict) -> dict:
+    """Build a Matrix-compatible ``agent_state`` message from presence data.
+
+    Parameters
+    ----------
+    agent_id:
+        Unique identifier for the agent (e.g. ``"timmy"``).
+    presence:
+        Raw ADR-023 presence dict.
+
+    Returns
+    -------
+    dict
+        Message with keys ``type``, ``agent_id``, ``data``, and ``ts``.
+    """
+    return {
+        "type": "agent_state",
+        "agent_id": agent_id,
+        "data": {
+            "display_name": presence.get("display_name", agent_id.title()),
+            "role": presence.get("role", "assistant"),
+            "status": _derive_status(presence.get("current_focus", "idle")),
+            "mood": presence.get("mood", "calm"),
+            "energy": presence.get("energy", 0.5),
+            "bark": presence.get("bark", ""),
+            "familiar": _get_familiar_state(),
+        },
+        "ts": int(time.time()),
+    }
+
+
+def produce_system_status() -> dict:
+    """Generate a system_status message for the Matrix.
+
+    Returns a dict with system health metrics including agent count,
+    visitor count, uptime, thinking engine status, and memory count.
+
+    Returns
+    -------
+    dict
+        Message with keys ``type``, ``data`` (containing ``agents_online``,
+        ``visitors``, ``uptime_seconds``, ``thinking_active``, ``memory_count``),
+        and ``ts``.
+
+    Examples
+    --------
+    >>> produce_system_status()
+    {
+        "type": "system_status",
+        "data": {
+            "agents_online": 5,
+            "visitors": 2,
+            "uptime_seconds": 3600,
+            "thinking_active": True,
+            "memory_count": 150,
+        },
+        "ts": 1742529600,
+    }
+    """
+    # Count agents with status != offline
+    agents_online = 0
+    try:
+        from timmy.agents.loader import list_agents
+
+        agents = list_agents()
+        agents_online = sum(1 for a in agents if a.get("status", "") not in ("offline", ""))
+    except Exception as exc:
+        logger.debug("Failed to count agents: %s", exc)
+
+    # Count visitors from WebSocket clients
+    visitors = 0
+    try:
+        from dashboard.routes.world import _ws_clients
+
+        visitors = len(_ws_clients)
+    except Exception as exc:
+        logger.debug("Failed to count visitors: %s", exc)
+
+    # Calculate uptime
+    uptime_seconds = 0
+    try:
+        from datetime import UTC
+
+        from config import APP_START_TIME
+
+        uptime_seconds = int((datetime.now(UTC) - APP_START_TIME).total_seconds())
+    except Exception as exc:
+        logger.debug("Failed to calculate uptime: %s", exc)
+
+    # Check thinking engine status
+    thinking_active = False
+    try:
+        from config import settings
+        from timmy.thinking import thinking_engine
+
+        thinking_active = settings.thinking_enabled and thinking_engine is not None
+    except Exception as exc:
+        logger.debug("Failed to check thinking status: %s", exc)
+
+    # Count memories in vector store
+    memory_count = 0
+    try:
+        from timmy.memory_system import get_memory_stats
+
+        stats = get_memory_stats()
+        memory_count = stats.get("total_entries", 0)
+    except Exception as exc:
+        logger.debug("Failed to count memories: %s", exc)
+
+    return {
+        "type": "system_status",
+        "data": {
+            "agents_online": agents_online,
+            "visitors": visitors,
+            "uptime_seconds": uptime_seconds,
+            "thinking_active": thinking_active,
+            "memory_count": memory_count,
+        },
+        "ts": int(time.time()),
+    }

src/infrastructure/protocol.py

@@ -0,0 +1,261 @@
+"""Shared WebSocket message protocol for the Matrix frontend.
+
+Defines all WebSocket message types as an enum and typed dataclasses
+with ``to_json()`` / ``from_json()`` helpers so every producer and the
+gateway speak the same language.
+
+Message wire format
+-------------------
+.. code-block:: json
+
+   {"type": "agent_state", "agent_id": "timmy", "data": {...}, "ts": 1234567890}
+"""
+
+import json
+import logging
+import time
+from dataclasses import asdict, dataclass, field
+from enum import StrEnum
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class MessageType(StrEnum):
+    """All WebSocket message types defined by the Matrix PROTOCOL.md."""
+
+    AGENT_STATE = "agent_state"
+    VISITOR_STATE = "visitor_state"
+    BARK = "bark"
+    THOUGHT = "thought"
+    SYSTEM_STATUS = "system_status"
+    CONNECTION_ACK = "connection_ack"
+    ERROR = "error"
+    TASK_UPDATE = "task_update"
+    MEMORY_FLASH = "memory_flash"
+
+
+# ---------------------------------------------------------------------------
+# Base message
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class WSMessage:
+    """Base WebSocket message with common envelope fields."""
+
+    type: str
+    ts: float = field(default_factory=time.time)
+
+    def to_json(self) -> str:
+        """Serialise the message to a JSON string."""
+        return json.dumps(asdict(self))
+
+    @classmethod
+    def from_json(cls, raw: str) -> "WSMessage":
+        """Deserialise a JSON string into the correct message subclass.
+
+        Falls back to the base ``WSMessage`` when the ``type`` field is
+        unrecognised.
+        """
+        data = json.loads(raw)
+        msg_type = data.get("type")
+        sub = _REGISTRY.get(msg_type)
+        if sub is not None:
+            return sub.from_json(raw)
+        return cls(**data)
+
+
+# ---------------------------------------------------------------------------
+# Concrete message types
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class AgentStateMessage(WSMessage):
+    """State update for a single agent."""
+
+    type: str = field(default=MessageType.AGENT_STATE)
+    agent_id: str = ""
+    data: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_json(cls, raw: str) -> "AgentStateMessage":
+        payload = json.loads(raw)
+        return cls(
+            type=payload.get("type", MessageType.AGENT_STATE),
+            ts=payload.get("ts", time.time()),
+            agent_id=payload.get("agent_id", ""),
+            data=payload.get("data", {}),
+        )
+
+
+@dataclass
+class VisitorStateMessage(WSMessage):
+    """State update for a visitor / user session."""
+
+    type: str = field(default=MessageType.VISITOR_STATE)
+    visitor_id: str = ""
+    data: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_json(cls, raw: str) -> "VisitorStateMessage":
+        payload = json.loads(raw)
+        return cls(
+            type=payload.get("type", MessageType.VISITOR_STATE),
+            ts=payload.get("ts", time.time()),
+            visitor_id=payload.get("visitor_id", ""),
+            data=payload.get("data", {}),
+        )
+
+
+@dataclass
+class BarkMessage(WSMessage):
+    """A bark (chat-like utterance) from an agent."""
+
+    type: str = field(default=MessageType.BARK)
+    agent_id: str = ""
+    content: str = ""
+
+    @classmethod
+    def from_json(cls, raw: str) -> "BarkMessage":
+        payload = json.loads(raw)
+        return cls(
+            type=payload.get("type", MessageType.BARK),
+            ts=payload.get("ts", time.time()),
+            agent_id=payload.get("agent_id", ""),
+            content=payload.get("content", ""),
+        )
+
+
+@dataclass
+class ThoughtMessage(WSMessage):
+    """An inner thought from an agent."""
+
+    type: str = field(default=MessageType.THOUGHT)
+    agent_id: str = ""
+    content: str = ""
+
+    @classmethod
+    def from_json(cls, raw: str) -> "ThoughtMessage":
+        payload = json.loads(raw)
+        return cls(
+            type=payload.get("type", MessageType.THOUGHT),
+            ts=payload.get("ts", time.time()),
+            agent_id=payload.get("agent_id", ""),
+            content=payload.get("content", ""),
+        )
+
+
+@dataclass
+class SystemStatusMessage(WSMessage):
+    """System-wide status broadcast."""
+
+    type: str = field(default=MessageType.SYSTEM_STATUS)
+    status: str = ""
+    data: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_json(cls, raw: str) -> "SystemStatusMessage":
+        payload = json.loads(raw)
+        return cls(
+            type=payload.get("type", MessageType.SYSTEM_STATUS),
+            ts=payload.get("ts", time.time()),
+            status=payload.get("status", ""),
+            data=payload.get("data", {}),
+        )
+
+
+@dataclass
+class ConnectionAckMessage(WSMessage):
+    """Acknowledgement sent when a client connects."""
+
+    type: str = field(default=MessageType.CONNECTION_ACK)
+    client_id: str = ""
+
+    @classmethod
+    def from_json(cls, raw: str) -> "ConnectionAckMessage":
+        payload = json.loads(raw)
+        return cls(
+            type=payload.get("type", MessageType.CONNECTION_ACK),
+            ts=payload.get("ts", time.time()),
+            client_id=payload.get("client_id", ""),
+        )
+
+
+@dataclass
+class ErrorMessage(WSMessage):
+    """Error message sent to a client."""
+
+    type: str = field(default=MessageType.ERROR)
+    code: str = ""
+    message: str = ""
+
+    @classmethod
+    def from_json(cls, raw: str) -> "ErrorMessage":
+        payload = json.loads(raw)
+        return cls(
+            type=payload.get("type", MessageType.ERROR),
+            ts=payload.get("ts", time.time()),
+            code=payload.get("code", ""),
+            message=payload.get("message", ""),
+        )
+
+
+@dataclass
+class TaskUpdateMessage(WSMessage):
+    """Update about a task (created, assigned, completed, etc.)."""
+
+    type: str = field(default=MessageType.TASK_UPDATE)
+    task_id: str = ""
+    status: str = ""
+    data: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_json(cls, raw: str) -> "TaskUpdateMessage":
+        payload = json.loads(raw)
+        return cls(
+            type=payload.get("type", MessageType.TASK_UPDATE),
+            ts=payload.get("ts", time.time()),
+            task_id=payload.get("task_id", ""),
+            status=payload.get("status", ""),
+            data=payload.get("data", {}),
+        )
+
+
+@dataclass
+class MemoryFlashMessage(WSMessage):
+    """A flash of memory — a recalled or stored memory event."""
+
+    type: str = field(default=MessageType.MEMORY_FLASH)
+    agent_id: str = ""
+    memory_key: str = ""
+    content: str = ""
+
+    @classmethod
+    def from_json(cls, raw: str) -> "MemoryFlashMessage":
+        payload = json.loads(raw)
+        return cls(
+            type=payload.get("type", MessageType.MEMORY_FLASH),
+            ts=payload.get("ts", time.time()),
+            agent_id=payload.get("agent_id", ""),
+            memory_key=payload.get("memory_key", ""),
+            content=payload.get("content", ""),
+        )
+
+
+# ---------------------------------------------------------------------------
+# Registry for from_json dispatch
+# ---------------------------------------------------------------------------
+
+_REGISTRY: dict[str, type[WSMessage]] = {
+    MessageType.AGENT_STATE: AgentStateMessage,
+    MessageType.VISITOR_STATE: VisitorStateMessage,
+    MessageType.BARK: BarkMessage,
+    MessageType.THOUGHT: ThoughtMessage,
+    MessageType.SYSTEM_STATUS: SystemStatusMessage,
+    MessageType.CONNECTION_ACK: ConnectionAckMessage,
+    MessageType.ERROR: ErrorMessage,
+    MessageType.TASK_UPDATE: TaskUpdateMessage,
+    MessageType.MEMORY_FLASH: MemoryFlashMessage,
+}

src/infrastructure/visitor.py

@@ -0,0 +1,166 @@
+"""Visitor state tracking for the Matrix frontend.
+
+Tracks active visitors as they connect and move around the 3D world,
+and provides serialization for Matrix protocol broadcast messages.
+"""
+
+import time
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+
+
+@dataclass
+class VisitorState:
+    """State for a single visitor in the Matrix.
+
+    Attributes
+    ----------
+    visitor_id: Unique identifier for the visitor (client ID).
+    display_name: Human-readable name shown above the visitor.
+    position: 3D coordinates (x, y, z) in the world.
+    rotation: Rotation angle in degrees (0-360).
+    connected_at: ISO timestamp when the visitor connected.
+    """
+
+    visitor_id: str
+    display_name: str = ""
+    position: dict[str, float] = field(default_factory=lambda: {"x": 0.0, "y": 0.0, "z": 0.0})
+    rotation: float = 0.0
+    connected_at: str = field(
+        default_factory=lambda: datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+    )
+
+    def __post_init__(self):
+        """Set display_name to visitor_id if not provided; copy position dict."""
+        if not self.display_name:
+            self.display_name = self.visitor_id
+        # Copy position to avoid shared mutable state
+        self.position = dict(self.position)
+
+
+class VisitorRegistry:
+    """Registry of active visitors in the Matrix.
+
+    Thread-safe singleton pattern (Python GIL protects dict operations).
+    Used by the WebSocket layer to track and broadcast visitor positions.
+    """
+
+    _instance: "VisitorRegistry | None" = None
+
+    def __new__(cls) -> "VisitorRegistry":
+        """Singleton constructor."""
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._visitors: dict[str, VisitorState] = {}
+        return cls._instance
+
+    def add(
+        self, visitor_id: str, display_name: str = "", position: dict | None = None
+    ) -> VisitorState:
+        """Add a new visitor to the registry.
+
+        Parameters
+        ----------
+        visitor_id: Unique identifier for the visitor.
+        display_name: Optional display name (defaults to visitor_id).
+        position: Optional initial position (defaults to origin).
+
+        Returns
+        -------
+        The newly created VisitorState.
+        """
+        visitor = VisitorState(
+            visitor_id=visitor_id,
+            display_name=display_name,
+            position=position if position else {"x": 0.0, "y": 0.0, "z": 0.0},
+        )
+        self._visitors[visitor_id] = visitor
+        return visitor
+
+    def remove(self, visitor_id: str) -> bool:
+        """Remove a visitor from the registry.
+
+        Parameters
+        ----------
+        visitor_id: The visitor to remove.
+
+        Returns
+        -------
+        True if the visitor was found and removed, False otherwise.
+        """
+        if visitor_id in self._visitors:
+            del self._visitors[visitor_id]
+            return True
+        return False
+
+    def update_position(
+        self,
+        visitor_id: str,
+        position: dict[str, float],
+        rotation: float | None = None,
+    ) -> bool:
+        """Update a visitor's position and rotation.
+
+        Parameters
+        ----------
+        visitor_id: The visitor to update.
+        position: New 3D coordinates (x, y, z).
+        rotation: Optional new rotation angle.
+
+        Returns
+        -------
+        True if the visitor was found and updated, False otherwise.
+        """
+        if visitor_id not in self._visitors:
+            return False
+
+        self._visitors[visitor_id].position = position
+        if rotation is not None:
+            self._visitors[visitor_id].rotation = rotation
+        return True
+
+    def get(self, visitor_id: str) -> VisitorState | None:
+        """Get a single visitor's state.
+
+        Parameters
+        ----------
+        visitor_id: The visitor to retrieve.
+
+        Returns
+        -------
+        The VisitorState if found, None otherwise.
+        """
+        return self._visitors.get(visitor_id)
+
+    def get_all(self) -> list[dict]:
+        """Get all active visitors as Matrix protocol message dicts.
+
+        Returns
+        -------
+        List of visitor_state dicts ready for WebSocket broadcast.
+        Each dict has: type, visitor_id, data (with display_name,
+        position, rotation, connected_at), and ts.
+        """
+        now = int(time.time())
+        return [
+            {
+                "type": "visitor_state",
+                "visitor_id": v.visitor_id,
+                "data": {
+                    "display_name": v.display_name,
+                    "position": v.position,
+                    "rotation": v.rotation,
+                    "connected_at": v.connected_at,
+                },
+                "ts": now,
+            }
+            for v in self._visitors.values()
+        ]
+
+    def clear(self) -> None:
+        """Remove all visitors (useful for testing)."""
+        self._visitors.clear()
+
+    def __len__(self) -> int:
+        """Return the number of active visitors."""
+        return len(self._visitors)

src/infrastructure/world/__init__.py

@@ -0,0 +1,29 @@
+"""World interface — engine-agnostic adapter pattern for embodied agents.
+
+Provides the ``WorldInterface`` ABC and an adapter registry so Timmy can
+observe, act, and speak in any game world (Morrowind, Luanti, Godot, …)
+through a single contract.
+
+Quick start::
+
+    from infrastructure.world import get_adapter, register_adapter
+    from infrastructure.world.interface import WorldInterface
+
+    register_adapter("mock", MockWorldAdapter)
+    world = get_adapter("mock")
+    perception = world.observe()
+"""
+
+from infrastructure.world.registry import AdapterRegistry
+
+_registry = AdapterRegistry()
+
+register_adapter = _registry.register
+get_adapter = _registry.get
+list_adapters = _registry.list_adapters
+
+__all__ = [
+    "register_adapter",
+    "get_adapter",
+    "list_adapters",
+]

src/infrastructure/world/adapters/__init__.py

@@ -0,0 +1 @@
+"""Built-in world adapters."""

src/infrastructure/world/adapters/mock.py

@@ -0,0 +1,99 @@
+"""Mock world adapter — returns canned perception and logs commands.
+
+Useful for testing the heartbeat loop and WorldInterface contract
+without a running game server.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from datetime import UTC, datetime
+
+from infrastructure.world.interface import WorldInterface
+from infrastructure.world.types import (
+    ActionResult,
+    ActionStatus,
+    CommandInput,
+    PerceptionOutput,
+)
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class _ActionLog:
+    """Record of an action dispatched to the mock world."""
+
+    command: CommandInput
+    timestamp: datetime
+
+
+class MockWorldAdapter(WorldInterface):
+    """In-memory mock adapter for testing.
+
+    * ``observe()`` returns configurable canned perception.
+    * ``act()`` logs the command and returns success.
+    * ``speak()`` logs the message.
+
+    Inspect ``action_log`` and ``speech_log`` to verify behaviour in tests.
+    """
+
+    def __init__(
+        self,
+        *,
+        location: str = "Test Chamber",
+        entities: list[str] | None = None,
+        events: list[str] | None = None,
+    ) -> None:
+        self._location = location
+        self._entities = entities or ["TestNPC"]
+        self._events = events or []
+        self._connected = False
+        self.action_log: list[_ActionLog] = []
+        self.speech_log: list[dict] = []
+
+    # -- lifecycle ---------------------------------------------------------
+
+    def connect(self) -> None:
+        self._connected = True
+        logger.info("MockWorldAdapter connected")
+
+    def disconnect(self) -> None:
+        self._connected = False
+        logger.info("MockWorldAdapter disconnected")
+
+    @property
+    def is_connected(self) -> bool:
+        return self._connected
+
+    # -- core contract -----------------------------------------------------
+
+    def observe(self) -> PerceptionOutput:
+        logger.debug("MockWorldAdapter.observe()")
+        return PerceptionOutput(
+            timestamp=datetime.now(UTC),
+            location=self._location,
+            entities=list(self._entities),
+            events=list(self._events),
+            raw={"adapter": "mock"},
+        )
+
+    def act(self, command: CommandInput) -> ActionResult:
+        logger.debug("MockWorldAdapter.act(%s)", command.action)
+        self.action_log.append(_ActionLog(command=command, timestamp=datetime.now(UTC)))
+        return ActionResult(
+            status=ActionStatus.SUCCESS,
+            message=f"Mock executed: {command.action}",
+            data={"adapter": "mock"},
+        )
+
+    def speak(self, message: str, target: str | None = None) -> None:
+        logger.debug("MockWorldAdapter.speak(%r, target=%r)", message, target)
+        self.speech_log.append(
+            {
+                "message": message,
+                "target": target,
+                "timestamp": datetime.now(UTC).isoformat(),
+            }
+        )

src/infrastructure/world/adapters/tes3mp.py

@@ -0,0 +1,58 @@
+"""TES3MP world adapter — stub for Morrowind multiplayer via TES3MP.
+
+This adapter will eventually connect to a TES3MP server and translate
+the WorldInterface contract into TES3MP commands.  For now every method
+raises ``NotImplementedError`` with guidance on what needs wiring up.
+
+Once PR #864 merges, import PerceptionOutput and CommandInput directly
+from ``infrastructure.morrowind.schemas`` if their shapes differ from
+the canonical types in ``infrastructure.world.types``.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from infrastructure.world.interface import WorldInterface
+from infrastructure.world.types import ActionResult, CommandInput, PerceptionOutput
+
+logger = logging.getLogger(__name__)
+
+
+class TES3MPWorldAdapter(WorldInterface):
+    """Stub adapter for TES3MP (Morrowind multiplayer).
+
+    All core methods raise ``NotImplementedError``.
+    Implement ``connect()`` first — it should open a socket to the
+    TES3MP server and authenticate.
+    """
+
+    def __init__(self, *, host: str = "localhost", port: int = 25565) -> None:
+        self._host = host
+        self._port = port
+        self._connected = False
+
+    # -- lifecycle ---------------------------------------------------------
+
+    def connect(self) -> None:
+        raise NotImplementedError("TES3MPWorldAdapter.connect() — wire up TES3MP server socket")
+
+    def disconnect(self) -> None:
+        raise NotImplementedError("TES3MPWorldAdapter.disconnect() — close TES3MP server socket")
+
+    @property
+    def is_connected(self) -> bool:
+        return self._connected
+
+    # -- core contract (stubs) ---------------------------------------------
+
+    def observe(self) -> PerceptionOutput:
+        raise NotImplementedError("TES3MPWorldAdapter.observe() — poll TES3MP for player/NPC state")
+
+    def act(self, command: CommandInput) -> ActionResult:
+        raise NotImplementedError(
+            "TES3MPWorldAdapter.act() — translate CommandInput to TES3MP packet"
+        )
+
+    def speak(self, message: str, target: str | None = None) -> None:
+        raise NotImplementedError("TES3MPWorldAdapter.speak() — send chat message via TES3MP")

src/infrastructure/world/interface.py

@@ -0,0 +1,64 @@
+"""Abstract WorldInterface — the contract every game-world adapter must fulfil.
+
+Follows a Gymnasium-inspired pattern: observe → act → speak, with each
+method returning strongly-typed data structures.
+
+Any future engine (TES3MP, Luanti, Godot, …) plugs in by subclassing
+``WorldInterface`` and implementing the three methods.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from infrastructure.world.types import ActionResult, CommandInput, PerceptionOutput
+
+
+class WorldInterface(ABC):
+    """Engine-agnostic base class for world adapters.
+
+    Subclasses must implement:
+        - ``observe()``  — gather structured perception from the world
+        - ``act()``      — dispatch a command and return the outcome
+        - ``speak()``    — send a message to an NPC / player / broadcast
+
+    Lifecycle hooks ``connect()`` and ``disconnect()`` are optional.
+    """
+
+    # -- lifecycle (optional overrides) ------------------------------------
+
+    def connect(self) -> None:  # noqa: B027
+        """Establish connection to the game world.
+
+        Default implementation is a no-op.  Override to open sockets,
+        authenticate, etc.
+        """
+
+    def disconnect(self) -> None:  # noqa: B027
+        """Tear down the connection.
+
+        Default implementation is a no-op.
+        """
+
+    @property
+    def is_connected(self) -> bool:
+        """Return ``True`` if the adapter has an active connection.
+
+        Default returns ``True``.  Override for adapters that maintain
+        persistent connections.
+        """
+        return True
+
+    # -- core contract (must implement) ------------------------------------
+
+    @abstractmethod
+    def observe(self) -> PerceptionOutput:
+        """Return a structured snapshot of the current world state."""
+
+    @abstractmethod
+    def act(self, command: CommandInput) -> ActionResult:
+        """Execute *command* in the world and return the result."""
+
+    @abstractmethod
+    def speak(self, message: str, target: str | None = None) -> None:
+        """Send *message* in the world, optionally directed at *target*."""

src/infrastructure/world/registry.py

@@ -0,0 +1,54 @@
+"""Adapter registry — register and instantiate world adapters by name.
+
+Usage::
+
+    registry = AdapterRegistry()
+    registry.register("mock", MockWorldAdapter)
+    adapter = registry.get("mock", some_kwarg="value")
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from infrastructure.world.interface import WorldInterface
+
+logger = logging.getLogger(__name__)
+
+
+class AdapterRegistry:
+    """Name → WorldInterface class registry with instantiation."""
+
+    def __init__(self) -> None:
+        self._adapters: dict[str, type[WorldInterface]] = {}
+
+    def register(self, name: str, cls: type[WorldInterface]) -> None:
+        """Register an adapter class under *name*.
+
+        Raises ``TypeError`` if *cls* is not a ``WorldInterface`` subclass.
+        """
+        if not (isinstance(cls, type) and issubclass(cls, WorldInterface)):
+            raise TypeError(f"{cls!r} is not a WorldInterface subclass")
+        if name in self._adapters:
+            logger.warning("Overwriting adapter %r (was %r)", name, self._adapters[name])
+        self._adapters[name] = cls
+        logger.info("Registered world adapter: %s → %s", name, cls.__name__)
+
+    def get(self, name: str, **kwargs: Any) -> WorldInterface:
+        """Instantiate and return the adapter registered as *name*.
+
+        Raises ``KeyError`` if *name* is not registered.
+        """
+        cls = self._adapters[name]
+        return cls(**kwargs)
+
+    def list_adapters(self) -> list[str]:
+        """Return sorted list of registered adapter names."""
+        return sorted(self._adapters)
+
+    def __contains__(self, name: str) -> bool:
+        return name in self._adapters
+
+    def __len__(self) -> int:
+        return len(self._adapters)

src/infrastructure/world/types.py

@@ -0,0 +1,71 @@
+"""Canonical data types for world interaction.
+
+These mirror the PerceptionOutput / CommandInput types from PR #864's
+``morrowind/schemas.py``.  When that PR merges, these can be replaced
+with re-exports — but until then they serve as the stable contract for
+every WorldInterface adapter.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import StrEnum
+
+
+class ActionStatus(StrEnum):
+    """Outcome of an action dispatched to the world."""
+
+    SUCCESS = "success"
+    FAILURE = "failure"
+    PENDING = "pending"
+    NOOP = "noop"
+
+
+@dataclass
+class PerceptionOutput:
+    """Structured world state returned by ``WorldInterface.observe()``.
+
+    Attributes:
+        timestamp:  When the observation was captured.
+        location:   Free-form location descriptor (e.g. "Balmora, Fighters Guild").
+        entities:   List of nearby entity descriptions.
+        events:     Recent game events since last observation.
+        raw:        Optional raw / engine-specific payload for advanced consumers.
+    """
+
+    timestamp: datetime = field(default_factory=lambda: datetime.now(UTC))
+    location: str = ""
+    entities: list[str] = field(default_factory=list)
+    events: list[str] = field(default_factory=list)
+    raw: dict = field(default_factory=dict)
+
+
+@dataclass
+class CommandInput:
+    """Action command sent via ``WorldInterface.act()``.
+
+    Attributes:
+        action:     Verb / action name (e.g. "move", "attack", "use_item").
+        target:     Optional target identifier.
+        parameters: Arbitrary key-value payload for engine-specific params.
+    """
+
+    action: str
+    target: str | None = None
+    parameters: dict = field(default_factory=dict)
+
+
+@dataclass
+class ActionResult:
+    """Outcome returned by ``WorldInterface.act()``.
+
+    Attributes:
+        status:   Whether the action succeeded, failed, etc.
+        message:  Human-readable description of the outcome.
+        data:     Arbitrary engine-specific result payload.
+    """
+
+    status: ActionStatus = ActionStatus.SUCCESS
+    message: str = ""
+    data: dict = field(default_factory=dict)

src/loop/heartbeat.py

@@ -0,0 +1,286 @@
+"""Heartbeat v2 — WorldInterface-driven cognitive loop.
+
+Drives real observe → reason → act → reflect cycles through whatever
+``WorldInterface`` adapter is connected.  When no adapter is present,
+gracefully falls back to the existing ``run_cycle()`` behaviour.
+
+Usage::
+
+    heartbeat = Heartbeat(world=adapter, interval=30.0)
+    await heartbeat.run_once()          # single cycle
+    await heartbeat.start()             # background loop
+    heartbeat.stop()                    # graceful shutdown
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+
+from loop.phase1_gather import gather
+from loop.phase2_reason import reason
+from loop.phase3_act import act
+from loop.schema import ContextPayload
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Cycle log entry
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class CycleRecord:
+    """One observe → reason → act → reflect cycle."""
+
+    cycle_id: int
+    timestamp: str
+    observation: dict = field(default_factory=dict)
+    reasoning_summary: str = ""
+    action_taken: str = ""
+    action_status: str = ""
+    reflect_notes: str = ""
+    duration_ms: int = 0
+
+
+# ---------------------------------------------------------------------------
+# Heartbeat
+# ---------------------------------------------------------------------------
+
+
+class Heartbeat:
+    """Manages the recurring cognitive loop with optional world adapter.
+
+    Parameters
+    ----------
+    world:
+        A ``WorldInterface`` instance (or ``None`` for passive mode).
+    interval:
+        Seconds between heartbeat ticks.  30 s for embodied mode,
+        300 s (5 min) for passive thinking.
+    on_cycle:
+        Optional async callback invoked after each cycle with the
+        ``CycleRecord``.
+    """
+
+    def __init__(
+        self,
+        *,
+        world=None,  # WorldInterface | None
+        interval: float = 30.0,
+        on_cycle=None,  # Callable[[CycleRecord], Awaitable[None]] | None
+    ) -> None:
+        self._world = world
+        self._interval = interval
+        self._on_cycle = on_cycle
+        self._cycle_count: int = 0
+        self._running = False
+        self._task: asyncio.Task | None = None
+        self.history: list[CycleRecord] = []
+
+    # -- properties --------------------------------------------------------
+
+    @property
+    def world(self):
+        return self._world
+
+    @world.setter
+    def world(self, adapter) -> None:
+        self._world = adapter
+
+    @property
+    def interval(self) -> float:
+        return self._interval
+
+    @interval.setter
+    def interval(self, value: float) -> None:
+        self._interval = max(1.0, value)
+
+    @property
+    def is_running(self) -> bool:
+        return self._running
+
+    @property
+    def cycle_count(self) -> int:
+        return self._cycle_count
+
+    # -- single cycle ------------------------------------------------------
+
+    async def run_once(self) -> CycleRecord:
+        """Execute one full heartbeat cycle.
+
+        If a world adapter is present:
+            1. Observe — ``world.observe()``
+            2. Gather + Reason + Act via the three-phase loop, with the
+               observation injected into the payload
+            3. Dispatch the decided action back to ``world.act()``
+            4. Reflect — log the cycle
+
+        Without an adapter the existing loop runs on a timer-sourced
+        payload (passive thinking).
+        """
+        self._cycle_count += 1
+        start = time.monotonic()
+        record = CycleRecord(
+            cycle_id=self._cycle_count,
+            timestamp=datetime.now(UTC).isoformat(),
+        )
+
+        if self._world is not None:
+            record = await self._embodied_cycle(record)
+        else:
+            record = await self._passive_cycle(record)
+
+        record.duration_ms = int((time.monotonic() - start) * 1000)
+        self.history.append(record)
+
+        # Broadcast via WebSocket (best-effort)
+        await self._broadcast(record)
+
+        if self._on_cycle:
+            await self._on_cycle(record)
+
+        logger.info(
+            "Heartbeat cycle #%d complete (%d ms) — action=%s status=%s",
+            record.cycle_id,
+            record.duration_ms,
+            record.action_taken or "(passive)",
+            record.action_status or "n/a",
+        )
+        return record
+
+    # -- background loop ---------------------------------------------------
+
+    async def start(self) -> None:
+        """Start the recurring heartbeat loop as a background task."""
+        if self._running:
+            logger.warning("Heartbeat already running")
+            return
+        self._running = True
+        self._task = asyncio.current_task() or asyncio.ensure_future(self._loop())
+        if self._task is not asyncio.current_task():
+            return
+        await self._loop()
+
+    async def _loop(self) -> None:
+        logger.info(
+            "Heartbeat loop started (interval=%.1fs, adapter=%s)",
+            self._interval,
+            type(self._world).__name__ if self._world else "None",
+        )
+        while self._running:
+            try:
+                await self.run_once()
+            except Exception:
+                logger.exception("Heartbeat cycle failed")
+            await asyncio.sleep(self._interval)
+
+    def stop(self) -> None:
+        """Signal the heartbeat loop to stop after the current cycle."""
+        self._running = False
+        logger.info("Heartbeat stop requested")
+
+    # -- internal: embodied cycle ------------------------------------------
+
+    async def _embodied_cycle(self, record: CycleRecord) -> CycleRecord:
+        """Cycle with a live world adapter: observe → reason → act → reflect."""
+        from infrastructure.world.types import ActionStatus, CommandInput
+
+        # 1. Observe
+        perception = self._world.observe()
+        record.observation = {
+            "location": perception.location,
+            "entities": perception.entities,
+            "events": perception.events,
+        }
+
+        # 2. Feed observation into the three-phase loop
+        obs_content = (
+            f"Location: {perception.location}\n"
+            f"Entities: {', '.join(perception.entities)}\n"
+            f"Events: {', '.join(perception.events)}"
+        )
+        payload = ContextPayload(
+            source="world",
+            content=obs_content,
+            metadata={"perception": record.observation},
+        )
+
+        gathered = gather(payload)
+        reasoned = reason(gathered)
+        acted = act(reasoned)
+
+        # Extract action decision from the acted payload
+        action_name = acted.metadata.get("action", "idle")
+        action_target = acted.metadata.get("action_target")
+        action_params = acted.metadata.get("action_params", {})
+        record.reasoning_summary = acted.metadata.get("reasoning", acted.content[:200])
+
+        # 3. Dispatch action to world
+        if action_name != "idle":
+            cmd = CommandInput(
+                action=action_name,
+                target=action_target,
+                parameters=action_params,
+            )
+            result = self._world.act(cmd)
+            record.action_taken = action_name
+            record.action_status = result.status.value
+        else:
+            record.action_taken = "idle"
+            record.action_status = ActionStatus.NOOP.value
+
+        # 4. Reflect
+        record.reflect_notes = (
+            f"Observed {len(perception.entities)} entities at {perception.location}. "
+            f"Action: {record.action_taken} → {record.action_status}."
+        )
+
+        return record
+
+    # -- internal: passive cycle -------------------------------------------
+
+    async def _passive_cycle(self, record: CycleRecord) -> CycleRecord:
+        """Cycle without a world adapter — existing think_once() behaviour."""
+        payload = ContextPayload(
+            source="timer",
+            content="heartbeat",
+            metadata={"mode": "passive"},
+        )
+
+        gathered = gather(payload)
+        reasoned = reason(gathered)
+        acted = act(reasoned)
+
+        record.reasoning_summary = acted.content[:200]
+        record.action_taken = "think"
+        record.action_status = "noop"
+        record.reflect_notes = "Passive thinking cycle — no world adapter connected."
+
+        return record
+
+    # -- broadcast ---------------------------------------------------------
+
+    async def _broadcast(self, record: CycleRecord) -> None:
+        """Emit heartbeat cycle data via WebSocket (best-effort)."""
+        try:
+            from infrastructure.ws_manager.handler import ws_manager
+
+            await ws_manager.broadcast(
+                "heartbeat.cycle",
+                {
+                    "cycle_id": record.cycle_id,
+                    "timestamp": record.timestamp,
+                    "action": record.action_taken,
+                    "action_status": record.action_status,
+                    "reasoning_summary": record.reasoning_summary[:300],
+                    "observation": record.observation,
+                    "duration_ms": record.duration_ms,
+                },
+            )
+        except (ImportError, AttributeError, ConnectionError, RuntimeError) as exc:
+            logger.debug("Heartbeat broadcast skipped: %s", exc)

src/loop/phase1_gather.py

@@ -17,9 +17,9 @@ logger = logging.getLogger(__name__)
 def gather(payload: ContextPayload) -> ContextPayload:
     """Accept raw input and return structured context for reasoning.
 
-    Stub: tags the payload with phase=gather and logs transit.
-    Timmy will flesh this out with context selection, memory lookup,
-    adapter polling, and attention-residual weighting.
+    When the payload carries a ``perception`` dict in metadata (injected by
+    the heartbeat loop from a WorldInterface adapter), that observation is
+    folded into the gathered context.  Otherwise behaves as before.
     """
     logger.info(
         "Phase 1 (Gather) received: source=%s content_len=%d tokens=%d",
@@ -28,7 +28,20 @@ def gather(payload: ContextPayload) -> ContextPayload:
         payload.token_count,
     )
 
-    result = payload.with_metadata(phase="gather", gathered=True)
+    extra: dict = {"phase": "gather", "gathered": True}
+
+    # Enrich with world observation when present
+    perception = payload.metadata.get("perception")
+    if perception:
+        extra["world_observation"] = perception
+        logger.info(
+            "Phase 1 (Gather) world observation: location=%s entities=%d events=%d",
+            perception.get("location", "?"),
+            len(perception.get("entities", [])),
+            len(perception.get("events", [])),
+        )
+
+    result = payload.with_metadata(**extra)
 
     logger.info(
         "Phase 1 (Gather) produced: metadata_keys=%s",

src/timmy/backends.py

@@ -99,11 +99,11 @@ class GrokBackend:
 
     def _get_client(self):
         """Create OpenAI client configured for xAI endpoint."""
-        from config import settings
-
         import httpx
         from openai import OpenAI
 
+        from config import settings
+
         return OpenAI(
             api_key=self._api_key,
             base_url=settings.xai_base_url,
@@ -112,11 +112,11 @@ class GrokBackend:
 
     async def _get_async_client(self):
         """Create async OpenAI client configured for xAI endpoint."""
-        from config import settings
-
         import httpx
         from openai import AsyncOpenAI
 
+        from config import settings
+
         return AsyncOpenAI(
             api_key=self._api_key,
             base_url=settings.xai_base_url,
@@ -264,6 +264,7 @@ class GrokBackend:
                 },
             }
         except Exception as exc:
+            logger.exception("Grok health check failed")
             return {
                 "ok": False,
                 "error": str(exc),
@@ -430,6 +431,7 @@ class ClaudeBackend:
             )
             return {"ok": True, "error": None, "backend": "claude", "model": self._model}
         except Exception as exc:
+            logger.exception("Claude health check failed")
             return {"ok": False, "error": str(exc), "backend": "claude", "model": self._model}
 
     # ── Private helpers ───────────────────────────────────────────────────

src/timmy/cli.py

@@ -37,6 +37,39 @@ def _is_interactive() -> bool:
     return hasattr(sys.stdin, "isatty") and sys.stdin.isatty()
 
 
+def _read_message_input(message: list[str]) -> str:
+    """Join CLI args into a message, reading from stdin when requested.
+
+    Returns the final message string.  Raises ``typer.Exit(1)`` when
+    stdin is explicitly requested (``-``) but empty.
+    """
+    message_str = " ".join(message)
+
+    if message_str == "-" or not _is_interactive():
+        try:
+            stdin_content = sys.stdin.read().strip()
+        except (KeyboardInterrupt, EOFError):
+            stdin_content = ""
+        if stdin_content:
+            message_str = stdin_content
+        elif message_str == "-":
+            typer.echo("No input provided via stdin.", err=True)
+            raise typer.Exit(1)
+
+    return message_str
+
+
+def _resolve_session_id(session_id: str | None, new_session: bool) -> str:
+    """Return the effective session ID for a chat invocation."""
+    import uuid
+
+    if session_id is not None:
+        return session_id
+    if new_session:
+        return str(uuid.uuid4())
+    return _CLI_SESSION_ID
+
+
 def _prompt_interactive(req, tool_name: str, tool_args: dict) -> None:
     """Display tool details and prompt the human for approval."""
     description = format_action_description(tool_name, tool_args)
@@ -143,6 +176,35 @@ def think(
     timmy.print_response(f"Think carefully about: {topic}", stream=True, session_id=_CLI_SESSION_ID)
 
 
+def _read_message_input(message: list[str]) -> str:
+    """Join CLI arguments and read from stdin when appropriate."""
+    message_str = " ".join(message)
+
+    if message_str == "-" or not _is_interactive():
+        try:
+            stdin_content = sys.stdin.read().strip()
+        except (KeyboardInterrupt, EOFError):
+            stdin_content = ""
+        if stdin_content:
+            message_str = stdin_content
+        elif message_str == "-":
+            typer.echo("No input provided via stdin.", err=True)
+            raise typer.Exit(1)
+
+    return message_str
+
+
+def _resolve_session_id(session_id: str | None, new_session: bool) -> str:
+    """Return the effective session ID based on CLI flags."""
+    import uuid
+
+    if session_id is not None:
+        return session_id
+    if new_session:
+        return str(uuid.uuid4())
+    return _CLI_SESSION_ID
+
+
 @app.command()
 def chat(
     message: list[str] = typer.Argument(
@@ -179,38 +241,13 @@ def chat(
 
     Read from stdin by passing "-" as the message or piping input.
     """
-    import uuid
-
-    # Join multiple arguments into a single message string
-    message_str = " ".join(message)
-
-    # Handle stdin input if "-" is passed or stdin is not a tty
-    if message_str == "-" or not _is_interactive():
-        try:
-            stdin_content = sys.stdin.read().strip()
-        except (KeyboardInterrupt, EOFError):
-            stdin_content = ""
-        if stdin_content:
-            message_str = stdin_content
-        elif message_str == "-":
-            typer.echo("No input provided via stdin.", err=True)
-            raise typer.Exit(1)
-
-    if session_id is not None:
-        pass  # use the provided value
-    elif new_session:
-        session_id = str(uuid.uuid4())
-    else:
-        session_id = _CLI_SESSION_ID
+    message_str = _read_message_input(message)
+    session_id = _resolve_session_id(session_id, new_session)
     timmy = create_timmy(backend=backend, session_id=session_id)
 
-    # Use agent.run() so we can intercept paused runs for tool confirmation.
     run_output = timmy.run(message_str, stream=False, session_id=session_id)
-
-    # Handle paused runs — dangerous tools need user approval
     run_output = _handle_tool_confirmation(timmy, run_output, session_id, autonomous=autonomous)
 
-    # Print the final response
     content = run_output.content if hasattr(run_output, "content") else str(run_output)
     if content:
         from timmy.session import _clean_response
@@ -452,5 +489,43 @@ def focus(
             typer.echo("No active focus (broad mode).")
 
 
+@app.command(name="healthcheck")
+def healthcheck(
+    json_output: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
+    verbose: bool = typer.Option(
+        False, "--verbose", "-v", help="Show verbose output including issue details"
+    ),
+    quiet: bool = typer.Option(False, "--quiet", "-q", help="Only show status line (no details)"),
+):
+    """Quick health snapshot before coding.
+
+    Shows CI status, critical issues (P0/P1), test flakiness, and token economy.
+    Fast execution (< 5 seconds) for pre-work checks.
+
+    Refs: #710
+    """
+    import subprocess
+    import sys
+    from pathlib import Path
+
+    script_path = (
+        Path(__file__).resolve().parent.parent.parent
+        / "timmy_automations"
+        / "daily_run"
+        / "health_snapshot.py"
+    )
+
+    cmd = [sys.executable, str(script_path)]
+    if json_output:
+        cmd.append("--json")
+    if verbose:
+        cmd.append("--verbose")
+    if quiet:
+        cmd.append("--quiet")
+
+    result = subprocess.run(cmd)
+    raise typer.Exit(result.returncode)
+
+
 def main():
     app()

src/timmy/loop_qa.py

@@ -97,6 +97,7 @@ async def probe_tool_use() -> dict:
             "error_type": "empty_result",
         }
     except Exception as exc:
+        logger.exception("Tool use probe failed")
         return {
             "success": False,
             "capability": cap,
@@ -129,6 +130,7 @@ async def probe_multistep_planning() -> dict:
             "error_type": "verification_failed",
         }
     except Exception as exc:
+        logger.exception("Multistep planning probe failed")
         return {
             "success": False,
             "capability": cap,
@@ -151,6 +153,7 @@ async def probe_memory_write() -> dict:
             "error_type": None,
         }
     except Exception as exc:
+        logger.exception("Memory write probe failed")
         return {
             "success": False,
             "capability": cap,
@@ -179,6 +182,7 @@ async def probe_memory_read() -> dict:
             "error_type": "empty_result",
         }
     except Exception as exc:
+        logger.exception("Memory read probe failed")
         return {
             "success": False,
             "capability": cap,
@@ -214,6 +218,7 @@ async def probe_self_coding() -> dict:
             "error_type": "verification_failed",
         }
     except Exception as exc:
+        logger.exception("Self-coding probe failed")
         return {
             "success": False,
             "capability": cap,
@@ -325,6 +330,7 @@ class LoopQAOrchestrator:
             result = await probe_fn()
         except Exception as exc:
             # Probe itself crashed — record failure and report
+            logger.exception("Loop QA probe %s crashed", cap.value)
             capture_error(exc, source="loop_qa", context={"capability": cap.value})
             result = {
                 "success": False,

src/timmy/memory/unified.py

@@ -14,6 +14,8 @@ from dataclasses import dataclass, field
 from datetime import UTC, datetime
 from pathlib import Path
 
+from config import settings
+
 logger = logging.getLogger(__name__)
 
 # Paths
@@ -28,7 +30,7 @@ def get_connection() -> Generator[sqlite3.Connection, None, None]:
     with closing(sqlite3.connect(str(DB_PATH))) as conn:
         conn.row_factory = sqlite3.Row
         conn.execute("PRAGMA journal_mode=WAL")
-        conn.execute("PRAGMA busy_timeout=5000")
+        conn.execute(f"PRAGMA busy_timeout={settings.db_busy_timeout_ms}")
         _ensure_schema(conn)
         yield conn
 

src/timmy/memory_system.py

@@ -20,6 +20,7 @@ from dataclasses import dataclass, field
 from datetime import UTC, datetime, timedelta
 from pathlib import Path
 
+from config import settings
 from timmy.memory.embeddings import (
     EMBEDDING_DIM,
     EMBEDDING_MODEL,  # noqa: F401 — re-exported for backward compatibility
@@ -111,7 +112,7 @@ def get_connection() -> Generator[sqlite3.Connection, None, None]:
     with closing(sqlite3.connect(str(DB_PATH))) as conn:
         conn.row_factory = sqlite3.Row
         conn.execute("PRAGMA journal_mode=WAL")
-        conn.execute("PRAGMA busy_timeout=5000")
+        conn.execute(f"PRAGMA busy_timeout={settings.db_busy_timeout_ms}")
         _ensure_schema(conn)
         yield conn
 
@@ -949,7 +950,7 @@ class SemanticMemory:
             with closing(sqlite3.connect(str(self.db_path))) as conn:
                 conn.row_factory = sqlite3.Row
                 conn.execute("PRAGMA journal_mode=WAL")
-                conn.execute("PRAGMA busy_timeout=5000")
+                conn.execute(f"PRAGMA busy_timeout={settings.db_busy_timeout_ms}")
                 # Ensure schema exists
                 conn.execute("""
                     CREATE TABLE IF NOT EXISTS memories (

src/timmy/quest_system.py

@@ -0,0 +1,581 @@
+"""Token Quest System for agent rewards.
+
+Provides quest definitions, progress tracking, completion detection,
+and token awards for agent accomplishments.
+
+Quests are defined in config/quests.yaml and loaded at runtime.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
+from enum import StrEnum
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from config import settings
+
+logger = logging.getLogger(__name__)
+
+# Path to quest configuration
+QUEST_CONFIG_PATH = Path(settings.repo_root) / "config" / "quests.yaml"
+
+
+class QuestType(StrEnum):
+    """Types of quests supported by the system."""
+
+    ISSUE_COUNT = "issue_count"
+    ISSUE_REDUCE = "issue_reduce"
+    DOCS_UPDATE = "docs_update"
+    TEST_IMPROVE = "test_improve"
+    DAILY_RUN = "daily_run"
+    CUSTOM = "custom"
+
+
+class QuestStatus(StrEnum):
+    """Status of a quest for an agent."""
+
+    NOT_STARTED = "not_started"
+    IN_PROGRESS = "in_progress"
+    COMPLETED = "completed"
+    CLAIMED = "claimed"
+    EXPIRED = "expired"
+
+
+@dataclass
+class QuestDefinition:
+    """Definition of a quest from configuration."""
+
+    id: str
+    name: str
+    description: str
+    reward_tokens: int
+    quest_type: QuestType
+    enabled: bool
+    repeatable: bool
+    cooldown_hours: int
+    criteria: dict[str, Any]
+    notification_message: str
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> QuestDefinition:
+        """Create a QuestDefinition from a dictionary."""
+        return cls(
+            id=data["id"],
+            name=data.get("name", "Unnamed Quest"),
+            description=data.get("description", ""),
+            reward_tokens=data.get("reward_tokens", 0),
+            quest_type=QuestType(data.get("type", "custom")),
+            enabled=data.get("enabled", True),
+            repeatable=data.get("repeatable", False),
+            cooldown_hours=data.get("cooldown_hours", 0),
+            criteria=data.get("criteria", {}),
+            notification_message=data.get(
+                "notification_message", "Quest Complete! You earned {tokens} tokens."
+            ),
+        )
+
+
+@dataclass
+class QuestProgress:
+    """Progress of a quest for a specific agent."""
+
+    quest_id: str
+    agent_id: str
+    status: QuestStatus
+    current_value: int = 0
+    target_value: int = 0
+    started_at: str = ""
+    completed_at: str = ""
+    claimed_at: str = ""
+    completion_count: int = 0
+    last_completed_at: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for serialization."""
+        return {
+            "quest_id": self.quest_id,
+            "agent_id": self.agent_id,
+            "status": self.status.value,
+            "current_value": self.current_value,
+            "target_value": self.target_value,
+            "started_at": self.started_at,
+            "completed_at": self.completed_at,
+            "claimed_at": self.claimed_at,
+            "completion_count": self.completion_count,
+            "last_completed_at": self.last_completed_at,
+            "metadata": self.metadata,
+        }
+
+
+# In-memory storage for quest progress
+_quest_progress: dict[str, QuestProgress] = {}
+_quest_definitions: dict[str, QuestDefinition] = {}
+_quest_settings: dict[str, Any] = {}
+
+
+def _get_progress_key(quest_id: str, agent_id: str) -> str:
+    """Generate a unique key for quest progress."""
+    return f"{agent_id}:{quest_id}"
+
+
+def load_quest_config() -> tuple[dict[str, QuestDefinition], dict[str, Any]]:
+    """Load quest definitions from quests.yaml.
+
+    Returns:
+        Tuple of (quest definitions dict, settings dict)
+    """
+    global _quest_definitions, _quest_settings
+
+    if not QUEST_CONFIG_PATH.exists():
+        logger.warning("Quest config not found at %s", QUEST_CONFIG_PATH)
+        return {}, {}
+
+    try:
+        raw = QUEST_CONFIG_PATH.read_text()
+        config = yaml.safe_load(raw)
+
+        if not isinstance(config, dict):
+            logger.warning("Invalid quest config format")
+            return {}, {}
+
+        # Load quest definitions
+        quests_data = config.get("quests", {})
+        definitions = {}
+        for quest_id, quest_data in quests_data.items():
+            quest_data["id"] = quest_id
+            try:
+                definition = QuestDefinition.from_dict(quest_data)
+                definitions[quest_id] = definition
+            except (ValueError, KeyError) as exc:
+                logger.warning("Failed to load quest %s: %s", quest_id, exc)
+
+        # Load settings
+        _quest_settings = config.get("settings", {})
+        _quest_definitions = definitions
+
+        logger.debug("Loaded %d quest definitions", len(definitions))
+        return definitions, _quest_settings
+
+    except (OSError, yaml.YAMLError) as exc:
+        logger.warning("Failed to load quest config: %s", exc)
+        return {}, {}
+
+
+def get_quest_definitions() -> dict[str, QuestDefinition]:
+    """Get all quest definitions, loading if necessary."""
+    global _quest_definitions
+    if not _quest_definitions:
+        _quest_definitions, _ = load_quest_config()
+    return _quest_definitions
+
+
+def get_quest_definition(quest_id: str) -> QuestDefinition | None:
+    """Get a specific quest definition by ID."""
+    definitions = get_quest_definitions()
+    return definitions.get(quest_id)
+
+
+def get_active_quests() -> list[QuestDefinition]:
+    """Get all enabled quest definitions."""
+    definitions = get_quest_definitions()
+    return [q for q in definitions.values() if q.enabled]
+
+
+def get_quest_progress(quest_id: str, agent_id: str) -> QuestProgress | None:
+    """Get progress for a specific quest and agent."""
+    key = _get_progress_key(quest_id, agent_id)
+    return _quest_progress.get(key)
+
+
+def get_or_create_progress(quest_id: str, agent_id: str) -> QuestProgress:
+    """Get existing progress or create new for quest/agent."""
+    key = _get_progress_key(quest_id, agent_id)
+    if key not in _quest_progress:
+        quest = get_quest_definition(quest_id)
+        if not quest:
+            raise ValueError(f"Quest {quest_id} not found")
+
+        target = _get_target_value(quest)
+        _quest_progress[key] = QuestProgress(
+            quest_id=quest_id,
+            agent_id=agent_id,
+            status=QuestStatus.NOT_STARTED,
+            current_value=0,
+            target_value=target,
+            started_at=datetime.now(UTC).isoformat(),
+        )
+    return _quest_progress[key]
+
+
+def _get_target_value(quest: QuestDefinition) -> int:
+    """Extract target value from quest criteria."""
+    criteria = quest.criteria
+    if quest.quest_type == QuestType.ISSUE_COUNT:
+        return criteria.get("target_count", 1)
+    elif quest.quest_type == QuestType.ISSUE_REDUCE:
+        return criteria.get("target_reduction", 1)
+    elif quest.quest_type == QuestType.DAILY_RUN:
+        return criteria.get("min_sessions", 1)
+    elif quest.quest_type == QuestType.DOCS_UPDATE:
+        return criteria.get("min_files_changed", 1)
+    elif quest.quest_type == QuestType.TEST_IMPROVE:
+        return criteria.get("min_new_tests", 1)
+    return 1
+
+
+def update_quest_progress(
+    quest_id: str,
+    agent_id: str,
+    current_value: int,
+    metadata: dict[str, Any] | None = None,
+) -> QuestProgress:
+    """Update progress for a quest."""
+    progress = get_or_create_progress(quest_id, agent_id)
+    progress.current_value = current_value
+
+    if metadata:
+        progress.metadata.update(metadata)
+
+    # Check if quest is now complete
+    if progress.current_value >= progress.target_value:
+        if progress.status not in (QuestStatus.COMPLETED, QuestStatus.CLAIMED):
+            progress.status = QuestStatus.COMPLETED
+            progress.completed_at = datetime.now(UTC).isoformat()
+            logger.info("Quest %s completed for agent %s", quest_id, agent_id)
+
+    return progress
+
+
+def _is_on_cooldown(progress: QuestProgress, quest: QuestDefinition) -> bool:
+    """Check if a repeatable quest is on cooldown."""
+    if not quest.repeatable or not progress.last_completed_at:
+        return False
+
+    if quest.cooldown_hours <= 0:
+        return False
+
+    try:
+        last_completed = datetime.fromisoformat(progress.last_completed_at)
+        cooldown_end = last_completed + timedelta(hours=quest.cooldown_hours)
+        return datetime.now(UTC) < cooldown_end
+    except (ValueError, TypeError):
+        return False
+
+
+def claim_quest_reward(quest_id: str, agent_id: str) -> dict[str, Any] | None:
+    """Claim the token reward for a completed quest.
+
+    Returns:
+        Reward info dict if successful, None if not claimable
+    """
+    progress = get_quest_progress(quest_id, agent_id)
+    if not progress:
+        return None
+
+    quest = get_quest_definition(quest_id)
+    if not quest:
+        return None
+
+    # Check if quest is completed but not yet claimed
+    if progress.status != QuestStatus.COMPLETED:
+        return None
+
+    # Check cooldown for repeatable quests
+    if _is_on_cooldown(progress, quest):
+        return None
+
+    try:
+        # Award tokens via ledger
+        from lightning.ledger import create_invoice_entry, mark_settled
+
+        # Create a mock invoice for the reward
+        invoice_entry = create_invoice_entry(
+            payment_hash=f"quest_{quest_id}_{agent_id}_{int(time.time())}",
+            amount_sats=quest.reward_tokens,
+            memo=f"Quest reward: {quest.name}",
+            source="quest_reward",
+            agent_id=agent_id,
+        )
+
+        # Mark as settled immediately (quest rewards are auto-settled)
+        mark_settled(invoice_entry.payment_hash, preimage=f"quest_{quest_id}")
+
+        # Update progress
+        progress.status = QuestStatus.CLAIMED
+        progress.claimed_at = datetime.now(UTC).isoformat()
+        progress.completion_count += 1
+        progress.last_completed_at = progress.claimed_at
+
+        # Reset for repeatable quests
+        if quest.repeatable:
+            progress.status = QuestStatus.NOT_STARTED
+            progress.current_value = 0
+            progress.completed_at = ""
+            progress.claimed_at = ""
+
+        notification = quest.notification_message.format(tokens=quest.reward_tokens)
+
+        return {
+            "quest_id": quest_id,
+            "agent_id": agent_id,
+            "tokens_awarded": quest.reward_tokens,
+            "notification": notification,
+            "completion_count": progress.completion_count,
+        }
+
+    except Exception as exc:
+        logger.error("Failed to award quest reward: %s", exc)
+        return None
+
+
+def check_issue_count_quest(
+    quest: QuestDefinition,
+    agent_id: str,
+    closed_issues: list[dict],
+) -> QuestProgress | None:
+    """Check progress for issue_count type quest."""
+    criteria = quest.criteria
+    target_labels = set(criteria.get("issue_labels", []))
+    # target_count is available in criteria but not used directly here
+
+    # Count matching issues
+    matching_count = 0
+    for issue in closed_issues:
+        issue_labels = {label.get("name", "") for label in issue.get("labels", [])}
+        if target_labels.issubset(issue_labels) or (not target_labels and issue_labels):
+            matching_count += 1
+
+    progress = update_quest_progress(
+        quest.id, agent_id, matching_count, {"matching_issues": matching_count}
+    )
+
+    return progress
+
+
+def check_issue_reduce_quest(
+    quest: QuestDefinition,
+    agent_id: str,
+    previous_count: int,
+    current_count: int,
+) -> QuestProgress | None:
+    """Check progress for issue_reduce type quest."""
+    # target_reduction available in quest.criteria but we track actual reduction
+    reduction = max(0, previous_count - current_count)
+
+    progress = update_quest_progress(quest.id, agent_id, reduction, {"reduction": reduction})
+
+    return progress
+
+
+def check_daily_run_quest(
+    quest: QuestDefinition,
+    agent_id: str,
+    sessions_completed: int,
+) -> QuestProgress | None:
+    """Check progress for daily_run type quest."""
+    # min_sessions available in quest.criteria but we track actual sessions
+    progress = update_quest_progress(
+        quest.id, agent_id, sessions_completed, {"sessions": sessions_completed}
+    )
+
+    return progress
+
+
+def evaluate_quest_progress(
+    quest_id: str,
+    agent_id: str,
+    context: dict[str, Any],
+) -> QuestProgress | None:
+    """Evaluate quest progress based on quest type and context.
+
+    Args:
+        quest_id: The quest to evaluate
+        agent_id: The agent to evaluate for
+        context: Context data for evaluation (issues, metrics, etc.)
+
+    Returns:
+        Updated QuestProgress or None if evaluation failed
+    """
+    quest = get_quest_definition(quest_id)
+    if not quest or not quest.enabled:
+        return None
+
+    progress = get_quest_progress(quest_id, agent_id)
+
+    # Check cooldown for repeatable quests
+    if progress and _is_on_cooldown(progress, quest):
+        return progress
+
+    try:
+        if quest.quest_type == QuestType.ISSUE_COUNT:
+            closed_issues = context.get("closed_issues", [])
+            return check_issue_count_quest(quest, agent_id, closed_issues)
+
+        elif quest.quest_type == QuestType.ISSUE_REDUCE:
+            prev_count = context.get("previous_issue_count", 0)
+            curr_count = context.get("current_issue_count", 0)
+            return check_issue_reduce_quest(quest, agent_id, prev_count, curr_count)
+
+        elif quest.quest_type == QuestType.DAILY_RUN:
+            sessions = context.get("sessions_completed", 0)
+            return check_daily_run_quest(quest, agent_id, sessions)
+
+        elif quest.quest_type == QuestType.CUSTOM:
+            # Custom quests require manual completion
+            return progress
+
+        else:
+            logger.debug("Quest type %s not yet implemented", quest.quest_type)
+            return progress
+
+    except Exception as exc:
+        logger.warning("Quest evaluation failed for %s: %s", quest_id, exc)
+        return progress
+
+
+def auto_evaluate_all_quests(agent_id: str, context: dict[str, Any]) -> list[dict]:
+    """Evaluate all active quests for an agent and award rewards.
+
+    Returns:
+        List of reward info for newly completed quests
+    """
+    rewards = []
+    active_quests = get_active_quests()
+
+    for quest in active_quests:
+        progress = evaluate_quest_progress(quest.id, agent_id, context)
+        if progress and progress.status == QuestStatus.COMPLETED:
+            # Auto-claim the reward
+            reward = claim_quest_reward(quest.id, agent_id)
+            if reward:
+                rewards.append(reward)
+
+    return rewards
+
+
+def get_agent_quests_status(agent_id: str) -> dict[str, Any]:
+    """Get complete quest status for an agent."""
+    definitions = get_quest_definitions()
+    quests_status = []
+    total_rewards = 0
+    completed_count = 0
+
+    for quest_id, quest in definitions.items():
+        progress = get_quest_progress(quest_id, agent_id)
+        if not progress:
+            progress = get_or_create_progress(quest_id, agent_id)
+
+        is_on_cooldown = _is_on_cooldown(progress, quest) if quest.repeatable else False
+
+        quest_info = {
+            "quest_id": quest_id,
+            "name": quest.name,
+            "description": quest.description,
+            "reward_tokens": quest.reward_tokens,
+            "type": quest.quest_type.value,
+            "enabled": quest.enabled,
+            "repeatable": quest.repeatable,
+            "status": progress.status.value,
+            "current_value": progress.current_value,
+            "target_value": progress.target_value,
+            "completion_count": progress.completion_count,
+            "on_cooldown": is_on_cooldown,
+            "cooldown_hours_remaining": 0,
+        }
+
+        if is_on_cooldown and progress.last_completed_at:
+            try:
+                last = datetime.fromisoformat(progress.last_completed_at)
+                cooldown_end = last + timedelta(hours=quest.cooldown_hours)
+                hours_remaining = (cooldown_end - datetime.now(UTC)).total_seconds() / 3600
+                quest_info["cooldown_hours_remaining"] = round(max(0, hours_remaining), 1)
+            except (ValueError, TypeError):
+                pass
+
+        quests_status.append(quest_info)
+        total_rewards += progress.completion_count * quest.reward_tokens
+        completed_count += progress.completion_count
+
+    return {
+        "agent_id": agent_id,
+        "quests": quests_status,
+        "total_tokens_earned": total_rewards,
+        "total_quests_completed": completed_count,
+        "active_quests_count": len([q for q in quests_status if q["enabled"]]),
+    }
+
+
+def reset_quest_progress(quest_id: str | None = None, agent_id: str | None = None) -> int:
+    """Reset quest progress. Useful for testing.
+
+    Args:
+        quest_id: Specific quest to reset, or None for all
+        agent_id: Specific agent to reset, or None for all
+
+    Returns:
+        Number of progress entries reset
+    """
+    global _quest_progress
+    count = 0
+
+    keys_to_reset = []
+    for key, _progress in _quest_progress.items():
+        key_agent, key_quest = key.split(":", 1)
+        if (quest_id is None or key_quest == quest_id) and (
+            agent_id is None or key_agent == agent_id
+        ):
+            keys_to_reset.append(key)
+
+    for key in keys_to_reset:
+        del _quest_progress[key]
+        count += 1
+
+    return count
+
+
+def get_quest_leaderboard() -> list[dict[str, Any]]:
+    """Get a leaderboard of agents by quest completion."""
+    agent_stats: dict[str, dict[str, Any]] = {}
+
+    for _key, progress in _quest_progress.items():
+        agent_id = progress.agent_id
+        if agent_id not in agent_stats:
+            agent_stats[agent_id] = {
+                "agent_id": agent_id,
+                "total_completions": 0,
+                "total_tokens": 0,
+                "quests_completed": set(),
+            }
+
+        quest = get_quest_definition(progress.quest_id)
+        if quest:
+            agent_stats[agent_id]["total_completions"] += progress.completion_count
+            agent_stats[agent_id]["total_tokens"] += progress.completion_count * quest.reward_tokens
+            if progress.completion_count > 0:
+                agent_stats[agent_id]["quests_completed"].add(quest.id)
+
+    leaderboard = []
+    for stats in agent_stats.values():
+        leaderboard.append(
+            {
+                "agent_id": stats["agent_id"],
+                "total_completions": stats["total_completions"],
+                "total_tokens": stats["total_tokens"],
+                "unique_quests_completed": len(stats["quests_completed"]),
+            }
+        )
+
+    # Sort by total tokens (descending)
+    leaderboard.sort(key=lambda x: x["total_tokens"], reverse=True)
+    return leaderboard
+
+
+# Initialize on module load
+load_quest_config()

src/timmy/tools.py

@@ -24,6 +24,9 @@ from config import settings
 
 logger = logging.getLogger(__name__)
 
+# Max characters of user query included in Lightning invoice memo
+_INVOICE_MEMO_MAX_LEN = 50
+
 # Lazy imports to handle test mocking
 _ImportError = None
 try:
@@ -447,7 +450,6 @@ def consult_grok(query: str) -> str:
         )
     except (ImportError, AttributeError) as exc:
         logger.warning("Tool execution failed (consult_grok logging): %s", exc)
-        pass
 
     # Generate Lightning invoice for monetization (unless free mode)
     invoice_info = ""
@@ -456,12 +458,11 @@ def consult_grok(query: str) -> str:
             from lightning.factory import get_backend as get_ln_backend
 
             ln = get_ln_backend()
-            sats = min(settings.grok_max_sats_per_query, 100)
-            inv = ln.create_invoice(sats, f"Grok query: {query[:50]}")
+            sats = min(settings.grok_max_sats_per_query, settings.grok_sats_hard_cap)
+            inv = ln.create_invoice(sats, f"Grok query: {query[:_INVOICE_MEMO_MAX_LEN]}")
             invoice_info = f"\n[Lightning invoice: {sats} sats — {inv.payment_request[:40]}...]"
         except (ImportError, OSError, ValueError) as exc:
             logger.warning("Tool execution failed (Lightning invoice): %s", exc)
-            pass
 
     result = backend.run(query)
 
@@ -472,6 +473,69 @@ def consult_grok(query: str) -> str:
     return response
 
 
+def web_fetch(url: str, max_tokens: int = 4000) -> str:
+    """Fetch a web page and return its main text content.
+
+    Downloads the URL, extracts readable text using trafilatura, and
+    truncates to a token budget.  Use this to read full articles, docs,
+    or blog posts that web_search only returns snippets for.
+
+    Args:
+        url: The URL to fetch (must start with http:// or https://).
+        max_tokens: Maximum approximate token budget (default 4000).
+                    Text is truncated to max_tokens * 4 characters.
+
+    Returns:
+        Extracted text content, or an error message on failure.
+    """
+    if not url or not url.startswith(("http://", "https://")):
+        return f"Error: invalid URL — must start with http:// or https://: {url!r}"
+
+    try:
+        import requests as _requests
+    except ImportError:
+        return "Error: 'requests' package is not installed. Install with: pip install requests"
+
+    try:
+        import trafilatura
+    except ImportError:
+        return (
+            "Error: 'trafilatura' package is not installed. Install with: pip install trafilatura"
+        )
+
+    try:
+        resp = _requests.get(
+            url,
+            timeout=15,
+            headers={"User-Agent": "TimmyResearchBot/1.0"},
+        )
+        resp.raise_for_status()
+    except _requests.exceptions.Timeout:
+        return f"Error: request timed out after 15 seconds for {url}"
+    except _requests.exceptions.HTTPError as exc:
+        return f"Error: HTTP {exc.response.status_code} for {url}"
+    except _requests.exceptions.RequestException as exc:
+        return f"Error: failed to fetch {url} — {exc}"
+
+    text = trafilatura.extract(resp.text, include_tables=True, include_links=True)
+    if not text:
+        return f"Error: could not extract readable content from {url}"
+
+    char_budget = max_tokens * 4
+    if len(text) > char_budget:
+        text = text[:char_budget] + f"\n\n[…truncated to ~{max_tokens} tokens]"
+
+    return text
+
+
+def _register_web_fetch_tool(toolkit: Toolkit) -> None:
+    """Register the web_fetch tool for full-page content extraction."""
+    try:
+        toolkit.register(web_fetch, name="web_fetch")
+    except Exception as exc:
+        logger.warning("Tool execution failed (web_fetch registration): %s", exc)
+
+
 def _register_core_tools(toolkit: Toolkit, base_path: Path) -> None:
     """Register core execution and file tools."""
     # Python execution
@@ -671,6 +735,7 @@ def create_full_toolkit(base_dir: str | Path | None = None):
     base_path = Path(base_dir) if base_dir else Path(settings.repo_root)
 
     _register_core_tools(toolkit, base_path)
+    _register_web_fetch_tool(toolkit)
     _register_grok_tool(toolkit)
     _register_memory_tools(toolkit)
     _register_agentic_loop_tool(toolkit)
@@ -828,6 +893,11 @@ def _analysis_tool_catalog() -> dict:
             "description": "Evaluate mathematical expressions with exact results",
             "available_in": ["orchestrator"],
         },
+        "web_fetch": {
+            "name": "Web Fetch",
+            "description": "Fetch a web page and extract clean readable text (trafilatura)",
+            "available_in": ["orchestrator"],
+        },
     }
 
 
@@ -940,7 +1010,7 @@ def _merge_catalog(
                 "available_in": available_in,
             }
     except ImportError:
-        pass
+        logger.debug("Optional catalog %s.%s not available", module_path, attr_name)
 
 
 def get_all_available_tools() -> dict[str, dict]:

src/timmy/tools_delegation/__init__.py

@@ -139,6 +139,7 @@ def _run_kimi(cmd: list[str], workdir: str) -> dict[str, Any]:
             "error": "Kimi timed out after 300s. Task may be too broad — try breaking it into smaller pieces.",
         }
     except Exception as exc:
+        logger.exception("Failed to run Kimi subprocess")
         return {
             "success": False,
             "error": f"Failed to run Kimi: {exc}",

src/timmy/tools_intro/__init__.py

@@ -122,6 +122,7 @@ def check_ollama_health() -> dict[str, Any]:
             models = response.json().get("models", [])
             result["available_models"] = [m.get("name", "") for m in models]
     except Exception as e:
+        logger.exception("Ollama health check failed")
         result["error"] = str(e)
 
     return result
@@ -289,6 +290,7 @@ def get_live_system_status() -> dict[str, Any]:
     try:
         result["system"] = get_system_info()
     except Exception as exc:
+        logger.exception("Failed to get system info")
         result["system"] = {"error": str(exc)}
 
     # Task queue
@@ -301,6 +303,7 @@ def get_live_system_status() -> dict[str, Any]:
     try:
         result["memory"] = get_memory_status()
     except Exception as exc:
+        logger.exception("Failed to get memory status")
         result["memory"] = {"error": str(exc)}
 
     # Uptime
@@ -406,4 +409,5 @@ def run_self_tests(scope: str = "fast", _repo_root: str | None = None) -> dict[s
     except subprocess.TimeoutExpired:
         return {"success": False, "error": "Test run timed out (120s limit)"}
     except Exception as exc:
+        logger.exception("Self-test run failed")
         return {"success": False, "error": str(exc)}

src/timmyctl/__init__.py

@@ -0,0 +1,7 @@
+"""Timmy Control Panel — CLI entry point for automations.
+
+This package provides the `timmyctl` command-line interface for managing
+Timmy automations, configuration, and daily operations.
+"""
+
+__version__ = "1.0.0"

src/timmyctl/cli.py

@@ -0,0 +1,316 @@
+"""Timmy Control Panel CLI — primary control surface for automations.
+
+Usage:
+    timmyctl daily-run          # Run the Daily Run orchestration
+    timmyctl log-run            # Capture a Daily Run logbook entry
+    timmyctl inbox              # Show what's "calling Timmy"
+    timmyctl config             # Display key configuration
+"""
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+import typer
+import yaml
+from rich.console import Console
+from rich.table import Table
+
+# Initialize Rich console for nice output
+console = Console()
+
+app = typer.Typer(
+    help="Timmy Control Panel — primary control surface for automations",
+    rich_markup_mode="rich",
+)
+
+# Default config paths
+DEFAULT_CONFIG_DIR = Path("timmy_automations/config")
+AUTOMATIONS_CONFIG = DEFAULT_CONFIG_DIR / "automations.json"
+DAILY_RUN_CONFIG = DEFAULT_CONFIG_DIR / "daily_run.json"
+TRIAGE_RULES_CONFIG = DEFAULT_CONFIG_DIR / "triage_rules.yaml"
+
+
+def _load_json_config(path: Path) -> dict[str, Any]:
+    """Load a JSON config file, returning empty dict on error."""
+    try:
+        with open(path, encoding="utf-8") as f:
+            return json.load(f)
+    except (FileNotFoundError, json.JSONDecodeError) as e:
+        console.print(f"[red]Error loading {path}: {e}[/red]")
+        return {}
+
+
+def _load_yaml_config(path: Path) -> dict[str, Any]:
+    """Load a YAML config file, returning empty dict on error."""
+    try:
+        with open(path, encoding="utf-8") as f:
+            return yaml.safe_load(f) or {}
+    except (FileNotFoundError, yaml.YAMLError) as e:
+        console.print(f"[red]Error loading {path}: {e}[/red]")
+        return {}
+
+
+def _get_config_dir() -> Path:
+    """Return the config directory path."""
+    # Allow override via environment variable
+    env_dir = os.environ.get("TIMMY_CONFIG_DIR")
+    if env_dir:
+        return Path(env_dir)
+    return DEFAULT_CONFIG_DIR
+
+
+@app.command()
+def daily_run(
+    dry_run: bool = typer.Option(
+        False, "--dry-run", "-n", help="Show what would run without executing"
+    ),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show detailed output"),
+):
+    """Run the Daily Run orchestration (agenda + summary).
+
+    Executes the daily run workflow including:
+    - Loop Guard checks
+    - Cycle Retrospective
+    - Triage scoring (if scheduled)
+    - Loop introspection (if scheduled)
+    """
+    console.print("[bold green]Timmy Daily Run[/bold green]")
+    console.print()
+
+    config_path = _get_config_dir() / "daily_run.json"
+    config = _load_json_config(config_path)
+
+    if not config:
+        console.print("[yellow]No daily run configuration found.[/yellow]")
+        raise typer.Exit(1)
+
+    schedules = config.get("schedules", {})
+    triggers = config.get("triggers", {})
+
+    if verbose:
+        console.print(f"[dim]Config loaded from: {config_path}[/dim]")
+        console.print()
+
+    # Show the daily run schedule
+    table = Table(title="Daily Run Schedules")
+    table.add_column("Schedule", style="cyan")
+    table.add_column("Description", style="green")
+    table.add_column("Automations", style="yellow")
+
+    for schedule_name, schedule_data in schedules.items():
+        automations = schedule_data.get("automations", [])
+        table.add_row(
+            schedule_name,
+            schedule_data.get("description", ""),
+            ", ".join(automations) if automations else "—",
+        )
+
+    console.print(table)
+    console.print()
+
+    # Show triggers
+    trigger_table = Table(title="Triggers")
+    trigger_table.add_column("Trigger", style="cyan")
+    trigger_table.add_column("Description", style="green")
+    trigger_table.add_column("Automations", style="yellow")
+
+    for trigger_name, trigger_data in triggers.items():
+        automations = trigger_data.get("automations", [])
+        trigger_table.add_row(
+            trigger_name,
+            trigger_data.get("description", ""),
+            ", ".join(automations) if automations else "—",
+        )
+
+    console.print(trigger_table)
+    console.print()
+
+    if dry_run:
+        console.print("[yellow]Dry run mode — no actions executed.[/yellow]")
+    else:
+        console.print("[green]Executing daily run automations...[/green]")
+        # TODO: Implement actual automation execution
+        # This would call the appropriate scripts from the automations config
+        console.print("[dim]Automation execution not yet implemented.[/dim]")
+
+
+@app.command()
+def log_run(
+    message: str = typer.Argument(..., help="Logbook entry message"),
+    category: str = typer.Option(
+        "general", "--category", "-c", help="Entry category (e.g., retro, todo, note)"
+    ),
+):
+    """Capture a quick Daily Run logbook entry.
+
+    Logs a structured entry to the daily run logbook for later review.
+    Entries are timestamped and categorized automatically.
+    """
+    from datetime import datetime
+
+    timestamp = datetime.now().isoformat()
+
+    console.print("[bold green]Daily Run Log Entry[/bold green]")
+    console.print()
+    console.print(f"[dim]Timestamp:[/dim] {timestamp}")
+    console.print(f"[dim]Category:[/dim] {category}")
+    console.print(f"[dim]Message:[/dim] {message}")
+    console.print()
+
+    # TODO: Persist to actual logbook file
+    # This would append to a logbook file (e.g., .loop/logbook.jsonl)
+    console.print("[green]✓[/green] Entry logged (simulated)")
+
+
+@app.command()
+def inbox(
+    limit: int = typer.Option(10, "--limit", "-l", help="Maximum items to show"),
+    include_prs: bool = typer.Option(True, "--prs/--no-prs", help="Show open PRs"),
+    include_issues: bool = typer.Option(True, "--issues/--no-issues", help="Show relevant issues"),
+):
+    """Show what's "calling Timmy" — PRs, Daily Run items, alerts.
+
+    Displays a unified inbox of items requiring attention:
+    - Open pull requests awaiting review
+    - Daily run queue items
+    - Alerts and notifications
+    """
+    console.print("[bold green]Timmy Inbox[/bold green]")
+    console.print()
+
+    # Load automations to show what's enabled
+    config_path = _get_config_dir() / "automations.json"
+    config = _load_json_config(config_path)
+
+    automations = config.get("automations", [])
+    enabled_automations = [a for a in automations if a.get("enabled", False)]
+
+    # Show automation status
+    auto_table = Table(title="Active Automations")
+    auto_table.add_column("ID", style="cyan")
+    auto_table.add_column("Name", style="green")
+    auto_table.add_column("Category", style="yellow")
+    auto_table.add_column("Trigger", style="magenta")
+
+    for auto in enabled_automations[:limit]:
+        auto_table.add_row(
+            auto.get("id", ""),
+            auto.get("name", ""),
+            "✓" if auto.get("enabled", False) else "✗",
+            auto.get("category", ""),
+        )
+
+    console.print(auto_table)
+    console.print()
+
+    # TODO: Fetch actual PRs from Gitea API
+    if include_prs:
+        pr_table = Table(title="Open Pull Requests (placeholder)")
+        pr_table.add_column("#", style="cyan")
+        pr_table.add_column("Title", style="green")
+        pr_table.add_column("Author", style="yellow")
+        pr_table.add_column("Status", style="magenta")
+        pr_table.add_row("—", "[dim]No PRs fetched (Gitea API not configured)[/dim]", "—", "—")
+        console.print(pr_table)
+        console.print()
+
+    # TODO: Fetch relevant issues from Gitea API
+    if include_issues:
+        issue_table = Table(title="Issues Calling for Attention (placeholder)")
+        issue_table.add_column("#", style="cyan")
+        issue_table.add_column("Title", style="green")
+        issue_table.add_column("Type", style="yellow")
+        issue_table.add_column("Priority", style="magenta")
+        issue_table.add_row(
+            "—", "[dim]No issues fetched (Gitea API not configured)[/dim]", "—", "—"
+        )
+        console.print(issue_table)
+        console.print()
+
+
+@app.command()
+def config(
+    key: str | None = typer.Argument(None, help="Show specific config key (e.g., 'automations')"),
+    show_rules: bool = typer.Option(False, "--rules", "-r", help="Show triage rules overview"),
+):
+    """Display key configuration — labels, logbook issue ID, token rules overview.
+
+    Shows the current Timmy automation configuration including:
+    - Automation manifest
+    - Daily run schedules
+    - Triage scoring rules
+    """
+    console.print("[bold green]Timmy Configuration[/bold green]")
+    console.print()
+
+    config_dir = _get_config_dir()
+
+    if key == "automations" or key is None:
+        auto_config = _load_json_config(config_dir / "automations.json")
+        automations = auto_config.get("automations", [])
+
+        table = Table(title="Automations Manifest")
+        table.add_column("ID", style="cyan")
+        table.add_column("Name", style="green")
+        table.add_column("Enabled", style="yellow")
+        table.add_column("Category", style="magenta")
+
+        for auto in automations:
+            enabled = "✓" if auto.get("enabled", False) else "✗"
+            table.add_row(
+                auto.get("id", ""),
+                auto.get("name", ""),
+                enabled,
+                auto.get("category", ""),
+            )
+
+        console.print(table)
+        console.print()
+
+    if key == "daily_run" or (key is None and not show_rules):
+        daily_config = _load_json_config(config_dir / "daily_run.json")
+
+        if daily_config:
+            console.print("[bold]Daily Run Configuration:[/bold]")
+            console.print(f"[dim]Version:[/dim] {daily_config.get('version', 'unknown')}")
+            console.print(f"[dim]Description:[/dim] {daily_config.get('description', '')}")
+            console.print()
+
+    if show_rules or key == "triage_rules":
+        rules_config = _load_yaml_config(config_dir / "triage_rules.yaml")
+
+        if rules_config:
+            thresholds = rules_config.get("thresholds", {})
+            console.print("[bold]Triage Scoring Rules:[/bold]")
+            console.print(f"  Ready threshold: {thresholds.get('ready', 'N/A')}")
+            console.print(f"  Excellent threshold: {thresholds.get('excellent', 'N/A')}")
+            console.print()
+
+            scope = rules_config.get("scope", {})
+            console.print("[bold]Scope Scoring:[/bold]")
+            console.print(f"  Meta penalty: {scope.get('meta_penalty', 'N/A')}")
+            console.print()
+
+            alignment = rules_config.get("alignment", {})
+            console.print("[bold]Alignment Scoring:[/bold]")
+            console.print(f"  Bug score: {alignment.get('bug_score', 'N/A')}")
+            console.print(f"  Refactor score: {alignment.get('refactor_score', 'N/A')}")
+            console.print(f"  Feature score: {alignment.get('feature_score', 'N/A')}")
+            console.print()
+
+            quarantine = rules_config.get("quarantine", {})
+            console.print("[bold]Quarantine Rules:[/bold]")
+            console.print(f"  Failure threshold: {quarantine.get('failure_threshold', 'N/A')}")
+            console.print(f"  Lookback cycles: {quarantine.get('lookback_cycles', 'N/A')}")
+            console.print()
+
+
+def main():
+    """Entry point for the timmyctl CLI."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

static/world/index.html

@@ -13,11 +13,121 @@
             <div class="mood" id="mood-text">focused</div>
         </div>
         <div id="connection-dot"></div>
+        <button id="info-btn" class="info-button" aria-label="About The Matrix" title="About The Matrix">
+            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+                <circle cx="12" cy="12" r="10"></circle>
+                <line x1="12" y1="16" x2="12" y2="12"></line>
+                <line x1="12" y1="8" x2="12.01" y2="8"></line>
+            </svg>
+        </button>
+        <button id="submit-job-btn" class="submit-job-button" aria-label="Submit Job" title="Submit Job">
+            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+                <path d="M12 5v14M5 12h14"></path>
+            </svg>
+            <span>Job</span>
+        </button>
         <div id="speech-area">
             <div class="bubble" id="speech-bubble"></div>
         </div>
     </div>
 
+    <!-- Submit Job Modal -->
+    <div id="submit-job-modal" class="submit-job-modal">
+        <div class="submit-job-content">
+            <button id="submit-job-close" class="submit-job-close" aria-label="Close">
+                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+                    <line x1="18" y1="6" x2="6" y2="18"></line>
+                    <line x1="6" y1="6" x2="18" y2="18"></line>
+                </svg>
+            </button>
+            <h2>Submit Job</h2>
+            <p class="submit-job-subtitle">Create a task for Timmy and the agent swarm</p>
+            
+            <form id="submit-job-form" class="submit-job-form">
+                <div class="form-group">
+                    <label for="job-title">Title <span class="required">*</span></label>
+                    <input type="text" id="job-title" name="title" placeholder="Brief description of the task" maxlength="200">
+                    <div class="char-count" id="title-char-count">0 / 200</div>
+                    <div class="validation-error" id="title-error"></div>
+                </div>
+                
+                <div class="form-group">
+                    <label for="job-description">Description</label>
+                    <textarea id="job-description" name="description" placeholder="Detailed instructions, requirements, and context..." rows="6" maxlength="2000"></textarea>
+                    <div class="char-count" id="desc-char-count">0 / 2000</div>
+                    <div class="validation-warning" id="desc-warning"></div>
+                    <div class="validation-error" id="desc-error"></div>
+                </div>
+                
+                <div class="form-group">
+                    <label for="job-priority">Priority</label>
+                    <select id="job-priority" name="priority">
+                        <option value="low">Low</option>
+                        <option value="medium" selected>Medium</option>
+                        <option value="high">High</option>
+                        <option value="urgent">Urgent</option>
+                    </select>
+                </div>
+                
+                <div class="submit-job-actions">
+                    <button type="button" id="cancel-job-btn" class="btn-secondary">Cancel</button>
+                    <button type="submit" id="submit-job-submit" class="btn-primary" disabled>Submit Job</button>
+                </div>
+            </form>
+            
+            <div id="submit-job-success" class="submit-job-success hidden">
+                <div class="success-icon">
+                    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+                        <path d="M22 11.08V12a10 10 0 1 1-5.93-9.14"></path>
+                        <polyline points="22 4 12 14.01 9 11.01"></polyline>
+                    </svg>
+                </div>
+                <h3>Job Submitted!</h3>
+                <p>Your task has been added to the queue. Timmy will review it shortly.</p>
+                <button type="button" id="submit-another-btn" class="btn-primary">Submit Another</button>
+            </div>
+        </div>
+        <div id="submit-job-backdrop" class="submit-job-backdrop"></div>
+    </div>
+
+    <!-- About Panel -->
+    <div id="about-panel" class="about-panel">
+        <div class="about-panel-content">
+            <button id="about-close" class="about-close" aria-label="Close">
+                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+                    <line x1="18" y1="6" x2="6" y2="18"></line>
+                    <line x1="6" y1="6" x2="18" y2="18"></line>
+                </svg>
+            </button>
+            <h2>Welcome to The Matrix</h2>
+            
+            <section>
+                <h3>🌌 The Matrix</h3>
+                <p>The Matrix is a 3D visualization of Timmy's AI agent workspace. Enter the workshop to see Timmy at work—pondering the arcane arts of code, managing tasks, and orchestrating autonomous agents in real-time.</p>
+            </section>
+            
+            <section>
+                <h3>🛠️ The Workshop</h3>
+                <p>The Workshop is where you interact directly with Timmy:</p>
+                <ul>
+                    <li><strong>Submit Jobs</strong> — Create tasks, delegate work, and track progress</li>
+                    <li><strong>Chat with Agents</strong> — Converse with Timmy and his swarm of specialized agents</li>
+                    <li><strong>Fund Sessions</strong> — Power your work with satoshis via Lightning Network</li>
+                </ul>
+            </section>
+            
+            <section>
+                <h3>⚡ Lightning & Sats</h3>
+                <p>The Matrix runs on Bitcoin. Sessions are funded with satoshis (sats) over the Lightning Network—enabling fast, cheap micropayments that keep Timmy energized and working for you. No subscriptions, no limits—pay as you go.</p>
+            </section>
+            
+            <div class="about-footer">
+                <span>Sovereign AI · Soul on Bitcoin</span>
+            </div>
+        </div>
+        <div id="about-backdrop" class="about-backdrop"></div>
+    </div>
+
     <script type="importmap">
     {
         "imports": {
@@ -74,6 +184,271 @@
         });
         stateReader.connect();
 
+        // --- About Panel ---
+        const infoBtn = document.getElementById("info-btn");
+        const aboutPanel = document.getElementById("about-panel");
+        const aboutClose = document.getElementById("about-close");
+        const aboutBackdrop = document.getElementById("about-backdrop");
+
+        function openAboutPanel() {
+            aboutPanel.classList.add("open");
+            document.body.style.overflow = "hidden";
+        }
+
+        function closeAboutPanel() {
+            aboutPanel.classList.remove("open");
+            document.body.style.overflow = "";
+        }
+
+        infoBtn.addEventListener("click", openAboutPanel);
+        aboutClose.addEventListener("click", closeAboutPanel);
+        aboutBackdrop.addEventListener("click", closeAboutPanel);
+
+        // Close on Escape key
+        document.addEventListener("keydown", (e) => {
+            if (e.key === "Escape" && aboutPanel.classList.contains("open")) {
+                closeAboutPanel();
+            }
+        });
+
+        // --- Submit Job Modal ---
+        const submitJobBtn = document.getElementById("submit-job-btn");
+        const submitJobModal = document.getElementById("submit-job-modal");
+        const submitJobClose = document.getElementById("submit-job-close");
+        const submitJobBackdrop = document.getElementById("submit-job-backdrop");
+        const cancelJobBtn = document.getElementById("cancel-job-btn");
+        const submitJobForm = document.getElementById("submit-job-form");
+        const submitJobSubmit = document.getElementById("submit-job-submit");
+        const jobTitle = document.getElementById("job-title");
+        const jobDescription = document.getElementById("job-description");
+        const titleCharCount = document.getElementById("title-char-count");
+        const descCharCount = document.getElementById("desc-char-count");
+        const titleError = document.getElementById("title-error");
+        const descError = document.getElementById("desc-error");
+        const descWarning = document.getElementById("desc-warning");
+        const submitJobSuccess = document.getElementById("submit-job-success");
+        const submitAnotherBtn = document.getElementById("submit-another-btn");
+
+        // Constants
+        const MAX_TITLE_LENGTH = 200;
+        const MAX_DESC_LENGTH = 2000;
+        const TITLE_WARNING_THRESHOLD = 150;
+        const DESC_WARNING_THRESHOLD = 1800;
+
+        function openSubmitJobModal() {
+            submitJobModal.classList.add("open");
+            document.body.style.overflow = "hidden";
+            jobTitle.focus();
+            validateForm();
+        }
+
+        function closeSubmitJobModal() {
+            submitJobModal.classList.remove("open");
+            document.body.style.overflow = "";
+            // Reset form after animation
+            setTimeout(() => {
+                resetForm();
+            }, 300);
+        }
+
+        function resetForm() {
+            submitJobForm.reset();
+            submitJobForm.classList.remove("hidden");
+            submitJobSuccess.classList.add("hidden");
+            updateCharCounts();
+            clearErrors();
+            validateForm();
+        }
+
+        function clearErrors() {
+            titleError.textContent = "";
+            titleError.classList.remove("visible");
+            descError.textContent = "";
+            descError.classList.remove("visible");
+            descWarning.textContent = "";
+            descWarning.classList.remove("visible");
+            jobTitle.classList.remove("error");
+            jobDescription.classList.remove("error");
+        }
+
+        function updateCharCounts() {
+            const titleLen = jobTitle.value.length;
+            const descLen = jobDescription.value.length;
+            
+            titleCharCount.textContent = `${titleLen} / ${MAX_TITLE_LENGTH}`;
+            descCharCount.textContent = `${descLen} / ${MAX_DESC_LENGTH}`;
+            
+            // Update color based on thresholds
+            if (titleLen > MAX_TITLE_LENGTH) {
+                titleCharCount.classList.add("over-limit");
+            } else if (titleLen > TITLE_WARNING_THRESHOLD) {
+                titleCharCount.classList.add("near-limit");
+                titleCharCount.classList.remove("over-limit");
+            } else {
+                titleCharCount.classList.remove("near-limit", "over-limit");
+            }
+            
+            if (descLen > MAX_DESC_LENGTH) {
+                descCharCount.classList.add("over-limit");
+            } else if (descLen > DESC_WARNING_THRESHOLD) {
+                descCharCount.classList.add("near-limit");
+                descCharCount.classList.remove("over-limit");
+            } else {
+                descCharCount.classList.remove("near-limit", "over-limit");
+            }
+        }
+
+        function validateTitle() {
+            const value = jobTitle.value.trim();
+            const length = jobTitle.value.length;
+            
+            if (length > MAX_TITLE_LENGTH) {
+                titleError.textContent = `Title must be ${MAX_TITLE_LENGTH} characters or less`;
+                titleError.classList.add("visible");
+                jobTitle.classList.add("error");
+                return false;
+            }
+            
+            if (value === "") {
+                titleError.textContent = "Title is required";
+                titleError.classList.add("visible");
+                jobTitle.classList.add("error");
+                return false;
+            }
+            
+            titleError.textContent = "";
+            titleError.classList.remove("visible");
+            jobTitle.classList.remove("error");
+            return true;
+        }
+
+        function validateDescription() {
+            const length = jobDescription.value.length;
+            
+            if (length > MAX_DESC_LENGTH) {
+                descError.textContent = `Description must be ${MAX_DESC_LENGTH} characters or less`;
+                descError.classList.add("visible");
+                descWarning.textContent = "";
+                descWarning.classList.remove("visible");
+                jobDescription.classList.add("error");
+                return false;
+            }
+            
+            // Show warning when near limit
+            if (length > DESC_WARNING_THRESHOLD && length <= MAX_DESC_LENGTH) {
+                const remaining = MAX_DESC_LENGTH - length;
+                descWarning.textContent = `${remaining} characters remaining`;
+                descWarning.classList.add("visible");
+            } else {
+                descWarning.textContent = "";
+                descWarning.classList.remove("visible");
+            }
+            
+            descError.textContent = "";
+            descError.classList.remove("visible");
+            jobDescription.classList.remove("error");
+            return true;
+        }
+
+        function validateForm() {
+            const titleValid = jobTitle.value.trim() !== "" && jobTitle.value.length <= MAX_TITLE_LENGTH;
+            const descValid = jobDescription.value.length <= MAX_DESC_LENGTH;
+            
+            submitJobSubmit.disabled = !(titleValid && descValid);
+        }
+
+        // Event listeners
+        submitJobBtn.addEventListener("click", openSubmitJobModal);
+        submitJobClose.addEventListener("click", closeSubmitJobModal);
+        submitJobBackdrop.addEventListener("click", closeSubmitJobModal);
+        cancelJobBtn.addEventListener("click", closeSubmitJobModal);
+        submitAnotherBtn.addEventListener("click", resetForm);
+
+        // Input event listeners for real-time validation
+        jobTitle.addEventListener("input", () => {
+            updateCharCounts();
+            validateForm();
+            if (titleError.classList.contains("visible")) {
+                validateTitle();
+            }
+        });
+
+        jobTitle.addEventListener("blur", () => {
+            if (jobTitle.value.trim() !== "" || titleError.classList.contains("visible")) {
+                validateTitle();
+            }
+        });
+
+        jobDescription.addEventListener("input", () => {
+            updateCharCounts();
+            validateForm();
+            if (descError.classList.contains("visible")) {
+                validateDescription();
+            }
+        });
+
+        jobDescription.addEventListener("blur", () => {
+            validateDescription();
+        });
+
+        // Form submission
+        submitJobForm.addEventListener("submit", async (e) => {
+            e.preventDefault();
+            
+            const isTitleValid = validateTitle();
+            const isDescValid = validateDescription();
+            
+            if (!isTitleValid || !isDescValid) {
+                return;
+            }
+            
+            // Disable submit button while processing
+            submitJobSubmit.disabled = true;
+            submitJobSubmit.textContent = "Submitting...";
+            
+            const formData = {
+                title: jobTitle.value.trim(),
+                description: jobDescription.value.trim(),
+                priority: document.getElementById("job-priority").value,
+                submitted_at: new Date().toISOString()
+            };
+            
+            try {
+                // Submit to API
+                const response = await fetch("/api/tasks", {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                    },
+                    body: JSON.stringify(formData)
+                });
+                
+                if (response.ok) {
+                    // Show success state
+                    submitJobForm.classList.add("hidden");
+                    submitJobSuccess.classList.remove("hidden");
+                } else {
+                    const errorData = await response.json().catch(() => ({}));
+                    descError.textContent = errorData.detail || "Failed to submit job. Please try again.";
+                    descError.classList.add("visible");
+                }
+            } catch (error) {
+                // For demo/development, show success even if API fails
+                submitJobForm.classList.add("hidden");
+                submitJobSuccess.classList.remove("hidden");
+            } finally {
+                submitJobSubmit.disabled = false;
+                submitJobSubmit.textContent = "Submit Job";
+            }
+        });
+
+        // Close on Escape key for Submit Job Modal
+        document.addEventListener("keydown", (e) => {
+            if (e.key === "Escape" && submitJobModal.classList.contains("open")) {
+                closeSubmitJobModal();
+            }
+        });
+
         // --- Resize ---
         window.addEventListener("resize", () => {
             camera.aspect = window.innerWidth / window.innerHeight;

static/world/style.css

@@ -87,3 +87,569 @@ canvas {
 #connection-dot.connected {
     background: #00b450;
 }
+
+/* Info button */
+.info-button {
+    position: absolute;
+    top: 14px;
+    right: 36px;
+    width: 28px;
+    height: 28px;
+    padding: 0;
+    background: rgba(10, 10, 20, 0.7);
+    border: 1px solid rgba(218, 165, 32, 0.4);
+    border-radius: 50%;
+    color: #daa520;
+    cursor: pointer;
+    pointer-events: auto;
+    transition: all 0.2s ease;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+}
+
+.info-button:hover {
+    background: rgba(218, 165, 32, 0.15);
+    border-color: rgba(218, 165, 32, 0.7);
+    transform: scale(1.05);
+}
+
+.info-button svg {
+    width: 16px;
+    height: 16px;
+}
+
+/* About Panel */
+.about-panel {
+    position: fixed;
+    top: 0;
+    right: 0;
+    width: 100%;
+    height: 100%;
+    z-index: 100;
+    pointer-events: none;
+    visibility: hidden;
+    opacity: 0;
+    transition: opacity 0.3s ease, visibility 0.3s ease;
+}
+
+.about-panel.open {
+    pointer-events: auto;
+    visibility: visible;
+    opacity: 1;
+}
+
+.about-panel-content {
+    position: absolute;
+    top: 0;
+    right: 0;
+    width: 380px;
+    max-width: 90%;
+    height: 100%;
+    background: rgba(10, 10, 20, 0.97);
+    border-left: 1px solid rgba(218, 165, 32, 0.3);
+    padding: 60px 24px 24px 24px;
+    overflow-y: auto;
+    transform: translateX(100%);
+    transition: transform 0.3s ease;
+    box-shadow: -4px 0 20px rgba(0, 0, 0, 0.5);
+}
+
+.about-panel.open .about-panel-content {
+    transform: translateX(0);
+}
+
+.about-close {
+    position: absolute;
+    top: 16px;
+    right: 16px;
+    width: 32px;
+    height: 32px;
+    padding: 0;
+    background: transparent;
+    border: 1px solid rgba(160, 160, 160, 0.3);
+    border-radius: 50%;
+    color: #aaa;
+    cursor: pointer;
+    transition: all 0.2s ease;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+}
+
+.about-close:hover {
+    background: rgba(255, 255, 255, 0.1);
+    border-color: rgba(218, 165, 32, 0.5);
+    color: #daa520;
+}
+
+.about-close svg {
+    width: 18px;
+    height: 18px;
+}
+
+.about-panel-content h2 {
+    font-size: 20px;
+    color: #daa520;
+    margin-bottom: 24px;
+    font-weight: 600;
+}
+
+.about-panel-content section {
+    margin-bottom: 24px;
+}
+
+.about-panel-content h3 {
+    font-size: 14px;
+    color: #e0e0e0;
+    margin-bottom: 10px;
+    font-weight: 600;
+}
+
+.about-panel-content p {
+    font-size: 13px;
+    line-height: 1.6;
+    color: #aaa;
+    margin-bottom: 10px;
+}
+
+.about-panel-content ul {
+    list-style: none;
+    padding: 0;
+    margin: 0;
+}
+
+.about-panel-content li {
+    font-size: 13px;
+    line-height: 1.6;
+    color: #aaa;
+    margin-bottom: 8px;
+    padding-left: 16px;
+    position: relative;
+}
+
+.about-panel-content li::before {
+    content: "•";
+    position: absolute;
+    left: 0;
+    color: #daa520;
+}
+
+.about-panel-content li strong {
+    color: #ccc;
+}
+
+.about-footer {
+    margin-top: 32px;
+    padding-top: 16px;
+    border-top: 1px solid rgba(160, 160, 160, 0.2);
+    font-size: 12px;
+    color: #666;
+    text-align: center;
+}
+
+.about-backdrop {
+    position: absolute;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+    background: rgba(0, 0, 0, 0.5);
+    opacity: 0;
+    transition: opacity 0.3s ease;
+}
+
+.about-panel.open .about-backdrop {
+    opacity: 1;
+}
+
+/* Submit Job Button */
+.submit-job-button {
+    position: absolute;
+    top: 14px;
+    right: 72px;
+    height: 28px;
+    padding: 0 12px;
+    background: rgba(10, 10, 20, 0.7);
+    border: 1px solid rgba(0, 180, 80, 0.4);
+    border-radius: 14px;
+    color: #00b450;
+    cursor: pointer;
+    pointer-events: auto;
+    transition: all 0.2s ease;
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    font-family: "Courier New", monospace;
+    font-size: 12px;
+}
+
+.submit-job-button:hover {
+    background: rgba(0, 180, 80, 0.15);
+    border-color: rgba(0, 180, 80, 0.7);
+    transform: scale(1.05);
+}
+
+.submit-job-button svg {
+    width: 14px;
+    height: 14px;
+}
+
+/* Submit Job Modal */
+.submit-job-modal {
+    position: fixed;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+    z-index: 100;
+    pointer-events: none;
+    visibility: hidden;
+    opacity: 0;
+    transition: opacity 0.3s ease, visibility 0.3s ease;
+}
+
+.submit-job-modal.open {
+    pointer-events: auto;
+    visibility: visible;
+    opacity: 1;
+}
+
+.submit-job-content {
+    position: absolute;
+    top: 50%;
+    left: 50%;
+    transform: translate(-50%, -50%) scale(0.95);
+    width: 480px;
+    max-width: 90%;
+    max-height: 90vh;
+    background: rgba(10, 10, 20, 0.98);
+    border: 1px solid rgba(218, 165, 32, 0.3);
+    border-radius: 12px;
+    padding: 32px;
+    overflow-y: auto;
+    transition: transform 0.3s ease;
+    box-shadow: 0 8px 32px rgba(0, 0, 0, 0.6);
+}
+
+.submit-job-modal.open .submit-job-content {
+    transform: translate(-50%, -50%) scale(1);
+}
+
+.submit-job-close {
+    position: absolute;
+    top: 16px;
+    right: 16px;
+    width: 32px;
+    height: 32px;
+    padding: 0;
+    background: transparent;
+    border: 1px solid rgba(160, 160, 160, 0.3);
+    border-radius: 50%;
+    color: #aaa;
+    cursor: pointer;
+    transition: all 0.2s ease;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+}
+
+.submit-job-close:hover {
+    background: rgba(255, 255, 255, 0.1);
+    border-color: rgba(218, 165, 32, 0.5);
+    color: #daa520;
+}
+
+.submit-job-close svg {
+    width: 18px;
+    height: 18px;
+}
+
+.submit-job-content h2 {
+    font-size: 22px;
+    color: #daa520;
+    margin: 0 0 8px 0;
+    font-weight: 600;
+}
+
+.submit-job-subtitle {
+    font-size: 13px;
+    color: #888;
+    margin: 0 0 24px 0;
+}
+
+/* Form Styles */
+.submit-job-form {
+    display: flex;
+    flex-direction: column;
+    gap: 20px;
+}
+
+.submit-job-form.hidden {
+    display: none;
+}
+
+.form-group {
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+}
+
+.form-group label {
+    font-size: 13px;
+    color: #ccc;
+    font-weight: 500;
+}
+
+.form-group label .required {
+    color: #ff4444;
+    margin-left: 4px;
+}
+
+.form-group input,
+.form-group textarea,
+.form-group select {
+    background: rgba(30, 30, 40, 0.8);
+    border: 1px solid rgba(160, 160, 160, 0.3);
+    border-radius: 6px;
+    padding: 10px 12px;
+    color: #e0e0e0;
+    font-family: "Courier New", monospace;
+    font-size: 14px;
+    transition: border-color 0.2s ease, box-shadow 0.2s ease;
+}
+
+.form-group input:focus,
+.form-group textarea:focus,
+.form-group select:focus {
+    outline: none;
+    border-color: rgba(218, 165, 32, 0.6);
+    box-shadow: 0 0 0 2px rgba(218, 165, 32, 0.1);
+}
+
+.form-group input.error,
+.form-group textarea.error {
+    border-color: #ff4444;
+    box-shadow: 0 0 0 2px rgba(255, 68, 68, 0.1);
+}
+
+.form-group input::placeholder,
+.form-group textarea::placeholder {
+    color: #666;
+}
+
+.form-group textarea {
+    resize: vertical;
+    min-height: 100px;
+}
+
+.form-group select {
+    cursor: pointer;
+    appearance: none;
+    background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='12' viewBox='0 0 24 24' fill='none' stroke='%23888' stroke-width='2'%3E%3Cpath d='m6 9 6 6 6-6'/%3E%3C/svg%3E");
+    background-repeat: no-repeat;
+    background-position: right 12px center;
+    padding-right: 36px;
+}
+
+.form-group select option {
+    background: #1a1a2e;
+    color: #e0e0e0;
+}
+
+/* Character Count */
+.char-count {
+    font-size: 11px;
+    color: #666;
+    text-align: right;
+    margin-top: 4px;
+    transition: color 0.2s ease;
+}
+
+.char-count.near-limit {
+    color: #ffaa33;
+}
+
+.char-count.over-limit {
+    color: #ff4444;
+    font-weight: bold;
+}
+
+/* Validation Messages */
+.validation-error {
+    font-size: 12px;
+    color: #ff4444;
+    margin-top: 4px;
+    min-height: 16px;
+    opacity: 0;
+    transition: opacity 0.2s ease;
+}
+
+.validation-error.visible {
+    opacity: 1;
+}
+
+.validation-warning {
+    font-size: 12px;
+    color: #ffaa33;
+    margin-top: 4px;
+    min-height: 16px;
+    opacity: 0;
+    transition: opacity 0.2s ease;
+}
+
+.validation-warning.visible {
+    opacity: 1;
+}
+
+/* Action Buttons */
+.submit-job-actions {
+    display: flex;
+    gap: 12px;
+    justify-content: flex-end;
+    margin-top: 8px;
+}
+
+.btn-secondary {
+    padding: 10px 20px;
+    background: transparent;
+    border: 1px solid rgba(160, 160, 160, 0.4);
+    border-radius: 6px;
+    color: #aaa;
+    font-family: "Courier New", monospace;
+    font-size: 14px;
+    cursor: pointer;
+    transition: all 0.2s ease;
+}
+
+.btn-secondary:hover {
+    background: rgba(255, 255, 255, 0.05);
+    border-color: rgba(160, 160, 160, 0.6);
+    color: #ccc;
+}
+
+.btn-primary {
+    padding: 10px 20px;
+    background: linear-gradient(135deg, rgba(0, 180, 80, 0.8), rgba(0, 140, 60, 0.9));
+    border: 1px solid rgba(0, 180, 80, 0.5);
+    border-radius: 6px;
+    color: #fff;
+    font-family: "Courier New", monospace;
+    font-size: 14px;
+    cursor: pointer;
+    transition: all 0.2s ease;
+}
+
+.btn-primary:hover:not(:disabled) {
+    background: linear-gradient(135deg, rgba(0, 200, 90, 0.9), rgba(0, 160, 70, 1));
+    transform: translateY(-1px);
+    box-shadow: 0 4px 12px rgba(0, 180, 80, 0.3);
+}
+
+.btn-primary:disabled {
+    background: rgba(100, 100, 100, 0.3);
+    border-color: rgba(100, 100, 100, 0.3);
+    color: #666;
+    cursor: not-allowed;
+}
+
+/* Success State */
+.submit-job-success {
+    text-align: center;
+    padding: 32px 16px;
+}
+
+.submit-job-success.hidden {
+    display: none;
+}
+
+.success-icon {
+    width: 64px;
+    height: 64px;
+    margin: 0 auto 20px;
+    color: #00b450;
+}
+
+.success-icon svg {
+    width: 100%;
+    height: 100%;
+}
+
+.submit-job-success h3 {
+    font-size: 20px;
+    color: #00b450;
+    margin: 0 0 12px 0;
+}
+
+.submit-job-success p {
+    font-size: 14px;
+    color: #888;
+    margin: 0 0 24px 0;
+    line-height: 1.5;
+}
+
+/* Backdrop */
+.submit-job-backdrop {
+    position: absolute;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+    background: rgba(0, 0, 0, 0.6);
+    opacity: 0;
+    transition: opacity 0.3s ease;
+}
+
+.submit-job-modal.open .submit-job-backdrop {
+    opacity: 1;
+}
+
+/* Mobile adjustments */
+@media (max-width: 480px) {
+    .about-panel-content {
+        width: 100%;
+        max-width: 100%;
+        padding: 56px 20px 20px 20px;
+    }
+    
+    .info-button {
+        right: 32px;
+        width: 26px;
+        height: 26px;
+    }
+    
+    .info-button svg {
+        width: 14px;
+        height: 14px;
+    }
+    
+    .submit-job-button {
+        right: 64px;
+        height: 26px;
+        padding: 0 10px;
+        font-size: 11px;
+    }
+    
+    .submit-job-button svg {
+        width: 12px;
+        height: 12px;
+    }
+    
+    .submit-job-content {
+        width: 95%;
+        padding: 24px 20px;
+    }
+    
+    .submit-job-content h2 {
+        font-size: 20px;
+    }
+    
+    .submit-job-actions {
+        flex-direction: column-reverse;
+    }
+    
+    .btn-secondary,
+    .btn-primary {
+        width: 100%;
+    }
+}

tests/conftest.py

@@ -31,6 +31,8 @@ for _mod in [
     "pyzbar.pyzbar",
     "pyttsx3",
     "sentence_transformers",
+    "swarm",
+    "swarm.event_log",
 ]:
     sys.modules.setdefault(_mod, MagicMock())
 

tests/dashboard/middleware/test_csrf_decorator_support.py

@@ -120,3 +120,50 @@ class TestCSRFDecoratorSupport:
         # Protected endpoint should be 403
         response2 = client.post("/protected")
         assert response2.status_code == 403
+
+    def test_csrf_exempt_endpoint_not_executed_before_check(self):
+        """Regression test for #626: endpoint must NOT execute before CSRF check.
+
+        Previously the middleware called call_next() first, executing the endpoint
+        and its side effects, then checked @csrf_exempt afterward. This meant
+        non-exempt endpoints would execute even when CSRF validation failed.
+        """
+        app = FastAPI()
+        app.add_middleware(CSRFMiddleware)
+
+        side_effect_log: list[str] = []
+
+        @app.post("/protected-with-side-effects")
+        def protected_with_side_effects():
+            side_effect_log.append("executed")
+            return {"message": "should not run"}
+
+        client = TestClient(app)
+
+        # POST without CSRF token — should be blocked with 403
+        response = client.post("/protected-with-side-effects")
+        assert response.status_code == 403
+        # The critical assertion: the endpoint must NOT have executed
+        assert side_effect_log == [], (
+            "Endpoint executed before CSRF validation! Side effects occurred "
+            "despite CSRF failure (see issue #626)."
+        )
+
+    def test_csrf_exempt_endpoint_does_execute(self):
+        """Ensure @csrf_exempt endpoints still execute normally."""
+        app = FastAPI()
+        app.add_middleware(CSRFMiddleware)
+
+        side_effect_log: list[str] = []
+
+        @app.post("/exempt-webhook")
+        @csrf_exempt
+        def exempt_webhook():
+            side_effect_log.append("executed")
+            return {"message": "webhook ok"}
+
+        client = TestClient(app)
+
+        response = client.post("/exempt-webhook")
+        assert response.status_code == 200
+        assert side_effect_log == ["executed"]

tests/dashboard/test_scorecards.py

@@ -0,0 +1,680 @@
+"""Tests for agent scorecard functionality."""
+
+from datetime import UTC, datetime, timedelta
+from unittest.mock import MagicMock, patch
+
+from dashboard.services.scorecard_service import (
+    AgentMetrics,
+    PeriodType,
+    ScorecardSummary,
+    _aggregate_metrics,
+    _detect_patterns,
+    _extract_actor_from_event,
+    _generate_narrative_bullets,
+    _get_period_bounds,
+    _is_tracked_agent,
+    _query_token_transactions,
+    generate_all_scorecards,
+    generate_scorecard,
+    get_tracked_agents,
+)
+from infrastructure.events.bus import Event
+
+
+class TestPeriodBounds:
+    """Test period boundary calculations."""
+
+    def test_daily_period_bounds(self):
+        """Test daily period returns correct 24-hour window."""
+        reference = datetime(2026, 3, 21, 12, 30, 45, tzinfo=UTC)
+        start, end = _get_period_bounds(PeriodType.daily, reference)
+
+        assert end == datetime(2026, 3, 21, 0, 0, 0, tzinfo=UTC)
+        assert start == datetime(2026, 3, 20, 0, 0, 0, tzinfo=UTC)
+        assert (end - start) == timedelta(days=1)
+
+    def test_weekly_period_bounds(self):
+        """Test weekly period returns correct 7-day window."""
+        reference = datetime(2026, 3, 21, 12, 30, 45, tzinfo=UTC)
+        start, end = _get_period_bounds(PeriodType.weekly, reference)
+
+        assert end == datetime(2026, 3, 21, 0, 0, 0, tzinfo=UTC)
+        assert start == datetime(2026, 3, 14, 0, 0, 0, tzinfo=UTC)
+        assert (end - start) == timedelta(days=7)
+
+    def test_default_reference_date(self):
+        """Test default reference date uses current time."""
+        start, end = _get_period_bounds(PeriodType.daily)
+        now = datetime.now(UTC)
+
+        # End should be start of current day (midnight)
+        expected_end = now.replace(hour=0, minute=0, second=0, microsecond=0)
+        assert end == expected_end
+        # Start should be 24 hours before end
+        assert (end - start) == timedelta(days=1)
+
+
+class TestTrackedAgents:
+    """Test agent tracking functions."""
+
+    def test_get_tracked_agents(self):
+        """Test get_tracked_agents returns sorted list."""
+        agents = get_tracked_agents()
+        assert isinstance(agents, list)
+        assert "kimi" in agents
+        assert "claude" in agents
+        assert "gemini" in agents
+        assert "hermes" in agents
+        assert "manus" in agents
+        assert agents == sorted(agents)
+
+    def test_is_tracked_agent_true(self):
+        """Test _is_tracked_agent returns True for tracked agents."""
+        assert _is_tracked_agent("kimi") is True
+        assert _is_tracked_agent("KIMI") is True  # case insensitive
+        assert _is_tracked_agent("claude") is True
+        assert _is_tracked_agent("hermes") is True
+
+    def test_is_tracked_agent_false(self):
+        """Test _is_tracked_agent returns False for untracked agents."""
+        assert _is_tracked_agent("unknown") is False
+        assert _is_tracked_agent("rockachopa") is False
+        assert _is_tracked_agent("") is False
+
+
+class TestExtractActor:
+    """Test actor extraction from events."""
+
+    def test_extract_from_actor_field(self):
+        """Test extraction from data.actor field."""
+        event = Event(type="test", source="system", data={"actor": "kimi"})
+        assert _extract_actor_from_event(event) == "kimi"
+
+    def test_extract_from_agent_id_field(self):
+        """Test extraction from data.agent_id field."""
+        event = Event(type="test", source="system", data={"agent_id": "claude"})
+        assert _extract_actor_from_event(event) == "claude"
+
+    def test_extract_from_source_fallback(self):
+        """Test fallback to event.source."""
+        event = Event(type="test", source="gemini", data={})
+        assert _extract_actor_from_event(event) == "gemini"
+
+    def test_actor_priority_over_agent_id(self):
+        """Test actor field takes priority over agent_id."""
+        event = Event(type="test", source="system", data={"actor": "kimi", "agent_id": "claude"})
+        assert _extract_actor_from_event(event) == "kimi"
+
+
+class TestAggregateMetrics:
+    """Test metrics aggregation from events."""
+
+    def test_empty_events(self):
+        """Test aggregation with no events returns empty dict."""
+        result = _aggregate_metrics([])
+        assert result == {}
+
+    def test_push_event_aggregation(self):
+        """Test push events aggregate commits correctly."""
+        events = [
+            Event(type="gitea.push", source="gitea", data={"actor": "kimi", "num_commits": 3}),
+            Event(type="gitea.push", source="gitea", data={"actor": "kimi", "num_commits": 2}),
+        ]
+        result = _aggregate_metrics(events)
+
+        assert "kimi" in result
+        assert result["kimi"].commits == 5
+
+    def test_issue_opened_aggregation(self):
+        """Test issue opened events aggregate correctly."""
+        events = [
+            Event(
+                type="gitea.issue.opened",
+                source="gitea",
+                data={"actor": "claude", "issue_number": 100},
+            ),
+            Event(
+                type="gitea.issue.opened",
+                source="gitea",
+                data={"actor": "claude", "issue_number": 101},
+            ),
+        ]
+        result = _aggregate_metrics(events)
+
+        assert "claude" in result
+        assert len(result["claude"].issues_touched) == 2
+        assert 100 in result["claude"].issues_touched
+        assert 101 in result["claude"].issues_touched
+
+    def test_comment_aggregation(self):
+        """Test comment events aggregate correctly."""
+        events = [
+            Event(
+                type="gitea.issue.comment",
+                source="gitea",
+                data={"actor": "gemini", "issue_number": 100},
+            ),
+            Event(
+                type="gitea.issue.comment",
+                source="gitea",
+                data={"actor": "gemini", "issue_number": 101},
+            ),
+        ]
+        result = _aggregate_metrics(events)
+
+        assert "gemini" in result
+        assert result["gemini"].comments == 2
+        assert len(result["gemini"].issues_touched) == 2  # Comments touch issues too
+
+    def test_pr_events_aggregation(self):
+        """Test PR open and merge events aggregate correctly."""
+        events = [
+            Event(
+                type="gitea.pull_request",
+                source="gitea",
+                data={"actor": "kimi", "pr_number": 50, "action": "opened"},
+            ),
+            Event(
+                type="gitea.pull_request",
+                source="gitea",
+                data={"actor": "kimi", "pr_number": 50, "action": "closed", "merged": True},
+            ),
+            Event(
+                type="gitea.pull_request",
+                source="gitea",
+                data={"actor": "kimi", "pr_number": 51, "action": "opened"},
+            ),
+        ]
+        result = _aggregate_metrics(events)
+
+        assert "kimi" in result
+        assert len(result["kimi"].prs_opened) == 2
+        assert len(result["kimi"].prs_merged) == 1
+        assert 50 in result["kimi"].prs_merged
+
+    def test_untracked_agent_filtered(self):
+        """Test events from untracked agents are filtered out."""
+        events = [
+            Event(
+                type="gitea.push", source="gitea", data={"actor": "rockachopa", "num_commits": 5}
+            ),
+        ]
+        result = _aggregate_metrics(events)
+
+        assert "rockachopa" not in result
+
+    def test_task_completion_aggregation(self):
+        """Test task completion events aggregate test files."""
+        events = [
+            Event(
+                type="agent.task.completed",
+                source="gitea",
+                data={
+                    "agent_id": "kimi",
+                    "tests_affected": ["test_foo.py", "test_bar.py"],
+                    "token_reward": 10,
+                },
+            ),
+        ]
+        result = _aggregate_metrics(events)
+
+        assert "kimi" in result
+        assert len(result["kimi"].tests_affected) == 2
+        assert "test_foo.py" in result["kimi"].tests_affected
+        assert result["kimi"].tokens_earned == 10
+
+
+class TestAgentMetrics:
+    """Test AgentMetrics class."""
+
+    def test_merge_rate_zero_prs(self):
+        """Test merge rate is 0 when no PRs opened."""
+        metrics = AgentMetrics(agent_id="kimi")
+        assert metrics.pr_merge_rate == 0.0
+
+    def test_merge_rate_perfect(self):
+        """Test 100% merge rate calculation."""
+        metrics = AgentMetrics(agent_id="kimi", prs_opened={1, 2, 3}, prs_merged={1, 2, 3})
+        assert metrics.pr_merge_rate == 1.0
+
+    def test_merge_rate_partial(self):
+        """Test partial merge rate calculation."""
+        metrics = AgentMetrics(agent_id="kimi", prs_opened={1, 2, 3, 4}, prs_merged={1, 2})
+        assert metrics.pr_merge_rate == 0.5
+
+
+class TestDetectPatterns:
+    """Test pattern detection logic."""
+
+    def test_high_merge_rate_pattern(self):
+        """Test detection of high merge rate pattern."""
+        metrics = AgentMetrics(
+            agent_id="kimi",
+            prs_opened={1, 2, 3, 4, 5},
+            prs_merged={1, 2, 3, 4},  # 80% merge rate
+        )
+        patterns = _detect_patterns(metrics)
+
+        assert any("High merge rate" in p for p in patterns)
+
+    def test_low_merge_rate_pattern(self):
+        """Test detection of low merge rate pattern."""
+        metrics = AgentMetrics(
+            agent_id="kimi",
+            prs_opened={1, 2, 3, 4, 5},
+            prs_merged={1},  # 20% merge rate
+        )
+        patterns = _detect_patterns(metrics)
+
+        assert any("low merge rate" in p for p in patterns)
+
+    def test_high_commits_no_prs_pattern(self):
+        """Test detection of direct-to-main commits pattern."""
+        metrics = AgentMetrics(
+            agent_id="kimi",
+            commits=15,
+            prs_opened=set(),
+        )
+        patterns = _detect_patterns(metrics)
+
+        assert any("High commit volume without PRs" in p for p in patterns)
+
+    def test_silent_worker_pattern(self):
+        """Test detection of silent worker pattern."""
+        metrics = AgentMetrics(
+            agent_id="kimi",
+            issues_touched={1, 2, 3, 4, 5, 6},
+            comments=0,
+        )
+        patterns = _detect_patterns(metrics)
+
+        assert any("silent worker" in p for p in patterns)
+
+    def test_communicative_pattern(self):
+        """Test detection of highly communicative pattern."""
+        metrics = AgentMetrics(
+            agent_id="kimi",
+            issues_touched={1, 2},  # 2 issues
+            comments=10,  # 5x comments per issue
+        )
+        patterns = _detect_patterns(metrics)
+
+        assert any("Highly communicative" in p for p in patterns)
+
+    def test_token_accumulation_pattern(self):
+        """Test detection of token accumulation pattern."""
+        metrics = AgentMetrics(
+            agent_id="kimi",
+            tokens_earned=150,
+            tokens_spent=10,
+        )
+        patterns = _detect_patterns(metrics)
+
+        assert any("Strong token accumulation" in p for p in patterns)
+
+    def test_token_spend_pattern(self):
+        """Test detection of high token spend pattern."""
+        metrics = AgentMetrics(
+            agent_id="kimi",
+            tokens_earned=10,
+            tokens_spent=100,
+        )
+        patterns = _detect_patterns(metrics)
+
+        assert any("High token spend" in p for p in patterns)
+
+
+class TestGenerateNarrative:
+    """Test narrative bullet generation."""
+
+    def test_empty_metrics_narrative(self):
+        """Test narrative for empty metrics mentions no activity."""
+        metrics = AgentMetrics(agent_id="kimi")
+        bullets = _generate_narrative_bullets(metrics, PeriodType.daily)
+
+        assert len(bullets) == 1
+        assert "No recorded activity" in bullets[0]
+
+    def test_activity_summary_narrative(self):
+        """Test narrative includes activity summary."""
+        metrics = AgentMetrics(
+            agent_id="kimi",
+            commits=5,
+            prs_opened={1, 2},
+            prs_merged={1},
+        )
+        bullets = _generate_narrative_bullets(metrics, PeriodType.daily)
+
+        activity_bullet = next((b for b in bullets if "Active across" in b), None)
+        assert activity_bullet is not None
+        assert "5 commits" in activity_bullet
+        assert "2 PRs opened" in activity_bullet
+        assert "1 PR merged" in activity_bullet
+
+    def test_tests_affected_narrative(self):
+        """Test narrative includes tests affected."""
+        metrics = AgentMetrics(
+            agent_id="kimi",
+            tests_affected={"test_a.py", "test_b.py"},
+        )
+        bullets = _generate_narrative_bullets(metrics, PeriodType.daily)
+
+        assert any("2 test files" in b for b in bullets)
+
+    def test_tokens_earned_narrative(self):
+        """Test narrative includes token earnings."""
+        metrics = AgentMetrics(
+            agent_id="kimi",
+            tokens_earned=100,
+            tokens_spent=20,
+        )
+        bullets = _generate_narrative_bullets(metrics, PeriodType.daily)
+
+        assert any("Net earned 80 tokens" in b for b in bullets)
+
+    def test_tokens_spent_narrative(self):
+        """Test narrative includes token spending."""
+        metrics = AgentMetrics(
+            agent_id="kimi",
+            tokens_earned=20,
+            tokens_spent=100,
+        )
+        bullets = _generate_narrative_bullets(metrics, PeriodType.daily)
+
+        assert any("Net spent 80 tokens" in b for b in bullets)
+
+    def test_balanced_tokens_narrative(self):
+        """Test narrative for balanced token flow."""
+        metrics = AgentMetrics(
+            agent_id="kimi",
+            tokens_earned=100,
+            tokens_spent=100,
+        )
+        bullets = _generate_narrative_bullets(metrics, PeriodType.daily)
+
+        assert any("Balanced token flow" in b for b in bullets)
+
+
+class TestScorecardSummary:
+    """Test ScorecardSummary dataclass."""
+
+    def test_to_dict_structure(self):
+        """Test to_dict returns expected structure."""
+        metrics = AgentMetrics(
+            agent_id="kimi",
+            issues_touched={1, 2},
+            prs_opened={10, 11},
+            prs_merged={10},
+            tokens_earned=100,
+            tokens_spent=20,
+        )
+        summary = ScorecardSummary(
+            agent_id="kimi",
+            period_type=PeriodType.daily,
+            period_start=datetime.now(UTC),
+            period_end=datetime.now(UTC),
+            metrics=metrics,
+            narrative_bullets=["Test bullet"],
+            patterns=["Test pattern"],
+        )
+        data = summary.to_dict()
+
+        assert data["agent_id"] == "kimi"
+        assert data["period_type"] == "daily"
+        assert "metrics" in data
+        assert data["metrics"]["issues_touched"] == 2
+        assert data["metrics"]["prs_opened"] == 2
+        assert data["metrics"]["prs_merged"] == 1
+        assert data["metrics"]["pr_merge_rate"] == 0.5
+        assert data["metrics"]["tokens_earned"] == 100
+        assert data["metrics"]["token_net"] == 80
+        assert data["narrative_bullets"] == ["Test bullet"]
+        assert data["patterns"] == ["Test pattern"]
+
+
+class TestQueryTokenTransactions:
+    """Test token transaction querying."""
+
+    def test_empty_ledger(self):
+        """Test empty ledger returns zero values."""
+        with patch("lightning.ledger.get_transactions", return_value=[]):
+            earned, spent = _query_token_transactions("kimi", datetime.now(UTC), datetime.now(UTC))
+            assert earned == 0
+            assert spent == 0
+
+    def test_ledger_with_transactions(self):
+        """Test ledger aggregation of transactions."""
+        now = datetime.now(UTC)
+        mock_tx = [
+            MagicMock(
+                agent_id="kimi",
+                tx_type=MagicMock(value="incoming"),
+                amount_sats=100,
+                created_at=now.isoformat(),
+            ),
+            MagicMock(
+                agent_id="kimi",
+                tx_type=MagicMock(value="outgoing"),
+                amount_sats=30,
+                created_at=now.isoformat(),
+            ),
+        ]
+        with patch("lightning.ledger.get_transactions", return_value=mock_tx):
+            earned, spent = _query_token_transactions(
+                "kimi", now - timedelta(hours=1), now + timedelta(hours=1)
+            )
+            assert earned == 100
+            assert spent == 30
+
+    def test_ledger_filters_by_agent(self):
+        """Test ledger filters transactions by agent_id."""
+        now = datetime.now(UTC)
+        mock_tx = [
+            MagicMock(
+                agent_id="claude",
+                tx_type=MagicMock(value="incoming"),
+                amount_sats=100,
+                created_at=now.isoformat(),
+            ),
+        ]
+        with patch("lightning.ledger.get_transactions", return_value=mock_tx):
+            earned, spent = _query_token_transactions(
+                "kimi", now - timedelta(hours=1), now + timedelta(hours=1)
+            )
+            assert earned == 0  # Transaction was for claude, not kimi
+
+    def test_ledger_filters_by_time(self):
+        """Test ledger filters transactions by time range."""
+        now = datetime.now(UTC)
+        old_time = now - timedelta(days=2)
+        mock_tx = [
+            MagicMock(
+                agent_id="kimi",
+                tx_type=MagicMock(value="incoming"),
+                amount_sats=100,
+                created_at=old_time.isoformat(),
+            ),
+        ]
+        with patch("lightning.ledger.get_transactions", return_value=mock_tx):
+            # Query for today only
+            earned, spent = _query_token_transactions(
+                "kimi", now - timedelta(hours=1), now + timedelta(hours=1)
+            )
+            assert earned == 0  # Transaction was 2 days ago
+
+
+class TestGenerateScorecard:
+    """Test scorecard generation."""
+
+    def test_generate_scorecard_no_activity(self):
+        """Test scorecard generation for agent with no activity."""
+        with patch(
+            "dashboard.services.scorecard_service._collect_events_for_period", return_value=[]
+        ):
+            with patch(
+                "dashboard.services.scorecard_service._query_token_transactions",
+                return_value=(0, 0),
+            ):
+                scorecard = generate_scorecard("kimi", PeriodType.daily)
+
+        assert scorecard is not None
+        assert scorecard.agent_id == "kimi"
+        assert scorecard.period_type == PeriodType.daily
+        assert len(scorecard.narrative_bullets) == 1
+        assert "No recorded activity" in scorecard.narrative_bullets[0]
+
+    def test_generate_scorecard_with_activity(self):
+        """Test scorecard generation includes activity."""
+        events = [
+            Event(type="gitea.push", source="gitea", data={"actor": "kimi", "num_commits": 5}),
+        ]
+        with patch(
+            "dashboard.services.scorecard_service._collect_events_for_period", return_value=events
+        ):
+            with patch(
+                "dashboard.services.scorecard_service._query_token_transactions",
+                return_value=(100, 20),
+            ):
+                scorecard = generate_scorecard("kimi", PeriodType.daily)
+
+        assert scorecard is not None
+        assert scorecard.metrics.commits == 5
+        assert scorecard.metrics.tokens_earned == 100
+        assert scorecard.metrics.tokens_spent == 20
+
+
+class TestGenerateAllScorecards:
+    """Test generating scorecards for all agents."""
+
+    def test_generates_for_all_tracked_agents(self):
+        """Test all tracked agents get scorecards even with no activity."""
+        with patch(
+            "dashboard.services.scorecard_service._collect_events_for_period", return_value=[]
+        ):
+            with patch(
+                "dashboard.services.scorecard_service._query_token_transactions",
+                return_value=(0, 0),
+            ):
+                scorecards = generate_all_scorecards(PeriodType.daily)
+
+        agent_ids = {s.agent_id for s in scorecards}
+        expected = {"kimi", "claude", "gemini", "hermes", "manus"}
+        assert expected.issubset(agent_ids)
+
+    def test_scorecards_sorted(self):
+        """Test scorecards are sorted by agent_id."""
+        with patch(
+            "dashboard.services.scorecard_service._collect_events_for_period", return_value=[]
+        ):
+            with patch(
+                "dashboard.services.scorecard_service._query_token_transactions",
+                return_value=(0, 0),
+            ):
+                scorecards = generate_all_scorecards(PeriodType.daily)
+
+        agent_ids = [s.agent_id for s in scorecards]
+        assert agent_ids == sorted(agent_ids)
+
+
+class TestScorecardRoutes:
+    """Test scorecard API routes."""
+
+    def test_list_agents_endpoint(self, client):
+        """Test GET /scorecards/api/agents returns tracked agents."""
+        response = client.get("/scorecards/api/agents")
+        assert response.status_code == 200
+        data = response.json()
+        assert "agents" in data
+        assert "kimi" in data["agents"]
+        assert "claude" in data["agents"]
+
+    def test_get_scorecard_endpoint(self, client):
+        """Test GET /scorecards/api/{agent_id} returns scorecard."""
+        with patch("dashboard.routes.scorecards.generate_scorecard") as mock_generate:
+            mock_generate.return_value = ScorecardSummary(
+                agent_id="kimi",
+                period_type=PeriodType.daily,
+                period_start=datetime.now(UTC),
+                period_end=datetime.now(UTC),
+                metrics=AgentMetrics(agent_id="kimi"),
+                narrative_bullets=["Test bullet"],
+                patterns=[],
+            )
+            response = client.get("/scorecards/api/kimi?period=daily")
+
+        assert response.status_code == 200
+        data = response.json()
+        assert data["agent_id"] == "kimi"
+        assert data["period_type"] == "daily"
+
+    def test_get_scorecard_invalid_period(self, client):
+        """Test GET with invalid period returns 400."""
+        response = client.get("/scorecards/api/kimi?period=invalid")
+        assert response.status_code == 400
+        assert "error" in response.json()
+
+    def test_get_all_scorecards_endpoint(self, client):
+        """Test GET /scorecards/api returns all scorecards."""
+        with patch("dashboard.routes.scorecards.generate_all_scorecards") as mock_generate:
+            mock_generate.return_value = [
+                ScorecardSummary(
+                    agent_id="kimi",
+                    period_type=PeriodType.daily,
+                    period_start=datetime.now(UTC),
+                    period_end=datetime.now(UTC),
+                    metrics=AgentMetrics(agent_id="kimi"),
+                    narrative_bullets=[],
+                    patterns=[],
+                ),
+            ]
+            response = client.get("/scorecards/api?period=daily")
+
+        assert response.status_code == 200
+        data = response.json()
+        assert data["period"] == "daily"
+        assert "scorecards" in data
+        assert len(data["scorecards"]) == 1
+
+    def test_scorecards_page_renders(self, client):
+        """Test GET /scorecards returns HTML page."""
+        response = client.get("/scorecards")
+        assert response.status_code == 200
+        assert "text/html" in response.headers.get("content-type", "")
+        assert "AGENT SCORECARDS" in response.text
+
+    def test_scorecard_panel_renders(self, client):
+        """Test GET /scorecards/panel/{agent_id} returns HTML."""
+        with patch("dashboard.routes.scorecards.generate_scorecard") as mock_generate:
+            mock_generate.return_value = ScorecardSummary(
+                agent_id="kimi",
+                period_type=PeriodType.daily,
+                period_start=datetime.now(UTC),
+                period_end=datetime.now(UTC),
+                metrics=AgentMetrics(agent_id="kimi", commits=5),
+                narrative_bullets=["Active across 5 commits this day."],
+                patterns=["High activity"],
+            )
+            response = client.get("/scorecards/panel/kimi?period=daily")
+
+        assert response.status_code == 200
+        assert "text/html" in response.headers.get("content-type", "")
+        assert "Kimi" in response.text
+
+    def test_all_panels_renders(self, client):
+        """Test GET /scorecards/all/panels returns HTML with all panels."""
+        with patch("dashboard.routes.scorecards.generate_all_scorecards") as mock_generate:
+            mock_generate.return_value = [
+                ScorecardSummary(
+                    agent_id="kimi",
+                    period_type=PeriodType.daily,
+                    period_start=datetime.now(UTC),
+                    period_end=datetime.now(UTC),
+                    metrics=AgentMetrics(agent_id="kimi"),
+                    narrative_bullets=[],
+                    patterns=[],
+                ),
+            ]
+            response = client.get("/scorecards/all/panels?period=daily")
+
+        assert response.status_code == 200
+        assert "text/html" in response.headers.get("content-type", "")

tests/infrastructure/test_db_pool.py

@@ -0,0 +1,427 @@
+"""Tests for infrastructure.db_pool module."""
+
+import sqlite3
+import threading
+import time
+from pathlib import Path
+
+import pytest
+
+from infrastructure.db_pool import ConnectionPool
+
+
+class TestConnectionPoolInit:
+    """Test ConnectionPool initialization."""
+
+    def test_init_with_string_path(self, tmp_path):
+        """Pool can be initialized with a string path."""
+        db_path = str(tmp_path / "test.db")
+        pool = ConnectionPool(db_path)
+        assert pool._db_path == Path(db_path)
+
+    def test_init_with_path_object(self, tmp_path):
+        """Pool can be initialized with a Path object."""
+        db_path = tmp_path / "test.db"
+        pool = ConnectionPool(db_path)
+        assert pool._db_path == db_path
+
+    def test_init_creates_thread_local(self, tmp_path):
+        """Pool initializes thread-local storage."""
+        pool = ConnectionPool(tmp_path / "test.db")
+        assert hasattr(pool, "_local")
+        assert isinstance(pool._local, threading.local)
+
+
+class TestGetConnection:
+    """Test get_connection() method."""
+
+    def test_get_connection_returns_valid_sqlite3_connection(self, tmp_path):
+        """get_connection() returns a valid sqlite3 connection."""
+        pool = ConnectionPool(tmp_path / "test.db")
+        conn = pool.get_connection()
+        assert isinstance(conn, sqlite3.Connection)
+        # Verify it's a working connection
+        cursor = conn.execute("SELECT 1")
+        assert cursor.fetchone()[0] == 1
+
+    def test_get_connection_creates_db_file(self, tmp_path):
+        """get_connection() creates the database file if it doesn't exist."""
+        db_path = tmp_path / "subdir" / "test.db"
+        assert not db_path.exists()
+        pool = ConnectionPool(db_path)
+        pool.get_connection()
+        assert db_path.exists()
+
+    def test_get_connection_sets_row_factory(self, tmp_path):
+        """get_connection() sets row_factory to sqlite3.Row."""
+        pool = ConnectionPool(tmp_path / "test.db")
+        conn = pool.get_connection()
+        assert conn.row_factory is sqlite3.Row
+
+    def test_multiple_calls_same_thread_reuse_connection(self, tmp_path):
+        """Multiple calls from same thread reuse the same connection."""
+        pool = ConnectionPool(tmp_path / "test.db")
+        conn1 = pool.get_connection()
+        conn2 = pool.get_connection()
+        assert conn1 is conn2
+
+    def test_different_threads_get_different_connections(self, tmp_path):
+        """Different threads get different connections."""
+        pool = ConnectionPool(tmp_path / "test.db")
+        connections = []
+
+        def get_conn():
+            connections.append(pool.get_connection())
+
+        t1 = threading.Thread(target=get_conn)
+        t2 = threading.Thread(target=get_conn)
+        t1.start()
+        t2.start()
+        t1.join()
+        t2.join()
+
+        assert len(connections) == 2
+        assert connections[0] is not connections[1]
+
+
+class TestCloseConnection:
+    """Test close_connection() method."""
+
+    def test_close_connection_closes_sqlite_connection(self, tmp_path):
+        """close_connection() closes the underlying sqlite connection."""
+        pool = ConnectionPool(tmp_path / "test.db")
+        conn = pool.get_connection()
+        pool.close_connection()
+        # Connection should be closed
+        with pytest.raises(sqlite3.ProgrammingError):
+            conn.execute("SELECT 1")
+
+    def test_close_connection_cleans_up_thread_local(self, tmp_path):
+        """close_connection() cleans up thread-local storage."""
+        pool = ConnectionPool(tmp_path / "test.db")
+        pool.get_connection()
+        assert hasattr(pool._local, "conn")
+        assert pool._local.conn is not None
+
+        pool.close_connection()
+
+        # Should either not have the attr or it should be None
+        assert not hasattr(pool._local, "conn") or pool._local.conn is None
+
+    def test_close_connection_without_getting_connection_is_safe(self, tmp_path):
+        """close_connection() is safe to call even without getting a connection first."""
+        pool = ConnectionPool(tmp_path / "test.db")
+        # Should not raise
+        pool.close_connection()
+
+    def test_close_connection_multiple_calls_is_safe(self, tmp_path):
+        """close_connection() can be called multiple times safely."""
+        pool = ConnectionPool(tmp_path / "test.db")
+        pool.get_connection()
+        pool.close_connection()
+        # Should not raise
+        pool.close_connection()
+
+
+class TestContextManager:
+    """Test the connection() context manager."""
+
+    def test_connection_yields_valid_connection(self, tmp_path):
+        """connection() context manager yields a valid sqlite3 connection."""
+        pool = ConnectionPool(tmp_path / "test.db")
+        with pool.connection() as conn:
+            assert isinstance(conn, sqlite3.Connection)
+            cursor = conn.execute("SELECT 42")
+            assert cursor.fetchone()[0] == 42
+
+    def test_connection_closes_on_exit(self, tmp_path):
+        """connection() context manager closes connection on exit."""
+        pool = ConnectionPool(tmp_path / "test.db")
+        with pool.connection() as conn:
+            pass
+        # Connection should be closed after context exit
+        with pytest.raises(sqlite3.ProgrammingError):
+            conn.execute("SELECT 1")
+
+    def test_connection_closes_on_exception(self, tmp_path):
+        """connection() context manager closes connection even on exception."""
+        pool = ConnectionPool(tmp_path / "test.db")
+        conn_ref = None
+        try:
+            with pool.connection() as conn:
+                conn_ref = conn
+                raise ValueError("Test exception")
+        except ValueError:
+            pass
+        # Connection should still be closed
+        with pytest.raises(sqlite3.ProgrammingError):
+            conn_ref.execute("SELECT 1")
+
+    def test_connection_context_manager_is_reusable(self, tmp_path):
+        """connection() context manager can be used multiple times."""
+        pool = ConnectionPool(tmp_path / "test.db")
+
+        with pool.connection() as conn1:
+            result1 = conn1.execute("SELECT 1").fetchone()[0]
+
+        with pool.connection() as conn2:
+            result2 = conn2.execute("SELECT 2").fetchone()[0]
+
+        assert result1 == 1
+        assert result2 == 2
+
+
+class TestThreadSafety:
+    """Test thread-safety of the connection pool."""
+
+    def test_concurrent_access(self, tmp_path):
+        """Multiple threads can use the pool concurrently."""
+        pool = ConnectionPool(tmp_path / "test.db")
+        results = []
+        errors = []
+
+        def worker(worker_id):
+            try:
+                with pool.connection() as conn:
+                    conn.execute("CREATE TABLE IF NOT EXISTS test (id INTEGER)")
+                    conn.execute("INSERT INTO test VALUES (?)", (worker_id,))
+                    conn.commit()
+                    time.sleep(0.01)  # Small delay to increase contention
+                    results.append(worker_id)
+            except Exception as e:
+                errors.append(e)
+
+        threads = [threading.Thread(target=worker, args=(i,)) for i in range(5)]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        assert len(errors) == 0, f"Errors occurred: {errors}"
+        assert len(results) == 5
+
+    def test_thread_isolation(self, tmp_path):
+        """Each thread has isolated connections (verified by thread-local data)."""
+        pool = ConnectionPool(tmp_path / "test.db")
+        results = []
+
+        def worker(worker_id):
+            # Get connection and write worker-specific data
+            conn = pool.get_connection()
+            conn.execute("CREATE TABLE IF NOT EXISTS isolation_test (thread_id INTEGER)")
+            conn.execute("DELETE FROM isolation_test")  # Clear previous data
+            conn.execute("INSERT INTO isolation_test VALUES (?)", (worker_id,))
+            conn.commit()
+            # Read back the data
+            result = conn.execute("SELECT thread_id FROM isolation_test").fetchone()[0]
+            results.append((worker_id, result))
+            pool.close_connection()
+
+        threads = [threading.Thread(target=worker, args=(i,)) for i in range(3)]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        # Each thread should have written and read its own ID
+        assert len(results) == 3
+        for worker_id, read_id in results:
+            assert worker_id == read_id, f"Thread {worker_id} read {read_id} instead"
+
+
+class TestCloseAll:
+    """Test close_all() method."""
+
+    def test_close_all_closes_current_thread_connection(self, tmp_path):
+        """close_all() closes the connection for the current thread."""
+        pool = ConnectionPool(tmp_path / "test.db")
+        conn = pool.get_connection()
+        pool.close_all()
+        # Connection should be closed
+        with pytest.raises(sqlite3.ProgrammingError):
+            conn.execute("SELECT 1")
+
+
+class TestConnectionLeaks:
+    """Test that connections do not leak."""
+
+    def test_get_connection_after_close_returns_fresh_connection(self, tmp_path):
+        """After close, get_connection() returns a new working connection."""
+        pool = ConnectionPool(tmp_path / "test.db")
+        conn1 = pool.get_connection()
+        pool.close_connection()
+
+        conn2 = pool.get_connection()
+        assert conn2 is not conn1
+        # New connection must be usable
+        cursor = conn2.execute("SELECT 1")
+        assert cursor.fetchone()[0] == 1
+        pool.close_connection()
+
+    def test_context_manager_does_not_leak_connection(self, tmp_path):
+        """After context manager exit, thread-local conn is cleared."""
+        pool = ConnectionPool(tmp_path / "test.db")
+        with pool.connection():
+            pass
+        # Thread-local should be cleaned up
+        assert pool._local.conn is None
+
+    def test_context_manager_exception_does_not_leak_connection(self, tmp_path):
+        """Connection is cleaned up even when an exception occurs."""
+        pool = ConnectionPool(tmp_path / "test.db")
+        try:
+            with pool.connection():
+                raise RuntimeError("boom")
+        except RuntimeError:
+            pass
+        assert pool._local.conn is None
+
+    def test_threads_do_not_leak_into_each_other(self, tmp_path):
+        """A connection opened in one thread is invisible to another."""
+        pool = ConnectionPool(tmp_path / "test.db")
+        # Open a connection on main thread
+        pool.get_connection()
+
+        visible_from_other_thread = []
+
+        def check():
+            has_conn = hasattr(pool._local, "conn") and pool._local.conn is not None
+            visible_from_other_thread.append(has_conn)
+
+        t = threading.Thread(target=check)
+        t.start()
+        t.join()
+
+        assert visible_from_other_thread == [False]
+        pool.close_connection()
+
+    def test_repeated_open_close_cycles(self, tmp_path):
+        """Repeated open/close cycles do not accumulate leaked connections."""
+        pool = ConnectionPool(tmp_path / "test.db")
+        for _ in range(50):
+            with pool.connection() as conn:
+                conn.execute("SELECT 1")
+            # After each cycle, connection should be cleaned up
+            assert pool._local.conn is None
+
+
+class TestPragmaApplication:
+    """Test that SQLite pragmas can be applied and persist on pooled connections.
+
+    The codebase uses WAL journal mode and busy_timeout pragmas on connections
+    obtained from the pool. These tests verify that pattern works correctly.
+    """
+
+    def test_wal_journal_mode_persists(self, tmp_path):
+        """WAL journal mode set on a pooled connection persists for its lifetime."""
+        pool = ConnectionPool(tmp_path / "test.db")
+        conn = pool.get_connection()
+        conn.execute("PRAGMA journal_mode=WAL")
+        mode = conn.execute("PRAGMA journal_mode").fetchone()[0]
+        assert mode == "wal"
+
+        # Same connection should retain the pragma
+        same_conn = pool.get_connection()
+        mode2 = same_conn.execute("PRAGMA journal_mode").fetchone()[0]
+        assert mode2 == "wal"
+        pool.close_connection()
+
+    def test_busy_timeout_persists(self, tmp_path):
+        """busy_timeout pragma set on a pooled connection persists."""
+        pool = ConnectionPool(tmp_path / "test.db")
+        conn = pool.get_connection()
+        conn.execute("PRAGMA busy_timeout=5000")
+        timeout = conn.execute("PRAGMA busy_timeout").fetchone()[0]
+        assert timeout == 5000
+        pool.close_connection()
+
+    def test_pragmas_apply_per_connection(self, tmp_path):
+        """Pragmas set on one thread's connection are independent of another's."""
+        pool = ConnectionPool(tmp_path / "test.db")
+        conn_main = pool.get_connection()
+        conn_main.execute("PRAGMA cache_size=9999")
+
+        other_cache = []
+
+        def check_pragma():
+            conn = pool.get_connection()
+            # Don't set cache_size — should get the default, not 9999
+            val = conn.execute("PRAGMA cache_size").fetchone()[0]
+            other_cache.append(val)
+            pool.close_connection()
+
+        t = threading.Thread(target=check_pragma)
+        t.start()
+        t.join()
+
+        # Other thread's connection should NOT have our custom cache_size
+        assert other_cache[0] != 9999
+        pool.close_connection()
+
+    def test_session_pragma_resets_on_new_connection(self, tmp_path):
+        """Session-level pragmas (cache_size) reset on a new connection."""
+        pool = ConnectionPool(tmp_path / "test.db")
+        conn1 = pool.get_connection()
+        conn1.execute("PRAGMA cache_size=9999")
+        assert conn1.execute("PRAGMA cache_size").fetchone()[0] == 9999
+        pool.close_connection()
+
+        conn2 = pool.get_connection()
+        cache = conn2.execute("PRAGMA cache_size").fetchone()[0]
+        # New connection gets default cache_size, not the previous value
+        assert cache != 9999
+        pool.close_connection()
+
+    def test_wal_mode_via_context_manager(self, tmp_path):
+        """WAL mode can be set within a context manager block."""
+        pool = ConnectionPool(tmp_path / "test.db")
+        with pool.connection() as conn:
+            conn.execute("PRAGMA journal_mode=WAL")
+            mode = conn.execute("PRAGMA journal_mode").fetchone()[0]
+            assert mode == "wal"
+
+
+class TestIntegration:
+    """Integration tests for real-world usage patterns."""
+
+    def test_basic_crud_operations(self, tmp_path):
+        """Can perform basic CRUD operations through the pool."""
+        pool = ConnectionPool(tmp_path / "test.db")
+
+        with pool.connection() as conn:
+            # Create table
+            conn.execute("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)")
+            # Insert
+            conn.execute("INSERT INTO users (name) VALUES (?)", ("Alice",))
+            conn.execute("INSERT INTO users (name) VALUES (?)", ("Bob",))
+            conn.commit()
+            # Query
+            cursor = conn.execute("SELECT * FROM users ORDER BY id")
+            rows = cursor.fetchall()
+            assert len(rows) == 2
+            assert rows[0]["name"] == "Alice"
+            assert rows[1]["name"] == "Bob"
+
+    def test_multiple_pools_different_databases(self, tmp_path):
+        """Multiple pools can manage different databases independently."""
+        pool1 = ConnectionPool(tmp_path / "db1.db")
+        pool2 = ConnectionPool(tmp_path / "db2.db")
+
+        with pool1.connection() as conn1:
+            conn1.execute("CREATE TABLE test (val INTEGER)")
+            conn1.execute("INSERT INTO test VALUES (1)")
+            conn1.commit()
+
+        with pool2.connection() as conn2:
+            conn2.execute("CREATE TABLE test (val INTEGER)")
+            conn2.execute("INSERT INTO test VALUES (2)")
+            conn2.commit()
+
+        # Verify isolation
+        with pool1.connection() as conn1:
+            result = conn1.execute("SELECT val FROM test").fetchone()[0]
+            assert result == 1
+
+        with pool2.connection() as conn2:
+            result = conn2.execute("SELECT val FROM test").fetchone()[0]
+            assert result == 2

tests/infrastructure/test_multimodal.py

@@ -0,0 +1,509 @@
+"""Tests for infrastructure.models.multimodal — multi-modal model management."""
+
+import json
+from unittest.mock import MagicMock, patch
+
+from infrastructure.models.multimodal import (
+    DEFAULT_FALLBACK_CHAINS,
+    KNOWN_MODEL_CAPABILITIES,
+    ModelCapability,
+    ModelInfo,
+    MultiModalManager,
+    get_model_for_capability,
+    model_supports_tools,
+    model_supports_vision,
+    pull_model_with_fallback,
+)
+
+# ---------------------------------------------------------------------------
+# ModelCapability enum
+# ---------------------------------------------------------------------------
+
+
+class TestModelCapability:
+    def test_members_exist(self):
+        assert ModelCapability.TEXT
+        assert ModelCapability.VISION
+        assert ModelCapability.AUDIO
+        assert ModelCapability.TOOLS
+        assert ModelCapability.JSON
+        assert ModelCapability.STREAMING
+
+    def test_all_members_unique(self):
+        values = [m.value for m in ModelCapability]
+        assert len(values) == len(set(values))
+
+
+# ---------------------------------------------------------------------------
+# ModelInfo dataclass
+# ---------------------------------------------------------------------------
+
+
+class TestModelInfo:
+    def test_defaults(self):
+        info = ModelInfo(name="test-model")
+        assert info.name == "test-model"
+        assert info.capabilities == set()
+        assert info.is_available is False
+        assert info.is_pulled is False
+        assert info.size_mb is None
+        assert info.description == ""
+
+    def test_supports_true(self):
+        info = ModelInfo(name="m", capabilities={ModelCapability.TEXT, ModelCapability.VISION})
+        assert info.supports(ModelCapability.TEXT) is True
+        assert info.supports(ModelCapability.VISION) is True
+
+    def test_supports_false(self):
+        info = ModelInfo(name="m", capabilities={ModelCapability.TEXT})
+        assert info.supports(ModelCapability.VISION) is False
+
+
+# ---------------------------------------------------------------------------
+# Known model capabilities lookup table
+# ---------------------------------------------------------------------------
+
+
+class TestKnownModelCapabilities:
+    def test_vision_models_have_vision(self):
+        vision_names = [
+            "llama3.2-vision",
+            "llava",
+            "moondream",
+            "qwen2.5-vl",
+        ]
+        for name in vision_names:
+            assert ModelCapability.VISION in KNOWN_MODEL_CAPABILITIES[name], name
+
+    def test_text_models_lack_vision(self):
+        text_only = ["deepseek-r1", "gemma2", "phi3"]
+        for name in text_only:
+            assert ModelCapability.VISION not in KNOWN_MODEL_CAPABILITIES[name], name
+
+    def test_all_models_have_text(self):
+        for name, caps in KNOWN_MODEL_CAPABILITIES.items():
+            assert ModelCapability.TEXT in caps, f"{name} should have TEXT"
+
+
+# ---------------------------------------------------------------------------
+# Default fallback chains
+# ---------------------------------------------------------------------------
+
+
+class TestDefaultFallbackChains:
+    def test_vision_chain_non_empty(self):
+        assert len(DEFAULT_FALLBACK_CHAINS[ModelCapability.VISION]) > 0
+
+    def test_tools_chain_non_empty(self):
+        assert len(DEFAULT_FALLBACK_CHAINS[ModelCapability.TOOLS]) > 0
+
+    def test_audio_chain_empty(self):
+        assert DEFAULT_FALLBACK_CHAINS[ModelCapability.AUDIO] == []
+
+
+# ---------------------------------------------------------------------------
+# Helpers to build a manager without hitting the network
+# ---------------------------------------------------------------------------
+
+
+def _fake_ollama_tags(*model_names: str) -> bytes:
+    """Build a JSON response mimicking Ollama /api/tags."""
+    models = []
+    for name in model_names:
+        models.append({"name": name, "size": 4 * 1024 * 1024 * 1024, "details": {"family": "test"}})
+    return json.dumps({"models": models}).encode()
+
+
+def _make_manager(model_names: list[str] | None = None) -> MultiModalManager:
+    """Create a MultiModalManager with mocked Ollama responses."""
+    if model_names is None:
+        # No models available — Ollama unreachable
+        with patch("urllib.request.urlopen", side_effect=ConnectionError("no ollama")):
+            return MultiModalManager(ollama_url="http://localhost:11434")
+
+    resp = MagicMock()
+    resp.__enter__ = MagicMock(return_value=resp)
+    resp.__exit__ = MagicMock(return_value=False)
+    resp.read.return_value = _fake_ollama_tags(*model_names)
+    resp.status = 200
+
+    with patch("urllib.request.urlopen", return_value=resp):
+        return MultiModalManager(ollama_url="http://localhost:11434")
+
+
+# ---------------------------------------------------------------------------
+# MultiModalManager — init & refresh
+# ---------------------------------------------------------------------------
+
+
+class TestMultiModalManagerInit:
+    def test_init_no_ollama(self):
+        mgr = _make_manager(None)
+        assert mgr.list_available_models() == []
+
+    def test_init_with_models(self):
+        mgr = _make_manager(["llama3.1:8b", "llava:7b"])
+        names = {m.name for m in mgr.list_available_models()}
+        assert names == {"llama3.1:8b", "llava:7b"}
+
+    def test_refresh_updates_models(self):
+        mgr = _make_manager([])
+        assert mgr.list_available_models() == []
+
+        resp = MagicMock()
+        resp.__enter__ = MagicMock(return_value=resp)
+        resp.__exit__ = MagicMock(return_value=False)
+        resp.read.return_value = _fake_ollama_tags("gemma2:9b")
+        resp.status = 200
+
+        with patch("urllib.request.urlopen", return_value=resp):
+            mgr.refresh()
+
+        names = {m.name for m in mgr.list_available_models()}
+        assert "gemma2:9b" in names
+
+
+# ---------------------------------------------------------------------------
+# _detect_capabilities
+# ---------------------------------------------------------------------------
+
+
+class TestDetectCapabilities:
+    def test_exact_match(self):
+        mgr = _make_manager(None)
+        caps = mgr._detect_capabilities("llava:7b")
+        assert ModelCapability.VISION in caps
+
+    def test_base_name_match(self):
+        mgr = _make_manager(None)
+        caps = mgr._detect_capabilities("llava:99b")
+        # "llava:99b" not in table, but "llava" is
+        assert ModelCapability.VISION in caps
+
+    def test_unknown_model_defaults_to_text(self):
+        mgr = _make_manager(None)
+        caps = mgr._detect_capabilities("totally-unknown-model:1b")
+        assert caps == {ModelCapability.TEXT, ModelCapability.STREAMING}
+
+
+# ---------------------------------------------------------------------------
+# get_model_capabilities / model_supports
+# ---------------------------------------------------------------------------
+
+
+class TestGetModelCapabilities:
+    def test_available_model(self):
+        mgr = _make_manager(["llava:7b"])
+        caps = mgr.get_model_capabilities("llava:7b")
+        assert ModelCapability.VISION in caps
+
+    def test_unavailable_model_uses_detection(self):
+        mgr = _make_manager([])
+        caps = mgr.get_model_capabilities("llava:7b")
+        assert ModelCapability.VISION in caps
+
+
+class TestModelSupports:
+    def test_supports_true(self):
+        mgr = _make_manager(["llava:7b"])
+        assert mgr.model_supports("llava:7b", ModelCapability.VISION) is True
+
+    def test_supports_false(self):
+        mgr = _make_manager(["deepseek-r1:7b"])
+        assert mgr.model_supports("deepseek-r1:7b", ModelCapability.VISION) is False
+
+
+# ---------------------------------------------------------------------------
+# get_models_with_capability
+# ---------------------------------------------------------------------------
+
+
+class TestGetModelsWithCapability:
+    def test_returns_vision_models(self):
+        mgr = _make_manager(["llava:7b", "deepseek-r1:7b"])
+        vision = mgr.get_models_with_capability(ModelCapability.VISION)
+        names = {m.name for m in vision}
+        assert "llava:7b" in names
+        assert "deepseek-r1:7b" not in names
+
+    def test_empty_when_none_available(self):
+        mgr = _make_manager(["deepseek-r1:7b"])
+        vision = mgr.get_models_with_capability(ModelCapability.VISION)
+        assert vision == []
+
+
+# ---------------------------------------------------------------------------
+# get_best_model_for
+# ---------------------------------------------------------------------------
+
+
+class TestGetBestModelFor:
+    def test_preferred_model_with_capability(self):
+        mgr = _make_manager(["llava:7b", "llama3.1:8b"])
+        result = mgr.get_best_model_for(ModelCapability.VISION, preferred_model="llava:7b")
+        assert result == "llava:7b"
+
+    def test_preferred_model_without_capability_uses_fallback(self):
+        mgr = _make_manager(["deepseek-r1:7b", "llava:7b"])
+        # preferred doesn't have VISION, fallback chain has llava:7b
+        result = mgr.get_best_model_for(ModelCapability.VISION, preferred_model="deepseek-r1:7b")
+        assert result == "llava:7b"
+
+    def test_fallback_chain_order(self):
+        # First in chain: llama3.2:3b
+        mgr = _make_manager(["llama3.2:3b", "llava:7b"])
+        result = mgr.get_best_model_for(ModelCapability.VISION)
+        assert result == "llama3.2:3b"
+
+    def test_any_capable_model_when_no_fallback(self):
+        mgr = _make_manager(["moondream:1.8b"])
+        mgr._fallback_chains[ModelCapability.VISION] = []  # clear chain
+        result = mgr.get_best_model_for(ModelCapability.VISION)
+        assert result == "moondream:1.8b"
+
+    def test_none_when_no_capable_model(self):
+        mgr = _make_manager(["deepseek-r1:7b"])
+        result = mgr.get_best_model_for(ModelCapability.VISION)
+        assert result is None
+
+    def test_preferred_model_not_available_skipped(self):
+        mgr = _make_manager(["llava:7b"])
+        # preferred_model "llava:13b" is not in available_models
+        result = mgr.get_best_model_for(ModelCapability.VISION, preferred_model="llava:13b")
+        assert result == "llava:7b"
+
+
+# ---------------------------------------------------------------------------
+# pull_model_with_fallback (manager method)
+# ---------------------------------------------------------------------------
+
+
+class TestPullModelWithFallback:
+    def test_already_available(self):
+        mgr = _make_manager(["llama3.1:8b"])
+        model, is_fallback = mgr.pull_model_with_fallback("llama3.1:8b")
+        assert model == "llama3.1:8b"
+        assert is_fallback is False
+
+    def test_pull_succeeds(self):
+        mgr = _make_manager([])
+
+        pull_resp = MagicMock()
+        pull_resp.__enter__ = MagicMock(return_value=pull_resp)
+        pull_resp.__exit__ = MagicMock(return_value=False)
+        pull_resp.status = 200
+
+        # After pull, refresh returns the model
+        refresh_resp = MagicMock()
+        refresh_resp.__enter__ = MagicMock(return_value=refresh_resp)
+        refresh_resp.__exit__ = MagicMock(return_value=False)
+        refresh_resp.read.return_value = _fake_ollama_tags("llama3.1:8b")
+        refresh_resp.status = 200
+
+        with patch("urllib.request.urlopen", side_effect=[pull_resp, refresh_resp]):
+            model, is_fallback = mgr.pull_model_with_fallback("llama3.1:8b")
+        assert model == "llama3.1:8b"
+        assert is_fallback is False
+
+    def test_pull_fails_uses_capability_fallback(self):
+        mgr = _make_manager(["llava:7b"])
+        with patch("urllib.request.urlopen", side_effect=ConnectionError("fail")):
+            model, is_fallback = mgr.pull_model_with_fallback(
+                "nonexistent-vision:1b",
+                capability=ModelCapability.VISION,
+            )
+        assert model == "llava:7b"
+        assert is_fallback is True
+
+    def test_pull_fails_uses_default_model(self):
+        mgr = _make_manager([settings_ollama_model := "llama3.1:8b"])
+        with (
+            patch("urllib.request.urlopen", side_effect=ConnectionError("fail")),
+            patch("infrastructure.models.multimodal.settings") as mock_settings,
+        ):
+            mock_settings.ollama_model = settings_ollama_model
+            mock_settings.ollama_url = "http://localhost:11434"
+            model, is_fallback = mgr.pull_model_with_fallback("missing-model:99b")
+        assert model == "llama3.1:8b"
+        assert is_fallback is True
+
+    def test_auto_pull_false_skips_pull(self):
+        mgr = _make_manager([])
+        with patch("infrastructure.models.multimodal.settings") as mock_settings:
+            mock_settings.ollama_model = "default"
+            model, is_fallback = mgr.pull_model_with_fallback("missing:1b", auto_pull=False)
+        # Falls through to absolute last resort
+        assert model == "missing:1b"
+        assert is_fallback is False
+
+    def test_absolute_last_resort(self):
+        mgr = _make_manager([])
+        with (
+            patch("urllib.request.urlopen", side_effect=ConnectionError("fail")),
+            patch("infrastructure.models.multimodal.settings") as mock_settings,
+        ):
+            mock_settings.ollama_model = "not-available"
+            model, is_fallback = mgr.pull_model_with_fallback("primary:1b")
+        assert model == "primary:1b"
+        assert is_fallback is False
+
+
+# ---------------------------------------------------------------------------
+# _pull_model
+# ---------------------------------------------------------------------------
+
+
+class TestPullModel:
+    def test_pull_success(self):
+        mgr = _make_manager([])
+
+        pull_resp = MagicMock()
+        pull_resp.__enter__ = MagicMock(return_value=pull_resp)
+        pull_resp.__exit__ = MagicMock(return_value=False)
+        pull_resp.status = 200
+
+        refresh_resp = MagicMock()
+        refresh_resp.__enter__ = MagicMock(return_value=refresh_resp)
+        refresh_resp.__exit__ = MagicMock(return_value=False)
+        refresh_resp.read.return_value = _fake_ollama_tags("new-model:1b")
+        refresh_resp.status = 200
+
+        with patch("urllib.request.urlopen", side_effect=[pull_resp, refresh_resp]):
+            assert mgr._pull_model("new-model:1b") is True
+
+    def test_pull_network_error(self):
+        mgr = _make_manager([])
+        with patch("urllib.request.urlopen", side_effect=ConnectionError("offline")):
+            assert mgr._pull_model("any-model:1b") is False
+
+
+# ---------------------------------------------------------------------------
+# configure_fallback_chain / get_fallback_chain
+# ---------------------------------------------------------------------------
+
+
+class TestFallbackChainConfig:
+    def test_configure_and_get(self):
+        mgr = _make_manager(None)
+        mgr.configure_fallback_chain(ModelCapability.VISION, ["model-a", "model-b"])
+        assert mgr.get_fallback_chain(ModelCapability.VISION) == ["model-a", "model-b"]
+
+    def test_get_returns_copy(self):
+        mgr = _make_manager(None)
+        chain = mgr.get_fallback_chain(ModelCapability.VISION)
+        chain.append("mutated")
+        assert "mutated" not in mgr.get_fallback_chain(ModelCapability.VISION)
+
+    def test_get_empty_for_unknown(self):
+        mgr = _make_manager(None)
+        # AUDIO has an empty chain by default
+        assert mgr.get_fallback_chain(ModelCapability.AUDIO) == []
+
+
+# ---------------------------------------------------------------------------
+# get_model_for_content
+# ---------------------------------------------------------------------------
+
+
+class TestGetModelForContent:
+    def test_image_content(self):
+        mgr = _make_manager(["llava:7b"])
+        model, is_fb = mgr.get_model_for_content("image")
+        assert model == "llava:7b"
+
+    def test_vision_content(self):
+        mgr = _make_manager(["llava:7b"])
+        model, _ = mgr.get_model_for_content("vision")
+        assert model == "llava:7b"
+
+    def test_multimodal_content(self):
+        mgr = _make_manager(["llava:7b"])
+        model, _ = mgr.get_model_for_content("multimodal")
+        assert model == "llava:7b"
+
+    def test_audio_content(self):
+        mgr = _make_manager(["llama3.1:8b"])
+        with patch("infrastructure.models.multimodal.settings") as mock_settings:
+            mock_settings.ollama_model = "llama3.1:8b"
+            mock_settings.ollama_url = "http://localhost:11434"
+            model, _ = mgr.get_model_for_content("audio")
+        assert model == "llama3.1:8b"
+
+    def test_text_content(self):
+        mgr = _make_manager(["llama3.1:8b"])
+        with patch("infrastructure.models.multimodal.settings") as mock_settings:
+            mock_settings.ollama_model = "llama3.1:8b"
+            mock_settings.ollama_url = "http://localhost:11434"
+            model, _ = mgr.get_model_for_content("text")
+        assert model == "llama3.1:8b"
+
+    def test_preferred_model_respected(self):
+        mgr = _make_manager(["llama3.2:3b", "llava:7b"])
+        model, _ = mgr.get_model_for_content("image", preferred_model="llama3.2:3b")
+        assert model == "llama3.2:3b"
+
+    def test_case_insensitive(self):
+        mgr = _make_manager(["llava:7b"])
+        model, _ = mgr.get_model_for_content("IMAGE")
+        assert model == "llava:7b"
+
+
+# ---------------------------------------------------------------------------
+# Module-level convenience functions
+# ---------------------------------------------------------------------------
+
+
+class TestConvenienceFunctions:
+    def _patch_manager(self, mgr):
+        return patch(
+            "infrastructure.models.multimodal._multimodal_manager",
+            mgr,
+        )
+
+    def test_get_model_for_capability(self):
+        mgr = _make_manager(["llava:7b"])
+        with self._patch_manager(mgr):
+            result = get_model_for_capability(ModelCapability.VISION)
+        assert result == "llava:7b"
+
+    def test_pull_model_with_fallback_convenience(self):
+        mgr = _make_manager(["llama3.1:8b"])
+        with self._patch_manager(mgr):
+            model, is_fb = pull_model_with_fallback("llama3.1:8b")
+        assert model == "llama3.1:8b"
+        assert is_fb is False
+
+    def test_model_supports_vision_true(self):
+        mgr = _make_manager(["llava:7b"])
+        with self._patch_manager(mgr):
+            assert model_supports_vision("llava:7b") is True
+
+    def test_model_supports_vision_false(self):
+        mgr = _make_manager(["llama3.1:8b"])
+        with self._patch_manager(mgr):
+            assert model_supports_vision("llama3.1:8b") is False
+
+    def test_model_supports_tools_true(self):
+        mgr = _make_manager(["llama3.1:8b"])
+        with self._patch_manager(mgr):
+            assert model_supports_tools("llama3.1:8b") is True
+
+    def test_model_supports_tools_false(self):
+        mgr = _make_manager(["deepseek-r1:7b"])
+        with self._patch_manager(mgr):
+            assert model_supports_tools("deepseek-r1:7b") is False
+
+
+# ---------------------------------------------------------------------------
+# ModelInfo in available_models — size_mb and description populated
+# ---------------------------------------------------------------------------
+
+
+class TestModelInfoPopulation:
+    def test_size_and_description(self):
+        mgr = _make_manager(["llama3.1:8b"])
+        info = mgr._available_models["llama3.1:8b"]
+        assert info.is_available is True
+        assert info.is_pulled is True
+        assert info.size_mb == 4 * 1024  # 4 GiB in MiB
+        assert info.description == "test"

tests/infrastructure/world/test_interface.py

@@ -0,0 +1,129 @@
+"""Tests for the WorldInterface contract and type system."""
+
+import pytest
+
+from infrastructure.world.interface import WorldInterface
+from infrastructure.world.types import (
+    ActionResult,
+    ActionStatus,
+    CommandInput,
+    PerceptionOutput,
+)
+
+# ---------------------------------------------------------------------------
+# Type construction
+# ---------------------------------------------------------------------------
+
+
+class TestPerceptionOutput:
+    def test_defaults(self):
+        p = PerceptionOutput()
+        assert p.location == ""
+        assert p.entities == []
+        assert p.events == []
+        assert p.raw == {}
+        assert p.timestamp is not None
+
+    def test_custom_values(self):
+        p = PerceptionOutput(
+            location="Balmora",
+            entities=["Guard", "Merchant"],
+            events=["door_opened"],
+        )
+        assert p.location == "Balmora"
+        assert len(p.entities) == 2
+        assert "door_opened" in p.events
+
+
+class TestCommandInput:
+    def test_minimal(self):
+        c = CommandInput(action="move")
+        assert c.action == "move"
+        assert c.target is None
+        assert c.parameters == {}
+
+    def test_with_target_and_params(self):
+        c = CommandInput(action="attack", target="Rat", parameters={"weapon": "sword"})
+        assert c.target == "Rat"
+        assert c.parameters["weapon"] == "sword"
+
+
+class TestActionResult:
+    def test_defaults(self):
+        r = ActionResult()
+        assert r.status == ActionStatus.SUCCESS
+        assert r.message == ""
+
+    def test_failure(self):
+        r = ActionResult(status=ActionStatus.FAILURE, message="blocked")
+        assert r.status == ActionStatus.FAILURE
+
+
+class TestActionStatus:
+    def test_values(self):
+        assert ActionStatus.SUCCESS.value == "success"
+        assert ActionStatus.FAILURE.value == "failure"
+        assert ActionStatus.PENDING.value == "pending"
+        assert ActionStatus.NOOP.value == "noop"
+
+
+# ---------------------------------------------------------------------------
+# Abstract contract
+# ---------------------------------------------------------------------------
+
+
+class TestWorldInterfaceContract:
+    """Verify the ABC cannot be instantiated directly."""
+
+    def test_cannot_instantiate(self):
+        with pytest.raises(TypeError):
+            WorldInterface()
+
+    def test_subclass_must_implement_observe(self):
+        class Incomplete(WorldInterface):
+            def act(self, command):
+                pass
+
+            def speak(self, message, target=None):
+                pass
+
+        with pytest.raises(TypeError):
+            Incomplete()
+
+    def test_subclass_must_implement_act(self):
+        class Incomplete(WorldInterface):
+            def observe(self):
+                return PerceptionOutput()
+
+            def speak(self, message, target=None):
+                pass
+
+        with pytest.raises(TypeError):
+            Incomplete()
+
+    def test_subclass_must_implement_speak(self):
+        class Incomplete(WorldInterface):
+            def observe(self):
+                return PerceptionOutput()
+
+            def act(self, command):
+                return ActionResult()
+
+        with pytest.raises(TypeError):
+            Incomplete()
+
+    def test_complete_subclass_instantiates(self):
+        class Complete(WorldInterface):
+            def observe(self):
+                return PerceptionOutput()
+
+            def act(self, command):
+                return ActionResult()
+
+            def speak(self, message, target=None):
+                pass
+
+        adapter = Complete()
+        assert adapter.is_connected is True  # default
+        assert isinstance(adapter.observe(), PerceptionOutput)
+        assert isinstance(adapter.act(CommandInput(action="test")), ActionResult)

tests/infrastructure/world/test_mock_adapter.py

@@ -0,0 +1,80 @@
+"""Tests for the MockWorldAdapter — full observe/act/speak cycle."""
+
+from infrastructure.world.adapters.mock import MockWorldAdapter
+from infrastructure.world.types import ActionStatus, CommandInput, PerceptionOutput
+
+
+class TestMockWorldAdapter:
+    def test_observe_returns_perception(self):
+        adapter = MockWorldAdapter(location="Vivec")
+        perception = adapter.observe()
+        assert isinstance(perception, PerceptionOutput)
+        assert perception.location == "Vivec"
+        assert perception.raw == {"adapter": "mock"}
+
+    def test_observe_entities(self):
+        adapter = MockWorldAdapter(entities=["Jiub", "Silt Strider"])
+        perception = adapter.observe()
+        assert perception.entities == ["Jiub", "Silt Strider"]
+
+    def test_act_logs_command(self):
+        adapter = MockWorldAdapter()
+        cmd = CommandInput(action="move", target="north")
+        result = adapter.act(cmd)
+        assert result.status == ActionStatus.SUCCESS
+        assert "move" in result.message
+        assert len(adapter.action_log) == 1
+        assert adapter.action_log[0].command.action == "move"
+
+    def test_act_multiple_commands(self):
+        adapter = MockWorldAdapter()
+        adapter.act(CommandInput(action="attack"))
+        adapter.act(CommandInput(action="defend"))
+        adapter.act(CommandInput(action="retreat"))
+        assert len(adapter.action_log) == 3
+
+    def test_speak_logs_message(self):
+        adapter = MockWorldAdapter()
+        adapter.speak("Hello, traveler!")
+        assert len(adapter.speech_log) == 1
+        assert adapter.speech_log[0]["message"] == "Hello, traveler!"
+        assert adapter.speech_log[0]["target"] is None
+
+    def test_speak_with_target(self):
+        adapter = MockWorldAdapter()
+        adapter.speak("Die, scum!", target="Cliff Racer")
+        assert adapter.speech_log[0]["target"] == "Cliff Racer"
+
+    def test_lifecycle(self):
+        adapter = MockWorldAdapter()
+        assert adapter.is_connected is False
+        adapter.connect()
+        assert adapter.is_connected is True
+        adapter.disconnect()
+        assert adapter.is_connected is False
+
+    def test_full_observe_act_speak_cycle(self):
+        """Acceptance criterion: full observe/act/speak cycle passes."""
+        adapter = MockWorldAdapter(
+            location="Seyda Neen",
+            entities=["Fargoth", "Hrisskar"],
+            events=["quest_started"],
+        )
+        adapter.connect()
+
+        # Observe
+        perception = adapter.observe()
+        assert perception.location == "Seyda Neen"
+        assert len(perception.entities) == 2
+        assert "quest_started" in perception.events
+
+        # Act
+        result = adapter.act(CommandInput(action="talk", target="Fargoth"))
+        assert result.status == ActionStatus.SUCCESS
+
+        # Speak
+        adapter.speak("Where is your ring, Fargoth?", target="Fargoth")
+        assert len(adapter.speech_log) == 1
+
+        adapter.disconnect()
+        assert adapter.is_connected is False

tests/infrastructure/world/test_registry.py

@@ -0,0 +1,68 @@
+"""Tests for the adapter registry."""
+
+import pytest
+
+from infrastructure.world.adapters.mock import MockWorldAdapter
+from infrastructure.world.registry import AdapterRegistry
+
+
+class TestAdapterRegistry:
+    def test_register_and_get(self):
+        reg = AdapterRegistry()
+        reg.register("mock", MockWorldAdapter)
+        adapter = reg.get("mock")
+        assert isinstance(adapter, MockWorldAdapter)
+
+    def test_register_with_kwargs(self):
+        reg = AdapterRegistry()
+        reg.register("mock", MockWorldAdapter)
+        adapter = reg.get("mock", location="Custom Room")
+        assert adapter._location == "Custom Room"
+
+    def test_get_unknown_raises(self):
+        reg = AdapterRegistry()
+        with pytest.raises(KeyError):
+            reg.get("nonexistent")
+
+    def test_register_non_subclass_raises(self):
+        reg = AdapterRegistry()
+        with pytest.raises(TypeError):
+            reg.register("bad", dict)
+
+    def test_list_adapters(self):
+        reg = AdapterRegistry()
+        reg.register("beta", MockWorldAdapter)
+        reg.register("alpha", MockWorldAdapter)
+        assert reg.list_adapters() == ["alpha", "beta"]
+
+    def test_contains(self):
+        reg = AdapterRegistry()
+        reg.register("mock", MockWorldAdapter)
+        assert "mock" in reg
+        assert "other" not in reg
+
+    def test_len(self):
+        reg = AdapterRegistry()
+        assert len(reg) == 0
+        reg.register("mock", MockWorldAdapter)
+        assert len(reg) == 1
+
+    def test_overwrite_warns(self, caplog):
+        import logging
+
+        reg = AdapterRegistry()
+        reg.register("mock", MockWorldAdapter)
+        with caplog.at_level(logging.WARNING):
+            reg.register("mock", MockWorldAdapter)
+        assert "Overwriting" in caplog.text
+
+
+class TestModuleLevelRegistry:
+    """Test the convenience functions in infrastructure.world.__init__."""
+
+    def test_register_and_get(self):
+        from infrastructure.world import get_adapter, register_adapter
+
+        register_adapter("test_mock", MockWorldAdapter)
+        adapter = get_adapter("test_mock")
+        assert isinstance(adapter, MockWorldAdapter)

tests/infrastructure/world/test_tes3mp_adapter.py

@@ -0,0 +1,44 @@
+"""Tests for the TES3MP stub adapter."""
+
+import pytest
+
+from infrastructure.world.adapters.tes3mp import TES3MPWorldAdapter
+from infrastructure.world.types import CommandInput
+
+
+class TestTES3MPStub:
+    """Acceptance criterion: stub imports cleanly and raises NotImplementedError."""
+
+    def test_instantiates(self):
+        adapter = TES3MPWorldAdapter(host="127.0.0.1", port=25565)
+        assert adapter._host == "127.0.0.1"
+        assert adapter._port == 25565
+
+    def test_is_connected_default_false(self):
+        adapter = TES3MPWorldAdapter()
+        assert adapter.is_connected is False
+
+    def test_connect_raises(self):
+        adapter = TES3MPWorldAdapter()
+        with pytest.raises(NotImplementedError, match="connect"):
+            adapter.connect()
+
+    def test_disconnect_raises(self):
+        adapter = TES3MPWorldAdapter()
+        with pytest.raises(NotImplementedError, match="disconnect"):
+            adapter.disconnect()
+
+    def test_observe_raises(self):
+        adapter = TES3MPWorldAdapter()
+        with pytest.raises(NotImplementedError, match="observe"):
+            adapter.observe()
+
+    def test_act_raises(self):
+        adapter = TES3MPWorldAdapter()
+        with pytest.raises(NotImplementedError, match="act"):
+            adapter.act(CommandInput(action="move"))
+
+    def test_speak_raises(self):
+        adapter = TES3MPWorldAdapter()
+        with pytest.raises(NotImplementedError, match="speak"):
+            adapter.speak("Hello")

tests/loop/test_cycle_retro.py

@@ -58,6 +58,55 @@ class TestDetectIssueFromBranch:
             assert mod.detect_issue_from_branch() is None
 
 
+class TestConsumeOnce:
+    """cycle_result.json must be deleted after reading."""
+
+    def test_cycle_result_deleted_after_read(self, mod, tmp_path):
+        """After _load_cycle_result() data is consumed in main(), the file is deleted."""
+        result_file = tmp_path / "cycle_result.json"
+        result_file.write_text('{"issue": 42, "type": "bug"}')
+
+        with (
+            patch.object(mod, "CYCLE_RESULT_FILE", result_file),
+            patch.object(mod, "RETRO_FILE", tmp_path / "retro" / "cycles.jsonl"),
+            patch.object(mod, "SUMMARY_FILE", tmp_path / "retro" / "summary.json"),
+            patch.object(mod, "EPOCH_COUNTER_FILE", tmp_path / "retro" / ".epoch_counter"),
+            patch(
+                "sys.argv",
+                ["cycle_retro", "--cycle", "1", "--success", "--main-green", "--duration", "60"],
+            ),
+        ):
+            mod.main()
+
+        assert not result_file.exists(), "cycle_result.json should be deleted after consumption"
+
+    def test_cycle_result_not_deleted_when_empty(self, mod, tmp_path):
+        """If cycle_result.json doesn't exist, no error occurs."""
+        result_file = tmp_path / "nonexistent_result.json"
+
+        with (
+            patch.object(mod, "CYCLE_RESULT_FILE", result_file),
+            patch.object(mod, "RETRO_FILE", tmp_path / "retro" / "cycles.jsonl"),
+            patch.object(mod, "SUMMARY_FILE", tmp_path / "retro" / "summary.json"),
+            patch.object(mod, "EPOCH_COUNTER_FILE", tmp_path / "retro" / ".epoch_counter"),
+            patch(
+                "sys.argv",
+                [
+                    "cycle_retro",
+                    "--cycle",
+                    "1",
+                    "--success",
+                    "--main-green",
+                    "--duration",
+                    "60",
+                    "--issue",
+                    "10",
+                ],
+            ),
+        ):
+            mod.main()  # Should not raise
+
+
 class TestBackfillExtractIssueNumber:
     """Tests for backfill_retro.extract_issue_number PR-number filtering."""
 

tests/loop/test_heartbeat.py

@@ -0,0 +1,176 @@
+"""Tests for Heartbeat v2 — WorldInterface-driven cognitive loop.
+
+Acceptance criteria:
+- With MockWorldAdapter: heartbeat runs, logs show observe→reason→act→reflect
+- Without adapter: existing think_once() behaviour unchanged
+- WebSocket broadcasts include current action and reasoning summary
+"""
+
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from infrastructure.world.adapters.mock import MockWorldAdapter
+from infrastructure.world.types import ActionStatus
+from loop.heartbeat import CycleRecord, Heartbeat
+
+
+@pytest.fixture
+def mock_adapter():
+    adapter = MockWorldAdapter(
+        location="Balmora",
+        entities=["Guard", "Merchant"],
+        events=["player_entered"],
+    )
+    adapter.connect()
+    return adapter
+
+
+class TestHeartbeatWithAdapter:
+    """With MockWorldAdapter: heartbeat runs full embodied cycle."""
+
+    @pytest.mark.asyncio
+    async def test_run_once_returns_cycle_record(self, mock_adapter):
+        hb = Heartbeat(world=mock_adapter)
+        record = await hb.run_once()
+        assert isinstance(record, CycleRecord)
+        assert record.cycle_id == 1
+
+    @pytest.mark.asyncio
+    async def test_observation_populated(self, mock_adapter):
+        hb = Heartbeat(world=mock_adapter)
+        record = await hb.run_once()
+        assert record.observation["location"] == "Balmora"
+        assert "Guard" in record.observation["entities"]
+        assert "player_entered" in record.observation["events"]
+
+    @pytest.mark.asyncio
+    async def test_action_dispatched_to_world(self, mock_adapter):
+        """Act phase should dispatch to world.act() for non-idle actions."""
+        hb = Heartbeat(world=mock_adapter)
+        record = await hb.run_once()
+        # The default loop phases don't set an explicit action, so it
+        # falls through to "idle" → NOOP. That's correct behaviour —
+        # the real LLM-powered reason phase will set action metadata.
+        assert record.action_status in (
+            ActionStatus.NOOP.value,
+            ActionStatus.SUCCESS.value,
+        )
+
+    @pytest.mark.asyncio
+    async def test_reflect_notes_present(self, mock_adapter):
+        hb = Heartbeat(world=mock_adapter)
+        record = await hb.run_once()
+        assert "Balmora" in record.reflect_notes
+
+    @pytest.mark.asyncio
+    async def test_cycle_count_increments(self, mock_adapter):
+        hb = Heartbeat(world=mock_adapter)
+        await hb.run_once()
+        await hb.run_once()
+        assert hb.cycle_count == 2
+        assert len(hb.history) == 2
+
+    @pytest.mark.asyncio
+    async def test_duration_recorded(self, mock_adapter):
+        hb = Heartbeat(world=mock_adapter)
+        record = await hb.run_once()
+        assert record.duration_ms >= 0
+
+    @pytest.mark.asyncio
+    async def test_on_cycle_callback(self, mock_adapter):
+        received = []
+
+        async def callback(record):
+            received.append(record)
+
+        hb = Heartbeat(world=mock_adapter, on_cycle=callback)
+        await hb.run_once()
+        assert len(received) == 1
+        assert received[0].cycle_id == 1
+
+
+class TestHeartbeatWithoutAdapter:
+    """Without adapter: existing think_once() behaviour unchanged."""
+
+    @pytest.mark.asyncio
+    async def test_passive_cycle(self):
+        hb = Heartbeat(world=None)
+        record = await hb.run_once()
+        assert record.action_taken == "think"
+        assert record.action_status == "noop"
+        assert "Passive" in record.reflect_notes
+
+    @pytest.mark.asyncio
+    async def test_passive_no_observation(self):
+        hb = Heartbeat(world=None)
+        record = await hb.run_once()
+        assert record.observation == {}
+
+
+class TestHeartbeatLifecycle:
+    def test_interval_property(self):
+        hb = Heartbeat(interval=60.0)
+        assert hb.interval == 60.0
+        hb.interval = 10.0
+        assert hb.interval == 10.0
+
+    def test_interval_minimum(self):
+        hb = Heartbeat()
+        hb.interval = 0.1
+        assert hb.interval == 1.0
+
+    def test_world_property(self):
+        hb = Heartbeat()
+        assert hb.world is None
+        adapter = MockWorldAdapter()
+        hb.world = adapter
+        assert hb.world is adapter
+
+    def test_stop_sets_flag(self):
+        hb = Heartbeat()
+        assert not hb.is_running
+        hb.stop()
+        assert not hb.is_running
+
+
+class TestHeartbeatBroadcast:
+    """WebSocket broadcasts include action and reasoning summary."""
+
+    @pytest.mark.asyncio
+    async def test_broadcast_called(self, mock_adapter):
+        with patch(
+            "loop.heartbeat.ws_manager",
+            create=True,
+        ) as mock_ws:
+            mock_ws.broadcast = AsyncMock()
+            # Patch the import inside heartbeat
+            with patch("infrastructure.ws_manager.handler.ws_manager") as ws_mod:
+                ws_mod.broadcast = AsyncMock()
+                hb = Heartbeat(world=mock_adapter)
+                await hb.run_once()
+                ws_mod.broadcast.assert_called_once()
+                call_args = ws_mod.broadcast.call_args
+                assert call_args[0][0] == "heartbeat.cycle"
+                data = call_args[0][1]
+                assert "action" in data
+                assert "reasoning_summary" in data
+                assert "observation" in data
+
+
+class TestHeartbeatLog:
+    """Verify logging of observe→reason→act→reflect cycle."""
+
+    @pytest.mark.asyncio
+    async def test_embodied_cycle_logs(self, mock_adapter, caplog):
+        import logging
+
+        with caplog.at_level(logging.INFO):
+            hb = Heartbeat(world=mock_adapter)
+            await hb.run_once()
+
+        messages = caplog.text
+        assert "Phase 1 (Gather)" in messages
+        assert "Phase 2 (Reason)" in messages
+        assert "Phase 3 (Act)" in messages
+        assert "Heartbeat cycle #1 complete" in messages

tests/loop/test_loop_guard_corrupt_queue.py

@@ -0,0 +1,97 @@
+"""Tests for load_queue corrupt JSON handling in loop_guard.py."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+import scripts.loop_guard as lg
+
+
+@pytest.fixture(autouse=True)
+def _isolate(tmp_path, monkeypatch):
+    """Redirect loop_guard paths to tmp_path for isolation."""
+    monkeypatch.setattr(lg, "QUEUE_FILE", tmp_path / "queue.json")
+    monkeypatch.setattr(lg, "IDLE_STATE_FILE", tmp_path / "idle_state.json")
+    monkeypatch.setattr(lg, "CYCLE_RESULT_FILE", tmp_path / "cycle_result.json")
+    monkeypatch.setattr(lg, "GITEA_API", "http://test:3000/api/v1")
+    monkeypatch.setattr(lg, "REPO_SLUG", "owner/repo")
+
+
+def test_load_queue_missing_file(tmp_path):
+    """Missing queue file returns empty list."""
+    result = lg.load_queue()
+    assert result == []
+
+
+def test_load_queue_valid_data(tmp_path):
+    """Valid queue.json returns ready items."""
+    data = [
+        {"issue": 1, "title": "Ready issue", "ready": True},
+        {"issue": 2, "title": "Not ready", "ready": False},
+    ]
+    lg.QUEUE_FILE.parent.mkdir(parents=True, exist_ok=True)
+    lg.QUEUE_FILE.write_text(json.dumps(data, indent=2))
+
+    result = lg.load_queue()
+    assert len(result) == 1
+    assert result[0]["issue"] == 1
+
+
+def test_load_queue_corrupt_json_logs_warning(tmp_path, capsys):
+    """Corrupt queue.json returns empty list and logs warning."""
+    lg.QUEUE_FILE.parent.mkdir(parents=True, exist_ok=True)
+    lg.QUEUE_FILE.write_text("not valid json {{{")
+
+    result = lg.load_queue()
+    assert result == []
+
+    captured = capsys.readouterr()
+    assert "WARNING" in captured.out
+    assert "Corrupt queue.json" in captured.out
+
+
+def test_load_queue_not_a_list(tmp_path):
+    """Queue.json that is not a list returns empty list."""
+    lg.QUEUE_FILE.parent.mkdir(parents=True, exist_ok=True)
+    lg.QUEUE_FILE.write_text(json.dumps({"not": "a list"}))
+
+    result = lg.load_queue()
+    assert result == []
+
+
+def test_load_queue_no_ready_items(tmp_path):
+    """Queue with no ready items returns empty list."""
+    data = [
+        {"issue": 1, "title": "Not ready 1", "ready": False},
+        {"issue": 2, "title": "Not ready 2", "ready": False},
+    ]
+    lg.QUEUE_FILE.parent.mkdir(parents=True, exist_ok=True)
+    lg.QUEUE_FILE.write_text(json.dumps(data, indent=2))
+
+    result = lg.load_queue()
+    assert result == []
+
+
+def test_load_queue_oserror_logs_warning(tmp_path, monkeypatch, capsys):
+    """OSError when reading queue.json returns empty list and logs warning."""
+    lg.QUEUE_FILE.parent.mkdir(parents=True, exist_ok=True)
+    lg.QUEUE_FILE.write_text("[]")
+
+    # Mock Path.read_text to raise OSError
+    original_read_text = Path.read_text
+
+    def mock_read_text(self, *args, **kwargs):
+        if self.name == "queue.json":
+            raise OSError("Permission denied")
+        return original_read_text(self, *args, **kwargs)
+
+    monkeypatch.setattr(Path, "read_text", mock_read_text)
+
+    result = lg.load_queue()
+    assert result == []
+
+    captured = capsys.readouterr()
+    assert "WARNING" in captured.out
+    assert "Cannot read queue.json" in captured.out

tests/loop/test_loop_guard_validate.py

@@ -0,0 +1,163 @@
+"""Tests for cycle_result.json validation in loop_guard.
+
+Covers validate_cycle_result(), _load_cycle_result(), and _is_issue_open().
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+import scripts.loop_guard as lg
+
+
+@pytest.fixture(autouse=True)
+def _isolate(tmp_path, monkeypatch):
+    """Redirect loop_guard paths to tmp_path for isolation."""
+    monkeypatch.setattr(lg, "CYCLE_RESULT_FILE", tmp_path / "cycle_result.json")
+    monkeypatch.setattr(lg, "CYCLE_DURATION", 300)
+    monkeypatch.setattr(lg, "GITEA_API", "http://test:3000/api/v1")
+    monkeypatch.setattr(lg, "REPO_SLUG", "owner/repo")
+
+
+def _write_cr(tmp_path, data: dict, age_seconds: float = 0) -> Path:
+    """Write a cycle_result.json and optionally backdate it."""
+    p = tmp_path / "cycle_result.json"
+    p.write_text(json.dumps(data))
+    if age_seconds:
+        mtime = time.time() - age_seconds
+        import os
+
+        os.utime(p, (mtime, mtime))
+    return p
+
+
+# --- _load_cycle_result ---
+
+
+def test_load_cycle_result_missing(tmp_path):
+    assert lg._load_cycle_result() == {}
+
+
+def test_load_cycle_result_valid(tmp_path):
+    _write_cr(tmp_path, {"issue": 42, "type": "fix"})
+    assert lg._load_cycle_result() == {"issue": 42, "type": "fix"}
+
+
+def test_load_cycle_result_markdown_fenced(tmp_path):
+    p = tmp_path / "cycle_result.json"
+    p.write_text('```json\n{"issue": 99}\n```')
+    assert lg._load_cycle_result() == {"issue": 99}
+
+
+def test_load_cycle_result_malformed(tmp_path):
+    p = tmp_path / "cycle_result.json"
+    p.write_text("not json at all")
+    assert lg._load_cycle_result() == {}
+
+
+# --- _is_issue_open ---
+
+
+def test_is_issue_open_true(monkeypatch):
+    monkeypatch.setattr(lg, "_get_token", lambda: "tok")
+    resp_data = json.dumps({"state": "open"}).encode()
+
+    class FakeResp:
+        def read(self):
+            return resp_data
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *a):
+            pass
+
+    with patch("urllib.request.urlopen", return_value=FakeResp()):
+        assert lg._is_issue_open(42) is True
+
+
+def test_is_issue_open_closed(monkeypatch):
+    monkeypatch.setattr(lg, "_get_token", lambda: "tok")
+    resp_data = json.dumps({"state": "closed"}).encode()
+
+    class FakeResp:
+        def read(self):
+            return resp_data
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *a):
+            pass
+
+    with patch("urllib.request.urlopen", return_value=FakeResp()):
+        assert lg._is_issue_open(42) is False
+
+
+def test_is_issue_open_no_token(monkeypatch):
+    monkeypatch.setattr(lg, "_get_token", lambda: "")
+    assert lg._is_issue_open(42) is None
+
+
+def test_is_issue_open_api_error(monkeypatch):
+    monkeypatch.setattr(lg, "_get_token", lambda: "tok")
+    with patch("urllib.request.urlopen", side_effect=OSError("timeout")):
+        assert lg._is_issue_open(42) is None
+
+
+# --- validate_cycle_result ---
+
+
+def test_validate_no_file(tmp_path):
+    """No file → returns False, no crash."""
+    assert lg.validate_cycle_result() is False
+
+
+def test_validate_fresh_file_open_issue(tmp_path, monkeypatch):
+    """Fresh file with open issue → kept."""
+    _write_cr(tmp_path, {"issue": 10})
+    monkeypatch.setattr(lg, "_is_issue_open", lambda n: True)
+    assert lg.validate_cycle_result() is False
+    assert (tmp_path / "cycle_result.json").exists()
+
+
+def test_validate_stale_file_removed(tmp_path):
+    """File older than 2× CYCLE_DURATION → removed."""
+    _write_cr(tmp_path, {"issue": 10}, age_seconds=700)
+    assert lg.validate_cycle_result() is True
+    assert not (tmp_path / "cycle_result.json").exists()
+
+
+def test_validate_fresh_file_closed_issue(tmp_path, monkeypatch):
+    """Fresh file referencing closed issue → removed."""
+    _write_cr(tmp_path, {"issue": 10})
+    monkeypatch.setattr(lg, "_is_issue_open", lambda n: False)
+    assert lg.validate_cycle_result() is True
+    assert not (tmp_path / "cycle_result.json").exists()
+
+
+def test_validate_api_failure_keeps_file(tmp_path, monkeypatch):
+    """API failure → file kept (graceful degradation)."""
+    _write_cr(tmp_path, {"issue": 10})
+    monkeypatch.setattr(lg, "_is_issue_open", lambda n: None)
+    assert lg.validate_cycle_result() is False
+    assert (tmp_path / "cycle_result.json").exists()
+
+
+def test_validate_no_issue_field(tmp_path):
+    """File without issue field → kept (only age check applies)."""
+    _write_cr(tmp_path, {"type": "fix"})
+    assert lg.validate_cycle_result() is False
+    assert (tmp_path / "cycle_result.json").exists()
+
+
+def test_validate_stale_threshold_boundary(tmp_path, monkeypatch):
+    """File just under threshold → kept (not stale yet)."""
+    _write_cr(tmp_path, {"issue": 10}, age_seconds=599)
+    monkeypatch.setattr(lg, "_is_issue_open", lambda n: True)
+    assert lg.validate_cycle_result() is False
+    assert (tmp_path / "cycle_result.json").exists()

tests/scripts/test_triage_score_validation.py

@@ -0,0 +1,159 @@
+"""Tests for queue.json validation and backup in triage_score.py."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+import scripts.triage_score as ts
+
+
+@pytest.fixture(autouse=True)
+def _isolate(tmp_path, monkeypatch):
+    """Redirect triage_score paths to tmp_path for isolation."""
+    monkeypatch.setattr(ts, "QUEUE_FILE", tmp_path / "queue.json")
+    monkeypatch.setattr(ts, "QUEUE_BACKUP_FILE", tmp_path / "queue.json.bak")
+    monkeypatch.setattr(ts, "RETRO_FILE", tmp_path / "retro" / "triage.jsonl")
+    monkeypatch.setattr(ts, "QUARANTINE_FILE", tmp_path / "quarantine.json")
+    monkeypatch.setattr(ts, "CYCLE_RETRO_FILE", tmp_path / "retro" / "cycles.jsonl")
+
+
+def test_backup_created_on_write(tmp_path):
+    """When writing queue.json, a backup should be created from previous valid file."""
+    # Create initial valid queue file
+    initial_data = [{"issue": 1, "title": "Test", "ready": True}]
+    ts.QUEUE_FILE.parent.mkdir(parents=True, exist_ok=True)
+    ts.QUEUE_FILE.write_text(json.dumps(initial_data))
+
+    # Write new data
+    new_data = [{"issue": 2, "title": "New", "ready": True}]
+    ts.QUEUE_FILE.write_text(json.dumps(new_data, indent=2) + "\n")
+
+    # Manually run the backup logic as run_triage would
+    if ts.QUEUE_FILE.exists():
+        try:
+            json.loads(ts.QUEUE_FILE.read_text())
+            ts.QUEUE_BACKUP_FILE.write_text(ts.QUEUE_FILE.read_text())
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    # Both files should exist with same content
+    assert ts.QUEUE_BACKUP_FILE.exists()
+    assert json.loads(ts.QUEUE_BACKUP_FILE.read_text()) == new_data
+
+
+def test_corrupt_queue_restored_from_backup(tmp_path, capsys):
+    """If queue.json is corrupt, it should be restored from backup."""
+    # Create a valid backup
+    valid_data = [{"issue": 1, "title": "Backup", "ready": True}]
+    ts.QUEUE_BACKUP_FILE.parent.mkdir(parents=True, exist_ok=True)
+    ts.QUEUE_BACKUP_FILE.write_text(json.dumps(valid_data, indent=2) + "\n")
+
+    # Create a corrupt queue file
+    ts.QUEUE_FILE.parent.mkdir(parents=True, exist_ok=True)
+    ts.QUEUE_FILE.write_text("not valid json {{{")
+
+    # Run validation and restore logic
+    try:
+        json.loads(ts.QUEUE_FILE.read_text())
+    except (json.JSONDecodeError, OSError):
+        if ts.QUEUE_BACKUP_FILE.exists():
+            try:
+                backup_data = ts.QUEUE_BACKUP_FILE.read_text()
+                json.loads(backup_data)  # Validate backup
+                ts.QUEUE_FILE.write_text(backup_data)
+                print("[triage] Restored queue.json from backup")
+            except (json.JSONDecodeError, OSError):
+                ts.QUEUE_FILE.write_text("[]\n")
+        else:
+            ts.QUEUE_FILE.write_text("[]\n")
+
+    # Queue should be restored from backup
+    assert json.loads(ts.QUEUE_FILE.read_text()) == valid_data
+    captured = capsys.readouterr()
+    assert "Restored queue.json from backup" in captured.out
+
+
+def test_corrupt_queue_no_backup_writes_empty_list(tmp_path):
+    """If queue.json is corrupt and no backup exists, write empty list."""
+    # Ensure no backup exists
+    assert not ts.QUEUE_BACKUP_FILE.exists()
+
+    # Create a corrupt queue file
+    ts.QUEUE_FILE.parent.mkdir(parents=True, exist_ok=True)
+    ts.QUEUE_FILE.write_text("not valid json {{{")
+
+    # Run validation and restore logic
+    try:
+        json.loads(ts.QUEUE_FILE.read_text())
+    except (json.JSONDecodeError, OSError):
+        if ts.QUEUE_BACKUP_FILE.exists():
+            try:
+                backup_data = ts.QUEUE_BACKUP_FILE.read_text()
+                json.loads(backup_data)
+                ts.QUEUE_FILE.write_text(backup_data)
+            except (json.JSONDecodeError, OSError):
+                ts.QUEUE_FILE.write_text("[]\n")
+        else:
+            ts.QUEUE_FILE.write_text("[]\n")
+
+    # Should have empty list
+    assert json.loads(ts.QUEUE_FILE.read_text()) == []
+
+
+def test_corrupt_backup_writes_empty_list(tmp_path):
+    """If both queue.json and backup are corrupt, write empty list."""
+    # Create a corrupt backup
+    ts.QUEUE_BACKUP_FILE.parent.mkdir(parents=True, exist_ok=True)
+    ts.QUEUE_BACKUP_FILE.write_text("also corrupt backup")
+
+    # Create a corrupt queue file
+    ts.QUEUE_FILE.parent.mkdir(parents=True, exist_ok=True)
+    ts.QUEUE_FILE.write_text("not valid json {{{")
+
+    # Run validation and restore logic
+    try:
+        json.loads(ts.QUEUE_FILE.read_text())
+    except (json.JSONDecodeError, OSError):
+        if ts.QUEUE_BACKUP_FILE.exists():
+            try:
+                backup_data = ts.QUEUE_BACKUP_FILE.read_text()
+                json.loads(backup_data)
+                ts.QUEUE_FILE.write_text(backup_data)
+            except (json.JSONDecodeError, OSError):
+                ts.QUEUE_FILE.write_text("[]\n")
+        else:
+            ts.QUEUE_FILE.write_text("[]\n")
+
+    # Should have empty list
+    assert json.loads(ts.QUEUE_FILE.read_text()) == []
+
+
+def test_valid_queue_not_corrupt_no_backup_overwrite(tmp_path):
+    """Don't overwrite backup if current queue.json is corrupt."""
+    # Create a valid backup
+    valid_backup = [{"issue": 99, "title": "Old Backup", "ready": True}]
+    ts.QUEUE_BACKUP_FILE.parent.mkdir(parents=True, exist_ok=True)
+    ts.QUEUE_BACKUP_FILE.write_text(json.dumps(valid_backup, indent=2) + "\n")
+
+    # Create a corrupt queue file
+    ts.QUEUE_FILE.parent.mkdir(parents=True, exist_ok=True)
+    ts.QUEUE_FILE.write_text("corrupt data")
+
+    # Try to save backup (should skip because current is corrupt)
+    if ts.QUEUE_FILE.exists():
+        try:
+            json.loads(ts.QUEUE_FILE.read_text())  # This will fail
+            ts.QUEUE_BACKUP_FILE.write_text(ts.QUEUE_FILE.read_text())
+        except (json.JSONDecodeError, OSError):
+            pass  # Should hit this branch
+
+    # Backup should still have original valid data
+    assert json.loads(ts.QUEUE_BACKUP_FILE.read_text()) == valid_backup
+
+
+def test_backup_path_configuration():
+    """Ensure backup file path is properly configured relative to queue file."""
+    assert ts.QUEUE_BACKUP_FILE.parent == ts.QUEUE_FILE.parent
+    assert ts.QUEUE_BACKUP_FILE.name == "queue.json.bak"
+    assert ts.QUEUE_FILE.name == "queue.json"

tests/spark/test_advisor.py

@@ -0,0 +1,327 @@
+"""Comprehensive tests for spark.advisor module.
+
+Covers all advisory-generation helpers:
+- _check_failure_patterns (grouped agent failures)
+- _check_agent_performance (top / struggling agents)
+- _check_bid_patterns (spread + high average)
+- _check_prediction_accuracy (low / high accuracy)
+- _check_system_activity (idle / tasks-posted-but-no-completions)
+- generate_advisories (integration, sorting, min-events guard)
+"""
+
+import json
+
+from spark.advisor import (
+    _MIN_EVENTS,
+    Advisory,
+    _check_agent_performance,
+    _check_bid_patterns,
+    _check_failure_patterns,
+    _check_prediction_accuracy,
+    _check_system_activity,
+    generate_advisories,
+)
+from spark.memory import record_event
+
+# ── Advisory dataclass ─────────────────────────────────────────────────────
+
+
+class TestAdvisoryDataclass:
+    def test_defaults(self):
+        a = Advisory(
+            category="test",
+            priority=0.5,
+            title="T",
+            detail="D",
+            suggested_action="A",
+        )
+        assert a.subject is None
+        assert a.evidence_count == 0
+
+    def test_all_fields(self):
+        a = Advisory(
+            category="c",
+            priority=0.9,
+            title="T",
+            detail="D",
+            suggested_action="A",
+            subject="agent-1",
+            evidence_count=7,
+        )
+        assert a.subject == "agent-1"
+        assert a.evidence_count == 7
+
+
+# ── _check_failure_patterns ────────────────────────────────────────────────
+
+
+class TestCheckFailurePatterns:
+    def test_no_failures_returns_empty(self):
+        assert _check_failure_patterns() == []
+
+    def test_single_failure_not_enough(self):
+        record_event("task_failed", "once", agent_id="a1", task_id="t1")
+        assert _check_failure_patterns() == []
+
+    def test_two_failures_triggers_advisory(self):
+        for i in range(2):
+            record_event("task_failed", f"fail {i}", agent_id="agent-abc", task_id=f"t{i}")
+        results = _check_failure_patterns()
+        assert len(results) == 1
+        assert results[0].category == "failure_prevention"
+        assert results[0].subject == "agent-abc"
+        assert results[0].evidence_count == 2
+
+    def test_priority_scales_with_count(self):
+        for i in range(5):
+            record_event("task_failed", f"fail {i}", agent_id="agent-x", task_id=f"f{i}")
+        results = _check_failure_patterns()
+        assert len(results) == 1
+        assert results[0].priority > 0.5
+
+    def test_priority_capped_at_one(self):
+        for i in range(20):
+            record_event("task_failed", f"fail {i}", agent_id="agent-y", task_id=f"ff{i}")
+        results = _check_failure_patterns()
+        assert results[0].priority <= 1.0
+
+    def test_multiple_agents_separate_advisories(self):
+        for i in range(3):
+            record_event("task_failed", f"a fail {i}", agent_id="agent-a", task_id=f"a{i}")
+            record_event("task_failed", f"b fail {i}", agent_id="agent-b", task_id=f"b{i}")
+        results = _check_failure_patterns()
+        assert len(results) == 2
+        subjects = {r.subject for r in results}
+        assert subjects == {"agent-a", "agent-b"}
+
+    def test_events_without_agent_id_skipped(self):
+        for i in range(3):
+            record_event("task_failed", f"no-agent {i}", task_id=f"na{i}")
+        assert _check_failure_patterns() == []
+
+
+# ── _check_agent_performance ───────────────────────────────────────────────
+
+
+class TestCheckAgentPerformance:
+    def test_no_events_returns_empty(self):
+        assert _check_agent_performance() == []
+
+    def test_too_few_tasks_skipped(self):
+        record_event("task_completed", "done", agent_id="agent-1", task_id="t1")
+        assert _check_agent_performance() == []
+
+    def test_high_performer_detected(self):
+        for i in range(4):
+            record_event("task_completed", f"done {i}", agent_id="agent-star", task_id=f"s{i}")
+        results = _check_agent_performance()
+        perf = [r for r in results if r.category == "agent_performance"]
+        assert len(perf) == 1
+        assert "excels" in perf[0].title
+        assert perf[0].subject == "agent-star"
+
+    def test_struggling_agent_detected(self):
+        # 1 success, 4 failures = 20% rate
+        record_event("task_completed", "ok", agent_id="agent-bad", task_id="ok1")
+        for i in range(4):
+            record_event("task_failed", f"nope {i}", agent_id="agent-bad", task_id=f"bad{i}")
+        results = _check_agent_performance()
+        struggling = [r for r in results if "struggling" in r.title]
+        assert len(struggling) == 1
+        assert struggling[0].priority > 0.5
+
+    def test_middling_agent_no_advisory(self):
+        # 50% success rate — neither excelling nor struggling
+        for i in range(3):
+            record_event("task_completed", f"ok {i}", agent_id="agent-mid", task_id=f"m{i}")
+        for i in range(3):
+            record_event("task_failed", f"nope {i}", agent_id="agent-mid", task_id=f"mf{i}")
+        results = _check_agent_performance()
+        mid_advisories = [r for r in results if r.subject == "agent-mid"]
+        assert mid_advisories == []
+
+    def test_events_without_agent_id_skipped(self):
+        for i in range(5):
+            record_event("task_completed", f"done {i}", task_id=f"no-agent-{i}")
+        assert _check_agent_performance() == []
+
+
+# ── _check_bid_patterns ────────────────────────────────────────────────────
+
+
+class TestCheckBidPatterns:
+    def _record_bids(self, amounts):
+        for i, sats in enumerate(amounts):
+            record_event(
+                "bid_submitted",
+                f"bid {i}",
+                agent_id=f"a{i}",
+                task_id=f"bt{i}",
+                data=json.dumps({"bid_sats": sats}),
+            )
+
+    def test_too_few_bids_returns_empty(self):
+        self._record_bids([10, 20, 30])
+        assert _check_bid_patterns() == []
+
+    def test_wide_spread_detected(self):
+        # avg=50, spread=90 > 50*1.5=75
+        self._record_bids([5, 10, 50, 90, 95])
+        results = _check_bid_patterns()
+        spread_advisories = [r for r in results if "spread" in r.title.lower()]
+        assert len(spread_advisories) == 1
+
+    def test_high_average_detected(self):
+        self._record_bids([80, 85, 90, 95, 100])
+        results = _check_bid_patterns()
+        high_avg = [r for r in results if "High average" in r.title]
+        assert len(high_avg) == 1
+
+    def test_normal_bids_no_advisory(self):
+        # Tight spread, low average
+        self._record_bids([30, 32, 28, 31, 29])
+        results = _check_bid_patterns()
+        assert results == []
+
+    def test_invalid_json_data_skipped(self):
+        for i in range(6):
+            record_event(
+                "bid_submitted",
+                f"bid {i}",
+                agent_id=f"a{i}",
+                task_id=f"inv{i}",
+                data="not-json",
+            )
+        results = _check_bid_patterns()
+        assert results == []
+
+    def test_zero_bid_sats_skipped(self):
+        for i in range(6):
+            record_event(
+                "bid_submitted",
+                f"bid {i}",
+                data=json.dumps({"bid_sats": 0}),
+            )
+        assert _check_bid_patterns() == []
+
+    def test_both_spread_and_high_avg(self):
+        # Wide spread AND high average: avg=82, spread=150 > 82*1.5=123
+        self._record_bids([5, 80, 90, 100, 155])
+        results = _check_bid_patterns()
+        assert len(results) == 2
+
+
+# ── _check_prediction_accuracy ─────────────────────────────────────────────
+
+
+class TestCheckPredictionAccuracy:
+    def test_too_few_evaluations(self):
+        assert _check_prediction_accuracy() == []
+
+    def test_low_accuracy_advisory(self):
+        from spark.eidos import evaluate_prediction, predict_task_outcome
+
+        for i in range(4):
+            predict_task_outcome(f"pa-{i}", "task", ["agent-a"])
+            evaluate_prediction(f"pa-{i}", "agent-wrong", task_succeeded=False, winning_bid=999)
+        results = _check_prediction_accuracy()
+        low = [r for r in results if "Low prediction" in r.title]
+        assert len(low) == 1
+        assert low[0].priority > 0.5
+
+    def test_high_accuracy_advisory(self):
+        from spark.eidos import evaluate_prediction, predict_task_outcome
+
+        for i in range(4):
+            predict_task_outcome(f"ph-{i}", "task", ["agent-a"])
+            evaluate_prediction(f"ph-{i}", "agent-a", task_succeeded=True, winning_bid=30)
+        results = _check_prediction_accuracy()
+        high = [r for r in results if "Strong prediction" in r.title]
+        assert len(high) == 1
+
+    def test_middling_accuracy_no_advisory(self):
+        from spark.eidos import evaluate_prediction, predict_task_outcome
+
+        # Mix of correct and incorrect to get ~0.5 accuracy
+        for i in range(3):
+            predict_task_outcome(f"pm-{i}", "task", ["agent-a"])
+            evaluate_prediction(f"pm-{i}", "agent-a", task_succeeded=True, winning_bid=30)
+        for i in range(3):
+            predict_task_outcome(f"pmx-{i}", "task", ["agent-a"])
+            evaluate_prediction(f"pmx-{i}", "agent-wrong", task_succeeded=False, winning_bid=999)
+        results = _check_prediction_accuracy()
+        # avg should be middling — neither low nor high advisory
+        low = [r for r in results if "Low" in r.title]
+        high = [r for r in results if "Strong" in r.title]
+        # At least one side should be empty (depends on exact accuracy)
+        assert not (low and high)
+
+
+# ── _check_system_activity ─────────────────────────────────────────────────
+
+
+class TestCheckSystemActivity:
+    def test_no_events_idle_advisory(self):
+        results = _check_system_activity()
+        assert len(results) == 1
+        assert "No swarm activity" in results[0].title
+
+    def test_has_events_no_idle_advisory(self):
+        record_event("task_completed", "done", task_id="t1")
+        results = _check_system_activity()
+        idle = [r for r in results if "No swarm activity" in r.title]
+        assert idle == []
+
+    def test_tasks_posted_but_none_completing(self):
+        for i in range(5):
+            record_event("task_posted", f"posted {i}", task_id=f"tp{i}")
+        results = _check_system_activity()
+        stalled = [r for r in results if "none completing" in r.title.lower()]
+        assert len(stalled) == 1
+        assert stalled[0].evidence_count >= 4
+
+    def test_posts_with_completions_no_stalled_advisory(self):
+        for i in range(5):
+            record_event("task_posted", f"posted {i}", task_id=f"tpx{i}")
+        record_event("task_completed", "done", task_id="tpx0")
+        results = _check_system_activity()
+        stalled = [r for r in results if "none completing" in r.title.lower()]
+        assert stalled == []
+
+
+# ── generate_advisories (integration) ──────────────────────────────────────
+
+
+class TestGenerateAdvisories:
+    def test_below_min_events_returns_insufficient(self):
+        advisories = generate_advisories()
+        assert len(advisories) >= 1
+        assert advisories[0].title == "Insufficient data"
+        assert advisories[0].evidence_count == 0
+
+    def test_exactly_at_min_events_proceeds(self):
+        for i in range(_MIN_EVENTS):
+            record_event("task_posted", f"ev {i}", task_id=f"min{i}")
+        advisories = generate_advisories()
+        insufficient = [a for a in advisories if a.title == "Insufficient data"]
+        assert insufficient == []
+
+    def test_results_sorted_by_priority_descending(self):
+        for i in range(5):
+            record_event("task_posted", f"posted {i}", task_id=f"sp{i}")
+        for i in range(3):
+            record_event("task_failed", f"fail {i}", agent_id="agent-fail", task_id=f"sf{i}")
+        advisories = generate_advisories()
+        if len(advisories) >= 2:
+            for i in range(len(advisories) - 1):
+                assert advisories[i].priority >= advisories[i + 1].priority
+
+    def test_multiple_categories_produced(self):
+        # Create failures + posted-no-completions
+        for i in range(5):
+            record_event("task_failed", f"fail {i}", agent_id="agent-bad", task_id=f"mf{i}")
+        for i in range(5):
+            record_event("task_posted", f"posted {i}", task_id=f"mp{i}")
+        advisories = generate_advisories()
+        categories = {a.category for a in advisories}
+        assert len(categories) >= 2

tests/spark/test_eidos.py

@@ -0,0 +1,299 @@
+"""Comprehensive tests for spark.eidos module.
+
+Covers:
+- _get_conn (schema creation, WAL, busy timeout)
+- predict_task_outcome (baseline, with history, edge cases)
+- evaluate_prediction (correct, wrong, missing, double-eval)
+- _compute_accuracy (all components, edge cases)
+- get_predictions (filters: task_id, evaluated_only, limit)
+- get_accuracy_stats (empty, after evaluations)
+"""
+
+import pytest
+
+from spark.eidos import (
+    Prediction,
+    _compute_accuracy,
+    evaluate_prediction,
+    get_accuracy_stats,
+    get_predictions,
+    predict_task_outcome,
+)
+
+# ── Prediction dataclass ──────────────────────────────────────────────────
+
+
+class TestPredictionDataclass:
+    def test_defaults(self):
+        p = Prediction(
+            id="1",
+            task_id="t1",
+            prediction_type="outcome",
+            predicted_value="{}",
+            actual_value=None,
+            accuracy=None,
+            created_at="2026-01-01",
+            evaluated_at=None,
+        )
+        assert p.actual_value is None
+        assert p.accuracy is None
+
+
+# ── predict_task_outcome ──────────────────────────────────────────────────
+
+
+class TestPredictTaskOutcome:
+    def test_baseline_no_history(self):
+        result = predict_task_outcome("t-base", "Do stuff", ["a1", "a2"])
+        assert result["likely_winner"] == "a1"
+        assert result["success_probability"] == 0.7
+        assert result["estimated_bid_range"] == [20, 80]
+        assert "baseline" in result["reasoning"]
+        assert "prediction_id" in result
+
+    def test_empty_candidates(self):
+        result = predict_task_outcome("t-empty", "Nothing", [])
+        assert result["likely_winner"] is None
+
+    def test_history_selects_best_agent(self):
+        history = {
+            "a1": {"success_rate": 0.3, "avg_winning_bid": 40},
+            "a2": {"success_rate": 0.95, "avg_winning_bid": 50},
+        }
+        result = predict_task_outcome("t-hist", "Task", ["a1", "a2"], agent_history=history)
+        assert result["likely_winner"] == "a2"
+        assert result["success_probability"] > 0.7
+
+    def test_history_agent_not_in_candidates_ignored(self):
+        history = {
+            "a-outside": {"success_rate": 0.99, "avg_winning_bid": 10},
+        }
+        result = predict_task_outcome("t-out", "Task", ["a1"], agent_history=history)
+        # a-outside not in candidates, so falls back to baseline
+        assert result["likely_winner"] == "a1"
+
+    def test_history_adjusts_bid_range(self):
+        history = {
+            "a1": {"success_rate": 0.5, "avg_winning_bid": 100},
+            "a2": {"success_rate": 0.8, "avg_winning_bid": 200},
+        }
+        result = predict_task_outcome("t-bid", "Task", ["a1", "a2"], agent_history=history)
+        low, high = result["estimated_bid_range"]
+        assert low == max(1, int(100 * 0.8))
+        assert high == int(200 * 1.2)
+
+    def test_history_with_zero_avg_bid_skipped(self):
+        history = {
+            "a1": {"success_rate": 0.8, "avg_winning_bid": 0},
+        }
+        result = predict_task_outcome("t-zero-bid", "Task", ["a1"], agent_history=history)
+        # Zero avg_winning_bid should be skipped, keep default range
+        assert result["estimated_bid_range"] == [20, 80]
+
+    def test_prediction_stored_in_db(self):
+        result = predict_task_outcome("t-db", "Store me", ["a1"])
+        preds = get_predictions(task_id="t-db")
+        assert len(preds) == 1
+        assert preds[0].id == result["prediction_id"]
+        assert preds[0].prediction_type == "outcome"
+
+    def test_success_probability_clamped(self):
+        history = {
+            "a1": {"success_rate": 1.5, "avg_winning_bid": 50},
+        }
+        result = predict_task_outcome("t-clamp", "Task", ["a1"], agent_history=history)
+        assert result["success_probability"] <= 1.0
+
+
+# ── evaluate_prediction ───────────────────────────────────────────────────
+
+
+class TestEvaluatePrediction:
+    def test_correct_prediction(self):
+        predict_task_outcome("t-eval-ok", "Task", ["a1"])
+        result = evaluate_prediction("t-eval-ok", "a1", task_succeeded=True, winning_bid=30)
+        assert result is not None
+        assert 0.0 <= result["accuracy"] <= 1.0
+        assert result["actual"]["winner"] == "a1"
+        assert result["actual"]["succeeded"] is True
+
+    def test_wrong_prediction(self):
+        predict_task_outcome("t-eval-wrong", "Task", ["a1"])
+        result = evaluate_prediction("t-eval-wrong", "a2", task_succeeded=False)
+        assert result is not None
+        assert result["accuracy"] < 1.0
+
+    def test_no_prediction_returns_none(self):
+        result = evaluate_prediction("nonexistent", "a1", task_succeeded=True)
+        assert result is None
+
+    def test_double_evaluation_returns_none(self):
+        predict_task_outcome("t-double", "Task", ["a1"])
+        evaluate_prediction("t-double", "a1", task_succeeded=True)
+        result = evaluate_prediction("t-double", "a1", task_succeeded=True)
+        assert result is None
+
+    def test_evaluation_updates_db(self):
+        predict_task_outcome("t-upd", "Task", ["a1"])
+        evaluate_prediction("t-upd", "a1", task_succeeded=True, winning_bid=50)
+        preds = get_predictions(task_id="t-upd", evaluated_only=True)
+        assert len(preds) == 1
+        assert preds[0].accuracy is not None
+        assert preds[0].actual_value is not None
+        assert preds[0].evaluated_at is not None
+
+    def test_winning_bid_none(self):
+        predict_task_outcome("t-nobid", "Task", ["a1"])
+        result = evaluate_prediction("t-nobid", "a1", task_succeeded=True)
+        assert result is not None
+        assert result["actual"]["winning_bid"] is None
+
+
+# ── _compute_accuracy ─────────────────────────────────────────────────────
+
+
+class TestComputeAccuracy:
+    def test_perfect_match(self):
+        predicted = {
+            "likely_winner": "a1",
+            "success_probability": 1.0,
+            "estimated_bid_range": [20, 40],
+        }
+        actual = {"winner": "a1", "succeeded": True, "winning_bid": 30}
+        assert _compute_accuracy(predicted, actual) == pytest.approx(1.0, abs=0.01)
+
+    def test_all_wrong(self):
+        predicted = {
+            "likely_winner": "a1",
+            "success_probability": 1.0,
+            "estimated_bid_range": [10, 20],
+        }
+        actual = {"winner": "a2", "succeeded": False, "winning_bid": 100}
+        assert _compute_accuracy(predicted, actual) < 0.3
+
+    def test_no_winner_in_predicted(self):
+        predicted = {"success_probability": 0.5, "estimated_bid_range": [20, 40]}
+        actual = {"winner": "a1", "succeeded": True, "winning_bid": 30}
+        acc = _compute_accuracy(predicted, actual)
+        # Winner component skipped, success + bid counted
+        assert 0.0 <= acc <= 1.0
+
+    def test_no_winner_in_actual(self):
+        predicted = {"likely_winner": "a1", "success_probability": 0.5}
+        actual = {"succeeded": True}
+        acc = _compute_accuracy(predicted, actual)
+        assert 0.0 <= acc <= 1.0
+
+    def test_bid_outside_range_partial_credit(self):
+        predicted = {
+            "likely_winner": "a1",
+            "success_probability": 1.0,
+            "estimated_bid_range": [20, 40],
+        }
+        # Bid just outside range
+        actual = {"winner": "a1", "succeeded": True, "winning_bid": 45}
+        acc = _compute_accuracy(predicted, actual)
+        assert 0.5 < acc < 1.0
+
+    def test_bid_far_outside_range(self):
+        predicted = {
+            "likely_winner": "a1",
+            "success_probability": 1.0,
+            "estimated_bid_range": [20, 40],
+        }
+        actual = {"winner": "a1", "succeeded": True, "winning_bid": 500}
+        acc = _compute_accuracy(predicted, actual)
+        assert acc < 1.0
+
+    def test_no_actual_bid(self):
+        predicted = {
+            "likely_winner": "a1",
+            "success_probability": 0.7,
+            "estimated_bid_range": [20, 40],
+        }
+        actual = {"winner": "a1", "succeeded": True, "winning_bid": None}
+        acc = _compute_accuracy(predicted, actual)
+        # Bid component skipped — only winner + success
+        assert 0.0 <= acc <= 1.0
+
+    def test_failed_prediction_low_probability(self):
+        predicted = {"success_probability": 0.1}
+        actual = {"succeeded": False}
+        acc = _compute_accuracy(predicted, actual)
+        # Predicted low success and task failed → high accuracy
+        assert acc > 0.8
+
+
+# ── get_predictions ───────────────────────────────────────────────────────
+
+
+class TestGetPredictions:
+    def test_empty_db(self):
+        assert get_predictions() == []
+
+    def test_filter_by_task_id(self):
+        predict_task_outcome("t-filter1", "A", ["a1"])
+        predict_task_outcome("t-filter2", "B", ["a2"])
+        preds = get_predictions(task_id="t-filter1")
+        assert len(preds) == 1
+        assert preds[0].task_id == "t-filter1"
+
+    def test_evaluated_only(self):
+        predict_task_outcome("t-eo1", "A", ["a1"])
+        predict_task_outcome("t-eo2", "B", ["a1"])
+        evaluate_prediction("t-eo1", "a1", task_succeeded=True)
+        preds = get_predictions(evaluated_only=True)
+        assert len(preds) == 1
+        assert preds[0].task_id == "t-eo1"
+
+    def test_limit(self):
+        for i in range(10):
+            predict_task_outcome(f"t-lim{i}", "X", ["a1"])
+        preds = get_predictions(limit=3)
+        assert len(preds) == 3
+
+    def test_combined_filters(self):
+        predict_task_outcome("t-combo", "A", ["a1"])
+        evaluate_prediction("t-combo", "a1", task_succeeded=True)
+        predict_task_outcome("t-combo2", "B", ["a1"])
+        preds = get_predictions(task_id="t-combo", evaluated_only=True)
+        assert len(preds) == 1
+
+    def test_order_by_created_desc(self):
+        for i in range(3):
+            predict_task_outcome(f"t-ord{i}", f"Task {i}", ["a1"])
+        preds = get_predictions()
+        # Most recent first
+        assert preds[0].task_id == "t-ord2"
+
+
+# ── get_accuracy_stats ────────────────────────────────────────────────────
+
+
+class TestGetAccuracyStats:
+    def test_empty(self):
+        stats = get_accuracy_stats()
+        assert stats["total_predictions"] == 0
+        assert stats["evaluated"] == 0
+        assert stats["pending"] == 0
+        assert stats["avg_accuracy"] == 0.0
+        assert stats["min_accuracy"] == 0.0
+        assert stats["max_accuracy"] == 0.0
+
+    def test_with_unevaluated(self):
+        predict_task_outcome("t-uneval", "X", ["a1"])
+        stats = get_accuracy_stats()
+        assert stats["total_predictions"] == 1
+        assert stats["evaluated"] == 0
+        assert stats["pending"] == 1
+
+    def test_with_evaluations(self):
+        for i in range(3):
+            predict_task_outcome(f"t-stats{i}", "X", ["a1"])
+            evaluate_prediction(f"t-stats{i}", "a1", task_succeeded=True, winning_bid=30)
+        stats = get_accuracy_stats()
+        assert stats["total_predictions"] == 3
+        assert stats["evaluated"] == 3
+        assert stats["pending"] == 0
+        assert stats["avg_accuracy"] > 0.0
+        assert stats["min_accuracy"] <= stats["avg_accuracy"] <= stats["max_accuracy"]

tests/spark/test_memory.py

@@ -0,0 +1,389 @@
+"""Comprehensive tests for spark.memory module.
+
+Covers:
+- SparkEvent / SparkMemory dataclasses
+- _get_conn (schema creation, WAL, busy timeout, idempotent indexes)
+- score_importance (all event types, boosts, edge cases)
+- record_event (auto-importance, explicit importance, invalid JSON, swarm bridge)
+- get_events (all filters, ordering, limit)
+- count_events (total, by type)
+- store_memory (with/without expiry)
+- get_memories (all filters)
+- count_memories (total, by type)
+"""
+
+import json
+
+import pytest
+
+from spark.memory import (
+    IMPORTANCE_HIGH,
+    IMPORTANCE_LOW,
+    IMPORTANCE_MEDIUM,
+    SparkEvent,
+    SparkMemory,
+    _get_conn,
+    count_events,
+    count_memories,
+    get_events,
+    get_memories,
+    record_event,
+    score_importance,
+    store_memory,
+)
+
+# ── Constants ─────────────────────────────────────────────────────────────
+
+
+class TestConstants:
+    def test_importance_ordering(self):
+        assert IMPORTANCE_LOW < IMPORTANCE_MEDIUM < IMPORTANCE_HIGH
+
+
+# ── Dataclasses ───────────────────────────────────────────────────────────
+
+
+class TestSparkEventDataclass:
+    def test_all_fields(self):
+        ev = SparkEvent(
+            id="1",
+            event_type="task_posted",
+            agent_id="a1",
+            task_id="t1",
+            description="Test",
+            data="{}",
+            importance=0.5,
+            created_at="2026-01-01",
+        )
+        assert ev.event_type == "task_posted"
+        assert ev.agent_id == "a1"
+
+    def test_nullable_fields(self):
+        ev = SparkEvent(
+            id="2",
+            event_type="task_posted",
+            agent_id=None,
+            task_id=None,
+            description="",
+            data="{}",
+            importance=0.5,
+            created_at="2026-01-01",
+        )
+        assert ev.agent_id is None
+        assert ev.task_id is None
+
+
+class TestSparkMemoryDataclass:
+    def test_all_fields(self):
+        mem = SparkMemory(
+            id="1",
+            memory_type="pattern",
+            subject="system",
+            content="Test insight",
+            confidence=0.8,
+            source_events=5,
+            created_at="2026-01-01",
+            expires_at="2026-12-31",
+        )
+        assert mem.memory_type == "pattern"
+        assert mem.expires_at == "2026-12-31"
+
+    def test_nullable_expires(self):
+        mem = SparkMemory(
+            id="2",
+            memory_type="anomaly",
+            subject="agent-1",
+            content="Odd behavior",
+            confidence=0.6,
+            source_events=3,
+            created_at="2026-01-01",
+            expires_at=None,
+        )
+        assert mem.expires_at is None
+
+
+# ── _get_conn ─────────────────────────────────────────────────────────────
+
+
+class TestGetConn:
+    def test_creates_tables(self):
+        with _get_conn() as conn:
+            tables = conn.execute("SELECT name FROM sqlite_master WHERE type='table'").fetchall()
+            names = {r["name"] for r in tables}
+            assert "spark_events" in names
+            assert "spark_memories" in names
+
+    def test_wal_mode(self):
+        with _get_conn() as conn:
+            mode = conn.execute("PRAGMA journal_mode").fetchone()[0]
+            assert mode == "wal"
+
+    def test_busy_timeout(self):
+        with _get_conn() as conn:
+            timeout = conn.execute("PRAGMA busy_timeout").fetchone()[0]
+            assert timeout == 5000
+
+    def test_idempotent(self):
+        # Calling _get_conn twice should not raise
+        with _get_conn():
+            pass
+        with _get_conn():
+            pass
+
+
+# ── score_importance ──────────────────────────────────────────────────────
+
+
+class TestScoreImportance:
+    @pytest.mark.parametrize(
+        "event_type,expected_min,expected_max",
+        [
+            ("task_posted", 0.3, 0.5),
+            ("bid_submitted", 0.1, 0.3),
+            ("task_assigned", 0.4, 0.6),
+            ("task_completed", 0.5, 0.7),
+            ("task_failed", 0.9, 1.0),
+            ("agent_joined", 0.4, 0.6),
+            ("prediction_result", 0.6, 0.8),
+        ],
+    )
+    def test_base_scores(self, event_type, expected_min, expected_max):
+        score = score_importance(event_type, {})
+        assert expected_min <= score <= expected_max
+
+    def test_unknown_event_default(self):
+        assert score_importance("never_heard_of_this", {}) == 0.5
+
+    def test_failure_boost(self):
+        score = score_importance("task_failed", {})
+        assert score == 1.0
+
+    def test_high_bid_boost(self):
+        low = score_importance("bid_submitted", {"bid_sats": 10})
+        high = score_importance("bid_submitted", {"bid_sats": 100})
+        assert high > low
+        assert high <= 1.0
+
+    def test_high_bid_on_failure(self):
+        score = score_importance("task_failed", {"bid_sats": 100})
+        assert score == 1.0  # capped at 1.0
+
+    def test_score_always_rounded(self):
+        score = score_importance("bid_submitted", {"bid_sats": 100})
+        assert score == round(score, 2)
+
+
+# ── record_event ──────────────────────────────────────────────────────────
+
+
+class TestRecordEvent:
+    def test_basic_record(self):
+        eid = record_event("task_posted", "New task", task_id="t1")
+        assert isinstance(eid, str)
+        assert len(eid) > 0
+
+    def test_auto_importance(self):
+        record_event("task_failed", "Failed", task_id="t-auto")
+        events = get_events(task_id="t-auto")
+        assert events[0].importance >= 0.9
+
+    def test_explicit_importance(self):
+        record_event("task_posted", "Custom", task_id="t-expl", importance=0.1)
+        events = get_events(task_id="t-expl")
+        assert events[0].importance == 0.1
+
+    def test_with_agent_and_data(self):
+        data = json.dumps({"bid_sats": 42})
+        record_event("bid_submitted", "Bid", agent_id="a1", task_id="t-data", data=data)
+        events = get_events(task_id="t-data")
+        assert events[0].agent_id == "a1"
+        parsed = json.loads(events[0].data)
+        assert parsed["bid_sats"] == 42
+
+    def test_invalid_json_data_uses_default_importance(self):
+        record_event("task_posted", "Bad data", task_id="t-bad", data="not-json")
+        events = get_events(task_id="t-bad")
+        assert events[0].importance == 0.4  # base for task_posted
+
+    def test_returns_unique_ids(self):
+        id1 = record_event("task_posted", "A")
+        id2 = record_event("task_posted", "B")
+        assert id1 != id2
+
+
+# ── get_events ────────────────────────────────────────────────────────────
+
+
+class TestGetEvents:
+    def test_empty_db(self):
+        assert get_events() == []
+
+    def test_filter_by_type(self):
+        record_event("task_posted", "A")
+        record_event("task_completed", "B")
+        events = get_events(event_type="task_posted")
+        assert len(events) == 1
+        assert events[0].event_type == "task_posted"
+
+    def test_filter_by_agent(self):
+        record_event("task_posted", "A", agent_id="a1")
+        record_event("task_posted", "B", agent_id="a2")
+        events = get_events(agent_id="a1")
+        assert len(events) == 1
+        assert events[0].agent_id == "a1"
+
+    def test_filter_by_task(self):
+        record_event("task_posted", "A", task_id="t1")
+        record_event("task_posted", "B", task_id="t2")
+        events = get_events(task_id="t1")
+        assert len(events) == 1
+
+    def test_filter_by_min_importance(self):
+        record_event("task_posted", "Low", importance=0.1)
+        record_event("task_failed", "High", importance=0.9)
+        events = get_events(min_importance=0.5)
+        assert len(events) == 1
+        assert events[0].importance >= 0.5
+
+    def test_limit(self):
+        for i in range(10):
+            record_event("task_posted", f"ev{i}")
+        events = get_events(limit=3)
+        assert len(events) == 3
+
+    def test_order_by_created_desc(self):
+        record_event("task_posted", "first", task_id="ord1")
+        record_event("task_posted", "second", task_id="ord2")
+        events = get_events()
+        # Most recent first
+        assert events[0].task_id == "ord2"
+
+    def test_combined_filters(self):
+        record_event("task_failed", "A", agent_id="a1", task_id="t1", importance=0.9)
+        record_event("task_posted", "B", agent_id="a1", task_id="t2", importance=0.4)
+        record_event("task_failed", "C", agent_id="a2", task_id="t3", importance=0.9)
+        events = get_events(event_type="task_failed", agent_id="a1", min_importance=0.5)
+        assert len(events) == 1
+        assert events[0].task_id == "t1"
+
+
+# ── count_events ──────────────────────────────────────────────────────────
+
+
+class TestCountEvents:
+    def test_empty(self):
+        assert count_events() == 0
+
+    def test_total(self):
+        record_event("task_posted", "A")
+        record_event("task_failed", "B")
+        assert count_events() == 2
+
+    def test_by_type(self):
+        record_event("task_posted", "A")
+        record_event("task_posted", "B")
+        record_event("task_failed", "C")
+        assert count_events("task_posted") == 2
+        assert count_events("task_failed") == 1
+        assert count_events("task_completed") == 0
+
+
+# ── store_memory ──────────────────────────────────────────────────────────
+
+
+class TestStoreMemory:
+    def test_basic_store(self):
+        mid = store_memory("pattern", "system", "Test insight")
+        assert isinstance(mid, str)
+        assert len(mid) > 0
+
+    def test_returns_unique_ids(self):
+        id1 = store_memory("pattern", "a", "X")
+        id2 = store_memory("pattern", "b", "Y")
+        assert id1 != id2
+
+    def test_with_all_params(self):
+        store_memory(
+            "anomaly",
+            "agent-1",
+            "Odd pattern",
+            confidence=0.9,
+            source_events=10,
+            expires_at="2026-12-31",
+        )
+        mems = get_memories(subject="agent-1")
+        assert len(mems) == 1
+        assert mems[0].confidence == 0.9
+        assert mems[0].source_events == 10
+        assert mems[0].expires_at == "2026-12-31"
+
+    def test_default_values(self):
+        store_memory("insight", "sys", "Default test")
+        mems = get_memories(subject="sys")
+        assert mems[0].confidence == 0.5
+        assert mems[0].source_events == 0
+        assert mems[0].expires_at is None
+
+
+# ── get_memories ──────────────────────────────────────────────────────────
+
+
+class TestGetMemories:
+    def test_empty(self):
+        assert get_memories() == []
+
+    def test_filter_by_type(self):
+        store_memory("pattern", "a", "X")
+        store_memory("anomaly", "a", "Y")
+        mems = get_memories(memory_type="pattern")
+        assert len(mems) == 1
+        assert mems[0].memory_type == "pattern"
+
+    def test_filter_by_subject(self):
+        store_memory("pattern", "a", "X")
+        store_memory("pattern", "b", "Y")
+        mems = get_memories(subject="a")
+        assert len(mems) == 1
+
+    def test_filter_by_min_confidence(self):
+        store_memory("pattern", "a", "Low", confidence=0.2)
+        store_memory("pattern", "b", "High", confidence=0.9)
+        mems = get_memories(min_confidence=0.5)
+        assert len(mems) == 1
+        assert mems[0].content == "High"
+
+    def test_limit(self):
+        for i in range(10):
+            store_memory("pattern", "a", f"M{i}")
+        mems = get_memories(limit=3)
+        assert len(mems) == 3
+
+    def test_combined_filters(self):
+        store_memory("pattern", "a", "Target", confidence=0.9)
+        store_memory("anomaly", "a", "Wrong type", confidence=0.9)
+        store_memory("pattern", "b", "Wrong subject", confidence=0.9)
+        store_memory("pattern", "a", "Low conf", confidence=0.1)
+        mems = get_memories(memory_type="pattern", subject="a", min_confidence=0.5)
+        assert len(mems) == 1
+        assert mems[0].content == "Target"
+
+
+# ── count_memories ────────────────────────────────────────────────────────
+
+
+class TestCountMemories:
+    def test_empty(self):
+        assert count_memories() == 0
+
+    def test_total(self):
+        store_memory("pattern", "a", "X")
+        store_memory("anomaly", "b", "Y")
+        assert count_memories() == 2
+
+    def test_by_type(self):
+        store_memory("pattern", "a", "X")
+        store_memory("pattern", "b", "Y")
+        store_memory("anomaly", "c", "Z")
+        assert count_memories("pattern") == 2
+        assert count_memories("anomaly") == 1
+        assert count_memories("insight") == 0

tests/test_config_module.py

@@ -0,0 +1,470 @@
+"""Tests for src/config.py — Settings, validation, and helper functions."""
+
+import os
+from unittest.mock import patch
+
+import pytest
+
+
+class TestNormalizeOllamaUrl:
+    """normalize_ollama_url replaces localhost with 127.0.0.1."""
+
+    def test_replaces_localhost(self):
+        from config import normalize_ollama_url
+
+        assert normalize_ollama_url("http://localhost:11434") == "http://127.0.0.1:11434"
+
+    def test_preserves_ip(self):
+        from config import normalize_ollama_url
+
+        assert normalize_ollama_url("http://192.168.1.5:11434") == "http://192.168.1.5:11434"
+
+    def test_preserves_non_localhost_hostname(self):
+        from config import normalize_ollama_url
+
+        assert normalize_ollama_url("http://ollama.local:11434") == "http://ollama.local:11434"
+
+    def test_replaces_multiple_occurrences(self):
+        from config import normalize_ollama_url
+
+        result = normalize_ollama_url("http://localhost:11434/localhost")
+        assert result == "http://127.0.0.1:11434/127.0.0.1"
+
+
+class TestSettingsDefaults:
+    """Settings instantiation produces correct defaults."""
+
+    def _make_settings(self, **env_overrides):
+        """Create a fresh Settings instance with given env overrides."""
+        from config import Settings
+
+        clean_env = {
+            k: v
+            for k, v in os.environ.items()
+            if not k.startswith(("OLLAMA_", "TIMMY_", "AGENT_", "DEBUG"))
+        }
+        clean_env.update(env_overrides)
+        with patch.dict(os.environ, clean_env, clear=True):
+            return Settings()
+
+    def test_default_agent_name(self):
+        s = self._make_settings()
+        assert s.agent_name == "Agent"
+
+    def test_default_ollama_url(self):
+        s = self._make_settings()
+        assert s.ollama_url == "http://localhost:11434"
+
+    def test_default_ollama_model(self):
+        s = self._make_settings()
+        assert s.ollama_model == "qwen3:30b"
+
+    def test_default_ollama_num_ctx(self):
+        s = self._make_settings()
+        assert s.ollama_num_ctx == 4096
+
+    def test_default_debug_false(self):
+        s = self._make_settings()
+        assert s.debug is False
+
+    def test_default_timmy_env(self):
+        s = self._make_settings()
+        assert s.timmy_env == "development"
+
+    def test_default_timmy_test_mode(self):
+        s = self._make_settings()
+        assert s.timmy_test_mode is False
+
+    def test_default_spark_enabled(self):
+        s = self._make_settings()
+        assert s.spark_enabled is True
+
+    def test_default_lightning_backend(self):
+        s = self._make_settings()
+        assert s.lightning_backend == "mock"
+
+    def test_default_max_agent_steps(self):
+        s = self._make_settings()
+        assert s.max_agent_steps == 10
+
+    def test_default_memory_prune_days(self):
+        s = self._make_settings()
+        assert s.memory_prune_days == 90
+
+    def test_default_fallback_models_is_list(self):
+        s = self._make_settings()
+        assert isinstance(s.fallback_models, list)
+        assert len(s.fallback_models) > 0
+
+    def test_default_cors_origins_is_list(self):
+        s = self._make_settings()
+        assert isinstance(s.cors_origins, list)
+
+    def test_default_trusted_hosts_is_list(self):
+        s = self._make_settings()
+        assert isinstance(s.trusted_hosts, list)
+        assert "localhost" in s.trusted_hosts
+
+    def test_normalized_ollama_url_property(self):
+        s = self._make_settings()
+        assert "127.0.0.1" in s.normalized_ollama_url
+        assert "localhost" not in s.normalized_ollama_url
+
+
+class TestSettingsEnvOverrides:
+    """Environment variables override default values."""
+
+    def _make_settings(self, **env_overrides):
+        from config import Settings
+
+        clean_env = {
+            k: v
+            for k, v in os.environ.items()
+            if not k.startswith(("OLLAMA_", "TIMMY_", "AGENT_", "DEBUG"))
+        }
+        clean_env.update(env_overrides)
+        with patch.dict(os.environ, clean_env, clear=True):
+            return Settings()
+
+    def test_agent_name_override(self):
+        s = self._make_settings(AGENT_NAME="Timmy")
+        assert s.agent_name == "Timmy"
+
+    def test_ollama_url_override(self):
+        s = self._make_settings(OLLAMA_URL="http://10.0.0.1:11434")
+        assert s.ollama_url == "http://10.0.0.1:11434"
+
+    def test_ollama_model_override(self):
+        s = self._make_settings(OLLAMA_MODEL="llama3.1")
+        assert s.ollama_model == "llama3.1"
+
+    def test_debug_true_from_string(self):
+        s = self._make_settings(DEBUG="true")
+        assert s.debug is True
+
+    def test_debug_false_from_string(self):
+        s = self._make_settings(DEBUG="false")
+        assert s.debug is False
+
+    def test_numeric_override(self):
+        s = self._make_settings(OLLAMA_NUM_CTX="8192")
+        assert s.ollama_num_ctx == 8192
+
+    def test_max_agent_steps_override(self):
+        s = self._make_settings(MAX_AGENT_STEPS="25")
+        assert s.max_agent_steps == 25
+
+    def test_timmy_env_production(self):
+        s = self._make_settings(TIMMY_ENV="production")
+        assert s.timmy_env == "production"
+
+    def test_timmy_test_mode_true(self):
+        s = self._make_settings(TIMMY_TEST_MODE="true")
+        assert s.timmy_test_mode is True
+
+    def test_grok_enabled_override(self):
+        s = self._make_settings(GROK_ENABLED="true")
+        assert s.grok_enabled is True
+
+    def test_spark_enabled_override(self):
+        s = self._make_settings(SPARK_ENABLED="false")
+        assert s.spark_enabled is False
+
+    def test_memory_prune_days_override(self):
+        s = self._make_settings(MEMORY_PRUNE_DAYS="30")
+        assert s.memory_prune_days == 30
+
+
+class TestSettingsTypeValidation:
+    """Pydantic correctly parses and validates types from string env vars."""
+
+    def _make_settings(self, **env_overrides):
+        from config import Settings
+
+        clean_env = {
+            k: v
+            for k, v in os.environ.items()
+            if not k.startswith(("OLLAMA_", "TIMMY_", "AGENT_", "DEBUG"))
+        }
+        clean_env.update(env_overrides)
+        with patch.dict(os.environ, clean_env, clear=True):
+            return Settings()
+
+    def test_bool_from_1(self):
+        s = self._make_settings(DEBUG="1")
+        assert s.debug is True
+
+    def test_bool_from_0(self):
+        s = self._make_settings(DEBUG="0")
+        assert s.debug is False
+
+    def test_int_field_rejects_non_numeric(self):
+        from pydantic import ValidationError
+
+        with pytest.raises(ValidationError):
+            self._make_settings(OLLAMA_NUM_CTX="not_a_number")
+
+    def test_literal_field_rejects_invalid(self):
+        from pydantic import ValidationError
+
+        with pytest.raises(ValidationError):
+            self._make_settings(TIMMY_ENV="staging")
+
+    def test_literal_backend_rejects_invalid(self):
+        from pydantic import ValidationError
+
+        with pytest.raises(ValidationError):
+            self._make_settings(TIMMY_MODEL_BACKEND="openai")
+
+    def test_literal_backend_accepts_valid(self):
+        for backend in ("ollama", "grok", "claude", "auto"):
+            s = self._make_settings(TIMMY_MODEL_BACKEND=backend)
+            assert s.timmy_model_backend == backend
+
+    def test_extra_fields_ignored(self):
+        # model_config has extra="ignore"
+        s = self._make_settings(TOTALLY_UNKNOWN_FIELD="hello")
+        assert not hasattr(s, "totally_unknown_field")
+
+
+class TestSettingsEdgeCases:
+    """Edge cases: empty strings, missing vars, boundary values."""
+
+    def _make_settings(self, **env_overrides):
+        from config import Settings
+
+        clean_env = {
+            k: v
+            for k, v in os.environ.items()
+            if not k.startswith(("OLLAMA_", "TIMMY_", "AGENT_", "DEBUG"))
+        }
+        clean_env.update(env_overrides)
+        with patch.dict(os.environ, clean_env, clear=True):
+            return Settings()
+
+    def test_empty_string_tokens_stay_empty(self):
+        s = self._make_settings(TELEGRAM_TOKEN="", DISCORD_TOKEN="")
+        assert s.telegram_token == ""
+        assert s.discord_token == ""
+
+    def test_zero_int_fields(self):
+        s = self._make_settings(OLLAMA_NUM_CTX="0", MEMORY_PRUNE_DAYS="0")
+        assert s.ollama_num_ctx == 0
+        assert s.memory_prune_days == 0
+
+    def test_large_int_value(self):
+        s = self._make_settings(CHAT_API_MAX_BODY_BYTES="104857600")
+        assert s.chat_api_max_body_bytes == 104857600
+
+    def test_negative_int_accepted(self):
+        # Pydantic doesn't constrain these to positive
+        s = self._make_settings(MAX_AGENT_STEPS="-1")
+        assert s.max_agent_steps == -1
+
+
+class TestComputeRepoRoot:
+    """_compute_repo_root auto-detects .git directory."""
+
+    def test_returns_string(self):
+        from config import Settings
+
+        s = Settings()
+        result = s._compute_repo_root()
+        assert isinstance(result, str)
+        assert len(result) > 0
+
+    def test_explicit_repo_root_used(self):
+        from config import Settings
+
+        with patch.dict(os.environ, {"REPO_ROOT": "/tmp/myrepo"}, clear=False):
+            s = Settings()
+            s.repo_root = "/tmp/myrepo"
+            assert s._compute_repo_root() == "/tmp/myrepo"
+
+
+class TestModelPostInit:
+    """model_post_init resolves gitea_token from file fallback."""
+
+    def test_gitea_token_from_env(self):
+        from config import Settings
+
+        with patch.dict(os.environ, {"GITEA_TOKEN": "test-token-123"}, clear=False):
+            s = Settings()
+            assert s.gitea_token == "test-token-123"
+
+    def test_gitea_token_stays_empty_when_no_file(self):
+        from config import Settings
+
+        env = {k: v for k, v in os.environ.items() if k != "GITEA_TOKEN"}
+        with patch.dict(os.environ, env, clear=True):
+            with patch("os.path.isfile", return_value=False):
+                s = Settings()
+                assert s.gitea_token == ""
+
+
+class TestCheckOllamaModelAvailable:
+    """check_ollama_model_available handles network responses and errors."""
+
+    def test_returns_false_on_network_error(self):
+        from config import check_ollama_model_available
+
+        with patch("urllib.request.urlopen", side_effect=OSError("Connection refused")):
+            assert check_ollama_model_available("llama3.1") is False
+
+    def test_returns_true_when_model_found(self):
+        import json
+        from unittest.mock import MagicMock
+
+        from config import check_ollama_model_available
+
+        response_data = json.dumps({"models": [{"name": "llama3.1:8b-instruct"}]}).encode()
+        mock_response = MagicMock()
+        mock_response.read.return_value = response_data
+        mock_response.__enter__ = lambda s: s
+        mock_response.__exit__ = MagicMock(return_value=False)
+
+        with patch("urllib.request.urlopen", return_value=mock_response):
+            assert check_ollama_model_available("llama3.1") is True
+
+    def test_returns_false_when_model_not_found(self):
+        import json
+        from unittest.mock import MagicMock
+
+        from config import check_ollama_model_available
+
+        response_data = json.dumps({"models": [{"name": "qwen2.5:7b"}]}).encode()
+        mock_response = MagicMock()
+        mock_response.read.return_value = response_data
+        mock_response.__enter__ = lambda s: s
+        mock_response.__exit__ = MagicMock(return_value=False)
+
+        with patch("urllib.request.urlopen", return_value=mock_response):
+            assert check_ollama_model_available("llama3.1") is False
+
+
+class TestGetEffectiveOllamaModel:
+    """get_effective_ollama_model walks fallback chain."""
+
+    def test_returns_primary_when_available(self):
+        from config import get_effective_ollama_model
+
+        with patch("config.check_ollama_model_available", return_value=True):
+            result = get_effective_ollama_model()
+            assert result == "qwen3:30b"
+
+    def test_falls_back_when_primary_unavailable(self):
+        from config import get_effective_ollama_model
+
+        def side_effect(model):
+            return model == "llama3.1:8b-instruct"
+
+        with patch("config.check_ollama_model_available", side_effect=side_effect):
+            result = get_effective_ollama_model()
+            assert result == "llama3.1:8b-instruct"
+
+    def test_returns_user_model_when_nothing_available(self):
+        from config import get_effective_ollama_model
+
+        with patch("config.check_ollama_model_available", return_value=False):
+            result = get_effective_ollama_model()
+            assert result == "qwen3:30b"
+
+
+class TestValidateStartup:
+    """validate_startup enforces security in production, warns in dev."""
+
+    def setup_method(self):
+        import config
+
+        config._startup_validated = False
+
+    def test_skips_in_test_mode(self):
+        import config
+
+        with patch.dict(os.environ, {"TIMMY_TEST_MODE": "1"}):
+            config.validate_startup()
+            assert config._startup_validated is True
+
+    def test_dev_mode_warns_but_does_not_exit(self, caplog):
+        import logging
+
+        import config
+
+        config._startup_validated = False
+        env = {k: v for k, v in os.environ.items() if k != "TIMMY_TEST_MODE"}
+        env["TIMMY_ENV"] = "development"
+        with patch.dict(os.environ, env, clear=True):
+            with caplog.at_level(logging.WARNING, logger="config"):
+                config.validate_startup()
+        assert config._startup_validated is True
+
+    def test_production_exits_without_secrets(self):
+        import config
+
+        config._startup_validated = False
+        env = {k: v for k, v in os.environ.items() if k != "TIMMY_TEST_MODE"}
+        env["TIMMY_ENV"] = "production"
+        env.pop("L402_HMAC_SECRET", None)
+        env.pop("L402_MACAROON_SECRET", None)
+        with patch.dict(os.environ, env, clear=True):
+            with patch.object(config.settings, "timmy_env", "production"):
+                with patch.object(config.settings, "l402_hmac_secret", ""):
+                    with patch.object(config.settings, "l402_macaroon_secret", ""):
+                        with pytest.raises(SystemExit):
+                            config.validate_startup(force=True)
+
+    def test_production_exits_with_cors_wildcard(self):
+        import config
+
+        config._startup_validated = False
+        env = {k: v for k, v in os.environ.items() if k != "TIMMY_TEST_MODE"}
+        env["TIMMY_ENV"] = "production"
+        with patch.dict(os.environ, env, clear=True):
+            with patch.object(config.settings, "timmy_env", "production"):
+                with patch.object(config.settings, "l402_hmac_secret", "secret1"):
+                    with patch.object(config.settings, "l402_macaroon_secret", "secret2"):
+                        with patch.object(config.settings, "cors_origins", ["*"]):
+                            with pytest.raises(SystemExit):
+                                config.validate_startup(force=True)
+
+    def test_production_passes_with_all_secrets(self):
+        import config
+
+        config._startup_validated = False
+        env = {k: v for k, v in os.environ.items() if k != "TIMMY_TEST_MODE"}
+        env["TIMMY_ENV"] = "production"
+        with patch.dict(os.environ, env, clear=True):
+            with patch.object(config.settings, "timmy_env", "production"):
+                with patch.object(config.settings, "l402_hmac_secret", "secret1"):
+                    with patch.object(config.settings, "l402_macaroon_secret", "secret2"):
+                        with patch.object(
+                            config.settings,
+                            "cors_origins",
+                            ["http://localhost:3000"],
+                        ):
+                            config.validate_startup(force=True)
+        assert config._startup_validated is True
+
+    def test_idempotent_without_force(self):
+        import config
+
+        config._startup_validated = True
+        # Should return immediately without doing anything
+        config.validate_startup()
+        assert config._startup_validated is True
+
+
+class TestAppStartTime:
+    """APP_START_TIME is set at module load."""
+
+    def test_app_start_time_is_datetime(self):
+        from datetime import datetime
+
+        from config import APP_START_TIME
+
+        assert isinstance(APP_START_TIME, datetime)
+
+    def test_app_start_time_has_timezone(self):
+        from config import APP_START_TIME
+
+        assert APP_START_TIME.tzinfo is not None

tests/test_smoke.py

@@ -130,6 +130,13 @@ class TestAPIEndpoints:
         r = client.get("/health/sovereignty")
         assert r.status_code == 200
 
+    def test_health_snapshot(self, client):
+        r = client.get("/health/snapshot")
+        assert r.status_code == 200
+        data = r.json()
+        assert "overall_status" in data
+        assert data["overall_status"] in ["green", "yellow", "red", "unknown"]
+
     def test_queue_status(self, client):
         r = client.get("/api/queue/status")
         assert r.status_code == 200
@@ -186,6 +193,7 @@ class TestNo500:
             "/health",
             "/health/status",
             "/health/sovereignty",
+            "/health/snapshot",
             "/health/components",
             "/agents/default/panel",
             "/agents/default/history",

tests/timmy/test_golden_path.py

@@ -0,0 +1,536 @@
+"""Tests for the Golden Path generator."""
+
+import json
+from datetime import UTC, datetime
+from unittest.mock import MagicMock, patch
+
+from timmy_automations.daily_run.golden_path import (
+    TIME_ESTIMATES,
+    TYPE_PATTERNS,
+    GiteaClient,
+    GoldenPath,
+    PathItem,
+    build_golden_path,
+    classify_issue_type,
+    estimate_time,
+    extract_size,
+    generate_golden_path,
+    get_token,
+    group_issues_by_type,
+    load_config,
+    score_issue_for_path,
+)
+
+
+class TestLoadConfig:
+    """Tests for configuration loading."""
+
+    def test_load_config_defaults(self):
+        """Config should have sensible defaults."""
+        config = load_config()
+        assert "gitea_api" in config
+        assert "repo_slug" in config
+        assert "size_labels" in config
+
+    def test_load_config_env_override(self, monkeypatch):
+        """Environment variables should override defaults."""
+        monkeypatch.setenv("TIMMY_GITEA_API", "http://custom:3000/api/v1")
+        monkeypatch.setenv("TIMMY_REPO_SLUG", "custom/repo")
+        monkeypatch.setenv("TIMMY_GITEA_TOKEN", "test-token")
+
+        config = load_config()
+        assert config["gitea_api"] == "http://custom:3000/api/v1"
+        assert config["repo_slug"] == "custom/repo"
+        assert config["token"] == "test-token"
+
+
+class TestGetToken:
+    """Tests for token retrieval."""
+
+    def test_get_token_from_config(self):
+        """Token from config takes precedence."""
+        config = {"token": "config-token", "token_file": "~/.test"}
+        assert get_token(config) == "config-token"
+
+    @patch("pathlib.Path.exists")
+    @patch("pathlib.Path.read_text")
+    def test_get_token_from_file(self, mock_read, mock_exists):
+        """Token can be read from file."""
+        mock_exists.return_value = True
+        mock_read.return_value = "file-token\n"
+
+        config = {"token_file": "~/.hermes/test_token"}
+        assert get_token(config) == "file-token"
+
+    def test_get_token_none(self):
+        """Returns None if no token available."""
+        config = {"token_file": "/nonexistent/path"}
+        assert get_token(config) is None
+
+
+class TestExtractSize:
+    """Tests for size label extraction."""
+
+    def test_extract_size_xs(self):
+        """Should extract XS size."""
+        labels = [{"name": "size:XS"}, {"name": "bug"}]
+        assert extract_size(labels) == "XS"
+
+    def test_extract_size_s(self):
+        """Should extract S size."""
+        labels = [{"name": "bug"}, {"name": "size:S"}]
+        assert extract_size(labels) == "S"
+
+    def test_extract_size_m(self):
+        """Should extract M size."""
+        labels = [{"name": "size:M"}]
+        assert extract_size(labels) == "M"
+
+    def test_extract_size_unknown(self):
+        """Should return ? for unknown size."""
+        labels = [{"name": "bug"}, {"name": "feature"}]
+        assert extract_size(labels) == "?"
+
+    def test_extract_size_empty(self):
+        """Should return ? for empty labels."""
+        assert extract_size([]) == "?"
+
+
+class TestClassifyIssueType:
+    """Tests for issue type classification."""
+
+    def test_classify_triage(self):
+        """Should classify triage issues."""
+        issue = {
+            "title": "Triage new issues",
+            "labels": [{"name": "triage"}],
+        }
+        assert classify_issue_type(issue) == "triage"
+
+    def test_classify_test(self):
+        """Should classify test issues."""
+        issue = {
+            "title": "Add unit tests for parser",
+            "labels": [{"name": "test"}],
+        }
+        assert classify_issue_type(issue) == "test"
+
+    def test_classify_fix(self):
+        """Should classify fix issues."""
+        issue = {
+            "title": "Fix login bug",
+            "labels": [{"name": "bug"}],
+        }
+        assert classify_issue_type(issue) == "fix"
+
+    def test_classify_docs(self):
+        """Should classify docs issues."""
+        issue = {
+            "title": "Update README",
+            "labels": [{"name": "docs"}],
+        }
+        assert classify_issue_type(issue) == "docs"
+
+    def test_classify_refactor(self):
+        """Should classify refactor issues."""
+        issue = {
+            "title": "Refactor validation logic",
+            "labels": [{"name": "refactor"}],
+        }
+        assert classify_issue_type(issue) == "refactor"
+
+    def test_classify_default_to_fix(self):
+        """Should default to fix for uncategorized."""
+        issue = {
+            "title": "Something vague",
+            "labels": [{"name": "question"}],
+        }
+        assert classify_issue_type(issue) == "fix"
+
+    def test_classify_title_priority(self):
+        """Title patterns should contribute to classification."""
+        issue = {
+            "title": "Fix the broken parser",
+            "labels": [],
+        }
+        assert classify_issue_type(issue) == "fix"
+
+
+class TestEstimateTime:
+    """Tests for time estimation."""
+
+    def test_estimate_xs_fix(self):
+        """XS fix should be 10 minutes."""
+        issue = {
+            "title": "Fix typo",
+            "labels": [{"name": "size:XS"}, {"name": "bug"}],
+        }
+        assert estimate_time(issue) == 10
+
+    def test_estimate_s_test(self):
+        """S test should be 15 minutes."""
+        issue = {
+            "title": "Add test coverage",
+            "labels": [{"name": "size:S"}, {"name": "test"}],
+        }
+        assert estimate_time(issue) == 15
+
+    def test_estimate_m_fix(self):
+        """M fix should be 25 minutes."""
+        issue = {
+            "title": "Fix complex bug",
+            "labels": [{"name": "size:M"}, {"name": "bug"}],
+        }
+        assert estimate_time(issue) == 25
+
+    def test_estimate_unknown_size(self):
+        """Unknown size should fallback to S."""
+        issue = {
+            "title": "Some fix",
+            "labels": [{"name": "bug"}],
+        }
+        # Falls back to S/fix = 15
+        assert estimate_time(issue) == 15
+
+
+class TestScoreIssueForPath:
+    """Tests for issue scoring."""
+
+    def test_score_prefers_xs(self):
+        """XS issues should score higher."""
+        xs = {"title": "Fix", "labels": [{"name": "size:XS"}]}
+        s = {"title": "Fix", "labels": [{"name": "size:S"}]}
+        m = {"title": "Fix", "labels": [{"name": "size:M"}]}
+
+        assert score_issue_for_path(xs) > score_issue_for_path(s)
+        assert score_issue_for_path(s) > score_issue_for_path(m)
+
+    def test_score_prefers_clear_types(self):
+        """Issues with clear type labels score higher."""
+        # Bug label adds score, so with bug should be >= without bug
+        with_type = {
+            "title": "Fix bug",
+            "labels": [{"name": "size:S"}, {"name": "bug"}],
+        }
+        without_type = {
+            "title": "Something",
+            "labels": [{"name": "size:S"}],
+        }
+
+        assert score_issue_for_path(with_type) >= score_issue_for_path(without_type)
+
+    def test_score_accepts_criteria(self):
+        """Issues with acceptance criteria score higher."""
+        with_criteria = {
+            "title": "Fix",
+            "labels": [{"name": "size:S"}],
+            "body": "## Acceptance Criteria\n- [ ] Fix it",
+        }
+        without_criteria = {
+            "title": "Fix",
+            "labels": [{"name": "size:S"}],
+            "body": "Just fix it",
+        }
+
+        assert score_issue_for_path(with_criteria) > score_issue_for_path(without_criteria)
+
+
+class TestGroupIssuesByType:
+    """Tests for issue grouping."""
+
+    def test_groups_by_type(self):
+        """Issues should be grouped by their type."""
+        issues = [
+            {"title": "Fix bug", "labels": [{"name": "bug"}], "number": 1},
+            {"title": "Add test", "labels": [{"name": "test"}], "number": 2},
+            {"title": "Another fix", "labels": [{"name": "bug"}], "number": 3},
+        ]
+
+        grouped = group_issues_by_type(issues)
+
+        assert len(grouped["fix"]) == 2
+        assert len(grouped["test"]) == 1
+        assert len(grouped["triage"]) == 0
+
+    def test_sorts_by_score(self):
+        """Issues within groups should be sorted by score."""
+        issues = [
+            {"title": "Fix", "labels": [{"name": "size:M"}], "number": 1},
+            {"title": "Fix", "labels": [{"name": "size:XS"}], "number": 2},
+            {"title": "Fix", "labels": [{"name": "size:S"}], "number": 3},
+        ]
+
+        grouped = group_issues_by_type(issues)
+
+        # XS should be first (highest score)
+        assert grouped["fix"][0]["number"] == 2
+        # M should be last (lowest score)
+        assert grouped["fix"][2]["number"] == 1
+
+
+class TestBuildGoldenPath:
+    """Tests for Golden Path building."""
+
+    def test_builds_path_with_all_types(self):
+        """Path should include items from different types."""
+        grouped = {
+            "triage": [
+                {"title": "Triage", "labels": [{"name": "size:XS"}], "number": 1, "html_url": ""},
+            ],
+            "fix": [
+                {"title": "Fix 1", "labels": [{"name": "size:S"}], "number": 2, "html_url": ""},
+                {"title": "Fix 2", "labels": [{"name": "size:XS"}], "number": 3, "html_url": ""},
+            ],
+            "test": [
+                {"title": "Test", "labels": [{"name": "size:S"}], "number": 4, "html_url": ""},
+            ],
+            "docs": [],
+            "refactor": [],
+        }
+
+        path = build_golden_path(grouped, target_minutes=45)
+
+        assert path.item_count >= 3
+        assert path.items[0].issue_type == "triage"  # Warm-up
+        assert any(item.issue_type == "test" for item in path.items)
+
+    def test_respects_time_budget(self):
+        """Path should stay within reasonable time budget."""
+        grouped = {
+            "triage": [
+                {"title": "Triage", "labels": [{"name": "size:S"}], "number": 1, "html_url": ""},
+            ],
+            "fix": [
+                {"title": "Fix 1", "labels": [{"name": "size:S"}], "number": 2, "html_url": ""},
+                {"title": "Fix 2", "labels": [{"name": "size:S"}], "number": 3, "html_url": ""},
+            ],
+            "test": [
+                {"title": "Test", "labels": [{"name": "size:S"}], "number": 4, "html_url": ""},
+            ],
+            "docs": [],
+            "refactor": [],
+        }
+
+        path = build_golden_path(grouped, target_minutes=45)
+
+        # Should be in 30-60 minute range
+        assert 20 <= path.total_estimated_minutes <= 70
+
+    def test_no_duplicate_issues(self):
+        """Path should not include the same issue twice."""
+        grouped = {
+            "triage": [],
+            "fix": [
+                {"title": "Fix", "labels": [{"name": "size:S"}], "number": 1, "html_url": ""},
+            ],
+            "test": [],
+            "docs": [],
+            "refactor": [],
+        }
+
+        path = build_golden_path(grouped, target_minutes=45)
+
+        numbers = [item.number for item in path.items]
+        assert len(numbers) == len(set(numbers))  # No duplicates
+
+    def test_fallback_when_triage_missing(self):
+        """Should use fallback when no triage issues available."""
+        grouped = {
+            "triage": [],
+            "fix": [
+                {"title": "Fix", "labels": [{"name": "size:XS"}], "number": 1, "html_url": ""},
+            ],
+            "test": [
+                {"title": "Test", "labels": [{"name": "size:XS"}], "number": 2, "html_url": ""},
+            ],
+            "docs": [],
+            "refactor": [],
+        }
+
+        path = build_golden_path(grouped, target_minutes=45)
+
+        assert path.item_count > 0
+
+
+class TestGoldenPathDataclass:
+    """Tests for the GoldenPath dataclass."""
+
+    def test_total_time_calculation(self):
+        """Should sum item times correctly."""
+        path = GoldenPath(
+            generated_at=datetime.now(UTC).isoformat(),
+            target_minutes=45,
+            items=[
+                PathItem(1, "Test 1", "XS", "fix", 10, ""),
+                PathItem(2, "Test 2", "S", "test", 15, ""),
+            ],
+        )
+
+        assert path.total_estimated_minutes == 25
+
+    def test_to_dict(self):
+        """Should convert to dict correctly."""
+        path = GoldenPath(
+            generated_at="2024-01-01T00:00:00+00:00",
+            target_minutes=45,
+            items=[PathItem(1, "Test", "XS", "fix", 10, "http://test")],
+        )
+
+        data = path.to_dict()
+
+        assert data["target_minutes"] == 45
+        assert data["total_estimated_minutes"] == 10
+        assert data["item_count"] == 1
+        assert len(data["items"]) == 1
+
+    def test_to_json(self):
+        """Should convert to JSON correctly."""
+        path = GoldenPath(
+            generated_at="2024-01-01T00:00:00+00:00",
+            target_minutes=45,
+            items=[],
+        )
+
+        json_str = path.to_json()
+        data = json.loads(json_str)
+
+        assert data["target_minutes"] == 45
+
+
+class TestGiteaClient:
+    """Tests for the GiteaClient."""
+
+    def test_client_initialization(self):
+        """Client should initialize with config."""
+        config = {
+            "gitea_api": "http://test:3000/api/v1",
+            "repo_slug": "test/repo",
+        }
+        client = GiteaClient(config, "token123")
+
+        assert client.api_base == "http://test:3000/api/v1"
+        assert client.repo_slug == "test/repo"
+        assert client.token == "token123"
+
+    def test_headers_with_token(self):
+        """Headers should include auth token."""
+        config = {"gitea_api": "http://test", "repo_slug": "test/repo"}
+        client = GiteaClient(config, "mytoken")
+
+        headers = client._headers()
+
+        assert headers["Authorization"] == "token mytoken"
+        assert headers["Accept"] == "application/json"
+
+    def test_headers_without_token(self):
+        """Headers should work without token."""
+        config = {"gitea_api": "http://test", "repo_slug": "test/repo"}
+        client = GiteaClient(config, None)
+
+        headers = client._headers()
+
+        assert "Authorization" not in headers
+        assert headers["Accept"] == "application/json"
+
+    @patch("timmy_automations.daily_run.golden_path.urlopen")
+    def test_is_available_success(self, mock_urlopen):
+        """Should detect API availability."""
+        mock_response = MagicMock()
+        mock_response.status = 200
+        mock_context = MagicMock()
+        mock_context.__enter__ = MagicMock(return_value=mock_response)
+        mock_context.__exit__ = MagicMock(return_value=False)
+        mock_urlopen.return_value = mock_context
+
+        config = {"gitea_api": "http://test", "repo_slug": "test/repo"}
+        client = GiteaClient(config, None)
+
+        assert client.is_available() is True
+
+    @patch("urllib.request.urlopen")
+    def test_is_available_failure(self, mock_urlopen):
+        """Should handle API unavailability."""
+        from urllib.error import URLError
+
+        mock_urlopen.side_effect = URLError("Connection refused")
+
+        config = {"gitea_api": "http://test", "repo_slug": "test/repo"}
+        client = GiteaClient(config, None)
+
+        assert client.is_available() is False
+
+
+class TestIntegration:
+    """Integration-style tests."""
+
+    @patch("timmy_automations.daily_run.golden_path.GiteaClient")
+    def test_generate_golden_path_integration(self, mock_client_class):
+        """End-to-end test with mocked Gitea."""
+        # Setup mock
+        mock_client = MagicMock()
+        mock_client.is_available.return_value = True
+        mock_client.get_paginated.return_value = [
+            {
+                "number": 1,
+                "title": "Triage issues",
+                "labels": [{"name": "size:XS"}, {"name": "triage"}],
+                "html_url": "http://test/1",
+            },
+            {
+                "number": 2,
+                "title": "Fix bug",
+                "labels": [{"name": "size:S"}, {"name": "bug"}],
+                "html_url": "http://test/2",
+            },
+            {
+                "number": 3,
+                "title": "Add tests",
+                "labels": [{"name": "size:S"}, {"name": "test"}],
+                "html_url": "http://test/3",
+            },
+            {
+                "number": 4,
+                "title": "Another fix",
+                "labels": [{"name": "size:XS"}, {"name": "bug"}],
+                "html_url": "http://test/4",
+            },
+        ]
+        mock_client_class.return_value = mock_client
+
+        path = generate_golden_path(target_minutes=45)
+
+        assert path.item_count >= 3
+        assert all(item.url.startswith("http://test/") for item in path.items)
+
+    @patch("timmy_automations.daily_run.golden_path.GiteaClient")
+    def test_generate_when_unavailable(self, mock_client_class):
+        """Should return empty path when Gitea unavailable."""
+        mock_client = MagicMock()
+        mock_client.is_available.return_value = False
+        mock_client_class.return_value = mock_client
+
+        path = generate_golden_path(target_minutes=45)
+
+        assert path.item_count == 0
+        assert path.items == []
+
+
+class TestTypePatterns:
+    """Tests for type pattern definitions."""
+
+    def test_type_patterns_structure(self):
+        """Type patterns should have required keys."""
+        for _issue_type, patterns in TYPE_PATTERNS.items():
+            assert "labels" in patterns
+            assert "title" in patterns
+            assert isinstance(patterns["labels"], list)
+            assert isinstance(patterns["title"], list)
+
+    def test_time_estimates_structure(self):
+        """Time estimates should have all sizes."""
+        for size in ["XS", "S", "M"]:
+            assert size in TIME_ESTIMATES
+            for issue_type in ["triage", "fix", "test", "docs", "refactor"]:
+                assert issue_type in TIME_ESTIMATES[size]
+                assert isinstance(TIME_ESTIMATES[size][issue_type], int)
+                assert TIME_ESTIMATES[size][issue_type] > 0

tests/timmy/test_tools_web_fetch.py

@@ -0,0 +1,158 @@
+"""Unit tests for the web_fetch tool in timmy.tools."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+from timmy.tools import web_fetch
+
+
+class TestWebFetch:
+    """Tests for web_fetch function."""
+
+    def test_invalid_url_no_scheme(self):
+        """URLs without http(s) scheme are rejected."""
+        result = web_fetch("example.com")
+        assert "Error: invalid URL" in result
+
+    def test_invalid_url_empty(self):
+        """Empty URL is rejected."""
+        result = web_fetch("")
+        assert "Error: invalid URL" in result
+
+    def test_invalid_url_ftp(self):
+        """Non-HTTP schemes are rejected."""
+        result = web_fetch("ftp://example.com")
+        assert "Error: invalid URL" in result
+
+    @patch("timmy.tools.trafilatura", create=True)
+    @patch("timmy.tools._requests", create=True)
+    def test_successful_fetch(self, mock_requests, mock_trafilatura):
+        """Happy path: fetch + extract returns text."""
+        # We need to patch at import level inside the function
+        mock_resp = MagicMock()
+        mock_resp.text = "<html><body><p>Hello world</p></body></html>"
+
+        with patch.dict(
+            "sys.modules", {"requests": mock_requests, "trafilatura": mock_trafilatura}
+        ):
+            mock_requests.get.return_value = mock_resp
+            mock_requests.exceptions = _make_exceptions()
+            mock_trafilatura.extract.return_value = "Hello world"
+
+            result = web_fetch("https://example.com")
+
+        assert result == "Hello world"
+
+    @patch.dict("sys.modules", {"requests": MagicMock(), "trafilatura": MagicMock()})
+    def test_truncation(self):
+        """Long text is truncated to max_tokens * 4 chars."""
+        import sys
+
+        mock_trafilatura = sys.modules["trafilatura"]
+        mock_requests = sys.modules["requests"]
+
+        long_text = "a" * 20000
+        mock_resp = MagicMock()
+        mock_resp.text = "<html><body>" + long_text + "</body></html>"
+        mock_requests.get.return_value = mock_resp
+        mock_requests.exceptions = _make_exceptions()
+        mock_trafilatura.extract.return_value = long_text
+
+        result = web_fetch("https://example.com", max_tokens=100)
+
+        # 100 tokens * 4 chars = 400 chars max
+        assert len(result) < 500
+        assert "[…truncated" in result
+
+    @patch.dict("sys.modules", {"requests": MagicMock(), "trafilatura": MagicMock()})
+    def test_extraction_failure(self):
+        """Returns error when trafilatura can't extract text."""
+        import sys
+
+        mock_trafilatura = sys.modules["trafilatura"]
+        mock_requests = sys.modules["requests"]
+
+        mock_resp = MagicMock()
+        mock_resp.text = "<html></html>"
+        mock_requests.get.return_value = mock_resp
+        mock_requests.exceptions = _make_exceptions()
+        mock_trafilatura.extract.return_value = None
+
+        result = web_fetch("https://example.com")
+        assert "Error: could not extract" in result
+
+    @patch.dict("sys.modules", {"trafilatura": MagicMock()})
+    def test_timeout(self):
+        """Timeout errors are handled gracefully."""
+
+        mock_requests = MagicMock()
+        exc_mod = _make_exceptions()
+        mock_requests.exceptions = exc_mod
+        mock_requests.get.side_effect = exc_mod.Timeout("timed out")
+
+        with patch.dict("sys.modules", {"requests": mock_requests}):
+            result = web_fetch("https://example.com")
+
+        assert "timed out" in result
+
+    @patch.dict("sys.modules", {"trafilatura": MagicMock()})
+    def test_http_error(self):
+        """HTTP errors (404, 500, etc.) are handled gracefully."""
+
+        mock_requests = MagicMock()
+        exc_mod = _make_exceptions()
+        mock_requests.exceptions = exc_mod
+
+        mock_response = MagicMock()
+        mock_response.status_code = 404
+        mock_requests.get.return_value.raise_for_status.side_effect = exc_mod.HTTPError(
+            response=mock_response
+        )
+
+        with patch.dict("sys.modules", {"requests": mock_requests}):
+            result = web_fetch("https://example.com/nope")
+
+        assert "404" in result
+
+    def test_missing_requests(self):
+        """Graceful error when requests not installed."""
+        with patch.dict("sys.modules", {"requests": None}):
+            result = web_fetch("https://example.com")
+        assert "requests" in result and "not installed" in result
+
+    def test_missing_trafilatura(self):
+        """Graceful error when trafilatura not installed."""
+        mock_requests = MagicMock()
+        with patch.dict("sys.modules", {"requests": mock_requests, "trafilatura": None}):
+            result = web_fetch("https://example.com")
+        assert "trafilatura" in result and "not installed" in result
+
+    def test_catalog_entry_exists(self):
+        """web_fetch should appear in the tool catalog."""
+        from timmy.tools import get_all_available_tools
+
+        catalog = get_all_available_tools()
+        assert "web_fetch" in catalog
+        assert "orchestrator" in catalog["web_fetch"]["available_in"]
+
+
+def _make_exceptions():
+    """Create a mock exceptions module with real exception classes."""
+
+    class Timeout(Exception):
+        pass
+
+    class HTTPError(Exception):
+        def __init__(self, *args, response=None, **kwargs):
+            super().__init__(*args, **kwargs)
+            self.response = response
+
+    class RequestException(Exception):
+        pass
+
+    mod = MagicMock()
+    mod.Timeout = Timeout
+    mod.HTTPError = HTTPError
+    mod.RequestException = RequestException
+    return mod

tests/timmy/test_voice_tts_unit.py

@@ -0,0 +1,280 @@
+"""Unit tests for timmy_serve.voice_tts.
+
+Mocks pyttsx3 so tests run without audio hardware.
+"""
+
+import threading
+from unittest.mock import MagicMock, patch
+
+
+class TestVoiceTTSInit:
+    """Test VoiceTTS initialization with/without pyttsx3."""
+
+    def test_init_success(self):
+        """When pyttsx3 is available, engine initializes with given rate/volume."""
+        mock_pyttsx3 = MagicMock()
+        mock_engine = MagicMock()
+        mock_pyttsx3.init.return_value = mock_engine
+
+        with patch.dict("sys.modules", {"pyttsx3": mock_pyttsx3}):
+            from timmy_serve.voice_tts import VoiceTTS
+
+            tts = VoiceTTS(rate=200, volume=0.8)
+            assert tts.available is True
+            assert tts._rate == 200
+            assert tts._volume == 0.8
+            mock_engine.setProperty.assert_any_call("rate", 200)
+            mock_engine.setProperty.assert_any_call("volume", 0.8)
+
+    def test_init_import_failure(self):
+        """When pyttsx3 import fails, VoiceTTS degrades gracefully."""
+        with patch.dict("sys.modules", {"pyttsx3": None}):
+            # Force reimport by clearing cache
+            import sys
+
+            modules_to_clear = [k for k in sys.modules.keys() if "voice_tts" in k]
+            for mod in modules_to_clear:
+                del sys.modules[mod]
+
+            from timmy_serve.voice_tts import VoiceTTS
+
+            tts = VoiceTTS()
+            assert tts.available is False
+            assert tts._engine is None
+
+
+class TestVoiceTTSSpeak:
+    """Test VoiceTTS speak methods."""
+
+    def test_speak_skips_when_not_available(self):
+        """speak() should skip gracefully when TTS is not available."""
+        from timmy_serve.voice_tts import VoiceTTS
+
+        tts = VoiceTTS.__new__(VoiceTTS)
+        tts._engine = None
+        tts._available = False
+        tts._lock = threading.Lock()
+
+        # Should not raise
+        tts.speak("hello world")
+
+    def test_speak_sync_skips_when_not_available(self):
+        """speak_sync() should skip gracefully when TTS is not available."""
+        from timmy_serve.voice_tts import VoiceTTS
+
+        tts = VoiceTTS.__new__(VoiceTTS)
+        tts._engine = None
+        tts._available = False
+        tts._lock = threading.Lock()
+
+        # Should not raise
+        tts.speak_sync("hello world")
+
+    def test_speak_runs_in_background_thread(self):
+        """speak() should run speech in a background thread."""
+        from timmy_serve.voice_tts import VoiceTTS
+
+        tts = VoiceTTS.__new__(VoiceTTS)
+        tts._engine = MagicMock()
+        tts._available = True
+        tts._lock = threading.Lock()
+
+        captured_threads = []
+        original_thread = threading.Thread
+
+        def capture_thread(*args, **kwargs):
+            t = original_thread(*args, **kwargs)
+            captured_threads.append(t)
+            return t
+
+        with patch.object(threading, "Thread", side_effect=capture_thread):
+            tts.speak("test message")
+            # Wait for threads to complete
+            for t in captured_threads:
+                t.join(timeout=1)
+
+        tts._engine.say.assert_called_with("test message")
+        tts._engine.runAndWait.assert_called_once()
+
+
+class TestVoiceTTSProperties:
+    """Test VoiceTTS property setters."""
+
+    def test_set_rate_updates_property(self):
+        """set_rate() updates internal rate and engine property."""
+        from timmy_serve.voice_tts import VoiceTTS
+
+        tts = VoiceTTS.__new__(VoiceTTS)
+        tts._engine = MagicMock()
+        tts._rate = 175
+
+        tts.set_rate(220)
+        assert tts._rate == 220
+        tts._engine.setProperty.assert_called_with("rate", 220)
+
+    def test_set_rate_without_engine(self):
+        """set_rate() updates internal rate even when engine is None."""
+        from timmy_serve.voice_tts import VoiceTTS
+
+        tts = VoiceTTS.__new__(VoiceTTS)
+        tts._engine = None
+        tts._rate = 175
+
+        tts.set_rate(220)
+        assert tts._rate == 220
+
+    def test_set_volume_clamped_to_max(self):
+        """set_volume() clamps volume to maximum of 1.0."""
+        from timmy_serve.voice_tts import VoiceTTS
+
+        tts = VoiceTTS.__new__(VoiceTTS)
+        tts._engine = MagicMock()
+        tts._volume = 0.9
+
+        tts.set_volume(1.5)
+        assert tts._volume == 1.0
+        tts._engine.setProperty.assert_called_with("volume", 1.0)
+
+    def test_set_volume_clamped_to_min(self):
+        """set_volume() clamps volume to minimum of 0.0."""
+        from timmy_serve.voice_tts import VoiceTTS
+
+        tts = VoiceTTS.__new__(VoiceTTS)
+        tts._engine = MagicMock()
+        tts._volume = 0.9
+
+        tts.set_volume(-0.5)
+        assert tts._volume == 0.0
+        tts._engine.setProperty.assert_called_with("volume", 0.0)
+
+    def test_set_volume_within_range(self):
+        """set_volume() accepts values within 0.0-1.0 range."""
+        from timmy_serve.voice_tts import VoiceTTS
+
+        tts = VoiceTTS.__new__(VoiceTTS)
+        tts._engine = MagicMock()
+        tts._volume = 0.9
+
+        tts.set_volume(0.5)
+        assert tts._volume == 0.5
+        tts._engine.setProperty.assert_called_with("volume", 0.5)
+
+
+class TestVoiceTTSGetVoices:
+    """Test VoiceTTS get_voices() method."""
+
+    def test_get_voices_returns_empty_list_when_no_engine(self):
+        """get_voices() returns empty list when engine is None."""
+        from timmy_serve.voice_tts import VoiceTTS
+
+        tts = VoiceTTS.__new__(VoiceTTS)
+        tts._engine = None
+
+        result = tts.get_voices()
+        assert result == []
+
+    def test_get_voices_returns_formatted_voice_list(self):
+        """get_voices() returns list of voice dicts with id, name, languages."""
+        from timmy_serve.voice_tts import VoiceTTS
+
+        tts = VoiceTTS.__new__(VoiceTTS)
+
+        mock_voice1 = MagicMock()
+        mock_voice1.id = "com.apple.voice.compact.en-US.Samantha"
+        mock_voice1.name = "Samantha"
+        mock_voice1.languages = ["en-US"]
+
+        mock_voice2 = MagicMock()
+        mock_voice2.id = "com.apple.voice.compact.en-GB.Daniel"
+        mock_voice2.name = "Daniel"
+        mock_voice2.languages = ["en-GB"]
+
+        tts._engine = MagicMock()
+        tts._engine.getProperty.return_value = [mock_voice1, mock_voice2]
+
+        voices = tts.get_voices()
+        assert len(voices) == 2
+        assert voices[0]["id"] == "com.apple.voice.compact.en-US.Samantha"
+        assert voices[0]["name"] == "Samantha"
+        assert voices[0]["languages"] == ["en-US"]
+        assert voices[1]["id"] == "com.apple.voice.compact.en-GB.Daniel"
+        assert voices[1]["name"] == "Daniel"
+        assert voices[1]["languages"] == ["en-GB"]
+
+    def test_get_voices_handles_missing_languages_attr(self):
+        """get_voices() handles voices without languages attribute."""
+        from timmy_serve.voice_tts import VoiceTTS
+
+        tts = VoiceTTS.__new__(VoiceTTS)
+
+        mock_voice = MagicMock()
+        mock_voice.id = "voice1"
+        mock_voice.name = "Default Voice"
+        # No languages attribute
+        del mock_voice.languages
+
+        tts._engine = MagicMock()
+        tts._engine.getProperty.return_value = [mock_voice]
+
+        voices = tts.get_voices()
+        assert len(voices) == 1
+        assert voices[0]["languages"] == []
+
+    def test_get_voices_handles_exception(self):
+        """get_voices() returns empty list on exception."""
+        from timmy_serve.voice_tts import VoiceTTS
+
+        tts = VoiceTTS.__new__(VoiceTTS)
+        tts._engine = MagicMock()
+        tts._engine.getProperty.side_effect = RuntimeError("engine error")
+
+        result = tts.get_voices()
+        assert result == []
+
+
+class TestVoiceTTSSetVoice:
+    """Test VoiceTTS set_voice() method."""
+
+    def test_set_voice_updates_property(self):
+        """set_voice() updates engine voice property when engine exists."""
+        from timmy_serve.voice_tts import VoiceTTS
+
+        tts = VoiceTTS.__new__(VoiceTTS)
+        tts._engine = MagicMock()
+
+        tts.set_voice("com.apple.voice.compact.en-US.Samantha")
+        tts._engine.setProperty.assert_called_with(
+            "voice", "com.apple.voice.compact.en-US.Samantha"
+        )
+
+    def test_set_voice_skips_when_no_engine(self):
+        """set_voice() does nothing when engine is None."""
+        from timmy_serve.voice_tts import VoiceTTS
+
+        tts = VoiceTTS.__new__(VoiceTTS)
+        tts._engine = None
+
+        # Should not raise
+        tts.set_voice("some_voice_id")
+
+
+class TestVoiceTTSAvailableProperty:
+    """Test VoiceTTS available property."""
+
+    def test_available_returns_true_when_initialized(self):
+        """available property returns True when engine initialized."""
+        from timmy_serve.voice_tts import VoiceTTS
+
+        tts = VoiceTTS.__new__(VoiceTTS)
+        tts._available = True
+
+        assert tts.available is True
+
+    def test_available_returns_false_when_not_initialized(self):
+        """available property returns False when engine not initialized."""
+        from timmy_serve.voice_tts import VoiceTTS
+
+        tts = VoiceTTS.__new__(VoiceTTS)
+        tts._available = False
+
+        assert tts.available is False

tests/timmy_automations/test_health_snapshot.py

@@ -0,0 +1,410 @@
+"""Tests for health_snapshot module."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from unittest.mock import patch
+
+# Add timmy_automations to path for imports
+sys.path.insert(
+    0, str(Path(__file__).resolve().parent.parent.parent / "timmy_automations" / "daily_run")
+)
+
+from datetime import UTC
+
+import health_snapshot as hs
+
+
+class TestLoadConfig:
+    """Test configuration loading."""
+
+    def test_loads_default_config(self):
+        """Load default configuration."""
+        config = hs.load_config()
+
+        assert "gitea_api" in config
+        assert "repo_slug" in config
+        assert "critical_labels" in config
+        assert "flakiness_lookback_cycles" in config
+
+    def test_environment_overrides(self, monkeypatch):
+        """Environment variables override defaults."""
+        monkeypatch.setenv("TIMMY_GITEA_API", "http://test:3000/api/v1")
+        monkeypatch.setenv("TIMMY_REPO_SLUG", "test/repo")
+
+        config = hs.load_config()
+
+        assert config["gitea_api"] == "http://test:3000/api/v1"
+        assert config["repo_slug"] == "test/repo"
+
+
+class TestGetToken:
+    """Test token retrieval."""
+
+    def test_returns_config_token(self):
+        """Return token from config if present."""
+        config = {"token": "test-token-123"}
+        token = hs.get_token(config)
+
+        assert token == "test-token-123"
+
+    def test_reads_from_file(self, tmp_path, monkeypatch):
+        """Read token from file if no config token."""
+        token_file = tmp_path / "gitea_token"
+        token_file.write_text("file-token-456")
+
+        config = {"token_file": str(token_file)}
+        token = hs.get_token(config)
+
+        assert token == "file-token-456"
+
+    def test_returns_none_when_no_token(self, monkeypatch):
+        """Return None when no token available."""
+        # Prevent repo-root .timmy_gitea_token fallback from leaking real token
+        _orig_exists = Path.exists
+
+        def _exists_no_timmy(self):
+            if self.name == ".timmy_gitea_token":
+                return False
+            return _orig_exists(self)
+
+        monkeypatch.setattr(Path, "exists", _exists_no_timmy)
+        config = {"token_file": "/nonexistent/path"}
+        token = hs.get_token(config)
+
+        assert token is None
+
+
+class TestCISignal:
+    """Test CISignal dataclass."""
+
+    def test_default_details(self):
+        """Details defaults to empty dict."""
+        signal = hs.CISignal(status="pass", message="CI passing")
+
+        assert signal.details == {}
+
+    def test_with_details(self):
+        """Can include details."""
+        signal = hs.CISignal(status="pass", message="CI passing", details={"sha": "abc123"})
+
+        assert signal.details["sha"] == "abc123"
+
+
+class TestIssueSignal:
+    """Test IssueSignal dataclass."""
+
+    def test_default_issues_list(self):
+        """Issues defaults to empty list."""
+        signal = hs.IssueSignal(count=0, p0_count=0, p1_count=0)
+
+        assert signal.issues == []
+
+    def test_with_issues(self):
+        """Can include issues."""
+        issues = [{"number": 1, "title": "Test"}]
+        signal = hs.IssueSignal(count=1, p0_count=1, p1_count=0, issues=issues)
+
+        assert len(signal.issues) == 1
+
+
+class TestFlakinessSignal:
+    """Test FlakinessSignal dataclass."""
+
+    def test_calculated_fields(self):
+        """All fields set correctly."""
+        signal = hs.FlakinessSignal(
+            status="healthy",
+            recent_failures=2,
+            recent_cycles=20,
+            failure_rate=0.1,
+            message="Low flakiness",
+        )
+
+        assert signal.status == "healthy"
+        assert signal.recent_failures == 2
+        assert signal.failure_rate == 0.1
+
+
+class TestHealthSnapshot:
+    """Test HealthSnapshot dataclass."""
+
+    def test_to_dict_structure(self):
+        """to_dict produces expected structure."""
+        snapshot = hs.HealthSnapshot(
+            timestamp="2026-01-01T00:00:00+00:00",
+            overall_status="green",
+            ci=hs.CISignal(status="pass", message="CI passing"),
+            issues=hs.IssueSignal(count=0, p0_count=0, p1_count=0),
+            flakiness=hs.FlakinessSignal(
+                status="healthy",
+                recent_failures=0,
+                recent_cycles=10,
+                failure_rate=0.0,
+                message="All good",
+            ),
+            tokens=hs.TokenEconomySignal(status="balanced", message="Balanced"),
+        )
+
+        data = snapshot.to_dict()
+
+        assert data["timestamp"] == "2026-01-01T00:00:00+00:00"
+        assert data["overall_status"] == "green"
+        assert "ci" in data
+        assert "issues" in data
+        assert "flakiness" in data
+        assert "tokens" in data
+
+    def test_to_dict_limits_issues(self):
+        """to_dict limits issues to 5."""
+        many_issues = [{"number": i, "title": f"Issue {i}"} for i in range(10)]
+        snapshot = hs.HealthSnapshot(
+            timestamp="2026-01-01T00:00:00+00:00",
+            overall_status="green",
+            ci=hs.CISignal(status="pass", message="CI passing"),
+            issues=hs.IssueSignal(count=10, p0_count=5, p1_count=5, issues=many_issues),
+            flakiness=hs.FlakinessSignal(
+                status="healthy",
+                recent_failures=0,
+                recent_cycles=10,
+                failure_rate=0.0,
+                message="All good",
+            ),
+            tokens=hs.TokenEconomySignal(status="balanced", message="Balanced"),
+        )
+
+        data = snapshot.to_dict()
+
+        assert len(data["issues"]["issues"]) == 5
+
+
+class TestCalculateOverallStatus:
+    """Test overall status calculation."""
+
+    def test_green_when_all_healthy(self):
+        """Status is green when all signals healthy."""
+        ci = hs.CISignal(status="pass", message="CI passing")
+        issues = hs.IssueSignal(count=0, p0_count=0, p1_count=0)
+        flakiness = hs.FlakinessSignal(
+            status="healthy",
+            recent_failures=0,
+            recent_cycles=10,
+            failure_rate=0.0,
+            message="All good",
+        )
+
+        status = hs.calculate_overall_status(ci, issues, flakiness)
+
+        assert status == "green"
+
+    def test_red_when_ci_fails(self):
+        """Status is red when CI fails."""
+        ci = hs.CISignal(status="fail", message="CI failed")
+        issues = hs.IssueSignal(count=0, p0_count=0, p1_count=0)
+        flakiness = hs.FlakinessSignal(
+            status="healthy",
+            recent_failures=0,
+            recent_cycles=10,
+            failure_rate=0.0,
+            message="All good",
+        )
+
+        status = hs.calculate_overall_status(ci, issues, flakiness)
+
+        assert status == "red"
+
+    def test_red_when_p0_issues(self):
+        """Status is red when P0 issues exist."""
+        ci = hs.CISignal(status="pass", message="CI passing")
+        issues = hs.IssueSignal(count=1, p0_count=1, p1_count=0)
+        flakiness = hs.FlakinessSignal(
+            status="healthy",
+            recent_failures=0,
+            recent_cycles=10,
+            failure_rate=0.0,
+            message="All good",
+        )
+
+        status = hs.calculate_overall_status(ci, issues, flakiness)
+
+        assert status == "red"
+
+    def test_yellow_when_p1_issues(self):
+        """Status is yellow when P1 issues exist."""
+        ci = hs.CISignal(status="pass", message="CI passing")
+        issues = hs.IssueSignal(count=1, p0_count=0, p1_count=1)
+        flakiness = hs.FlakinessSignal(
+            status="healthy",
+            recent_failures=0,
+            recent_cycles=10,
+            failure_rate=0.0,
+            message="All good",
+        )
+
+        status = hs.calculate_overall_status(ci, issues, flakiness)
+
+        assert status == "yellow"
+
+    def test_yellow_when_flakiness_degraded(self):
+        """Status is yellow when flakiness degraded."""
+        ci = hs.CISignal(status="pass", message="CI passing")
+        issues = hs.IssueSignal(count=0, p0_count=0, p1_count=0)
+        flakiness = hs.FlakinessSignal(
+            status="degraded",
+            recent_failures=5,
+            recent_cycles=20,
+            failure_rate=0.25,
+            message="Moderate flakiness",
+        )
+
+        status = hs.calculate_overall_status(ci, issues, flakiness)
+
+        assert status == "yellow"
+
+    def test_red_when_flakiness_critical(self):
+        """Status is red when flakiness critical."""
+        ci = hs.CISignal(status="pass", message="CI passing")
+        issues = hs.IssueSignal(count=0, p0_count=0, p1_count=0)
+        flakiness = hs.FlakinessSignal(
+            status="critical",
+            recent_failures=10,
+            recent_cycles=20,
+            failure_rate=0.5,
+            message="High flakiness",
+        )
+
+        status = hs.calculate_overall_status(ci, issues, flakiness)
+
+        assert status == "red"
+
+
+class TestCheckFlakiness:
+    """Test flakiness checking."""
+
+    def test_no_data_returns_unknown(self, tmp_path, monkeypatch):
+        """Return unknown when no cycle data exists."""
+        monkeypatch.setattr(hs, "REPO_ROOT", tmp_path)
+        config = {"flakiness_lookback_cycles": 20}
+
+        signal = hs.check_flakiness(config)
+
+        assert signal.status == "unknown"
+        assert signal.message == "No cycle data available"
+
+    def test_calculates_failure_rate(self, tmp_path, monkeypatch):
+        """Calculate failure rate from cycle data."""
+        monkeypatch.setattr(hs, "REPO_ROOT", tmp_path)
+
+        retro_dir = tmp_path / ".loop" / "retro"
+        retro_dir.mkdir(parents=True)
+
+        cycles = [
+            json.dumps({"success": True, "cycle": 1}),
+            json.dumps({"success": True, "cycle": 2}),
+            json.dumps({"success": False, "cycle": 3}),
+            json.dumps({"success": True, "cycle": 4}),
+            json.dumps({"success": False, "cycle": 5}),
+        ]
+        retro_file = retro_dir / "cycles.jsonl"
+        retro_file.write_text("\n".join(cycles))
+
+        config = {"flakiness_lookback_cycles": 20}
+        signal = hs.check_flakiness(config)
+
+        assert signal.recent_cycles == 5
+        assert signal.recent_failures == 2
+        assert signal.failure_rate == 0.4
+        assert signal.status == "critical"  # 40% > 30%
+
+
+class TestCheckTokenEconomy:
+    """Test token economy checking."""
+
+    def test_no_data_returns_unknown(self, tmp_path, monkeypatch):
+        """Return unknown when no token data exists."""
+        monkeypatch.setattr(hs, "REPO_ROOT", tmp_path)
+        config = {}
+
+        signal = hs.check_token_economy(config)
+
+        assert signal.status == "unknown"
+
+    def test_calculates_balanced(self, tmp_path, monkeypatch):
+        """Detect balanced token economy."""
+        monkeypatch.setattr(hs, "REPO_ROOT", tmp_path)
+
+        loop_dir = tmp_path / ".loop"
+        loop_dir.mkdir(parents=True)
+
+        from datetime import datetime
+
+        now = datetime.now(UTC).isoformat()
+        transactions = [
+            json.dumps({"timestamp": now, "delta": 10}),
+            json.dumps({"timestamp": now, "delta": -5}),
+        ]
+        ledger_file = loop_dir / "token_economy.jsonl"
+        ledger_file.write_text("\n".join(transactions))
+
+        config = {}
+        signal = hs.check_token_economy(config)
+
+        assert signal.status == "balanced"
+        assert signal.recent_mint == 10
+        assert signal.recent_burn == 5
+
+
+class TestGiteaClient:
+    """Test Gitea API client."""
+
+    def test_initialization(self):
+        """Initialize with config and token."""
+        config = {"gitea_api": "http://test:3000/api/v1", "repo_slug": "test/repo"}
+        client = hs.GiteaClient(config, "token123")
+
+        assert client.api_base == "http://test:3000/api/v1"
+        assert client.repo_slug == "test/repo"
+        assert client.token == "token123"
+
+    def test_headers_with_token(self):
+        """Include authorization header with token."""
+        config = {"gitea_api": "http://test:3000/api/v1", "repo_slug": "test/repo"}
+        client = hs.GiteaClient(config, "token123")
+
+        headers = client._headers()
+
+        assert headers["Authorization"] == "token token123"
+        assert headers["Accept"] == "application/json"
+
+    def test_headers_without_token(self):
+        """No authorization header without token."""
+        config = {"gitea_api": "http://test:3000/api/v1", "repo_slug": "test/repo"}
+        client = hs.GiteaClient(config, None)
+
+        headers = client._headers()
+
+        assert "Authorization" not in headers
+        assert headers["Accept"] == "application/json"
+
+
+class TestGenerateSnapshot:
+    """Test snapshot generation."""
+
+    def test_returns_snapshot(self):
+        """Generate a complete snapshot."""
+        config = hs.load_config()
+
+        with (
+            patch.object(hs.GiteaClient, "is_available", return_value=False),
+            patch.object(hs.GiteaClient, "__init__", return_value=None),
+        ):
+            snapshot = hs.generate_snapshot(config, None)
+
+        assert isinstance(snapshot, hs.HealthSnapshot)
+        assert snapshot.overall_status in ["green", "yellow", "red", "unknown"]
+        assert snapshot.ci is not None
+        assert snapshot.issues is not None
+        assert snapshot.flakiness is not None
+        assert snapshot.tokens is not None

tests/timmy_automations/test_token_rules.py

@@ -0,0 +1,524 @@
+"""Tests for token_rules module."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+# Add timmy_automations to path for imports
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent.parent / "timmy_automations"))
+
+from utils import token_rules as tr
+
+
+class TestTokenEvent:
+    """Test TokenEvent dataclass."""
+
+    def test_delta_calculation_reward(self):
+        """Delta is positive for rewards."""
+        event = tr.TokenEvent(
+            name="test",
+            description="Test event",
+            reward=10,
+            penalty=0,
+            category="test",
+        )
+        assert event.delta == 10
+
+    def test_delta_calculation_penalty(self):
+        """Delta is negative for penalties."""
+        event = tr.TokenEvent(
+            name="test",
+            description="Test event",
+            reward=0,
+            penalty=-5,
+            category="test",
+        )
+        assert event.delta == -5
+
+    def test_delta_calculation_mixed(self):
+        """Delta is net of reward and penalty."""
+        event = tr.TokenEvent(
+            name="test",
+            description="Test event",
+            reward=10,
+            penalty=-3,
+            category="test",
+        )
+        assert event.delta == 7
+
+
+class TestTokenRulesLoading:
+    """Test TokenRules configuration loading."""
+
+    def test_loads_from_yaml_file(self, tmp_path):
+        """Load configuration from YAML file."""
+        yaml = pytest.importorskip("yaml")
+
+        config_file = tmp_path / "token_rules.yaml"
+        config_data = {
+            "version": "1.0.0-test",
+            "events": {
+                "test_event": {
+                    "description": "A test event",
+                    "reward": 15,
+                    "category": "test",
+                }
+            },
+            "gating_thresholds": {"test_op": 50},
+            "daily_limits": {"test": {"max_earn": 100, "max_spend": 10}},
+            "audit": {"log_all_transactions": False},
+        }
+        config_file.write_text(yaml.dump(config_data))
+
+        rules = tr.TokenRules(config_path=config_file)
+
+        assert rules.get_config_version() == "1.0.0-test"
+        assert rules.get_delta("test_event") == 15
+        assert rules.get_gate_threshold("test_op") == 50
+
+    def test_fallback_when_yaml_missing(self, tmp_path):
+        """Use fallback defaults when YAML file doesn't exist."""
+        config_file = tmp_path / "nonexistent.yaml"
+
+        rules = tr.TokenRules(config_path=config_file)
+
+        assert rules.get_config_version() == "fallback"
+        # Fallback should have some basic events
+        assert rules.get_delta("pr_merged") == 10
+        assert rules.get_delta("test_fixed") == 8
+        assert rules.get_delta("automation_failure") == -2
+
+    def test_fallback_when_yaml_not_installed(self, tmp_path):
+        """Use fallback when PyYAML is not installed."""
+        with patch.dict(sys.modules, {"yaml": None}):
+            config_file = tmp_path / "token_rules.yaml"
+            config_file.write_text("version: '1.0.0'")
+
+            rules = tr.TokenRules(config_path=config_file)
+
+            assert rules.get_config_version() == "fallback"
+
+
+class TestTokenRulesGetDelta:
+    """Test get_delta method."""
+
+    def test_get_delta_existing_event(self, tmp_path):
+        """Get delta for configured event."""
+        yaml = pytest.importorskip("yaml")
+
+        config_file = tmp_path / "token_rules.yaml"
+        config_data = {
+            "version": "1.0.0",
+            "events": {
+                "pr_merged": {"description": "PR merged", "reward": 10, "category": "merge"},
+                "automation_failure": {"description": "Failure", "penalty": -2, "category": "ops"},
+            },
+        }
+        config_file.write_text(yaml.dump(config_data))
+
+        rules = tr.TokenRules(config_path=config_file)
+
+        assert rules.get_delta("pr_merged") == 10
+        assert rules.get_delta("automation_failure") == -2
+
+    def test_get_delta_unknown_event(self, tmp_path):
+        """Return 0 for unknown events."""
+        config_file = tmp_path / "nonexistent.yaml"
+        rules = tr.TokenRules(config_path=config_file)
+
+        assert rules.get_delta("unknown_event") == 0
+
+
+class TestTokenRulesGetEvent:
+    """Test get_event method."""
+
+    def test_get_event_returns_full_config(self, tmp_path):
+        """Get full event configuration."""
+        yaml = pytest.importorskip("yaml")
+
+        config_file = tmp_path / "token_rules.yaml"
+        config_data = {
+            "version": "1.0.0",
+            "events": {
+                "pr_merged": {
+                    "description": "PR merged successfully",
+                    "reward": 10,
+                    "category": "merge",
+                    "gate_threshold": 0,
+                }
+            },
+        }
+        config_file.write_text(yaml.dump(config_data))
+
+        rules = tr.TokenRules(config_path=config_file)
+        event = rules.get_event("pr_merged")
+
+        assert event is not None
+        assert event.name == "pr_merged"
+        assert event.description == "PR merged successfully"
+        assert event.reward == 10
+        assert event.category == "merge"
+        assert event.gate_threshold == 0
+
+    def test_get_event_unknown_returns_none(self, tmp_path):
+        """Return None for unknown event."""
+        config_file = tmp_path / "nonexistent.yaml"
+        rules = tr.TokenRules(config_path=config_file)
+
+        assert rules.get_event("unknown") is None
+
+
+class TestTokenRulesListEvents:
+    """Test list_events method."""
+
+    def test_list_all_events(self, tmp_path):
+        """List all configured events."""
+        yaml = pytest.importorskip("yaml")
+
+        config_file = tmp_path / "token_rules.yaml"
+        config_data = {
+            "version": "1.0.0",
+            "events": {
+                "event_a": {"description": "A", "reward": 5, "category": "cat1"},
+                "event_b": {"description": "B", "reward": 10, "category": "cat2"},
+                "event_c": {"description": "C", "reward": 15, "category": "cat1"},
+            },
+        }
+        config_file.write_text(yaml.dump(config_data))
+
+        rules = tr.TokenRules(config_path=config_file)
+        events = rules.list_events()
+
+        assert len(events) == 3
+        event_names = {e.name for e in events}
+        assert "event_a" in event_names
+        assert "event_b" in event_names
+        assert "event_c" in event_names
+
+    def test_list_events_by_category(self, tmp_path):
+        """Filter events by category."""
+        yaml = pytest.importorskip("yaml")
+
+        config_file = tmp_path / "token_rules.yaml"
+        config_data = {
+            "version": "1.0.0",
+            "events": {
+                "event_a": {"description": "A", "reward": 5, "category": "cat1"},
+                "event_b": {"description": "B", "reward": 10, "category": "cat2"},
+                "event_c": {"description": "C", "reward": 15, "category": "cat1"},
+            },
+        }
+        config_file.write_text(yaml.dump(config_data))
+
+        rules = tr.TokenRules(config_path=config_file)
+        events = rules.list_events(category="cat1")
+
+        assert len(events) == 2
+        for event in events:
+            assert event.category == "cat1"
+
+
+class TestTokenRulesGating:
+    """Test gating threshold methods."""
+
+    def test_check_gate_with_threshold(self, tmp_path):
+        """Check gate when threshold is defined."""
+        yaml = pytest.importorskip("yaml")
+
+        config_file = tmp_path / "token_rules.yaml"
+        config_data = {
+            "version": "1.0.0",
+            "events": {},
+            "gating_thresholds": {"pr_merge": 50},
+        }
+        config_file.write_text(yaml.dump(config_data))
+
+        rules = tr.TokenRules(config_path=config_file)
+
+        assert rules.check_gate("pr_merge", current_tokens=100) is True
+        assert rules.check_gate("pr_merge", current_tokens=50) is True
+        assert rules.check_gate("pr_merge", current_tokens=49) is False
+        assert rules.check_gate("pr_merge", current_tokens=0) is False
+
+    def test_check_gate_no_threshold(self, tmp_path):
+        """Check gate when no threshold is defined (always allowed)."""
+        yaml = pytest.importorskip("yaml")
+
+        config_file = tmp_path / "token_rules.yaml"
+        config_data = {
+            "version": "1.0.0",
+            "events": {},
+            "gating_thresholds": {},
+        }
+        config_file.write_text(yaml.dump(config_data))
+
+        rules = tr.TokenRules(config_path=config_file)
+
+        # No threshold defined, should always be allowed
+        assert rules.check_gate("unknown_op", current_tokens=0) is True
+        assert rules.check_gate("unknown_op", current_tokens=-100) is True
+
+    def test_get_gate_threshold(self, tmp_path):
+        """Get threshold value."""
+        yaml = pytest.importorskip("yaml")
+
+        config_file = tmp_path / "token_rules.yaml"
+        config_data = {
+            "version": "1.0.0",
+            "gating_thresholds": {"pr_merge": 50, "sensitive_op": 100},
+        }
+        config_file.write_text(yaml.dump(config_data))
+
+        rules = tr.TokenRules(config_path=config_file)
+
+        assert rules.get_gate_threshold("pr_merge") == 50
+        assert rules.get_gate_threshold("sensitive_op") == 100
+        assert rules.get_gate_threshold("unknown") is None
+
+
+class TestTokenRulesDailyLimits:
+    """Test daily limits methods."""
+
+    def test_get_daily_limits(self, tmp_path):
+        """Get daily limits for a category."""
+        yaml = pytest.importorskip("yaml")
+
+        config_file = tmp_path / "token_rules.yaml"
+        config_data = {
+            "version": "1.0.0",
+            "daily_limits": {
+                "triage": {"max_earn": 100, "max_spend": 0},
+                "merge": {"max_earn": 50, "max_spend": 10},
+            },
+        }
+        config_file.write_text(yaml.dump(config_data))
+
+        rules = tr.TokenRules(config_path=config_file)
+
+        triage_limits = rules.get_daily_limits("triage")
+        assert triage_limits is not None
+        assert triage_limits.max_earn == 100
+        assert triage_limits.max_spend == 0
+
+        merge_limits = rules.get_daily_limits("merge")
+        assert merge_limits is not None
+        assert merge_limits.max_earn == 50
+        assert merge_limits.max_spend == 10
+
+    def test_get_daily_limits_unknown(self, tmp_path):
+        """Return None for unknown category."""
+        yaml = pytest.importorskip("yaml")
+
+        config_file = tmp_path / "token_rules.yaml"
+        config_data = {"version": "1.0.0", "daily_limits": {}}
+        config_file.write_text(yaml.dump(config_data))
+
+        rules = tr.TokenRules(config_path=config_file)
+
+        assert rules.get_daily_limits("unknown") is None
+
+
+class TestTokenRulesComputeTransaction:
+    """Test compute_transaction method."""
+
+    def test_compute_successful_transaction(self, tmp_path):
+        """Compute transaction for valid event."""
+        yaml = pytest.importorskip("yaml")
+
+        config_file = tmp_path / "token_rules.yaml"
+        config_data = {
+            "version": "1.0.0",
+            "events": {
+                "pr_merged": {"description": "PR merged", "reward": 10, "category": "merge"}
+            },
+        }
+        config_file.write_text(yaml.dump(config_data))
+
+        rules = tr.TokenRules(config_path=config_file)
+        result = rules.compute_transaction("pr_merged", current_tokens=100)
+
+        assert result["event"] == "pr_merged"
+        assert result["delta"] == 10
+        assert result["category"] == "merge"
+        assert result["allowed"] is True
+        assert result["new_balance"] == 110
+        assert result["limit_reached"] is False
+
+    def test_compute_unknown_event(self, tmp_path):
+        """Compute transaction for unknown event."""
+        config_file = tmp_path / "nonexistent.yaml"
+        rules = tr.TokenRules(config_path=config_file)
+        result = rules.compute_transaction("unknown_event", current_tokens=50)
+
+        assert result["event"] == "unknown_event"
+        assert result["delta"] == 0
+        assert result["allowed"] is False
+        assert result["reason"] == "unknown_event"
+        assert result["new_balance"] == 50
+
+    def test_compute_with_gate_check(self, tmp_path):
+        """Compute transaction respects gating."""
+        yaml = pytest.importorskip("yaml")
+
+        config_file = tmp_path / "token_rules.yaml"
+        config_data = {
+            "version": "1.0.0",
+            "events": {
+                "sensitive_op": {
+                    "description": "Sensitive",
+                    "reward": 50,
+                    "category": "sensitive",
+                    "gate_threshold": 100,
+                }
+            },
+        }
+        config_file.write_text(yaml.dump(config_data))
+
+        rules = tr.TokenRules(config_path=config_file)
+
+        # With enough tokens
+        result = rules.compute_transaction("sensitive_op", current_tokens=150)
+        assert result["allowed"] is True
+
+        # Without enough tokens
+        result = rules.compute_transaction("sensitive_op", current_tokens=50)
+        assert result["allowed"] is False
+        assert "gate_reason" in result
+
+    def test_compute_with_daily_limits(self, tmp_path):
+        """Compute transaction respects daily limits."""
+        yaml = pytest.importorskip("yaml")
+
+        config_file = tmp_path / "token_rules.yaml"
+        config_data = {
+            "version": "1.0.0",
+            "events": {
+                "triage_action": {
+                    "description": "Triage",
+                    "reward": 20,
+                    "category": "triage",
+                }
+            },
+            "daily_limits": {"triage": {"max_earn": 50, "max_spend": 0}},
+        }
+        config_file.write_text(yaml.dump(config_data))
+
+        rules = tr.TokenRules(config_path=config_file)
+
+        # Within limit
+        daily_earned = {"triage": 20}
+        result = rules.compute_transaction(
+            "triage_action", current_tokens=100, current_daily_earned=daily_earned
+        )
+        assert result["allowed"] is True
+        assert result["limit_reached"] is False
+
+        # Would exceed limit (20 + 20 > 50 is false, so this should be fine)
+        # Let's test with higher current earned
+        daily_earned = {"triage": 40}
+        result = rules.compute_transaction(
+            "triage_action", current_tokens=100, current_daily_earned=daily_earned
+        )
+        assert result["allowed"] is False
+        assert result["limit_reached"] is True
+        assert "limit_reason" in result
+
+
+class TestTokenRulesCategories:
+    """Test category methods."""
+
+    def test_get_categories(self, tmp_path):
+        """Get all unique categories."""
+        yaml = pytest.importorskip("yaml")
+
+        config_file = tmp_path / "token_rules.yaml"
+        config_data = {
+            "version": "1.0.0",
+            "events": {
+                "event_a": {"description": "A", "reward": 5, "category": "cat1"},
+                "event_b": {"description": "B", "reward": 10, "category": "cat2"},
+                "event_c": {"description": "C", "reward": 15, "category": "cat1"},
+            },
+        }
+        config_file.write_text(yaml.dump(config_data))
+
+        rules = tr.TokenRules(config_path=config_file)
+        categories = rules.get_categories()
+
+        assert sorted(categories) == ["cat1", "cat2"]
+
+
+class TestTokenRulesAudit:
+    """Test audit methods."""
+
+    def test_is_auditable_true(self, tmp_path):
+        """Check if auditable when enabled."""
+        yaml = pytest.importorskip("yaml")
+
+        config_file = tmp_path / "token_rules.yaml"
+        config_data = {"version": "1.0.0", "audit": {"log_all_transactions": True}}
+        config_file.write_text(yaml.dump(config_data))
+
+        rules = tr.TokenRules(config_path=config_file)
+        assert rules.is_auditable() is True
+
+    def test_is_auditable_false(self, tmp_path):
+        """Check if auditable when disabled."""
+        yaml = pytest.importorskip("yaml")
+
+        config_file = tmp_path / "token_rules.yaml"
+        config_data = {"version": "1.0.0", "audit": {"log_all_transactions": False}}
+        config_file.write_text(yaml.dump(config_data))
+
+        rules = tr.TokenRules(config_path=config_file)
+        assert rules.is_auditable() is False
+
+
+class TestConvenienceFunctions:
+    """Test module-level convenience functions."""
+
+    def test_get_token_delta(self, tmp_path):
+        """Convenience function returns delta."""
+        config_file = tmp_path / "nonexistent.yaml"
+
+        with patch.object(tr.TokenRules, "CONFIG_PATH", config_file):
+            delta = tr.get_token_delta("pr_merged")
+            assert delta == 10  # From fallback
+
+    def test_check_operation_gate(self, tmp_path):
+        """Convenience function checks gate."""
+        config_file = tmp_path / "nonexistent.yaml"
+
+        with patch.object(tr.TokenRules, "CONFIG_PATH", config_file):
+            # Fallback has pr_merge gate at 0
+            assert tr.check_operation_gate("pr_merge", current_tokens=0) is True
+            assert tr.check_operation_gate("pr_merge", current_tokens=100) is True
+
+    def test_compute_token_reward(self, tmp_path):
+        """Convenience function computes reward."""
+        config_file = tmp_path / "nonexistent.yaml"
+
+        with patch.object(tr.TokenRules, "CONFIG_PATH", config_file):
+            result = tr.compute_token_reward("pr_merged", current_tokens=50)
+            assert result["event"] == "pr_merged"
+            assert result["delta"] == 10
+            assert result["new_balance"] == 60
+
+    def test_list_token_events(self, tmp_path):
+        """Convenience function lists events."""
+        config_file = tmp_path / "nonexistent.yaml"
+
+        with patch.object(tr.TokenRules, "CONFIG_PATH", config_file):
+            events = tr.list_token_events()
+            assert len(events) >= 3  # Fallback has at least 3 events
+
+            # Check structure
+            for event in events:
+                assert "name" in event
+                assert "description" in event
+                assert "delta" in event
+                assert "category" in event

tests/timmy_automations/test_weekly_narrative.py

@@ -0,0 +1,343 @@
+"""Tests for weekly_narrative.py script."""
+
+from __future__ import annotations
+
+import json
+import sys
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+# Add timmy_automations to path for imports
+sys.path.insert(
+    0, str(Path(__file__).resolve().parent.parent.parent / "timmy_automations" / "daily_run")
+)
+
+import weekly_narrative as wn
+
+
+class TestParseTimestamp:
+    """Test timestamp parsing."""
+
+    def test_parse_iso_with_z(self):
+        """Parse ISO timestamp with Z suffix."""
+        result = wn.parse_ts("2026-03-21T12:00:00Z")
+        assert result is not None
+        assert result.year == 2026
+        assert result.month == 3
+        assert result.day == 21
+
+    def test_parse_iso_with_offset(self):
+        """Parse ISO timestamp with timezone offset."""
+        result = wn.parse_ts("2026-03-21T12:00:00+00:00")
+        assert result is not None
+        assert result.year == 2026
+
+    def test_parse_empty_string(self):
+        """Empty string returns None."""
+        result = wn.parse_ts("")
+        assert result is None
+
+    def test_parse_invalid_string(self):
+        """Invalid string returns None."""
+        result = wn.parse_ts("not-a-timestamp")
+        assert result is None
+
+
+class TestCollectCyclesData:
+    """Test cycle data collection."""
+
+    def test_no_cycles_file(self, tmp_path):
+        """Handle missing cycles file gracefully."""
+        with patch.object(wn, "REPO_ROOT", tmp_path):
+            since = datetime.now(UTC) - timedelta(days=7)
+            result = wn.collect_cycles_data(since)
+            assert result["total"] == 0
+            assert result["successes"] == 0
+            assert result["failures"] == 0
+
+    def test_collect_recent_cycles(self, tmp_path):
+        """Collect cycles within lookback period."""
+        retro_dir = tmp_path / ".loop" / "retro"
+        retro_dir.mkdir(parents=True)
+
+        now = datetime.now(UTC)
+        cycles = [
+            {"timestamp": now.isoformat(), "success": True, "cycle": 1},
+            {"timestamp": now.isoformat(), "success": False, "cycle": 2},
+            {"timestamp": (now - timedelta(days=10)).isoformat(), "success": True, "cycle": 3},
+        ]
+
+        with open(retro_dir / "cycles.jsonl", "w") as f:
+            for c in cycles:
+                f.write(json.dumps(c) + "\n")
+
+        with patch.object(wn, "REPO_ROOT", tmp_path):
+            since = now - timedelta(days=7)
+            result = wn.collect_cycles_data(since)
+            assert result["total"] == 2  # Only recent 2
+            assert result["successes"] == 1
+            assert result["failures"] == 1
+
+
+class TestExtractThemes:
+    """Test theme extraction from issues."""
+
+    def test_extract_layer_labels(self):
+        """Extract layer labels from issues."""
+        issues = [
+            {"labels": [{"name": "layer:triage"}, {"name": "bug"}]},
+            {"labels": [{"name": "layer:tests"}, {"name": "bug"}]},
+            {"labels": [{"name": "layer:triage"}, {"name": "feature"}]},
+        ]
+
+        result = wn.extract_themes(issues)
+
+        assert len(result["layers"]) == 2
+        layer_names = {layer["name"] for layer in result["layers"]}
+        assert "triage" in layer_names
+        assert "tests" in layer_names
+
+    def test_extract_type_labels(self):
+        """Extract type labels (bug/feature/etc)."""
+        issues = [
+            {"labels": [{"name": "bug"}]},
+            {"labels": [{"name": "feature"}]},
+            {"labels": [{"name": "bug"}]},
+        ]
+
+        result = wn.extract_themes(issues)
+
+        type_names = {t_type["name"] for t_type in result["types"]}
+        assert "bug" in type_names
+        assert "feature" in type_names
+
+    def test_empty_issues(self):
+        """Handle empty issue list."""
+        result = wn.extract_themes([])
+        assert result["layers"] == []
+        assert result["types"] == []
+        assert result["top_labels"] == []
+
+
+class TestExtractAgentContributions:
+    """Test agent contribution extraction."""
+
+    def test_extract_assignees(self):
+        """Extract assignee counts."""
+        issues = [
+            {"assignee": {"login": "kimi"}},
+            {"assignee": {"login": "hermes"}},
+            {"assignee": {"login": "kimi"}},
+        ]
+
+        result = wn.extract_agent_contributions(issues, [], [])
+
+        assert len(result["active_assignees"]) == 2
+        assignee_logins = {a["login"] for a in result["active_assignees"]}  # noqa: E741
+        assert "kimi" in assignee_logins
+        assert "hermes" in assignee_logins
+
+    def test_extract_pr_authors(self):
+        """Extract PR author counts."""
+        prs = [
+            {"user": {"login": "kimi"}},
+            {"user": {"login": "claude"}},
+            {"user": {"login": "kimi"}},
+        ]
+
+        result = wn.extract_agent_contributions([], prs, [])
+
+        assert len(result["pr_authors"]) == 2
+
+    def test_kimi_mentions_in_cycles(self):
+        """Count Kimi mentions in cycle notes."""
+        cycles = [
+            {"notes": "Kimi did great work", "reason": ""},
+            {"notes": "", "reason": "Kimi timeout"},
+            {"notes": "All good", "reason": ""},
+        ]
+
+        result = wn.extract_agent_contributions([], [], cycles)
+        assert result["kimi_mentioned_cycles"] == 2
+
+
+class TestAnalyzeTestShifts:
+    """Test test pattern analysis."""
+
+    def test_no_cycles(self):
+        """Handle no cycle data."""
+        result = wn.analyze_test_shifts([])
+        assert "note" in result
+
+    def test_test_metrics(self):
+        """Calculate test metrics from cycles."""
+        cycles = [
+            {"tests_passed": 100, "tests_added": 5},
+            {"tests_passed": 150, "tests_added": 3},
+        ]
+
+        result = wn.analyze_test_shifts(cycles)
+
+        assert result["total_tests_passed"] == 250
+        assert result["total_tests_added"] == 8
+
+
+class TestGenerateVibeSummary:
+    """Test vibe summary generation."""
+
+    def test_productive_vibe(self):
+        """High success rate and activity = productive vibe."""
+        cycles_data = {"success_rate": 0.95, "successes": 10, "failures": 1}
+        issues_data = {"closed_count": 5}
+
+        result = wn.generate_vibe_summary(cycles_data, issues_data, {}, {"layers": []}, {}, {}, {})
+
+        assert result["overall"] == "productive"
+        assert "strong week" in result["description"].lower()
+
+    def test_struggling_vibe(self):
+        """More failures than successes = struggling vibe."""
+        cycles_data = {"success_rate": 0.3, "successes": 3, "failures": 7}
+        issues_data = {"closed_count": 0}
+
+        result = wn.generate_vibe_summary(cycles_data, issues_data, {}, {"layers": []}, {}, {}, {})
+
+        assert result["overall"] == "struggling"
+
+    def test_quiet_vibe(self):
+        """Low activity = quiet vibe."""
+        cycles_data = {"success_rate": 0.0, "successes": 0, "failures": 0}
+        issues_data = {"closed_count": 0}
+
+        result = wn.generate_vibe_summary(cycles_data, issues_data, {}, {"layers": []}, {}, {}, {})
+
+        assert result["overall"] == "quiet"
+
+
+class TestGenerateMarkdownSummary:
+    """Test markdown summary generation."""
+
+    def test_includes_header(self):
+        """Markdown includes header."""
+        narrative = {
+            "period": {"start": "2026-03-14T00:00:00", "end": "2026-03-21T00:00:00"},
+            "vibe": {"overall": "productive", "description": "Good week"},
+            "activity": {
+                "cycles": {"total": 10, "successes": 9, "failures": 1},
+                "issues": {"closed": 5, "opened": 3},
+                "pull_requests": {"merged": 4, "opened": 2},
+            },
+        }
+
+        result = wn.generate_markdown_summary(narrative)
+
+        assert "# Weekly Narrative Summary" in result
+        assert "productive" in result.lower()
+        assert "10 total" in result or "10" in result
+
+    def test_includes_focus_areas(self):
+        """Markdown includes focus areas when present."""
+        narrative = {
+            "period": {"start": "2026-03-14", "end": "2026-03-21"},
+            "vibe": {
+                "overall": "productive",
+                "description": "Good week",
+                "focus_areas": ["triage (5 items)", "tests (3 items)"],
+            },
+            "activity": {
+                "cycles": {"total": 0, "successes": 0, "failures": 0},
+                "issues": {"closed": 0, "opened": 0},
+                "pull_requests": {"merged": 0, "opened": 0},
+            },
+        }
+
+        result = wn.generate_markdown_summary(narrative)
+
+        assert "Focus Areas" in result
+        assert "triage" in result
+
+
+class TestConfigLoading:
+    """Test configuration loading."""
+
+    def test_default_config(self, tmp_path):
+        """Default config when manifest missing."""
+        with patch.object(wn, "CONFIG_PATH", tmp_path / "nonexistent.json"):
+            config = wn.load_automation_config()
+            assert config["lookback_days"] == 7
+            assert config["enabled"] is True
+
+    def test_environment_override(self, tmp_path):
+        """Environment variables override config."""
+        with patch.dict("os.environ", {"TIMMY_WEEKLY_NARRATIVE_ENABLED": "false"}):
+            with patch.object(wn, "CONFIG_PATH", tmp_path / "nonexistent.json"):
+                config = wn.load_automation_config()
+                assert config["enabled"] is False
+
+
+class TestMain:
+    """Test main function."""
+
+    def test_disabled_exits_cleanly(self, tmp_path):
+        """When disabled and no --force, exits cleanly."""
+        with patch.object(wn, "REPO_ROOT", tmp_path):
+            with patch.object(wn, "load_automation_config", return_value={"enabled": False}):
+                with patch("sys.argv", ["weekly_narrative"]):
+                    result = wn.main()
+                    assert result == 0
+
+    def test_force_runs_when_disabled(self, tmp_path):
+        """--force runs even when disabled."""
+        # Setup minimal structure
+        (tmp_path / ".loop" / "retro").mkdir(parents=True)
+
+        with patch.object(wn, "REPO_ROOT", tmp_path):
+            with patch.object(
+                wn,
+                "load_automation_config",
+                return_value={
+                    "enabled": False,
+                    "lookback_days": 7,
+                    "gitea_api": "http://localhost:3000/api/v1",
+                    "repo_slug": "test/repo",
+                    "token_file": "~/.hermes/gitea_token",
+                },
+            ):
+                with patch.object(wn, "GiteaClient") as mock_client:
+                    mock_instance = MagicMock()
+                    mock_instance.is_available.return_value = False
+                    mock_client.return_value = mock_instance
+
+                    with patch("sys.argv", ["weekly_narrative", "--force"]):
+                        result = wn.main()
+                        # Should complete without error even though Gitea unavailable
+                        assert result == 0
+
+
+class TestGiteaClient:
+    """Test Gitea API client."""
+
+    def test_is_available_when_unavailable(self):
+        """is_available returns False when server down."""
+        config = {"gitea_api": "http://localhost:99999", "repo_slug": "test/repo"}
+        client = wn.GiteaClient(config, None)
+
+        # Should return False without raising
+        assert client.is_available() is False
+
+    def test_headers_with_token(self):
+        """Headers include Authorization when token provided."""
+        config = {"gitea_api": "http://localhost:3000", "repo_slug": "test/repo"}
+        client = wn.GiteaClient(config, "test-token")
+
+        headers = client._headers()
+        assert headers["Authorization"] == "token test-token"
+
+    def test_headers_without_token(self):
+        """Headers don't include Authorization when no token."""
+        config = {"gitea_api": "http://localhost:3000", "repo_slug": "test/repo"}
+        client = wn.GiteaClient(config, None)
+
+        headers = client._headers()
+        assert "Authorization" not in headers

tests/unit/test_matrix_config.py

@@ -0,0 +1,331 @@
+"""Tests for the matrix configuration loader utility."""
+
+from pathlib import Path
+
+import pytest
+import yaml
+
+from infrastructure.matrix_config import (
+    AgentConfig,
+    AgentsConfig,
+    EnvironmentConfig,
+    FeaturesConfig,
+    LightingConfig,
+    MatrixConfig,
+    PointLight,
+    load_from_yaml,
+)
+
+
+class TestPointLight:
+    """Tests for PointLight dataclass."""
+
+    def test_default_values(self):
+        """PointLight has correct defaults."""
+        pl = PointLight()
+        assert pl.color == "#FFFFFF"
+        assert pl.intensity == 1.0
+        assert pl.position == {"x": 0, "y": 0, "z": 0}
+
+    def test_from_dict_full(self):
+        """PointLight.from_dict loads all fields."""
+        data = {
+            "color": "#FF0000",
+            "intensity": 2.5,
+            "position": {"x": 1, "y": 2, "z": 3},
+        }
+        pl = PointLight.from_dict(data)
+        assert pl.color == "#FF0000"
+        assert pl.intensity == 2.5
+        assert pl.position == {"x": 1, "y": 2, "z": 3}
+
+    def test_from_dict_partial(self):
+        """PointLight.from_dict fills missing fields with defaults."""
+        data = {"color": "#00FF00"}
+        pl = PointLight.from_dict(data)
+        assert pl.color == "#00FF00"
+        assert pl.intensity == 1.0
+        assert pl.position == {"x": 0, "y": 0, "z": 0}
+
+
+class TestLightingConfig:
+    """Tests for LightingConfig dataclass."""
+
+    def test_default_values(self):
+        """LightingConfig has correct Workshop+Matrix blend defaults."""
+        cfg = LightingConfig()
+        assert cfg.ambient_color == "#FFAA55"  # Warm amber (Workshop)
+        assert cfg.ambient_intensity == 0.5
+        assert len(cfg.point_lights) == 3
+        # First light is warm amber center
+        assert cfg.point_lights[0].color == "#FFAA55"
+        # Second light is cool blue (Matrix)
+        assert cfg.point_lights[1].color == "#3B82F6"
+
+    def test_from_dict_full(self):
+        """LightingConfig.from_dict loads all fields."""
+        data = {
+            "ambient_color": "#123456",
+            "ambient_intensity": 0.8,
+            "point_lights": [
+                {"color": "#ABCDEF", "intensity": 1.5, "position": {"x": 1, "y": 1, "z": 1}}
+            ],
+        }
+        cfg = LightingConfig.from_dict(data)
+        assert cfg.ambient_color == "#123456"
+        assert cfg.ambient_intensity == 0.8
+        assert len(cfg.point_lights) == 1
+        assert cfg.point_lights[0].color == "#ABCDEF"
+
+    def test_from_dict_empty_list_uses_defaults(self):
+        """Empty point_lights list triggers default lights."""
+        data = {"ambient_color": "#000000", "point_lights": []}
+        cfg = LightingConfig.from_dict(data)
+        assert cfg.ambient_color == "#000000"
+        assert len(cfg.point_lights) == 3  # Default lights
+
+    def test_from_dict_none(self):
+        """LightingConfig.from_dict handles None."""
+        cfg = LightingConfig.from_dict(None)
+        assert cfg.ambient_color == "#FFAA55"
+        assert len(cfg.point_lights) == 3
+
+
+class TestEnvironmentConfig:
+    """Tests for EnvironmentConfig dataclass."""
+
+    def test_default_values(self):
+        """EnvironmentConfig has correct defaults."""
+        cfg = EnvironmentConfig()
+        assert cfg.rain_enabled is False
+        assert cfg.starfield_enabled is True  # Matrix starfield
+        assert cfg.fog_color == "#0f0f23"
+        assert cfg.fog_density == 0.02
+
+    def test_from_dict_full(self):
+        """EnvironmentConfig.from_dict loads all fields."""
+        data = {
+            "rain_enabled": True,
+            "starfield_enabled": False,
+            "fog_color": "#FFFFFF",
+            "fog_density": 0.1,
+        }
+        cfg = EnvironmentConfig.from_dict(data)
+        assert cfg.rain_enabled is True
+        assert cfg.starfield_enabled is False
+        assert cfg.fog_color == "#FFFFFF"
+        assert cfg.fog_density == 0.1
+
+    def test_from_dict_partial(self):
+        """EnvironmentConfig.from_dict fills missing fields."""
+        data = {"rain_enabled": True}
+        cfg = EnvironmentConfig.from_dict(data)
+        assert cfg.rain_enabled is True
+        assert cfg.starfield_enabled is True  # Default
+        assert cfg.fog_color == "#0f0f23"
+
+
+class TestFeaturesConfig:
+    """Tests for FeaturesConfig dataclass."""
+
+    def test_default_values_all_enabled(self):
+        """FeaturesConfig defaults to all features enabled."""
+        cfg = FeaturesConfig()
+        assert cfg.chat_enabled is True
+        assert cfg.visitor_avatars is True
+        assert cfg.pip_familiar is True
+        assert cfg.workshop_portal is True
+
+    def test_from_dict_full(self):
+        """FeaturesConfig.from_dict loads all fields."""
+        data = {
+            "chat_enabled": False,
+            "visitor_avatars": False,
+            "pip_familiar": False,
+            "workshop_portal": False,
+        }
+        cfg = FeaturesConfig.from_dict(data)
+        assert cfg.chat_enabled is False
+        assert cfg.visitor_avatars is False
+        assert cfg.pip_familiar is False
+        assert cfg.workshop_portal is False
+
+    def test_from_dict_partial(self):
+        """FeaturesConfig.from_dict fills missing fields."""
+        data = {"chat_enabled": False}
+        cfg = FeaturesConfig.from_dict(data)
+        assert cfg.chat_enabled is False
+        assert cfg.visitor_avatars is True  # Default
+        assert cfg.pip_familiar is True
+        assert cfg.workshop_portal is True
+
+
+class TestAgentConfig:
+    """Tests for AgentConfig dataclass."""
+
+    def test_default_values(self):
+        """AgentConfig has correct defaults."""
+        cfg = AgentConfig()
+        assert cfg.name == ""
+        assert cfg.role == ""
+        assert cfg.enabled is True
+
+    def test_from_dict_full(self):
+        """AgentConfig.from_dict loads all fields."""
+        data = {"name": "Timmy", "role": "guide", "enabled": False}
+        cfg = AgentConfig.from_dict(data)
+        assert cfg.name == "Timmy"
+        assert cfg.role == "guide"
+        assert cfg.enabled is False
+
+
+class TestAgentsConfig:
+    """Tests for AgentsConfig dataclass."""
+
+    def test_default_values(self):
+        """AgentsConfig has correct defaults."""
+        cfg = AgentsConfig()
+        assert cfg.default_count == 5
+        assert cfg.max_count == 20
+        assert cfg.agents == []
+
+    def test_from_dict_with_agents(self):
+        """AgentsConfig.from_dict loads agent list."""
+        data = {
+            "default_count": 10,
+            "max_count": 50,
+            "agents": [
+                {"name": "Timmy", "role": "guide", "enabled": True},
+                {"name": "Helper", "role": "assistant"},
+            ],
+        }
+        cfg = AgentsConfig.from_dict(data)
+        assert cfg.default_count == 10
+        assert cfg.max_count == 50
+        assert len(cfg.agents) == 2
+        assert cfg.agents[0].name == "Timmy"
+        assert cfg.agents[1].enabled is True  # Default
+
+
+class TestMatrixConfig:
+    """Tests for MatrixConfig dataclass."""
+
+    def test_default_values(self):
+        """MatrixConfig has correct composite defaults."""
+        cfg = MatrixConfig()
+        assert isinstance(cfg.lighting, LightingConfig)
+        assert isinstance(cfg.environment, EnvironmentConfig)
+        assert isinstance(cfg.features, FeaturesConfig)
+        assert isinstance(cfg.agents, AgentsConfig)
+        # Check the blend
+        assert cfg.lighting.ambient_color == "#FFAA55"
+        assert cfg.environment.starfield_enabled is True
+        assert cfg.features.chat_enabled is True
+
+    def test_from_dict_full(self):
+        """MatrixConfig.from_dict loads all sections."""
+        data = {
+            "lighting": {"ambient_color": "#000000"},
+            "environment": {"rain_enabled": True},
+            "features": {"chat_enabled": False},
+            "agents": {"default_count": 3},
+        }
+        cfg = MatrixConfig.from_dict(data)
+        assert cfg.lighting.ambient_color == "#000000"
+        assert cfg.environment.rain_enabled is True
+        assert cfg.features.chat_enabled is False
+        assert cfg.agents.default_count == 3
+
+    def test_from_dict_partial(self):
+        """MatrixConfig.from_dict fills missing sections with defaults."""
+        data = {"lighting": {"ambient_color": "#111111"}}
+        cfg = MatrixConfig.from_dict(data)
+        assert cfg.lighting.ambient_color == "#111111"
+        assert cfg.environment.starfield_enabled is True  # Default
+        assert cfg.features.pip_familiar is True  # Default
+
+    def test_from_dict_none(self):
+        """MatrixConfig.from_dict handles None."""
+        cfg = MatrixConfig.from_dict(None)
+        assert cfg.lighting.ambient_color == "#FFAA55"
+        assert cfg.features.chat_enabled is True
+
+    def test_to_dict_roundtrip(self):
+        """MatrixConfig.to_dict produces serializable output."""
+        cfg = MatrixConfig()
+        data = cfg.to_dict()
+        assert isinstance(data, dict)
+        assert "lighting" in data
+        assert "environment" in data
+        assert "features" in data
+        assert "agents" in data
+        # Verify point lights are included
+        assert len(data["lighting"]["point_lights"]) == 3
+
+
+class TestLoadFromYaml:
+    """Tests for load_from_yaml function."""
+
+    def test_loads_valid_yaml(self, tmp_path: Path):
+        """load_from_yaml reads a valid YAML file."""
+        config_path = tmp_path / "matrix.yaml"
+        data = {
+            "lighting": {"ambient_color": "#TEST11"},
+            "features": {"chat_enabled": False},
+        }
+        config_path.write_text(yaml.safe_dump(data))
+
+        cfg = load_from_yaml(config_path)
+        assert cfg.lighting.ambient_color == "#TEST11"
+        assert cfg.features.chat_enabled is False
+
+    def test_missing_file_returns_defaults(self, tmp_path: Path):
+        """load_from_yaml returns defaults when file doesn't exist."""
+        config_path = tmp_path / "nonexistent.yaml"
+        cfg = load_from_yaml(config_path)
+        assert cfg.lighting.ambient_color == "#FFAA55"
+        assert cfg.features.chat_enabled is True
+
+    def test_empty_file_returns_defaults(self, tmp_path: Path):
+        """load_from_yaml returns defaults for empty file."""
+        config_path = tmp_path / "empty.yaml"
+        config_path.write_text("")
+        cfg = load_from_yaml(config_path)
+        assert cfg.lighting.ambient_color == "#FFAA55"
+
+    def test_invalid_yaml_returns_defaults(self, tmp_path: Path):
+        """load_from_yaml returns defaults for invalid YAML."""
+        config_path = tmp_path / "invalid.yaml"
+        config_path.write_text("not: valid: yaml: [")
+        cfg = load_from_yaml(config_path)
+        assert cfg.lighting.ambient_color == "#FFAA55"
+        assert cfg.features.chat_enabled is True
+
+    def test_non_dict_yaml_returns_defaults(self, tmp_path: Path):
+        """load_from_yaml returns defaults when YAML is not a dict."""
+        config_path = tmp_path / "list.yaml"
+        config_path.write_text("- item1\n- item2")
+        cfg = load_from_yaml(config_path)
+        assert cfg.lighting.ambient_color == "#FFAA55"
+
+    def test_loads_actual_config_file(self):
+        """load_from_yaml can load the project's config/matrix.yaml."""
+        repo_root = Path(__file__).parent.parent.parent
+        config_path = repo_root / "config" / "matrix.yaml"
+        if not config_path.exists():
+            pytest.skip("config/matrix.yaml not found")
+
+        cfg = load_from_yaml(config_path)
+        # Verify it loaded with expected values
+        assert cfg.lighting.ambient_color == "#FFAA55"
+        assert len(cfg.lighting.point_lights) == 3
+        assert cfg.environment.starfield_enabled is True
+        assert cfg.features.workshop_portal is True
+
+    def test_str_path_accepted(self, tmp_path: Path):
+        """load_from_yaml accepts string path."""
+        config_path = tmp_path / "matrix.yaml"
+        config_path.write_text(yaml.safe_dump({"lighting": {"ambient_intensity": 0.9}}))
+
+        cfg = load_from_yaml(str(config_path))
+        assert cfg.lighting.ambient_intensity == 0.9

tests/unit/test_presence.py

@@ -0,0 +1,502 @@
+"""Tests for infrastructure.presence — presence state serializer."""
+
+from unittest.mock import patch
+
+import pytest
+
+from infrastructure.presence import (
+    DEFAULT_PIP_STATE,
+    _get_familiar_state,
+    produce_agent_state,
+    produce_bark,
+    produce_system_status,
+    produce_thought,
+    serialize_presence,
+)
+
+
+class TestSerializePresence:
+    """Round-trip and edge-case tests for serialize_presence()."""
+
+    @pytest.fixture()
+    def full_presence(self):
+        """A complete ADR-023 presence dict."""
+        return {
+            "version": 1,
+            "liveness": "2026-03-21T12:00:00Z",
+            "current_focus": "writing tests",
+            "mood": "focused",
+            "energy": 0.9,
+            "confidence": 0.85,
+            "active_threads": [
+                {"type": "thinking", "ref": "refactor presence", "status": "active"}
+            ],
+            "recent_events": ["committed code"],
+            "concerns": ["test coverage"],
+            "familiar": {"name": "Pip", "state": "alert"},
+        }
+
+    def test_full_round_trip(self, full_presence):
+        """All ADR-023 fields map to the expected camelCase keys."""
+        result = serialize_presence(full_presence)
+
+        assert result["timmyState"]["mood"] == "focused"
+        assert result["timmyState"]["activity"] == "writing tests"
+        assert result["timmyState"]["energy"] == 0.9
+        assert result["timmyState"]["confidence"] == 0.85
+        assert result["familiar"] == {"name": "Pip", "state": "alert"}
+        assert result["activeThreads"] == full_presence["active_threads"]
+        assert result["recentEvents"] == ["committed code"]
+        assert result["concerns"] == ["test coverage"]
+        assert result["visitorPresent"] is False
+        assert result["updatedAt"] == "2026-03-21T12:00:00Z"
+        assert result["version"] == 1
+
+    def test_defaults_on_empty_dict(self):
+        """Missing fields fall back to safe defaults."""
+        result = serialize_presence({})
+
+        assert result["timmyState"]["mood"] == "calm"
+        assert result["timmyState"]["activity"] == "idle"
+        assert result["timmyState"]["energy"] == 0.5
+        assert result["timmyState"]["confidence"] == 0.7
+        assert result["familiar"] is None
+        assert result["activeThreads"] == []
+        assert result["recentEvents"] == []
+        assert result["concerns"] == []
+        assert result["visitorPresent"] is False
+        assert result["version"] == 1
+        # updatedAt should be an ISO timestamp string
+        assert "T" in result["updatedAt"]
+
+    def test_partial_presence(self):
+        """Only some fields provided — others get defaults."""
+        result = serialize_presence({"mood": "excited", "energy": 0.3})
+
+        assert result["timmyState"]["mood"] == "excited"
+        assert result["timmyState"]["energy"] == 0.3
+        assert result["timmyState"]["confidence"] == 0.7  # default
+        assert result["activeThreads"] == []  # default
+
+    def test_return_type_is_dict(self, full_presence):
+        """serialize_presence always returns a plain dict."""
+        result = serialize_presence(full_presence)
+        assert isinstance(result, dict)
+        assert isinstance(result["timmyState"], dict)
+
+    def test_visitor_present_always_false(self, full_presence):
+        """visitorPresent is always False — set by the WS layer, not here."""
+        assert serialize_presence(full_presence)["visitorPresent"] is False
+        assert serialize_presence({})["visitorPresent"] is False
+
+
+class TestProduceAgentState:
+    """Tests for produce_agent_state() — Matrix agent_state message producer."""
+
+    @pytest.fixture()
+    def full_presence(self):
+        """A presence dict with all agent_state-relevant fields."""
+        return {
+            "display_name": "Timmy",
+            "role": "companion",
+            "current_focus": "thinking about tests",
+            "mood": "focused",
+            "energy": 0.9,
+            "bark": "Running test suite...",
+        }
+
+    @patch("infrastructure.presence.time")
+    def test_full_message_structure(self, mock_time, full_presence):
+        """Returns dict with type, agent_id, data, and ts keys."""
+        mock_time.time.return_value = 1742529600
+        result = produce_agent_state("timmy", full_presence)
+
+        assert result["type"] == "agent_state"
+        assert result["agent_id"] == "timmy"
+        assert result["ts"] == 1742529600
+        assert isinstance(result["data"], dict)
+
+    def test_data_fields(self, full_presence):
+        """data dict contains all required presence fields."""
+        data = produce_agent_state("timmy", full_presence)["data"]
+
+        assert data["display_name"] == "Timmy"
+        assert data["role"] == "companion"
+        assert data["status"] == "thinking"
+        assert data["mood"] == "focused"
+        assert data["energy"] == 0.9
+        assert data["bark"] == "Running test suite..."
+
+    def test_defaults_on_empty_presence(self):
+        """Missing fields get sensible defaults."""
+        result = produce_agent_state("timmy", {})
+        data = result["data"]
+
+        assert data["display_name"] == "Timmy"  # agent_id.title()
+        assert data["role"] == "assistant"
+        assert data["status"] == "idle"
+        assert data["mood"] == "calm"
+        assert data["energy"] == 0.5
+        assert data["bark"] == ""
+
+    def test_ts_is_unix_timestamp(self):
+        """ts should be an integer Unix timestamp."""
+        result = produce_agent_state("timmy", {})
+        assert isinstance(result["ts"], int)
+        assert result["ts"] > 0
+
+    @pytest.mark.parametrize(
+        ("focus", "expected_status"),
+        [
+            ("thinking about code", "thinking"),
+            ("speaking to user", "speaking"),
+            ("talking with agent", "speaking"),
+            ("idle", "idle"),
+            ("", "idle"),
+            ("writing tests", "online"),
+            ("reviewing PR", "online"),
+        ],
+    )
+    def test_status_derivation(self, focus, expected_status):
+        """current_focus maps to the correct Matrix status."""
+        data = produce_agent_state("t", {"current_focus": focus})["data"]
+        assert data["status"] == expected_status
+
+    def test_agent_id_passed_through(self):
+        """agent_id appears in the top-level message."""
+        result = produce_agent_state("spark", {})
+        assert result["agent_id"] == "spark"
+
+    def test_display_name_from_agent_id(self):
+        """When display_name is missing, it's derived from agent_id.title()."""
+        data = produce_agent_state("spark", {})["data"]
+        assert data["display_name"] == "Spark"
+
+    def test_familiar_in_data(self):
+        """agent_state.data includes familiar field with required keys."""
+        data = produce_agent_state("timmy", {})["data"]
+
+        assert "familiar" in data
+        familiar = data["familiar"]
+        assert familiar["name"] == "Pip"
+        assert "mood" in familiar
+        assert "energy" in familiar
+        assert familiar["color"] == "0x00b450"
+        assert familiar["trail_color"] == "0xdaa520"
+
+    def test_familiar_has_all_required_fields(self):
+        """familiar dict contains all required fields per acceptance criteria."""
+        data = produce_agent_state("timmy", {})["data"]
+        familiar = data["familiar"]
+
+        required_fields = {"name", "mood", "energy", "color", "trail_color"}
+        assert set(familiar.keys()) >= required_fields
+
+
+class TestFamiliarState:
+    """Tests for _get_familiar_state() — Pip familiar state retrieval."""
+
+    def test_get_familiar_state_returns_dict(self):
+        """_get_familiar_state returns a dict."""
+        result = _get_familiar_state()
+        assert isinstance(result, dict)
+
+    def test_get_familiar_state_has_required_fields(self):
+        """Result contains name, mood, energy, color, trail_color."""
+        result = _get_familiar_state()
+
+        assert result["name"] == "Pip"
+        assert "mood" in result
+        assert isinstance(result["energy"], (int, float))
+        assert result["color"] == "0x00b450"
+        assert result["trail_color"] == "0xdaa520"
+
+    def test_default_pip_state_constant(self):
+        """DEFAULT_PIP_STATE has expected values."""
+        assert DEFAULT_PIP_STATE["name"] == "Pip"
+        assert DEFAULT_PIP_STATE["mood"] == "sleepy"
+        assert DEFAULT_PIP_STATE["energy"] == 0.5
+        assert DEFAULT_PIP_STATE["color"] == "0x00b450"
+        assert DEFAULT_PIP_STATE["trail_color"] == "0xdaa520"
+
+    @patch("infrastructure.presence.logger")
+    def test_get_familiar_state_fallback_on_exception(self, mock_logger):
+        """When familiar module raises, falls back to default and logs warning."""
+        # Patch inside the function where pip_familiar is imported
+        with patch("timmy.familiar.pip_familiar.snapshot") as mock_snapshot:
+            mock_snapshot.side_effect = RuntimeError("Pip is napping")
+            result = _get_familiar_state()
+
+        assert result["name"] == "Pip"
+        assert result["mood"] == "sleepy"
+        mock_logger.warning.assert_called_once()
+        assert "Pip is napping" in str(mock_logger.warning.call_args)
+
+
+class TestProduceBark:
+    """Tests for produce_bark() — Matrix bark message producer."""
+
+    @patch("infrastructure.presence.time")
+    def test_full_message_structure(self, mock_time):
+        """Returns dict with type, agent_id, data, and ts keys."""
+        mock_time.time.return_value = 1742529600
+        result = produce_bark("timmy", "Hello world!")
+
+        assert result["type"] == "bark"
+        assert result["agent_id"] == "timmy"
+        assert result["ts"] == 1742529600
+        assert isinstance(result["data"], dict)
+
+    def test_data_fields(self):
+        """data dict contains text, reply_to, and style."""
+        result = produce_bark("timmy", "Hello world!", reply_to="msg-123", style="shout")
+        data = result["data"]
+
+        assert data["text"] == "Hello world!"
+        assert data["reply_to"] == "msg-123"
+        assert data["style"] == "shout"
+
+    def test_default_style_is_speech(self):
+        """When style is not provided, defaults to 'speech'."""
+        result = produce_bark("timmy", "Hello!")
+        assert result["data"]["style"] == "speech"
+
+    def test_default_reply_to_is_none(self):
+        """When reply_to is not provided, defaults to None."""
+        result = produce_bark("timmy", "Hello!")
+        assert result["data"]["reply_to"] is None
+
+    def test_text_truncated_to_280_chars(self):
+        """Text longer than 280 chars is truncated."""
+        long_text = "A" * 500
+        result = produce_bark("timmy", long_text)
+        assert len(result["data"]["text"]) == 280
+        assert result["data"]["text"] == "A" * 280
+
+    def test_text_exactly_280_chars_not_truncated(self):
+        """Text exactly 280 chars is not truncated."""
+        text = "B" * 280
+        result = produce_bark("timmy", text)
+        assert result["data"]["text"] == text
+
+    def test_text_shorter_than_280_not_padded(self):
+        """Text shorter than 280 chars is not padded."""
+        result = produce_bark("timmy", "Short")
+        assert result["data"]["text"] == "Short"
+
+    @pytest.mark.parametrize(
+        ("style", "expected_style"),
+        [
+            ("speech", "speech"),
+            ("thought", "thought"),
+            ("whisper", "whisper"),
+            ("shout", "shout"),
+        ],
+    )
+    def test_valid_styles_preserved(self, style, expected_style):
+        """Valid style values are preserved."""
+        result = produce_bark("timmy", "Hello!", style=style)
+        assert result["data"]["style"] == expected_style
+
+    @pytest.mark.parametrize(
+        "invalid_style",
+        ["yell", "scream", "", "SPEECH", "Speech", None, 123],
+    )
+    def test_invalid_style_defaults_to_speech(self, invalid_style):
+        """Invalid style values fall back to 'speech'."""
+        result = produce_bark("timmy", "Hello!", style=invalid_style)
+        assert result["data"]["style"] == "speech"
+
+    def test_empty_text_handled(self):
+        """Empty text is handled gracefully."""
+        result = produce_bark("timmy", "")
+        assert result["data"]["text"] == ""
+
+    def test_ts_is_unix_timestamp(self):
+        """ts should be an integer Unix timestamp."""
+        result = produce_bark("timmy", "Hello!")
+        assert isinstance(result["ts"], int)
+        assert result["ts"] > 0
+
+    def test_agent_id_passed_through(self):
+        """agent_id appears in the top-level message."""
+        result = produce_bark("spark", "Hello!")
+        assert result["agent_id"] == "spark"
+
+    def test_with_all_parameters(self):
+        """Full parameter set produces expected output."""
+        result = produce_bark(
+            agent_id="timmy",
+            text="Running test suite...",
+            reply_to="parent-msg-456",
+            style="thought",
+        )
+
+        assert result["type"] == "bark"
+        assert result["agent_id"] == "timmy"
+        assert result["data"]["text"] == "Running test suite..."
+        assert result["data"]["reply_to"] == "parent-msg-456"
+        assert result["data"]["style"] == "thought"
+
+
+class TestProduceThought:
+    """Tests for produce_thought() — Matrix thought message producer."""
+
+    @patch("infrastructure.presence.time")
+    def test_full_message_structure(self, mock_time):
+        """Returns dict with type, agent_id, data, and ts keys."""
+        mock_time.time.return_value = 1742529600
+        result = produce_thought("timmy", "Considering the options...", 42)
+
+        assert result["type"] == "thought"
+        assert result["agent_id"] == "timmy"
+        assert result["ts"] == 1742529600
+        assert isinstance(result["data"], dict)
+
+    def test_data_fields(self):
+        """data dict contains text, thought_id, and chain_id."""
+        result = produce_thought("timmy", "Considering...", 42, chain_id="chain-123")
+        data = result["data"]
+
+        assert data["text"] == "Considering..."
+        assert data["thought_id"] == 42
+        assert data["chain_id"] == "chain-123"
+
+    def test_default_chain_id_is_none(self):
+        """When chain_id is not provided, defaults to None."""
+        result = produce_thought("timmy", "Thinking...", 1)
+        assert result["data"]["chain_id"] is None
+
+    def test_text_truncated_to_500_chars(self):
+        """Text longer than 500 chars is truncated."""
+        long_text = "A" * 600
+        result = produce_thought("timmy", long_text, 1)
+        assert len(result["data"]["text"]) == 500
+        assert result["data"]["text"] == "A" * 500
+
+    def test_text_exactly_500_chars_not_truncated(self):
+        """Text exactly 500 chars is not truncated."""
+        text = "B" * 500
+        result = produce_thought("timmy", text, 1)
+        assert result["data"]["text"] == text
+
+    def test_text_shorter_than_500_not_padded(self):
+        """Text shorter than 500 chars is not padded."""
+        result = produce_thought("timmy", "Short thought", 1)
+        assert result["data"]["text"] == "Short thought"
+
+    def test_empty_text_handled(self):
+        """Empty text is handled gracefully."""
+        result = produce_thought("timmy", "", 1)
+        assert result["data"]["text"] == ""
+
+    def test_ts_is_unix_timestamp(self):
+        """ts should be an integer Unix timestamp."""
+        result = produce_thought("timmy", "Hello!", 1)
+        assert isinstance(result["ts"], int)
+        assert result["ts"] > 0
+
+    def test_agent_id_passed_through(self):
+        """agent_id appears in the top-level message."""
+        result = produce_thought("spark", "Hello!", 1)
+        assert result["agent_id"] == "spark"
+
+    def test_thought_id_passed_through(self):
+        """thought_id appears in the data."""
+        result = produce_thought("timmy", "Hello!", 999)
+        assert result["data"]["thought_id"] == 999
+
+    def test_with_all_parameters(self):
+        """Full parameter set produces expected output."""
+        result = produce_thought(
+            agent_id="timmy",
+            thought_text="Analyzing the situation...",
+            thought_id=42,
+            chain_id="chain-abc",
+        )
+
+        assert result["type"] == "thought"
+        assert result["agent_id"] == "timmy"
+        assert result["data"]["text"] == "Analyzing the situation..."
+        assert result["data"]["thought_id"] == 42
+        assert result["data"]["chain_id"] == "chain-abc"
+
+
+class TestProduceSystemStatus:
+    """Tests for produce_system_status() — Matrix system_status message producer."""
+
+    @patch("infrastructure.presence.time")
+    def test_full_message_structure(self, mock_time):
+        """Returns dict with type, data, and ts keys."""
+        mock_time.time.return_value = 1742529600
+        result = produce_system_status()
+
+        assert result["type"] == "system_status"
+        assert result["ts"] == 1742529600
+        assert isinstance(result["data"], dict)
+
+    def test_data_has_required_fields(self):
+        """data dict contains all required system status fields."""
+        result = produce_system_status()
+        data = result["data"]
+
+        assert "agents_online" in data
+        assert "visitors" in data
+        assert "uptime_seconds" in data
+        assert "thinking_active" in data
+        assert "memory_count" in data
+
+    def test_data_field_types(self):
+        """All data fields have correct types."""
+        result = produce_system_status()
+        data = result["data"]
+
+        assert isinstance(data["agents_online"], int)
+        assert isinstance(data["visitors"], int)
+        assert isinstance(data["uptime_seconds"], int)
+        assert isinstance(data["thinking_active"], bool)
+        assert isinstance(data["memory_count"], int)
+
+    def test_agents_online_is_non_negative(self):
+        """agents_online is never negative."""
+        result = produce_system_status()
+        assert result["data"]["agents_online"] >= 0
+
+    def test_visitors_is_non_negative(self):
+        """visitors is never negative."""
+        result = produce_system_status()
+        assert result["data"]["visitors"] >= 0
+
+    def test_uptime_seconds_is_non_negative(self):
+        """uptime_seconds is never negative."""
+        result = produce_system_status()
+        assert result["data"]["uptime_seconds"] >= 0
+
+    def test_memory_count_is_non_negative(self):
+        """memory_count is never negative."""
+        result = produce_system_status()
+        assert result["data"]["memory_count"] >= 0
+
+    @patch("infrastructure.presence.time")
+    def test_ts_is_unix_timestamp(self, mock_time):
+        """ts should be an integer Unix timestamp."""
+        mock_time.time.return_value = 1742529600
+        result = produce_system_status()
+        assert isinstance(result["ts"], int)
+        assert result["ts"] == 1742529600
+
+    @patch("infrastructure.presence.logger")
+    def test_graceful_degradation_on_import_errors(self, mock_logger):
+        """Function returns valid dict even when imports fail."""
+        # This test verifies the function handles failures gracefully
+        # by checking it always returns the expected structure
+        result = produce_system_status()
+
+        assert result["type"] == "system_status"
+        assert isinstance(result["data"], dict)
+        assert isinstance(result["ts"], int)
+
+    def test_returns_dict(self):
+        """produce_system_status always returns a plain dict."""
+        result = produce_system_status()
+        assert isinstance(result, dict)

tests/unit/test_protocol.py

@@ -0,0 +1,173 @@
+"""Tests for infrastructure.protocol — WebSocket message types."""
+
+import json
+
+import pytest
+
+from infrastructure.protocol import (
+    AgentStateMessage,
+    BarkMessage,
+    ConnectionAckMessage,
+    ErrorMessage,
+    MemoryFlashMessage,
+    MessageType,
+    SystemStatusMessage,
+    TaskUpdateMessage,
+    ThoughtMessage,
+    VisitorStateMessage,
+    WSMessage,
+)
+
+# ---------------------------------------------------------------------------
+# MessageType enum
+# ---------------------------------------------------------------------------
+
+
+class TestMessageType:
+    """MessageType enum covers all 9 Matrix PROTOCOL.md types."""
+
+    def test_has_all_nine_types(self):
+        assert len(MessageType) == 9
+
+    @pytest.mark.parametrize(
+        "member,value",
+        [
+            (MessageType.AGENT_STATE, "agent_state"),
+            (MessageType.VISITOR_STATE, "visitor_state"),
+            (MessageType.BARK, "bark"),
+            (MessageType.THOUGHT, "thought"),
+            (MessageType.SYSTEM_STATUS, "system_status"),
+            (MessageType.CONNECTION_ACK, "connection_ack"),
+            (MessageType.ERROR, "error"),
+            (MessageType.TASK_UPDATE, "task_update"),
+            (MessageType.MEMORY_FLASH, "memory_flash"),
+        ],
+    )
+    def test_enum_values(self, member, value):
+        assert member.value == value
+
+    def test_str_comparison(self):
+        """MessageType is a str enum so it can be compared to plain strings."""
+        assert MessageType.BARK == "bark"
+
+
+# ---------------------------------------------------------------------------
+# to_json / from_json round-trip
+# ---------------------------------------------------------------------------
+
+
+class TestAgentStateMessage:
+    def test_defaults(self):
+        msg = AgentStateMessage()
+        assert msg.type == "agent_state"
+        assert msg.agent_id == ""
+        assert msg.data == {}
+
+    def test_round_trip(self):
+        msg = AgentStateMessage(agent_id="timmy", data={"mood": "happy"}, ts=1000.0)
+        raw = msg.to_json()
+        restored = AgentStateMessage.from_json(raw)
+        assert restored.agent_id == "timmy"
+        assert restored.data == {"mood": "happy"}
+        assert restored.ts == 1000.0
+
+    def test_to_json_structure(self):
+        msg = AgentStateMessage(agent_id="timmy", data={"x": 1}, ts=123.0)
+        parsed = json.loads(msg.to_json())
+        assert parsed["type"] == "agent_state"
+        assert parsed["agent_id"] == "timmy"
+        assert parsed["data"] == {"x": 1}
+        assert parsed["ts"] == 123.0
+
+
+class TestVisitorStateMessage:
+    def test_round_trip(self):
+        msg = VisitorStateMessage(visitor_id="v1", data={"page": "/"}, ts=1.0)
+        restored = VisitorStateMessage.from_json(msg.to_json())
+        assert restored.visitor_id == "v1"
+        assert restored.data == {"page": "/"}
+
+
+class TestBarkMessage:
+    def test_round_trip(self):
+        msg = BarkMessage(agent_id="timmy", content="woof!", ts=1.0)
+        restored = BarkMessage.from_json(msg.to_json())
+        assert restored.agent_id == "timmy"
+        assert restored.content == "woof!"
+
+
+class TestThoughtMessage:
+    def test_round_trip(self):
+        msg = ThoughtMessage(agent_id="timmy", content="hmm...", ts=1.0)
+        restored = ThoughtMessage.from_json(msg.to_json())
+        assert restored.content == "hmm..."
+
+
+class TestSystemStatusMessage:
+    def test_round_trip(self):
+        msg = SystemStatusMessage(status="healthy", data={"uptime": 3600}, ts=1.0)
+        restored = SystemStatusMessage.from_json(msg.to_json())
+        assert restored.status == "healthy"
+        assert restored.data == {"uptime": 3600}
+
+
+class TestConnectionAckMessage:
+    def test_round_trip(self):
+        msg = ConnectionAckMessage(client_id="abc-123", ts=1.0)
+        restored = ConnectionAckMessage.from_json(msg.to_json())
+        assert restored.client_id == "abc-123"
+
+
+class TestErrorMessage:
+    def test_round_trip(self):
+        msg = ErrorMessage(code="INVALID", message="bad request", ts=1.0)
+        restored = ErrorMessage.from_json(msg.to_json())
+        assert restored.code == "INVALID"
+        assert restored.message == "bad request"
+
+
+class TestTaskUpdateMessage:
+    def test_round_trip(self):
+        msg = TaskUpdateMessage(task_id="t1", status="completed", data={"result": "ok"}, ts=1.0)
+        restored = TaskUpdateMessage.from_json(msg.to_json())
+        assert restored.task_id == "t1"
+        assert restored.status == "completed"
+        assert restored.data == {"result": "ok"}
+
+
+class TestMemoryFlashMessage:
+    def test_round_trip(self):
+        msg = MemoryFlashMessage(agent_id="timmy", memory_key="fav_food", content="kibble", ts=1.0)
+        restored = MemoryFlashMessage.from_json(msg.to_json())
+        assert restored.memory_key == "fav_food"
+        assert restored.content == "kibble"
+
+
+# ---------------------------------------------------------------------------
+# WSMessage.from_json dispatch
+# ---------------------------------------------------------------------------
+
+
+class TestWSMessageDispatch:
+    """WSMessage.from_json dispatches to the correct subclass."""
+
+    def test_dispatch_to_bark(self):
+        raw = json.dumps({"type": "bark", "agent_id": "t", "content": "woof", "ts": 1.0})
+        msg = WSMessage.from_json(raw)
+        assert isinstance(msg, BarkMessage)
+        assert msg.content == "woof"
+
+    def test_dispatch_to_error(self):
+        raw = json.dumps({"type": "error", "code": "E1", "message": "oops", "ts": 1.0})
+        msg = WSMessage.from_json(raw)
+        assert isinstance(msg, ErrorMessage)
+
+    def test_unknown_type_returns_base(self):
+        raw = json.dumps({"type": "unknown_future_type", "ts": 1.0})
+        msg = WSMessage.from_json(raw)
+        assert type(msg) is WSMessage
+        assert msg.type == "unknown_future_type"
+
+    def test_invalid_json_raises(self):
+        with pytest.raises(json.JSONDecodeError):
+            WSMessage.from_json("not json")

tests/unit/test_quest_system.py

@@ -0,0 +1,489 @@
+"""Unit tests for the quest system.
+
+Tests quest definitions, progress tracking, completion detection,
+and token rewards.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from timmy.quest_system import (
+    QuestDefinition,
+    QuestProgress,
+    QuestStatus,
+    QuestType,
+    _is_on_cooldown,
+    claim_quest_reward,
+    evaluate_quest_progress,
+    get_or_create_progress,
+    get_quest_definition,
+    get_quest_leaderboard,
+    load_quest_config,
+    reset_quest_progress,
+    update_quest_progress,
+)
+
+
+@pytest.fixture(autouse=True)
+def clean_quest_state():
+    """Reset quest progress between tests."""
+    reset_quest_progress()
+    yield
+    reset_quest_progress()
+
+
+@pytest.fixture
+def sample_issue_count_quest():
+    """Create a sample issue_count quest definition."""
+    return QuestDefinition(
+        id="test_close_issues",
+        name="Test Issue Closer",
+        description="Close 3 test issues",
+        reward_tokens=100,
+        quest_type=QuestType.ISSUE_COUNT,
+        enabled=True,
+        repeatable=False,
+        cooldown_hours=0,
+        criteria={"target_count": 3, "issue_labels": ["test"]},
+        notification_message="Test quest complete! Earned {tokens} tokens.",
+    )
+
+
+@pytest.fixture
+def sample_daily_run_quest():
+    """Create a sample daily_run quest definition."""
+    return QuestDefinition(
+        id="test_daily_run",
+        name="Test Daily Runner",
+        description="Complete 5 sessions",
+        reward_tokens=250,
+        quest_type=QuestType.DAILY_RUN,
+        enabled=True,
+        repeatable=True,
+        cooldown_hours=24,
+        criteria={"min_sessions": 5},
+        notification_message="Daily run quest complete! Earned {tokens} tokens.",
+    )
+
+
+# ── Quest Definition Tests ───────────────────────────────────────────────
+
+
+class TestQuestDefinition:
+    def test_from_dict_minimal(self):
+        data = {"id": "test_quest", "name": "Test Quest"}
+        quest = QuestDefinition.from_dict(data)
+        assert quest.id == "test_quest"
+        assert quest.name == "Test Quest"
+        assert quest.quest_type == QuestType.CUSTOM
+        assert quest.enabled is True
+
+    def test_from_dict_full(self):
+        data = {
+            "id": "full_quest",
+            "name": "Full Quest",
+            "description": "A test quest",
+            "reward_tokens": 500,
+            "type": "issue_count",
+            "enabled": False,
+            "repeatable": True,
+            "cooldown_hours": 12,
+            "criteria": {"target_count": 5},
+            "notification_message": "Done!",
+        }
+        quest = QuestDefinition.from_dict(data)
+        assert quest.id == "full_quest"
+        assert quest.reward_tokens == 500
+        assert quest.quest_type == QuestType.ISSUE_COUNT
+        assert quest.enabled is False
+        assert quest.repeatable is True
+        assert quest.cooldown_hours == 12
+
+
+# ── Quest Progress Tests ─────────────────────────────────────────────────
+
+
+class TestQuestProgress:
+    def test_progress_creation(self):
+        progress = QuestProgress(
+            quest_id="test_quest",
+            agent_id="test_agent",
+            status=QuestStatus.NOT_STARTED,
+        )
+        assert progress.quest_id == "test_quest"
+        assert progress.agent_id == "test_agent"
+        assert progress.current_value == 0
+
+    def test_progress_to_dict(self):
+        progress = QuestProgress(
+            quest_id="test_quest",
+            agent_id="test_agent",
+            status=QuestStatus.IN_PROGRESS,
+            current_value=2,
+            target_value=5,
+        )
+        data = progress.to_dict()
+        assert data["quest_id"] == "test_quest"
+        assert data["status"] == "in_progress"
+        assert data["current_value"] == 2
+
+
+# ── Quest Loading Tests ──────────────────────────────────────────────────
+
+
+class TestQuestLoading:
+    def test_load_quest_config(self):
+        definitions, settings = load_quest_config()
+        assert isinstance(definitions, dict)
+        assert isinstance(settings, dict)
+
+    def test_get_quest_definition_exists(self):
+        # Should return None for non-existent quest in fresh state
+        quest = get_quest_definition("nonexistent")
+        # The function returns from loaded config, which may have quests
+        # or be empty if config doesn't exist
+        assert quest is None or isinstance(quest, QuestDefinition)
+
+    def test_get_quest_definition_not_found(self):
+        quest = get_quest_definition("definitely_not_a_real_quest_12345")
+        assert quest is None
+
+
+# ── Quest Progress Management Tests ─────────────────────────────────────
+
+
+class TestQuestProgressManagement:
+    def test_get_or_create_progress_new(self):
+        # First create a quest definition
+        quest = QuestDefinition(
+            id="progress_test",
+            name="Progress Test",
+            description="Test quest",
+            reward_tokens=100,
+            quest_type=QuestType.ISSUE_COUNT,
+            enabled=True,
+            repeatable=False,
+            cooldown_hours=0,
+            criteria={"target_count": 3},
+            notification_message="Done!",
+        )
+
+        # Need to inject into the definitions dict
+        from timmy.quest_system import _quest_definitions
+
+        _quest_definitions["progress_test"] = quest
+
+        progress = get_or_create_progress("progress_test", "agent1")
+        assert progress.quest_id == "progress_test"
+        assert progress.agent_id == "agent1"
+        assert progress.status == QuestStatus.NOT_STARTED
+        assert progress.target_value == 3
+
+        del _quest_definitions["progress_test"]
+
+    def test_update_quest_progress(self):
+        quest = QuestDefinition(
+            id="update_test",
+            name="Update Test",
+            description="Test quest",
+            reward_tokens=100,
+            quest_type=QuestType.ISSUE_COUNT,
+            enabled=True,
+            repeatable=False,
+            cooldown_hours=0,
+            criteria={"target_count": 3},
+            notification_message="Done!",
+        )
+
+        from timmy.quest_system import _quest_definitions
+
+        _quest_definitions["update_test"] = quest
+
+        # Create initial progress
+        progress = get_or_create_progress("update_test", "agent1")
+        assert progress.current_value == 0
+
+        # Update progress
+        updated = update_quest_progress("update_test", "agent1", 2)
+        assert updated.current_value == 2
+        assert updated.status == QuestStatus.NOT_STARTED
+
+        # Complete the quest
+        completed = update_quest_progress("update_test", "agent1", 3)
+        assert completed.current_value == 3
+        assert completed.status == QuestStatus.COMPLETED
+        assert completed.completed_at != ""
+
+        del _quest_definitions["update_test"]
+
+
+# ── Quest Evaluation Tests ───────────────────────────────────────────────
+
+
+class TestQuestEvaluation:
+    def test_evaluate_issue_count_quest(self):
+        quest = QuestDefinition(
+            id="eval_test",
+            name="Eval Test",
+            description="Test quest",
+            reward_tokens=100,
+            quest_type=QuestType.ISSUE_COUNT,
+            enabled=True,
+            repeatable=False,
+            cooldown_hours=0,
+            criteria={"target_count": 2, "issue_labels": ["test"]},
+            notification_message="Done!",
+        )
+
+        from timmy.quest_system import _quest_definitions
+
+        _quest_definitions["eval_test"] = quest
+
+        # Simulate closed issues
+        closed_issues = [
+            {"id": 1, "labels": [{"name": "test"}]},
+            {"id": 2, "labels": [{"name": "test"}, {"name": "bug"}]},
+            {"id": 3, "labels": [{"name": "other"}]},
+        ]
+
+        context = {"closed_issues": closed_issues}
+        progress = evaluate_quest_progress("eval_test", "agent1", context)
+
+        assert progress is not None
+        assert progress.current_value == 2  # Two issues with 'test' label
+
+        del _quest_definitions["eval_test"]
+
+    def test_evaluate_issue_reduce_quest(self):
+        quest = QuestDefinition(
+            id="reduce_test",
+            name="Reduce Test",
+            description="Test quest",
+            reward_tokens=200,
+            quest_type=QuestType.ISSUE_REDUCE,
+            enabled=True,
+            repeatable=False,
+            cooldown_hours=0,
+            criteria={"target_reduction": 2},
+            notification_message="Done!",
+        )
+
+        from timmy.quest_system import _quest_definitions
+
+        _quest_definitions["reduce_test"] = quest
+
+        context = {"previous_issue_count": 10, "current_issue_count": 7}
+        progress = evaluate_quest_progress("reduce_test", "agent1", context)
+
+        assert progress is not None
+        assert progress.current_value == 3  # Reduced by 3
+
+        del _quest_definitions["reduce_test"]
+
+    def test_evaluate_daily_run_quest(self):
+        quest = QuestDefinition(
+            id="daily_test",
+            name="Daily Test",
+            description="Test quest",
+            reward_tokens=250,
+            quest_type=QuestType.DAILY_RUN,
+            enabled=True,
+            repeatable=True,
+            cooldown_hours=24,
+            criteria={"min_sessions": 5},
+            notification_message="Done!",
+        )
+
+        from timmy.quest_system import _quest_definitions
+
+        _quest_definitions["daily_test"] = quest
+
+        context = {"sessions_completed": 5}
+        progress = evaluate_quest_progress("daily_test", "agent1", context)
+
+        assert progress is not None
+        assert progress.current_value == 5
+        assert progress.status == QuestStatus.COMPLETED
+
+        del _quest_definitions["daily_test"]
+
+
+# ── Quest Cooldown Tests ─────────────────────────────────────────────────
+
+
+class TestQuestCooldown:
+    def test_is_on_cooldown_no_cooldown(self):
+        quest = QuestDefinition(
+            id="cooldown_test",
+            name="Cooldown Test",
+            description="Test quest",
+            reward_tokens=100,
+            quest_type=QuestType.ISSUE_COUNT,
+            enabled=True,
+            repeatable=True,
+            cooldown_hours=24,
+            criteria={},
+            notification_message="Done!",
+        )
+
+        progress = QuestProgress(
+            quest_id="cooldown_test",
+            agent_id="agent1",
+            status=QuestStatus.CLAIMED,
+        )
+
+        # No last_completed_at means no cooldown
+        assert _is_on_cooldown(progress, quest) is False
+
+
+# ── Quest Reward Tests ───────────────────────────────────────────────────
+
+
+class TestQuestReward:
+    def test_claim_quest_reward_not_completed(self):
+        quest = QuestDefinition(
+            id="reward_test",
+            name="Reward Test",
+            description="Test quest",
+            reward_tokens=100,
+            quest_type=QuestType.ISSUE_COUNT,
+            enabled=True,
+            repeatable=False,
+            cooldown_hours=0,
+            criteria={"target_count": 3},
+            notification_message="Done!",
+        )
+
+        from timmy.quest_system import _quest_definitions, _quest_progress
+
+        _quest_definitions["reward_test"] = quest
+
+        # Create progress but don't complete
+        progress = get_or_create_progress("reward_test", "agent1")
+        _quest_progress["agent1:reward_test"] = progress
+
+        # Try to claim - should fail
+        reward = claim_quest_reward("reward_test", "agent1")
+        assert reward is None
+
+        del _quest_definitions["reward_test"]
+
+
+# ── Leaderboard Tests ────────────────────────────────────────────────────
+
+
+class TestQuestLeaderboard:
+    def test_get_quest_leaderboard_empty(self):
+        reset_quest_progress()
+        leaderboard = get_quest_leaderboard()
+        assert leaderboard == []
+
+    def test_get_quest_leaderboard_with_data(self):
+        # Create and complete a quest for two agents
+        quest = QuestDefinition(
+            id="leaderboard_test",
+            name="Leaderboard Test",
+            description="Test quest",
+            reward_tokens=100,
+            quest_type=QuestType.ISSUE_COUNT,
+            enabled=True,
+            repeatable=True,
+            cooldown_hours=0,
+            criteria={"target_count": 1},
+            notification_message="Done!",
+        )
+
+        from timmy.quest_system import _quest_definitions, _quest_progress
+
+        _quest_definitions["leaderboard_test"] = quest
+
+        # Create progress for agent1 with 2 completions
+        progress1 = QuestProgress(
+            quest_id="leaderboard_test",
+            agent_id="agent1",
+            status=QuestStatus.NOT_STARTED,
+            completion_count=2,
+        )
+        _quest_progress["agent1:leaderboard_test"] = progress1
+
+        # Create progress for agent2 with 1 completion
+        progress2 = QuestProgress(
+            quest_id="leaderboard_test",
+            agent_id="agent2",
+            status=QuestStatus.NOT_STARTED,
+            completion_count=1,
+        )
+        _quest_progress["agent2:leaderboard_test"] = progress2
+
+        leaderboard = get_quest_leaderboard()
+
+        assert len(leaderboard) == 2
+        # agent1 should be first (more tokens)
+        assert leaderboard[0]["agent_id"] == "agent1"
+        assert leaderboard[0]["total_tokens"] == 200
+        assert leaderboard[1]["agent_id"] == "agent2"
+        assert leaderboard[1]["total_tokens"] == 100
+
+        del _quest_definitions["leaderboard_test"]
+
+
+# ── Quest Reset Tests ─────────────────────────────────────────────────────
+
+
+class TestQuestReset:
+    def test_reset_quest_progress_all(self):
+        # Create some progress entries
+        progress1 = QuestProgress(
+            quest_id="quest1", agent_id="agent1", status=QuestStatus.NOT_STARTED
+        )
+        progress2 = QuestProgress(
+            quest_id="quest2", agent_id="agent2", status=QuestStatus.NOT_STARTED
+        )
+
+        from timmy.quest_system import _quest_progress
+
+        _quest_progress["agent1:quest1"] = progress1
+        _quest_progress["agent2:quest2"] = progress2
+
+        assert len(_quest_progress) == 2
+
+        count = reset_quest_progress()
+        assert count == 2
+        assert len(_quest_progress) == 0
+
+    def test_reset_quest_progress_specific_quest(self):
+        progress1 = QuestProgress(
+            quest_id="quest1", agent_id="agent1", status=QuestStatus.NOT_STARTED
+        )
+        progress2 = QuestProgress(
+            quest_id="quest2", agent_id="agent1", status=QuestStatus.NOT_STARTED
+        )
+
+        from timmy.quest_system import _quest_progress
+
+        _quest_progress["agent1:quest1"] = progress1
+        _quest_progress["agent1:quest2"] = progress2
+
+        count = reset_quest_progress(quest_id="quest1")
+        assert count == 1
+        assert "agent1:quest1" not in _quest_progress
+        assert "agent1:quest2" in _quest_progress
+
+    def test_reset_quest_progress_specific_agent(self):
+        progress1 = QuestProgress(
+            quest_id="quest1", agent_id="agent1", status=QuestStatus.NOT_STARTED
+        )
+        progress2 = QuestProgress(
+            quest_id="quest1", agent_id="agent2", status=QuestStatus.NOT_STARTED
+        )
+
+        from timmy.quest_system import _quest_progress
+
+        _quest_progress["agent1:quest1"] = progress1
+        _quest_progress["agent2:quest1"] = progress2
+
+        count = reset_quest_progress(agent_id="agent1")
+        assert count == 1
+        assert "agent1:quest1" not in _quest_progress
+        assert "agent2:quest1" in _quest_progress

tests/unit/test_rate_limit.py

@@ -0,0 +1,446 @@
+"""Tests for rate limiting middleware.
+
+Tests the RateLimiter class and RateLimitMiddleware for correct
+rate limiting behavior, cleanup, and edge cases.
+"""
+
+import time
+from unittest.mock import Mock
+
+import pytest
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+from dashboard.middleware.rate_limit import RateLimiter, RateLimitMiddleware
+
+
+class TestRateLimiter:
+    """Tests for the RateLimiter class."""
+
+    def test_init_defaults(self):
+        """RateLimiter initializes with default values."""
+        limiter = RateLimiter()
+        assert limiter.requests_per_minute == 30
+        assert limiter.cleanup_interval_seconds == 60
+        assert limiter._storage == {}
+
+    def test_init_custom_values(self):
+        """RateLimiter accepts custom configuration."""
+        limiter = RateLimiter(requests_per_minute=60, cleanup_interval_seconds=120)
+        assert limiter.requests_per_minute == 60
+        assert limiter.cleanup_interval_seconds == 120
+
+    def test_is_allowed_first_request(self):
+        """First request from an IP is always allowed."""
+        limiter = RateLimiter(requests_per_minute=5)
+        allowed, retry_after = limiter.is_allowed("192.168.1.1")
+        assert allowed is True
+        assert retry_after == 0.0
+        assert "192.168.1.1" in limiter._storage
+        assert len(limiter._storage["192.168.1.1"]) == 1
+
+    def test_is_allowed_under_limit(self):
+        """Requests under the limit are allowed."""
+        limiter = RateLimiter(requests_per_minute=5)
+
+        # Make 4 requests (under limit of 5)
+        for _ in range(4):
+            allowed, _ = limiter.is_allowed("192.168.1.1")
+            assert allowed is True
+
+        assert len(limiter._storage["192.168.1.1"]) == 4
+
+    def test_is_allowed_at_limit(self):
+        """Request at the limit is allowed."""
+        limiter = RateLimiter(requests_per_minute=5)
+
+        # Make exactly 5 requests
+        for _ in range(5):
+            allowed, _ = limiter.is_allowed("192.168.1.1")
+            assert allowed is True
+
+        assert len(limiter._storage["192.168.1.1"]) == 5
+
+    def test_is_allowed_over_limit(self):
+        """Request over the limit is denied."""
+        limiter = RateLimiter(requests_per_minute=5)
+
+        # Make 5 requests to hit the limit
+        for _ in range(5):
+            limiter.is_allowed("192.168.1.1")
+
+        # 6th request should be denied
+        allowed, retry_after = limiter.is_allowed("192.168.1.1")
+        assert allowed is False
+        assert retry_after > 0
+
+    def test_is_allowed_different_ips(self):
+        """Rate limiting is per-IP, not global."""
+        limiter = RateLimiter(requests_per_minute=5)
+
+        # Hit limit for IP 1
+        for _ in range(5):
+            limiter.is_allowed("192.168.1.1")
+
+        # IP 1 is now rate limited
+        allowed, _ = limiter.is_allowed("192.168.1.1")
+        assert allowed is False
+
+        # IP 2 should still be allowed
+        allowed, _ = limiter.is_allowed("192.168.1.2")
+        assert allowed is True
+
+    def test_window_expiration_allows_new_requests(self):
+        """After window expires, new requests are allowed."""
+        limiter = RateLimiter(requests_per_minute=5)
+
+        # Hit the limit
+        for _ in range(5):
+            limiter.is_allowed("192.168.1.1")
+
+        # Should be rate limited
+        allowed, _ = limiter.is_allowed("192.168.1.1")
+        assert allowed is False
+
+        # Simulate time passing by clearing timestamps manually
+        # (we can't wait 60 seconds in a test)
+        limiter._storage["192.168.1.1"].clear()
+
+        # Should now be allowed again
+        allowed, _ = limiter.is_allowed("192.168.1.1")
+        assert allowed is True
+
+    def test_cleanup_removes_stale_entries(self):
+        """Cleanup removes IPs with no recent requests."""
+        limiter = RateLimiter(
+            requests_per_minute=5,
+            cleanup_interval_seconds=1,  # Short interval for testing
+        )
+
+        # Add some requests
+        limiter.is_allowed("192.168.1.1")
+        limiter.is_allowed("192.168.1.2")
+
+        # Both IPs should be in storage
+        assert "192.168.1.1" in limiter._storage
+        assert "192.168.1.2" in limiter._storage
+
+        # Manually clear timestamps to simulate stale data
+        limiter._storage["192.168.1.1"].clear()
+        limiter._last_cleanup = time.time() - 2  # Force cleanup
+
+        # Trigger cleanup via check_request with a mock
+        mock_request = Mock()
+        mock_request.headers = {}
+        mock_request.client = Mock()
+        mock_request.client.host = "192.168.1.3"
+        mock_request.url.path = "/api/matrix/test"
+
+        limiter.check_request(mock_request)
+
+        # Stale IP should be removed
+        assert "192.168.1.1" not in limiter._storage
+        # IP with no requests (cleared) is also stale
+        assert "192.168.1.2" in limiter._storage
+
+    def test_get_client_ip_direct(self):
+        """Extract client IP from direct connection."""
+        limiter = RateLimiter()
+
+        mock_request = Mock()
+        mock_request.headers = {}
+        mock_request.client = Mock()
+        mock_request.client.host = "192.168.1.100"
+
+        ip = limiter._get_client_ip(mock_request)
+        assert ip == "192.168.1.100"
+
+    def test_get_client_ip_x_forwarded_for(self):
+        """Extract client IP from X-Forwarded-For header."""
+        limiter = RateLimiter()
+
+        mock_request = Mock()
+        mock_request.headers = {"x-forwarded-for": "10.0.0.1, 192.168.1.1"}
+        mock_request.client = Mock()
+        mock_request.client.host = "192.168.1.100"
+
+        ip = limiter._get_client_ip(mock_request)
+        assert ip == "10.0.0.1"
+
+    def test_get_client_ip_x_real_ip(self):
+        """Extract client IP from X-Real-IP header."""
+        limiter = RateLimiter()
+
+        mock_request = Mock()
+        mock_request.headers = {"x-real-ip": "10.0.0.5"}
+        mock_request.client = Mock()
+        mock_request.client.host = "192.168.1.100"
+
+        ip = limiter._get_client_ip(mock_request)
+        assert ip == "10.0.0.5"
+
+    def test_get_client_ip_no_client(self):
+        """Return 'unknown' when no client info available."""
+        limiter = RateLimiter()
+
+        mock_request = Mock()
+        mock_request.headers = {}
+        mock_request.client = None
+
+        ip = limiter._get_client_ip(mock_request)
+        assert ip == "unknown"
+
+
+class TestRateLimitMiddleware:
+    """Tests for the RateLimitMiddleware class."""
+
+    @pytest.fixture
+    def mock_app(self):
+        """Create a mock ASGI app."""
+
+        async def app(scope, receive, send):
+            response = JSONResponse({"status": "ok"})
+            await response(scope, receive, send)
+
+        return app
+
+    @pytest.fixture
+    def mock_request(self):
+        """Create a mock Request object."""
+        request = Mock(spec=Request)
+        request.url.path = "/api/matrix/test"
+        request.headers = {}
+        request.client = Mock()
+        request.client.host = "192.168.1.1"
+        return request
+
+    def test_init_defaults(self, mock_app):
+        """Middleware initializes with default values."""
+        middleware = RateLimitMiddleware(mock_app)
+        assert middleware.path_prefixes == []
+        assert middleware.limiter.requests_per_minute == 30
+
+    def test_init_custom_values(self, mock_app):
+        """Middleware accepts custom configuration."""
+        middleware = RateLimitMiddleware(
+            mock_app,
+            path_prefixes=["/api/matrix/"],
+            requests_per_minute=60,
+        )
+        assert middleware.path_prefixes == ["/api/matrix/"]
+        assert middleware.limiter.requests_per_minute == 60
+
+    def test_should_rate_limit_no_prefixes(self, mock_app):
+        """With no prefixes, all paths are rate limited."""
+        middleware = RateLimitMiddleware(mock_app)
+        assert middleware._should_rate_limit("/api/matrix/test") is True
+        assert middleware._should_rate_limit("/api/other/test") is True
+        assert middleware._should_rate_limit("/health") is True
+
+    def test_should_rate_limit_with_prefixes(self, mock_app):
+        """With prefixes, only matching paths are rate limited."""
+        middleware = RateLimitMiddleware(
+            mock_app,
+            path_prefixes=["/api/matrix/", "/api/public/"],
+        )
+        assert middleware._should_rate_limit("/api/matrix/test") is True
+        assert middleware._should_rate_limit("/api/matrix/") is True
+        assert middleware._should_rate_limit("/api/public/data") is True
+        assert middleware._should_rate_limit("/api/other/test") is False
+        assert middleware._should_rate_limit("/health") is False
+
+    @pytest.mark.asyncio
+    async def test_dispatch_allows_matching_path_under_limit(self, mock_app):
+        """Request to matching path under limit is allowed."""
+        middleware = RateLimitMiddleware(
+            mock_app,
+            path_prefixes=["/api/matrix/"],
+            requests_per_minute=5,
+        )
+
+        # Create a proper ASGI scope
+        scope = {
+            "type": "http",
+            "method": "GET",
+            "path": "/api/matrix/test",
+            "headers": [],
+        }
+
+        async def receive():
+            return {"type": "http.request", "body": b""}
+
+        response_body = []
+
+        async def send(message):
+            response_body.append(message)
+
+        await middleware(scope, receive, send)
+
+        # Should have sent response messages
+        assert len(response_body) > 0
+        # Check for 200 status in the response start message
+        start_message = next(
+            (m for m in response_body if m.get("type") == "http.response.start"), None
+        )
+        assert start_message is not None
+        assert start_message["status"] == 200
+
+    @pytest.mark.asyncio
+    async def test_dispatch_skips_non_matching_path(self, mock_app):
+        """Request to non-matching path bypasses rate limiting."""
+        middleware = RateLimitMiddleware(
+            mock_app,
+            path_prefixes=["/api/matrix/"],
+            requests_per_minute=5,
+        )
+
+        scope = {
+            "type": "http",
+            "method": "GET",
+            "path": "/api/other/test",  # Doesn't match /api/matrix/
+            "headers": [],
+        }
+
+        async def receive():
+            return {"type": "http.request", "body": b""}
+
+        response_body = []
+
+        async def send(message):
+            response_body.append(message)
+
+        await middleware(scope, receive, send)
+
+        # Should have sent response messages
+        assert len(response_body) > 0
+        start_message = next(
+            (m for m in response_body if m.get("type") == "http.response.start"), None
+        )
+        assert start_message is not None
+        assert start_message["status"] == 200
+
+    @pytest.mark.asyncio
+    async def test_dispatch_returns_429_when_rate_limited(self, mock_app):
+        """Request over limit returns 429 status."""
+        middleware = RateLimitMiddleware(
+            mock_app,
+            path_prefixes=["/api/matrix/"],
+            requests_per_minute=2,  # Low limit for testing
+        )
+
+        # First request - allowed
+        test_scope = {
+            "type": "http",
+            "method": "GET",
+            "path": "/api/matrix/test",
+            "headers": [],
+        }
+
+        async def receive():
+            return {"type": "http.request", "body": b""}
+
+        # Helper to capture response
+        def make_send(captured):
+            async def send(message):
+                captured.append(message)
+
+            return send
+
+        # Make requests to hit the limit
+        for _ in range(2):
+            response_body = []
+            await middleware(test_scope, receive, make_send(response_body))
+
+            start_message = next(
+                (m for m in response_body if m.get("type") == "http.response.start"),
+                None,
+            )
+            assert start_message["status"] == 200
+
+        # 3rd request should be rate limited
+        response_body = []
+        await middleware(test_scope, receive, make_send(response_body))
+
+        start_message = next(
+            (m for m in response_body if m.get("type") == "http.response.start"), None
+        )
+        assert start_message["status"] == 429
+
+        # Check for Retry-After header
+        headers = dict(start_message.get("headers", []))
+        assert b"retry-after" in headers or b"Retry-After" in headers
+
+
+class TestRateLimiterIntegration:
+    """Integration-style tests for rate limiter behavior."""
+
+    def test_multiple_ips_independent_limits(self):
+        """Each IP has its own independent rate limit."""
+        limiter = RateLimiter(requests_per_minute=3)
+
+        # Use up limit for IP 1
+        for _ in range(3):
+            limiter.is_allowed("10.0.0.1")
+
+        # Use up limit for IP 2
+        for _ in range(3):
+            limiter.is_allowed("10.0.0.2")
+
+        # Both should now be rate limited
+        assert limiter.is_allowed("10.0.0.1")[0] is False
+        assert limiter.is_allowed("10.0.0.2")[0] is False
+
+        # IP 3 should still be allowed
+        assert limiter.is_allowed("10.0.0.3")[0] is True
+
+    def test_timestamp_window_sliding(self):
+        """Rate limit window slides correctly as time passes."""
+        from collections import deque
+
+        limiter = RateLimiter(requests_per_minute=3)
+
+        # Add 3 timestamps manually (simulating old requests)
+        now = time.time()
+        limiter._storage["test-ip"] = deque(
+            [
+                now - 100,  # 100 seconds ago (outside 60s window)
+                now - 50,  # 50 seconds ago (inside window)
+                now - 10,  # 10 seconds ago (inside window)
+            ]
+        )
+
+        # Currently have 2 requests in window, so 1 more allowed
+        allowed, _ = limiter.is_allowed("test-ip")
+        assert allowed is True
+
+        # Now 3 in window, should be rate limited
+        allowed, _ = limiter.is_allowed("test-ip")
+        assert allowed is False
+
+    def test_cleanup_preserves_active_ips(self):
+        """Cleanup only removes IPs with no recent requests."""
+        from collections import deque
+
+        limiter = RateLimiter(
+            requests_per_minute=3,
+            cleanup_interval_seconds=1,
+        )
+
+        now = time.time()
+        # IP 1: active recently
+        limiter._storage["active-ip"] = deque([now - 10])
+        # IP 2: no timestamps (stale)
+        limiter._storage["stale-ip"] = deque()
+        # IP 3: old timestamps only
+        limiter._storage["old-ip"] = deque([now - 100])
+
+        limiter._last_cleanup = now - 2  # Force cleanup
+
+        # Run cleanup
+        limiter._cleanup_if_needed()
+
+        # Active IP should remain
+        assert "active-ip" in limiter._storage
+        # Stale IPs should be removed
+        assert "stale-ip" not in limiter._storage
+        assert "old-ip" not in limiter._storage

tests/unit/test_visitor.py

@@ -0,0 +1,367 @@
+"""Tests for infrastructure.visitor — visitor state tracking."""
+
+from unittest.mock import patch
+
+from infrastructure.visitor import VisitorRegistry, VisitorState
+
+# ---------------------------------------------------------------------------
+# VisitorState dataclass tests
+# ---------------------------------------------------------------------------
+
+
+class TestVisitorState:
+    """Tests for the VisitorState dataclass."""
+
+    def test_defaults(self):
+        """VisitorState has correct defaults when only visitor_id is provided."""
+        v = VisitorState(visitor_id="v1")
+
+        assert v.visitor_id == "v1"
+        assert v.display_name == "v1"  # Defaults to visitor_id
+        assert v.position == {"x": 0.0, "y": 0.0, "z": 0.0}
+        assert v.rotation == 0.0
+        assert "T" in v.connected_at  # ISO format check
+
+    def test_custom_values(self):
+        """VisitorState accepts custom values for all fields."""
+        v = VisitorState(
+            visitor_id="v2",
+            display_name="Alice",
+            position={"x": 1.0, "y": 2.0, "z": 3.0},
+            rotation=90.0,
+            connected_at="2026-03-21T12:00:00Z",
+        )
+
+        assert v.visitor_id == "v2"
+        assert v.display_name == "Alice"
+        assert v.position == {"x": 1.0, "y": 2.0, "z": 3.0}
+        assert v.rotation == 90.0
+        assert v.connected_at == "2026-03-21T12:00:00Z"
+
+    def test_display_name_defaults_to_visitor_id(self):
+        """Empty display_name falls back to visitor_id."""
+        v = VisitorState(visitor_id="charlie", display_name="")
+        assert v.display_name == "charlie"
+
+    def test_position_is_copied_not_shared(self):
+        """Each VisitorState has its own position dict."""
+        pos = {"x": 1.0, "y": 2.0, "z": 3.0}
+        v1 = VisitorState(visitor_id="v1", position=pos)
+        v2 = VisitorState(visitor_id="v2", position=pos)
+
+        v1.position["x"] = 99.0
+        assert v2.position["x"] == 1.0  # v2 unchanged
+
+
+# ---------------------------------------------------------------------------
+# VisitorRegistry singleton tests
+# ---------------------------------------------------------------------------
+
+
+class TestVisitorRegistrySingleton:
+    """Tests for the VisitorRegistry singleton behavior."""
+
+    def setup_method(self):
+        """Clear registry before each test."""
+        VisitorRegistry._instance = None
+
+    def teardown_method(self):
+        """Clean up after each test."""
+        VisitorRegistry._instance = None
+
+    def test_singleton_returns_same_instance(self):
+        """Multiple calls return the same registry object."""
+        r1 = VisitorRegistry()
+        r2 = VisitorRegistry()
+        assert r1 is r2
+
+    def test_singleton_shares_state(self):
+        """State is shared across all references to the singleton."""
+        r1 = VisitorRegistry()
+        r1.add("v1")
+
+        r2 = VisitorRegistry()
+        assert len(r2) == 1
+        assert r2.get("v1") is not None
+
+
+# ---------------------------------------------------------------------------
+# VisitorRegistry.add tests
+# ---------------------------------------------------------------------------
+
+
+class TestVisitorRegistryAdd:
+    """Tests for VisitorRegistry.add()."""
+
+    def setup_method(self):
+        """Clear registry before each test."""
+        VisitorRegistry._instance = None
+        self.registry = VisitorRegistry()
+
+    def teardown_method(self):
+        """Clean up after each test."""
+        VisitorRegistry._instance = None
+
+    def test_add_returns_visitor_state(self):
+        """add() returns the created VisitorState."""
+        result = self.registry.add("v1")
+        assert isinstance(result, VisitorState)
+        assert result.visitor_id == "v1"
+
+    def test_add_with_display_name(self):
+        """add() accepts a custom display name."""
+        result = self.registry.add("v1", display_name="Alice")
+        assert result.display_name == "Alice"
+
+    def test_add_with_position(self):
+        """add() accepts an initial position."""
+        pos = {"x": 10.0, "y": 20.0, "z": 30.0}
+        result = self.registry.add("v1", position=pos)
+        assert result.position == pos
+
+    def test_add_increases_count(self):
+        """Each add increases the registry size."""
+        assert len(self.registry) == 0
+        self.registry.add("v1")
+        assert len(self.registry) == 1
+        self.registry.add("v2")
+        assert len(self.registry) == 2
+
+
+# ---------------------------------------------------------------------------
+# VisitorRegistry.remove tests
+# ---------------------------------------------------------------------------
+
+
+class TestVisitorRegistryRemove:
+    """Tests for VisitorRegistry.remove()."""
+
+    def setup_method(self):
+        """Clear registry and add test visitors."""
+        VisitorRegistry._instance = None
+        self.registry = VisitorRegistry()
+        self.registry.add("v1")
+        self.registry.add("v2")
+
+    def teardown_method(self):
+        """Clean up after each test."""
+        VisitorRegistry._instance = None
+
+    def test_remove_existing_returns_true(self):
+        """Removing an existing visitor returns True."""
+        result = self.registry.remove("v1")
+        assert result is True
+        assert len(self.registry) == 1
+
+    def test_remove_nonexistent_returns_false(self):
+        """Removing a non-existent visitor returns False."""
+        result = self.registry.remove("unknown")
+        assert result is False
+        assert len(self.registry) == 2
+
+    def test_removes_correct_visitor(self):
+        """remove() only removes the specified visitor."""
+        self.registry.remove("v1")
+        assert self.registry.get("v1") is None
+        assert self.registry.get("v2") is not None
+
+
+# ---------------------------------------------------------------------------
+# VisitorRegistry.update_position tests
+# ---------------------------------------------------------------------------
+
+
+class TestVisitorRegistryUpdatePosition:
+    """Tests for VisitorRegistry.update_position()."""
+
+    def setup_method(self):
+        """Clear registry and add test visitor."""
+        VisitorRegistry._instance = None
+        self.registry = VisitorRegistry()
+        self.registry.add("v1", position={"x": 0.0, "y": 0.0, "z": 0.0})
+
+    def teardown_method(self):
+        """Clean up after each test."""
+        VisitorRegistry._instance = None
+
+    def test_update_position_returns_true(self):
+        """update_position returns True for existing visitor."""
+        result = self.registry.update_position("v1", {"x": 1.0, "y": 2.0, "z": 3.0})
+        assert result is True
+
+    def test_update_position_returns_false_for_unknown(self):
+        """update_position returns False for non-existent visitor."""
+        result = self.registry.update_position("unknown", {"x": 1.0, "y": 2.0, "z": 3.0})
+        assert result is False
+
+    def test_update_position_changes_values(self):
+        """update_position updates the stored position."""
+        new_pos = {"x": 10.0, "y": 20.0, "z": 30.0}
+        self.registry.update_position("v1", new_pos)
+
+        visitor = self.registry.get("v1")
+        assert visitor.position == new_pos
+
+    def test_update_position_with_rotation(self):
+        """update_position can also update rotation."""
+        self.registry.update_position("v1", {"x": 1.0, "y": 0.0, "z": 0.0}, rotation=180.0)
+
+        visitor = self.registry.get("v1")
+        assert visitor.rotation == 180.0
+
+    def test_update_position_without_rotation_preserves_it(self):
+        """Calling update_position without rotation preserves existing rotation."""
+        self.registry.update_position("v1", {"x": 1.0, "y": 0.0, "z": 0.0}, rotation=90.0)
+        self.registry.update_position("v1", {"x": 2.0, "y": 0.0, "z": 0.0})
+
+        visitor = self.registry.get("v1")
+        assert visitor.rotation == 90.0
+
+
+# ---------------------------------------------------------------------------
+# VisitorRegistry.get tests
+# ---------------------------------------------------------------------------
+
+
+class TestVisitorRegistryGet:
+    """Tests for VisitorRegistry.get()."""
+
+    def setup_method(self):
+        """Clear registry and add test visitor."""
+        VisitorRegistry._instance = None
+        self.registry = VisitorRegistry()
+        self.registry.add("v1", display_name="Alice")
+
+    def teardown_method(self):
+        """Clean up after each test."""
+        VisitorRegistry._instance = None
+
+    def test_get_existing_returns_visitor(self):
+        """get() returns VisitorState for existing visitor."""
+        result = self.registry.get("v1")
+        assert isinstance(result, VisitorState)
+        assert result.visitor_id == "v1"
+        assert result.display_name == "Alice"
+
+    def test_get_nonexistent_returns_none(self):
+        """get() returns None for non-existent visitor."""
+        result = self.registry.get("unknown")
+        assert result is None
+
+
+# ---------------------------------------------------------------------------
+# VisitorRegistry.get_all tests
+# ---------------------------------------------------------------------------
+
+
+class TestVisitorRegistryGetAll:
+    """Tests for VisitorRegistry.get_all() — Matrix protocol format."""
+
+    def setup_method(self):
+        """Clear registry and add test visitors."""
+        VisitorRegistry._instance = None
+        self.registry = VisitorRegistry()
+        self.registry.add("v1", display_name="Alice", position={"x": 1.0, "y": 2.0, "z": 3.0})
+        self.registry.add("v2", display_name="Bob", position={"x": 4.0, "y": 5.0, "z": 6.0})
+
+    def teardown_method(self):
+        """Clean up after each test."""
+        VisitorRegistry._instance = None
+
+    def test_get_all_returns_list(self):
+        """get_all() returns a list."""
+        result = self.registry.get_all()
+        assert isinstance(result, list)
+        assert len(result) == 2
+
+    def test_get_all_format_has_required_fields(self):
+        """Each entry has type, visitor_id, data, and ts."""
+        result = self.registry.get_all()
+
+        for entry in result:
+            assert "type" in entry
+            assert "visitor_id" in entry
+            assert "data" in entry
+            assert "ts" in entry
+
+    def test_get_all_type_is_visitor_state(self):
+        """The type field is 'visitor_state'."""
+        result = self.registry.get_all()
+        assert all(entry["type"] == "visitor_state" for entry in result)
+
+    def test_get_all_data_has_required_fields(self):
+        """data dict contains display_name, position, rotation, connected_at."""
+        result = self.registry.get_all()
+
+        for entry in result:
+            data = entry["data"]
+            assert "display_name" in data
+            assert "position" in data
+            assert "rotation" in data
+            assert "connected_at" in data
+
+    def test_get_all_position_is_dict(self):
+        """position within data is a dict with x, y, z."""
+        result = self.registry.get_all()
+
+        for entry in result:
+            pos = entry["data"]["position"]
+            assert isinstance(pos, dict)
+            assert "x" in pos
+            assert "y" in pos
+            assert "z" in pos
+
+    def test_get_all_ts_is_unix_timestamp(self):
+        """ts is an integer Unix timestamp."""
+        result = self.registry.get_all()
+
+        for entry in result:
+            assert isinstance(entry["ts"], int)
+            assert entry["ts"] > 0
+
+    @patch("infrastructure.visitor.time")
+    def test_get_all_uses_current_time(self, mock_time):
+        """ts is set from time.time()."""
+        mock_time.time.return_value = 1742529600
+
+        result = self.registry.get_all()
+        assert all(entry["ts"] == 1742529600 for entry in result)
+
+    def test_get_all_empty_registry(self):
+        """get_all() returns empty list when no visitors."""
+        self.registry.clear()
+        result = self.registry.get_all()
+        assert result == []
+
+
+# ---------------------------------------------------------------------------
+# VisitorRegistry.clear tests
+# ---------------------------------------------------------------------------
+
+
+class TestVisitorRegistryClear:
+    """Tests for VisitorRegistry.clear()."""
+
+    def setup_method(self):
+        """Clear registry and add test visitors."""
+        VisitorRegistry._instance = None
+        self.registry = VisitorRegistry()
+        self.registry.add("v1")
+        self.registry.add("v2")
+        self.registry.add("v3")
+
+    def teardown_method(self):
+        """Clean up after each test."""
+        VisitorRegistry._instance = None
+
+    def test_clear_removes_all_visitors(self):
+        """clear() removes all visitors from the registry."""
+        assert len(self.registry) == 3
+        self.registry.clear()
+        assert len(self.registry) == 0
+
+    def test_clear_allows_readding(self):
+        """Visitors can be re-added after clear()."""
+        self.registry.clear()
+        self.registry.add("v1")
+        assert len(self.registry) == 1