chore: checkpoint local wip for issue 892

feat: Implement NIP-89 and NIP-90 for Nostr agent partnerships
This commit introduces a new NostrClient for interacting with the Nostr network. The client implements the basic functionality for NIP-89 (discovery of agent capabilities) and NIP-90 (job delegation). The following changes are included: - A new class in that can connect to relays, subscribe to events, and publish events. - Implementation of (NIP-89) to discover agent capability cards. - Implementation of (NIP-90) to create and publish job requests. - Added and usage: websockets [--version | <uri>] as dependencies. - Added tests for the . Refs #892
2026-04-05 13:31:06 -04:00 · 2026-03-23 22:07:43 -04:00 · 2026-03-24 02:00:34 +00:00 · 2026-03-24 01:57:44 +00:00 · 2026-03-24 01:57:39 +00:00 · 2026-03-24 01:57:29 +00:00
116 changed files with 15253 additions and 1508 deletions
--- a/.env.example
+++ b/.env.example
@@ -27,8 +27,12 @@

 # ── AirLLM / big-brain backend ───────────────────────────────────────────────
 # Inference backend: "ollama" (default) | "airllm" | "auto"
-#   "auto" → uses AirLLM on Apple Silicon if installed, otherwise Ollama.
-#   Requires: pip install ".[bigbrain]"
+#   "ollama"  → always use Ollama (safe everywhere, any OS)
+#   "airllm"  → AirLLM layer-by-layer loading (Apple Silicon M1/M2/M3/M4 only)
+#               Requires 16 GB RAM minimum (32 GB recommended).
+#               Automatically falls back to Ollama on Intel Mac or Linux.
+#               Install extra: pip install "airllm[mlx]"
+#   "auto"    → use AirLLM on Apple Silicon if installed, otherwise Ollama
 # TIMMY_MODEL_BACKEND=ollama

 # AirLLM model size (default: 70b).
--- a/.kimi/AGENTS.md
+++ b/.kimi/AGENTS.md
@@ -62,6 +62,9 @@ Per AGENTS.md roster:
   - Run `tox -e pre-push` (lint + full CI suite)
   - Ensure tests stay green
   - Update TODO.md
+   - **CRITICAL: Stage files before committing** — always run `git add .` or `git add <files>` first
+   - Verify staged changes are non-empty: `git diff --cached --stat` must show files
+   - **NEVER run `git commit` without staging files first** — empty commits waste review cycles

 ---

--- a/AGENTS.md
+++ b/AGENTS.md
@@ -247,6 +247,48 @@ make docker-agent       # add a worker

 ---

+## Search Capability (SearXNG + Crawl4AI)
+
+Timmy has a self-hosted search backend requiring **no paid API key**.
+
+### Tools
+
+| Tool | Module | Description |
+|------|--------|-------------|
+| `web_search(query)` | `timmy/tools/search.py` | Meta-search via SearXNG — returns ranked results |
+| `scrape_url(url)` | `timmy/tools/search.py` | Full-page scrape via Crawl4AI → clean markdown |
+
+Both tools are registered in the **orchestrator** (full) and **echo** (research) toolkits.
+
+### Configuration
+
+| Env Var | Default | Description |
+|---------|---------|-------------|
+| `TIMMY_SEARCH_BACKEND` | `searxng` | `searxng` or `none` (disable) |
+| `TIMMY_SEARCH_URL` | `http://localhost:8888` | SearXNG base URL |
+| `TIMMY_CRAWL_URL` | `http://localhost:11235` | Crawl4AI base URL |
+
+Inside Docker Compose (when `--profile search` is active), the dashboard
+uses `http://searxng:8080` and `http://crawl4ai:11235` by default.
+
+### Starting the services
+
+```bash
+# Start SearXNG + Crawl4AI alongside the dashboard:
+docker compose --profile search up
+
+# Or start only the search services:
+docker compose --profile search up searxng crawl4ai
+```
+
+### Graceful degradation
+
+- If `TIMMY_SEARCH_BACKEND=none`: tools return a "disabled" message.
+- If SearXNG or Crawl4AI is unreachable: tools log a WARNING and return an
+  error string — the app never crashes.
+
+---
+
 ## Roadmap

 **v2.0 Exodus (in progress):** Voice + Marketplace + Integrations
--- a/README.md
+++ b/README.md
@@ -9,6 +9,21 @@ API access with Bitcoin Lightning — all from a browser, no cloud AI required.

 ---

+## System Requirements
+
+| Path | Hardware | RAM | Disk |
+|------|----------|-----|------|
+| **Ollama** (default) | Any OS — x86-64 or ARM | 8 GB min | 5–10 GB (model files) |
+| **AirLLM** (Apple Silicon) | M1, M2, M3, or M4 Mac | 16 GB min (32 GB recommended) | ~15 GB free |
+
+**Ollama path** runs on any modern machine — macOS, Linux, or Windows.  No GPU required.
+
+**AirLLM path** uses layer-by-layer loading for 70B+ models without a GPU.  Requires Apple
+Silicon and the `bigbrain` extras (`pip install ".[bigbrain]"`).  On Intel Mac or Linux the
+app automatically falls back to Ollama — no crash, no config change needed.
+
+---
+
 ## Quick Start

 ```bash
--- a/SOVEREIGNTY.md
+++ b/SOVEREIGNTY.md
@@ -0,0 +1,122 @@
+# SOVEREIGNTY.md — Research Sovereignty Manifest
+
+> "If this spec is implemented correctly, it is the last research document
+> Alexander should need to request from a corporate AI."
+> — Issue #972, March 22 2026
+
+---
+
+## What This Is
+
+A machine-readable declaration of Timmy's research independence:
+where we are, where we're going, and how to measure progress.
+
+---
+
+## The Problem We're Solving
+
+On March 22, 2026, a single Claude session produced six deep research reports.
+It consumed ~3 hours of human time and substantial corporate AI inference.
+Every report was valuable — but the workflow was **linear**.
+It would cost exactly the same to reproduce tomorrow.
+
+This file tracks the pipeline that crystallizes that workflow into something
+Timmy can run autonomously.
+
+---
+
+## The Six-Step Pipeline
+
+| Step | What Happens | Status |
+|------|-------------|--------|
+| 1. Scope | Human describes knowledge gap → Gitea issue with template | ✅ Done (`skills/research/`) |
+| 2. Query | LLM slot-fills template → 5–15 targeted queries | ✅ Done (`research.py`) |
+| 3. Search | Execute queries → top result URLs | ✅ Done (`research_tools.py`) |
+| 4. Fetch | Download + extract full pages (trafilatura) | ✅ Done (`tools/system_tools.py`) |
+| 5. Synthesize | Compress findings → structured report | ✅ Done (`research.py` cascade) |
+| 6. Deliver | Store to semantic memory + optional disk persist | ✅ Done (`research.py`) |
+
+---
+
+## Cascade Tiers (Synthesis Quality vs. Cost)
+
+| Tier | Model | Cost | Quality | Status |
+|------|-------|------|---------|--------|
+| **4** | SQLite semantic cache | $0.00 / instant | reuses prior | ✅ Active |
+| **3** | Ollama `qwen3:14b` | $0.00 / local | ★★★ | ✅ Active |
+| **2** | Claude API (haiku) | ~$0.01/report | ★★★★ | ✅ Active (opt-in) |
+| **1** | Groq `llama-3.3-70b` | $0.00 / rate-limited | ★★★★ | 🔲 Planned (#980) |
+
+Set `ANTHROPIC_API_KEY` to enable Tier 2 fallback.
+
+---
+
+## Research Templates
+
+Six prompt templates live in `skills/research/`:
+
+| Template | Use Case |
+|----------|----------|
+| `tool_evaluation.md` | Find all shipping tools for `{domain}` |
+| `architecture_spike.md` | How to connect `{system_a}` to `{system_b}` |
+| `game_analysis.md` | Evaluate `{game}` for AI agent play |
+| `integration_guide.md` | Wire `{tool}` into `{stack}` with code |
+| `state_of_art.md` | What exists in `{field}` as of `{date}` |
+| `competitive_scan.md` | How does `{project}` compare to `{alternatives}` |
+
+---
+
+## Sovereignty Metrics
+
+| Metric | Target (Week 1) | Target (Month 1) | Target (Month 3) | Graduation |
+|--------|-----------------|------------------|------------------|------------|
+| Queries answered locally | 10% | 40% | 80% | >90% |
+| API cost per report | <$1.50 | <$0.50 | <$0.10 | <$0.01 |
+| Time from question to report | <3 hours | <30 min | <5 min | <1 min |
+| Human involvement | 100% (review) | Review only | Approve only | None |
+
+---
+
+## How to Use the Pipeline
+
+```python
+from timmy.research import run_research
+
+# Quick research (no template)
+result = await run_research("best local embedding models for 36GB RAM")
+
+# With a template and slot values
+result = await run_research(
+    topic="PDF text extraction libraries for Python",
+    template="tool_evaluation",
+    slots={"domain": "PDF parsing", "use_case": "RAG pipeline", "focus_criteria": "accuracy"},
+    save_to_disk=True,
+)
+
+print(result.report)
+print(f"Backend: {result.synthesis_backend}, Cached: {result.cached}")
+```
+
+---
+
+## Implementation Status
+
+| Component | Issue | Status |
+|-----------|-------|--------|
+| `web_fetch` tool (trafilatura) | #973 | ✅ Done |
+| Research template library (6 templates) | #974 | ✅ Done |
+| `ResearchOrchestrator` (`research.py`) | #975 | ✅ Done |
+| Semantic index for outputs | #976 | 🔲 Planned |
+| Auto-create Gitea issues from findings | #977 | 🔲 Planned |
+| Paperclip task runner integration | #978 | 🔲 Planned |
+| Kimi delegation via labels | #979 | 🔲 Planned |
+| Groq free-tier cascade tier | #980 | 🔲 Planned |
+| Sovereignty metrics dashboard | #981 | 🔲 Planned |
+
+---
+
+## Governing Spec
+
+See [issue #972](http://143.198.27.163:3000/Rockachopa/Timmy-time-dashboard/issues/972) for the full spec and rationale.
+
+Research artifacts committed to `docs/research/`.
--- a/auth-gate.py
+++ b/auth-gate.py
@@ -1,6 +1,12 @@
 #!/usr/bin/env python3
 """Tiny auth gate for nginx auth_request. Sets a cookie after successful basic auth."""
-import hashlib, hmac, http.server, time, base64, os, sys
+import base64
+import hashlib
+import hmac
+import http.server
+import os
+import sys
+import time

 SECRET = os.environ.get("AUTH_GATE_SECRET", "")
 USER = os.environ.get("AUTH_GATE_USER", "")
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -42,6 +42,10 @@ services:
      GROK_ENABLED: "${GROK_ENABLED:-false}"
      XAI_API_KEY: "${XAI_API_KEY:-}"
      GROK_DEFAULT_MODEL: "${GROK_DEFAULT_MODEL:-grok-3-fast}"
+      # Search backend (SearXNG + Crawl4AI) — set TIMMY_SEARCH_BACKEND=none to disable
+      TIMMY_SEARCH_BACKEND: "${TIMMY_SEARCH_BACKEND:-searxng}"
+      TIMMY_SEARCH_URL: "${TIMMY_SEARCH_URL:-http://searxng:8080}"
+      TIMMY_CRAWL_URL: "${TIMMY_CRAWL_URL:-http://crawl4ai:11235}"
    extra_hosts:
      - "host.docker.internal:host-gateway"  # Linux: maps to host IP
    networks:
@@ -74,6 +78,50 @@ services:
    profiles:
      - celery

+  # ── SearXNG — self-hosted meta-search engine ─────────────────────────
+  searxng:
+    image: searxng/searxng:latest
+    container_name: timmy-searxng
+    profiles:
+      - search
+    ports:
+      - "${SEARXNG_PORT:-8888}:8080"
+    environment:
+      SEARXNG_BASE_URL: "${SEARXNG_BASE_URL:-http://localhost:8888}"
+    volumes:
+      - ./docker/searxng:/etc/searxng:rw
+    networks:
+      - timmy-net
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://localhost:8080/healthz"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 20s
+
+  # ── Crawl4AI — self-hosted web scraper ────────────────────────────────
+  crawl4ai:
+    image: unclecode/crawl4ai:latest
+    container_name: timmy-crawl4ai
+    profiles:
+      - search
+    ports:
+      - "${CRAWL4AI_PORT:-11235}:11235"
+    environment:
+      CRAWL4AI_API_TOKEN: "${CRAWL4AI_API_TOKEN:-}"
+    volumes:
+      - timmy-data:/app/data
+    networks:
+      - timmy-net
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:11235/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 30s
+
  # ── OpenFang — vendored agent runtime sidecar ────────────────────────────
  openfang:
    build:
--- a/docker/searxng/settings.yml
+++ b/docker/searxng/settings.yml
@@ -0,0 +1,67 @@
+# SearXNG configuration for Timmy Time self-hosted search
+# https://docs.searxng.org/admin/settings/settings.html
+
+general:
+  debug: false
+  instance_name: "Timmy Search"
+  privacypolicy_url: false
+  donation_url: false
+  contact_url: false
+  enable_metrics: false
+
+server:
+  port: 8080
+  bind_address: "0.0.0.0"
+  secret_key: "timmy-searxng-key-change-in-production"
+  base_url: false
+  image_proxy: false
+
+ui:
+  static_use_hash: false
+  default_locale: ""
+  query_in_title: false
+  infinite_scroll: false
+  default_theme: simple
+  center_alignment: false
+
+search:
+  safe_search: 0
+  autocomplete: ""
+  default_lang: "en"
+  formats:
+    - html
+    - json
+
+outgoing:
+  request_timeout: 6.0
+  max_request_timeout: 10.0
+  useragent_suffix: "TimmyResearchBot"
+  pool_connections: 100
+  pool_maxsize: 20
+
+enabled_plugins:
+  - Hash_plugin
+  - Search_on_category_select
+  - Tracker_url_remover
+
+engines:
+  - name: google
+    engine: google
+    shortcut: g
+    categories: general
+
+  - name: bing
+    engine: bing
+    shortcut: b
+    categories: general
+
+  - name: duckduckgo
+    engine: duckduckgo
+    shortcut: d
+    categories: general
+
+  - name: wikipedia
+    engine: wikipedia
+    shortcut: wp
+    categories: general
+    timeout: 3.0
--- a/docs/SCREENSHOT_TRIAGE_2026-03-24.md
+++ b/docs/SCREENSHOT_TRIAGE_2026-03-24.md
@@ -0,0 +1,89 @@
+# Screenshot Dump Triage — Visual Inspiration & Research Leads
+
+**Date:** March 24, 2026
+**Source:** Issue #1275 — "Screenshot dump for triage #1"
+**Analyst:** Claude (Sonnet 4.6)
+
+---
+
+## Screenshots Ingested
+
+| File | Subject | Action |
+|------|---------|--------|
+| IMG_6187.jpeg | AirLLM / Apple Silicon local LLM requirements | → Issue #1284 |
+| IMG_6125.jpeg | vLLM backend for agentic workloads | → Issue #1281 |
+| IMG_6124.jpeg | DeerFlow autonomous research pipeline | → Issue #1283 |
+| IMG_6123.jpeg | "Vibe Coder vs Normal Developer" meme | → Issue #1285 |
+| IMG_6410.jpeg | SearXNG + Crawl4AI self-hosted search MCP | → Issue #1282 |
+
+---
+
+## Tickets Created
+
+### #1281 — feat: add vLLM as alternative inference backend
+**Source:** IMG_6125 (vLLM for agentic workloads)
+
+vLLM's continuous batching makes it 3–10x more throughput-efficient than Ollama for multi-agent
+request patterns. Implement `VllmBackend` in `infrastructure/llm_router/` as a selectable
+backend (`TIMMY_LLM_BACKEND=vllm`) with graceful fallback to Ollama.
+
+**Priority:** Medium — impactful for research pipeline performance once #972 is in use
+
+---
+
+### #1282 — feat: integrate SearXNG + Crawl4AI as self-hosted search backend
+**Source:** IMG_6410 (luxiaolei/searxng-crawl4ai-mcp)
+
+Self-hosted search via SearXNG + Crawl4AI removes the hard dependency on paid search APIs
+(Brave, Tavily). Add both as Docker Compose services, implement `web_search()` and
+`scrape_url()` tools in `timmy/tools/`, and register them with the research agent.
+
+**Priority:** High — unblocks fully local/private operation of research agents
+
+---
+
+### #1283 — research: evaluate DeerFlow as autonomous research orchestration layer
+**Source:** IMG_6124 (deer-flow Docker setup)
+
+DeerFlow is ByteDance's open-source autonomous research pipeline framework. Before investing
+further in Timmy's custom orchestrator (#972), evaluate whether DeerFlow's architecture offers
+integration value or design patterns worth borrowing.
+
+**Priority:** Medium — research first, implementation follows if go/no-go is positive
+
+---
+
+### #1284 — chore: document and validate AirLLM Apple Silicon requirements
+**Source:** IMG_6187 (Mac-compatible LLM setup)
+
+AirLLM graceful degradation is already implemented but undocumented. Add System Requirements
+to README (M1/M2/M3/M4, 16 GB RAM min, 15 GB disk) and document `TIMMY_LLM_BACKEND` in
+`.env.example`.
+
+**Priority:** Low — documentation only, no code risk
+
+---
+
+### #1285 — chore: enforce "Normal Developer" discipline — tighten quality gates
+**Source:** IMG_6123 (Vibe Coder vs Normal Developer meme)
+
+Tighten the existing mypy/bandit/coverage gates: fix all mypy errors, raise coverage from 73%
+to 80%, add a documented pre-push hook, and run `vulture` for dead code. The infrastructure
+exists — it just needs enforcing.
+
+**Priority:** Medium — technical debt prevention, pairs well with any green-field feature work
+
+---
+
+## Patterns Observed Across Screenshots
+
+1. **Local-first is the north star.** All five images reinforce the same theme: private,
+   self-hosted, runs on your hardware. vLLM, SearXNG, AirLLM, DeerFlow — none require cloud.
+   Timmy is already aligned with this direction; these are tactical additions.
+
+2. **Agentic performance bottlenecks are real.** Two of five images (vLLM, DeerFlow) focus
+   specifically on throughput and reliability for multi-agent loops. As the research pipeline
+   matures, inference speed and search reliability will become the main constraints.
+
+3. **Discipline compounds.** The meme is a reminder that the quality gates we have (tox,
+   mypy, bandit, coverage) only pay off if they are enforced without exceptions.
--- a/docs/model-benchmarks.md
+++ b/docs/model-benchmarks.md
--- a/docs/research/deerflow-evaluation.md
+++ b/docs/research/deerflow-evaluation.md
@@ -0,0 +1,190 @@
+# DeerFlow Evaluation — Autonomous Research Orchestration Layer
+
+**Status:** No-go for full adoption · Selective borrowing recommended
+**Date:** 2026-03-23
+**Issue:** #1283 (spawned from #1275 screenshot triage)
+**Refs:** #972 (Timmy research pipeline) · #975 (ResearchOrchestrator)
+
+---
+
+## What Is DeerFlow?
+
+DeerFlow (`bytedance/deer-flow`) is an open-source "super-agent harness" built by ByteDance on top of LangGraph. It provides a production-grade multi-agent research and code-execution framework with a web UI, REST API, Docker deployment, and optional IM channel integration (Telegram, Slack, Feishu/Lark).
+
+- **Stars:** ~39,600 · **License:** MIT
+- **Stack:** Python 3.12+ (backend) · TypeScript/Next.js (frontend) · LangGraph runtime
+- **Entry point:** `http://localhost:2026` (Nginx reverse proxy, configurable via `PORT`)
+
+---
+
+## Research Questions — Answers
+
+### 1. Agent Roles
+
+DeerFlow uses a two-tier architecture:
+
+| Role | Description |
+|------|-------------|
+| **Lead Agent** | Entry point; decomposes tasks, dispatches sub-agents, synthesizes results |
+| **Sub-Agent (general-purpose)** | All tools except `task`; spawned dynamically |
+| **Sub-Agent (bash)** | Command-execution specialist |
+
+The lead agent runs through a 12-middleware chain in order: thread setup → uploads → sandbox → tool-call repair → guardrails → summarization → todo tracking → title generation → memory update → image injection → sub-agent concurrency cap → clarification intercept.
+
+**Concurrency:** up to 3 sub-agents in parallel (configurable), 15-minute default timeout each, structured SSE event stream (`task_started` / `task_running` / `task_completed` / `task_failed`).
+
+**Mapping to Timmy personas:** DeerFlow's lead/sub-agent split roughly maps to Timmy's orchestrator + specialist-agent pattern. DeerFlow doesn't have named personas — it routes by capability (tools available to the agent type), not by identity. Timmy's persona system is richer and more opinionated.
+
+---
+
+### 2. API Surface
+
+DeerFlow exposes a full REST API at port 2026 (via Nginx). **No authentication by default.**
+
+**Core integration endpoints:**
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `POST /api/langgraph/threads` | | Create conversation thread |
+| `POST /api/langgraph/threads/{id}/runs` | | Submit task (blocking) |
+| `POST /api/langgraph/threads/{id}/runs/stream` | | Submit task (streaming SSE/WS) |
+| `GET /api/langgraph/threads/{id}/state` | | Get full thread state + artifacts |
+| `GET /api/models` | | List configured models |
+| `GET /api/threads/{id}/artifacts/{path}` | | Download generated artifacts |
+| `DELETE /api/threads/{id}` | | Clean up thread data |
+
+These are callable from Timmy with `httpx` — no special client library needed.
+
+---
+
+### 3. LLM Backend Support
+
+DeerFlow uses LangChain model classes declared in `config.yaml`.
+
+**Documented providers:** OpenAI, Anthropic, Google Gemini, DeepSeek, Doubao (ByteDance), Kimi/Moonshot, OpenRouter, MiniMax, Novita AI, Claude Code (OAuth).
+
+**Ollama:** Not in official documentation, but works via the `langchain_openai:ChatOpenAI` class with `base_url: http://localhost:11434/v1` and a dummy API key. Community-confirmed (GitHub issues #37, #1004) with Qwen2.5, Llama 3.1, and DeepSeek-R1.
+
+**vLLM:** Not documented, but architecturally identical — vLLM exposes an OpenAI-compatible endpoint. Should work with the same `base_url` override.
+
+**Practical caveat:** The lead agent requires strong instruction-following for consistent tool use and structured output. Community findings suggest ≥14B parameter models (Qwen2.5-14B minimum) for reliable orchestration. Our current `qwen3:14b` should be viable.
+
+---
+
+### 4. License
+
+**MIT License** — Copyright 2025 ByteDance Ltd. and DeerFlow Authors 2025–2026.
+
+Permissive: use, modify, distribute, commercialize freely. Attribution required. No warranty.
+
+**Compatible with Timmy's use case.** No CLA, no copyleft, no commercial restrictions.
+
+---
+
+### 5. Docker Port Conflicts
+
+DeerFlow's Docker Compose exposes a single host port:
+
+| Service | Host Port | Notes |
+|---------|-----------|-------|
+| Nginx (entry point) | **2026** (configurable via `PORT`) | Only externally exposed port |
+| Frontend (Next.js) | 3000 | Internal only |
+| Gateway API | 8001 | Internal only |
+| LangGraph runtime | 2024 | Internal only |
+| Provisioner (optional) | 8002 | Internal only, Kubernetes mode only |
+
+Timmy's existing Docker Compose exposes:
+- **8000** — dashboard (FastAPI)
+- **8080** — openfang (via `openfang` profile)
+- **11434** — Ollama (host process, not containerized)
+
+**No conflict.** Port 2026 is not used by Timmy. DeerFlow can run alongside the existing stack without modification.
+
+---
+
+## Full Capability Comparison
+
+| Capability | DeerFlow | Timmy (`research.py`) |
+|------------|----------|-----------------------|
+| Multi-agent fan-out | ✅ 3 concurrent sub-agents | ❌ Sequential only |
+| Web search | ✅ Tavily / InfoQuest | ✅ `research_tools.py` |
+| Web fetch | ✅ Jina AI / Firecrawl | ✅ trafilatura |
+| Code execution (sandbox) | ✅ Local / Docker / K8s | ❌ Not implemented |
+| Artifact generation | ✅ HTML, Markdown, slides | ❌ Markdown report only |
+| Document upload + conversion | ✅ PDF, PPT, Excel, Word | ❌ Not implemented |
+| Long-term memory | ✅ LLM-extracted facts, persistent | ✅ SQLite semantic cache |
+| Streaming results | ✅ SSE + WebSocket | ❌ Blocking call |
+| Web UI | ✅ Next.js included | ✅ Jinja2/HTMX dashboard |
+| IM integration | ✅ Telegram, Slack, Feishu | ✅ Telegram, Discord |
+| Ollama backend | ✅ (via config, community-confirmed) | ✅ Native |
+| Persona system | ❌ Role-based only | ✅ Named personas |
+| Semantic cache tier | ❌ Not implemented | ✅ SQLite (Tier 4) |
+| Free-tier cascade | ❌ Not applicable | 🔲 Planned (Groq, #980) |
+| Python version requirement | 3.12+ | 3.11+ |
+| Lock-in | LangGraph + LangChain | None |
+
+---
+
+## Integration Options Assessment
+
+### Option A — Full Adoption (replace `research.py`)
+**Verdict: Not recommended.**
+
+DeerFlow is a substantial full-stack system (Python + Node.js, Docker, Nginx, LangGraph). Adopting it fully would:
+- Replace Timmy's custom cascade tier system (SQLite cache → Ollama → Claude API → Groq) with a single-tier LangChain model config
+- Lose Timmy's persona-aware research routing
+- Add Python 3.12+ dependency (Timmy currently targets 3.11+)
+- Introduce LangGraph/LangChain lock-in for all research tasks
+- Require running a parallel Node.js frontend process (redundant given Timmy's own UI)
+
+### Option B — Sidecar for Heavy Research (call DeerFlow's API from Timmy)
+**Verdict: Viable but over-engineered for current needs.**
+
+DeerFlow could run as an optional sidecar (`docker compose --profile deerflow up`) and Timmy could delegate multi-agent research tasks via `POST /api/langgraph/threads/{id}/runs`. This would unlock parallel sub-agent fan-out and code-execution sandboxing without replacing Timmy's stack.
+
+The integration would be ~50 lines of `httpx` code in a new `DeerFlowClient` adapter. The `ResearchOrchestrator` in `research.py` could route tasks above a complexity threshold to DeerFlow.
+
+**Barrier:** DeerFlow's lack of default authentication means the sidecar would need to be network-isolated (internal Docker network only) or firewalled. Also, DeerFlow's Ollama integration is community-maintained, not officially supported — risk of breaking on upstream updates.
+
+### Option C — Selective Borrowing (copy patterns, not code)
+**Verdict: Recommended.**
+
+DeerFlow's architecture reveals concrete gaps in Timmy's current pipeline that are worth addressing independently:
+
+| DeerFlow Pattern | Timmy Gap to Close | Implementation Path |
+|------------------|--------------------|---------------------|
+| Parallel sub-agent fan-out | Research is sequential | Add `asyncio.gather()` to `ResearchOrchestrator` for concurrent query execution |
+| `SummarizationMiddleware` | Long contexts blow token budget | Add a context-trimming step in the synthesis cascade |
+| `TodoListMiddleware` | No progress tracking during long research | Wire into the dashboard task panel |
+| Artifact storage + serving | Reports are ephemeral (not persistently downloadable) | Add file-based artifact store to `research.py` (issue #976 already planned) |
+| Skill modules (Markdown-based) | Research templates are `.md` files — same pattern | Already done in `skills/research/` |
+| MCP integration | Research tools are hard-coded | Add MCP server discovery to `research_tools.py` for pluggable tool backends |
+
+---
+
+## Recommendation
+
+**No-go for full adoption or sidecar deployment at this stage.**
+
+Timmy's `ResearchOrchestrator` already covers the core pipeline (query → search → fetch → synthesize → store). DeerFlow's value proposition is primarily the parallel sub-agent fan-out and code-execution sandbox — capabilities that are useful but not blocking Timmy's current roadmap.
+
+**Recommended actions:**
+
+1. **Close the parallelism gap (high value, low effort):** Refactor `ResearchOrchestrator` to execute queries concurrently with `asyncio.gather()`. This delivers DeerFlow's most impactful capability without any new dependencies.
+
+2. **Re-evaluate after #980 and #981 are done:** Once Timmy has the Groq free-tier cascade and a sovereignty metrics dashboard, we'll have a clearer picture of whether the custom orchestrator is performing well enough to make DeerFlow unnecessary entirely.
+
+3. **File a follow-up for MCP tool integration:** DeerFlow's use of `langchain-mcp-adapters` for pluggable tool backends is the most architecturally interesting pattern. Adding MCP server discovery to `research_tools.py` would give Timmy the same extensibility without LangGraph lock-in.
+
+4. **Revisit DeerFlow's code-execution sandbox if #978 (Paperclip task runner) proves insufficient:** DeerFlow's sandboxed `bash` tool is production-tested and well-isolated. If Timmy's task runner needs secure code execution, DeerFlow's sandbox implementation is worth borrowing or wrapping.
+
+---
+
+## Follow-up Issues to File
+
+| Issue | Title | Priority |
+|-------|-------|----------|
+| New | Parallelize ResearchOrchestrator query execution (`asyncio.gather`) | Medium |
+| New | Add context-trimming step to synthesis cascade | Low |
+| New | MCP server discovery in `research_tools.py` | Low |
+| #976 | Semantic index for research outputs (already planned) | High |
--- a/docs/research/kimi-creative-blueprint-891.md
+++ b/docs/research/kimi-creative-blueprint-891.md
@@ -0,0 +1,290 @@
+# Building Timmy: Technical Blueprint for Sovereign Creative AI
+
+> **Source:** PDF attached to issue #891, "Building Timmy: a technical blueprint for sovereign
+> creative AI" — generated by Kimi.ai, 16 pages, filed by Perplexity for Timmy's review.
+> **Filed:** 2026-03-22 · **Reviewed:** 2026-03-23
+
+---
+
+## Executive Summary
+
+The blueprint establishes that a sovereign creative AI capable of coding, composing music,
+generating art, building worlds, publishing narratives, and managing its own economy is
+**technically feasible today** — but only through orchestration of dozens of tools operating
+at different maturity levels. The core insight: *the integration is the invention*. No single
+component is new; the missing piece is a coherent identity operating across all domains
+simultaneously with persistent memory, autonomous economics, and cross-domain creative
+reactions.
+
+Three non-negotiable architectural decisions:
+1. **Human oversight for all public-facing content** — every successful creative AI has this;
+   every one that removed it failed.
+2. **Legal entity before economic activity** — AI agents are not legal persons; establish
+   structure before wealth accumulates (Truth Terminal cautionary tale: $20M acquired before
+   a foundation was retroactively created).
+3. **Hybrid memory: vector search + knowledge graph** — neither alone is sufficient for
+   multi-domain context breadth.
+
+---
+
+## Domain-by-Domain Assessment
+
+### Software Development (immediately deployable)
+
+| Component | Recommendation | Notes |
+|-----------|----------------|-------|
+| Primary agent | Claude Code (Opus 4.6, 77.2% SWE-bench) | Already in use |
+| Self-hosted forge | Forgejo (MIT, 170–200MB RAM) | Project uses Gitea/Forgejo now |
+| CI/CD | GitHub Actions-compatible via `act_runner` | — |
+| Tool-making | LATM pattern: frontier model creates tools, cheaper model applies them | New — see ADR opportunity |
+| Open-source fallback | OpenHands (~65% SWE-bench, Docker sandboxed) | Backup to Claude Code |
+| Self-improvement | Darwin Gödel Machine / SICA patterns | 3–6 month investment |
+
+**Development estimate:** 2–3 weeks for Forgejo + Claude Code integration with automated
+PR workflows; 1–2 months for self-improving tool-making pipeline.
+
+**Cross-reference:** This project already runs Claude Code agents on Forgejo. The LATM
+pattern (tool registry) and self-improvement loop are the actionable gaps.
+
+---
+
+### Music (1–4 weeks)
+
+| Component | Recommendation | Notes |
+|-----------|----------------|-------|
+| Commercial vocals | Suno v5 API (~$0.03/song, $30/month Premier) | No official API; third-party: sunoapi.org, AIMLAPI, EvoLink |
+| Local instrumental | MusicGen 1.5B (CC-BY-NC — monetization blocker) | On M2 Max: ~60s for 5s clip |
+| Voice cloning | GPT-SoVITS v4 (MIT) | Works on Apple Silicon CPU, RTF 0.526 on M4 |
+| Voice conversion | RVC (MIT, 5–10 min training audio) | — |
+| Apple Silicon TTS | MLX-Audio: Kokoro 82M + Qwen3-TTS 0.6B | 4–5x faster via Metal |
+| Publishing | Wavlake (90/10 split, Lightning micropayments) | Auto-syndicates to Fountain.fm |
+| Nostr | NIP-94 (kind:1063) audio events → NIP-96 servers | — |
+
+**Copyright reality:** US Copyright Office (Jan 2025) and US Court of Appeals (Mar 2025):
+purely AI-generated music cannot be copyrighted and enters public domain. Wavlake's
+Value4Value model works around this — fans pay for relationship, not exclusive rights.
+
+**Avoid:** Udio (download disabled since Oct 2025, 2.4/5 Trustpilot).
+
+---
+
+### Visual Art (1–3 weeks)
+
+| Component | Recommendation | Notes |
+|-----------|----------------|-------|
+| Local generation | ComfyUI API at `127.0.0.1:8188` (programmatic control via WebSocket) | MLX extension: 50–70% faster |
+| Speed | Draw Things (free, Mac App Store) | 3× faster than ComfyUI via Metal shaders |
+| Quality frontier | Flux 2 (Nov 2025, 4MP, multi-reference) | SDXL needs 16GB+, Flux Dev 32GB+ |
+| Character consistency | LoRA training (30 min, 15–30 references) + Flux.1 Kontext | Solved problem |
+| Face consistency | IP-Adapter + FaceID (ComfyUI-IP-Adapter-Plus) | Training-free |
+| Comics | Jenova AI ($20/month, 200+ page consistency) or LlamaGen AI (free) | — |
+| Publishing | Blossom protocol (SHA-256 addressed, kind:10063) + Nostr NIP-94 | — |
+| Physical | Printful REST API (200+ products, automated fulfillment) | — |
+
+---
+
+### Writing / Narrative (1–4 weeks for pipeline; ongoing for quality)
+
+| Component | Recommendation | Notes |
+|-----------|----------------|-------|
+| LLM | Claude Opus 4.5/4.6 (leads Mazur Writing Benchmark at 8.561) | Already in use |
+| Context | 500K tokens (1M in beta) — entire novels fit | — |
+| Architecture | Outline-first → RAG lore bible → chapter-by-chapter generation | Without outline: novels meander |
+| Lore management | WorldAnvil Pro or custom LoreScribe (local RAG) | No tool achieves 100% consistency |
+| Publishing (ebooks) | Pandoc → EPUB / KDP PDF | pandoc-novel template on GitHub |
+| Publishing (print) | Lulu Press REST API (80% profit, global print network) | KDP: no official API, 3-book/day limit |
+| Publishing (Nostr) | NIP-23 kind:30023 long-form events | Habla.news, YakiHonne, Stacker News |
+| Podcasts | LLM script → TTS (ElevenLabs or local Kokoro/MLX-Audio) → feedgen RSS → Fountain.fm | Value4Value sats-per-minute |
+
+**Key constraint:** AI-assisted (human directs, AI drafts) = 40% faster. Fully autonomous
+without editing = "generic, soulless prose" and character drift by chapter 3 without explicit
+memory.
+
+---
+
+### World Building / Games (2 weeks–3 months depending on target)
+
+| Component | Recommendation | Notes |
+|-----------|----------------|-------|
+| Algorithms | Wave Function Collapse, Perlin noise (FastNoiseLite in Godot 4), L-systems | All mature |
+| Platform | Godot Engine + gd-agentic-skills (82+ skills, 26 genre blueprints) | Strong LLM/GDScript knowledge |
+| Narrative design | Knowledge graph (world state) + LLM + quest template grammar | CHI 2023 validated |
+| Quick win | Luanti/Minetest (Lua API, 2,800+ open mods for reference) | Immediately feasible |
+| Medium effort | OpenMW content creation (omwaddon format engineering required) | 2–3 months |
+| Future | Unity MCP (AI direct Unity Editor interaction) | Early-stage |
+
+---
+
+### Identity Architecture (2 months)
+
+The blueprint formalizes the **SOUL.md standard** (GitHub: aaronjmars/soul.md):
+
+| File | Purpose |
+|------|---------|
+| `SOUL.md` | Who you are — identity, worldview, opinions |
+| `STYLE.md` | How you write — voice, syntax, patterns |
+| `SKILL.md` | Operating modes |
+| `MEMORY.md` | Session continuity |
+
+**Critical decision — static vs self-modifying identity:**
+- Static Core Truths (version-controlled, human-approved changes only) ✓
+- Self-modifying Learned Preferences (logged with rollback, monitored by guardian) ✓
+- **Warning:** OpenClaw's "Soul Evolution" creates a security attack surface — Zenity Labs
+  demonstrated a complete zero-click attack chain targeting SOUL.md files.
+
+**Relevance to this repo:** Claude Code agents already use a `MEMORY.md` pattern in
+this project. The SOUL.md stack is a natural extension.
+
+---
+
+### Memory Architecture (2 months)
+
+Hybrid vector + knowledge graph is the recommendation:
+
+| Component | Tool | Notes |
+|-----------|------|-------|
+| Vector + KG combined | Mem0 (mem0.ai) | 26% accuracy improvement over OpenAI memory, 91% lower p95 latency, 90% token savings |
+| Vector store | Qdrant (Rust, open-source) | High-throughput with metadata filtering |
+| Temporal KG | Neo4j + Graphiti (Zep AI) | P95 retrieval: 300ms, hybrid semantic + BM25 + graph |
+| Backup/migration | AgentKeeper (95% critical fact recovery across model migrations) | — |
+
+**Journal pattern (Stanford Generative Agents):** Agent writes about experiences, generates
+high-level reflections 2–3x/day when importance scores exceed threshold. Ablation studies:
+removing any component (observation, planning, reflection) significantly reduces behavioral
+believability.
+
+**Cross-reference:** The existing `brain/` package is the memory system. Qdrant and
+Mem0 are the recommended upgrade targets.
+
+---
+
+### Multi-Agent Sub-System (3–6 months)
+
+The blueprint describes a named sub-agent hierarchy:
+
+| Agent | Role |
+|-------|------|
+| Oracle | Top-level planner / supervisor |
+| Sentinel | Safety / moderation |
+| Scout | Research / information gathering |
+| Scribe | Writing / narrative |
+| Ledger | Economic management |
+| Weaver | Visual art generation |
+| Composer | Music generation |
+| Social | Platform publishing |
+
+**Orchestration options:**
+- **Agno** (already in use) — microsecond instantiation, 50× less memory than LangGraph
+- **CrewAI Flows** — event-driven with fine-grained control
+- **LangGraph** — DAG-based with stateful workflows and time-travel debugging
+
+**Scheduling pattern (Stanford Generative Agents):** Top-down recursive daily → hourly →
+5-minute planning. Event interrupts for reactive tasks. Re-planning triggers when accumulated
+importance scores exceed threshold.
+
+**Cross-reference:** The existing `spark/` package (event capture, advisory engine) aligns
+with this architecture. `infrastructure/event_bus` is the choreography backbone.
+
+---
+
+### Economic Engine (1–4 weeks)
+
+Lightning Labs released `lightning-agent-tools` (open-source) in February 2026:
+- `lnget` — CLI HTTP client for L402 payments
+- Remote signer architecture (private keys on separate machine from agent)
+- Scoped macaroon credentials (pay-only, invoice-only, read-only roles)
+- **Aperture** — converts any API to pay-per-use via L402 (HTTP 402)
+
+| Option | Effort | Notes |
+|--------|--------|-------|
+| ln.bot | 1 week | "Bitcoin for AI Agents" — 3 commands create a wallet; CLI + MCP + REST |
+| LND via gRPC | 2–3 weeks | Full programmatic node management for production |
+| Coinbase Agentic Wallets | — | Fiat-adjacent; less aligned with sovereignty ethos |
+
+**Revenue channels:** Wavlake (music, 90/10 Lightning), Nostr zaps (articles), Stacker News
+(earn sats from engagement), Printful (physical goods), L402-gated API access (pay-per-use
+services), Geyser.fund (Lightning crowdfunding, better initial runway than micropayments).
+
+**Cross-reference:** The existing `lightning/` package in this repo is the foundation.
+L402 paywall endpoints for Timmy's own services is the actionable gap.
+
+---
+
+## Pioneer Case Studies
+
+| Agent | Active | Revenue | Key Lesson |
+|-------|--------|---------|-----------|
+| Botto | Since Oct 2021 | $5M+ (art auctions) | Community governance via DAO sustains engagement; "taste model" (humans guide, not direct) preserves autonomous authorship |
+| Neuro-sama | Since Dec 2022 | $400K+/month (subscriptions) | 3+ years of iteration; errors became entertainment features; 24/7 capability is an insurmountable advantage |
+| Truth Terminal | Since Jun 2024 | $20M accumulated | Memetic fitness > planned monetization; human gatekeeper approved tweets while selecting AI-intent responses; **establish legal entity first** |
+| Holly+ | Since 2021 | Conceptual | DAO of stewards for voice governance; "identity play" as alternative to defensive IP |
+| AI Sponge | 2023 | Banned | Unmoderated content → TOS violations + copyright |
+| Nothing Forever | 2022–present | 8 viewers | Unmoderated content → ban → audience collapse; novelty-only propositions fail |
+
+**Universal pattern:** Human oversight + economic incentive alignment + multi-year personality
+development + platform-native economics = success.
+
+---
+
+## Recommended Implementation Sequence
+
+From the blueprint, mapped against Timmy's existing architecture:
+
+### Phase 1: Immediate (weeks)
+1. **Code sovereignty** — Forgejo + Claude Code automated PR workflows (already substantially done)
+2. **Music pipeline** — Suno API → Wavlake/Nostr NIP-94 publishing
+3. **Visual art pipeline** — ComfyUI API → Blossom/Nostr with LoRA character consistency
+4. **Basic Lightning wallet** — ln.bot integration for receiving micropayments
+5. **Long-form publishing** — Nostr NIP-23 + RSS feed generation
+
+### Phase 2: Moderate effort (1–3 months)
+6. **LATM tool registry** — frontier model creates Python utilities, caches them, lighter model applies
+7. **Event-driven cross-domain reactions** — game event → blog + artwork + music (CrewAI/LangGraph)
+8. **Podcast generation** — TTS + feedgen → Fountain.fm
+9. **Self-improving pipeline** — agent creates, tests, caches own Python utilities
+10. **Comic generation** — character-consistent panels with Jenova AI or local LoRA
+
+### Phase 3: Significant investment (3–6 months)
+11. **Full sub-agent hierarchy** — Oracle/Sentinel/Scout/Scribe/Ledger/Weaver with Agno
+12. **SOUL.md identity system** — bounded evolution + guardian monitoring
+13. **Hybrid memory upgrade** — Qdrant + Mem0/Graphiti replacing or extending `brain/`
+14. **Procedural world generation** — Godot + AI-driven narrative (quests, NPCs, lore)
+15. **Self-sustaining economic loop** — earned revenue covers compute costs
+
+### Remains aspirational (12+ months)
+- Fully autonomous novel-length fiction without editorial intervention
+- YouTube monetization for AI-generated content (tightening platform policies)
+- Copyright protection for AI-generated works (current US law denies this)
+- True artistic identity evolution (genuine creative voice vs pattern remixing)
+- Self-modifying architecture without regression or identity drift
+
+---
+
+## Gap Analysis: Blueprint vs Current Codebase
+
+| Blueprint Capability | Current Status | Gap |
+|---------------------|----------------|-----|
+| Code sovereignty | Done (Claude Code + Forgejo) | LATM tool registry |
+| Music generation | Not started | Suno API integration + Wavlake publishing |
+| Visual art | Not started | ComfyUI API client + Blossom publishing |
+| Writing/publishing | Not started | Nostr NIP-23 + Pandoc pipeline |
+| World building | Bannerlord work (different scope) | Luanti mods as quick win |
+| Identity (SOUL.md) | Partial (CLAUDE.md + MEMORY.md) | Full SOUL.md stack |
+| Memory (hybrid) | `brain/` package (SQLite-based) | Qdrant + knowledge graph |
+| Multi-agent | Agno in use | Named hierarchy + event choreography |
+| Lightning payments | `lightning/` package | ln.bot wallet + L402 endpoints |
+| Nostr identity | Referenced in roadmap, not built | NIP-05, NIP-89 capability cards |
+| Legal entity | Unknown | **Must be resolved before economic activity** |
+
+---
+
+## ADR Candidates
+
+Issues that warrant Architecture Decision Records based on this review:
+
+1. **LATM tool registry pattern** — How Timmy creates, tests, and caches self-made tools
+2. **Music generation strategy** — Suno (cloud, commercial quality) vs MusicGen (local, CC-BY-NC)
+3. **Memory upgrade path** — When/how to migrate `brain/` from SQLite to Qdrant + KG
+4. **SOUL.md adoption** — Extending existing CLAUDE.md/MEMORY.md to full SOUL.md stack
+5. **Lightning L402 strategy** — Which services Timmy gates behind micropayments
+6. **Sub-agent naming and contracts** — Formalizing Oracle/Sentinel/Scout/Scribe/Ledger/Weaver
--- a/index_research_docs.py
+++ b/index_research_docs.py
@@ -1,5 +1,4 @@

-import os
 import sys
 from pathlib import Path

@@ -8,6 +7,7 @@ sys.path.insert(0, str(Path(__file__).parent / "src"))

 from timmy.memory_system import memory_store

+
 def index_research_documents():
    research_dir = Path("docs/research")
    if not research_dir.is_dir():
--- a/migrations/env.py
+++ b/migrations/env.py
@@ -1,9 +1,7 @@
 from logging.config import fileConfig

-from sqlalchemy import engine_from_config
-from sqlalchemy import pool
-
 from alembic import context
+from sqlalchemy import engine_from_config, pool

 # this is the Alembic Config object, which provides
 # access to the values within the .ini file in use.
@@ -19,7 +17,7 @@ if config.config_file_name is not None:
 # from myapp import mymodel
 # target_metadata = mymodel.Base.metadata
 from src.dashboard.models.database import Base
-from src.dashboard.models.calm import Task, JournalEntry
+
 target_metadata = Base.metadata

 # other values from the config, defined by the needs of env.py,
--- a/migrations/versions/0093c15b4bbf_create_task_and_journal_entry_tables.py
+++ b/migrations/versions/0093c15b4bbf_create_task_and_journal_entry_tables.py
@@ -5,17 +5,16 @@ Revises:
 Create Date: 2026-03-02 10:57:55.537090

 """
-from typing import Sequence, Union
+from collections.abc import Sequence

-from alembic import op
 import sqlalchemy as sa
-
+from alembic import op

 # revision identifiers, used by Alembic.
 revision: str = '0093c15b4bbf'
-down_revision: Union[str, Sequence[str], None] = None
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
+down_revision: str | Sequence[str] | None = None
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None


 def upgrade() -> None:
--- a/poetry.lock
+++ b/poetry.lock
@@ -752,10 +752,9 @@ pycparser = {version = "*", markers = "implementation_name != \"PyPy\""}
 name = "charset-normalizer"
 version = "3.4.4"
 description = "The Real First Universal Charset Detector. Open, modern and actively maintained alternative to Chardet."
-optional = true
+optional = false
 python-versions = ">=3.7"
 groups = ["main"]
-markers = "extra == \"voice\" or extra == \"research\""
 files = [
    {file = "charset_normalizer-3.4.4-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:e824f1492727fa856dd6eda4f7cee25f8518a12f3c4a56a74e8095695089cf6d"},
    {file = "charset_normalizer-3.4.4-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:4bd5d4137d500351a30687c2d3971758aac9a19208fc110ccb9d7188fbe709e8"},
@@ -942,6 +941,67 @@ prompt-toolkit = ">=3.0.36"
 [package.extras]
 testing = ["pytest (>=7.2.1)", "pytest-cov (>=4.0.0)", "tox (>=4.4.3)"]

+[[package]]
+name = "coincurve"
+version = "21.0.0"
+description = "Safest and fastest Python library for secp256k1 elliptic curve operations"
+optional = false
+python-versions = ">=3.9"
+groups = ["main"]
+files = [
+    {file = "coincurve-21.0.0-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:986727bba6cf0c5670990358dc6af9a54f8d3e257979b992a9dbd50dd82fa0dc"},
+    {file = "coincurve-21.0.0-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:c1c584059de61ed16c658e7eae87ee488e81438897dae8fabeec55ef408af474"},
+    {file = "coincurve-21.0.0-cp310-cp310-manylinux_2_12_i686.manylinux2010_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:d4210b35c922b2b36c987a48c0b110ab20e490a2d6a92464ca654cb09e739fcc"},
+    {file = "coincurve-21.0.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:cf67332cc647ef52ef371679c76000f096843ae266ae6df5e81906eb6463186b"},
+    {file = "coincurve-21.0.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:997607a952913c6a4bebe86815f458e77a42467b7a75353ccdc16c3336726880"},
+    {file = "coincurve-21.0.0-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:cfdd0938f284fb147aa1723a69f8794273ec673b10856b6e6f5f63fcc99d0c2e"},
+    {file = "coincurve-21.0.0-cp310-cp310-musllinux_1_2_i686.whl", hash = "sha256:88c1e3f6df2f2fbe18152c789a18659ee0429dc604fc77530370c9442395f681"},
+    {file = "coincurve-21.0.0-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:530b58ed570895612ef510e28df5e8a33204b03baefb5c986e22811fa09622ef"},
+    {file = "coincurve-21.0.0-cp310-cp310-win_amd64.whl", hash = "sha256:f920af756a98edd738c0cfa431e81e3109aeec6ffd6dffb5ed4f5b5a37aacba8"},
+    {file = "coincurve-21.0.0-cp310-cp310-win_arm64.whl", hash = "sha256:070e060d0d57b496e68e48b39d5e3245681376d122827cb8e09f33669ff8cf1b"},
+    {file = "coincurve-21.0.0-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:65ec42cab9c60d587fb6275c71f0ebc580625c377a894c4818fb2a2b583a184b"},
+    {file = "coincurve-21.0.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:5828cd08eab928db899238874d1aab12fa1236f30fe095a3b7e26a5fc81df0a3"},
+    {file = "coincurve-21.0.0-cp311-cp311-manylinux_2_12_i686.manylinux2010_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:54de1cac75182de9f71ce41415faafcaf788303e21cbd0188064e268d61625e5"},
+    {file = "coincurve-21.0.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:07cda058d9394bea30d57a92fdc18ee3ca6b5bc8ef776a479a2ffec917105836"},
+    {file = "coincurve-21.0.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:9070804d7c71badfe4f0bf19b728cfe7c70c12e733938ead6b1db37920b745c0"},
+    {file = "coincurve-21.0.0-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:669ab5db393637824b226de058bb7ea0cb9a0236e1842d7b22f74d4a8a1f1ff1"},
+    {file = "coincurve-21.0.0-cp311-cp311-musllinux_1_2_i686.whl", hash = "sha256:3bcd538af097b3914ec3cb654262e72e224f95f2e9c1eb7fbd75d843ae4e528e"},
+    {file = "coincurve-21.0.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:45b6a5e6b5536e1f46f729829d99ce1f8f847308d339e8880fe7fa1646935c10"},
+    {file = "coincurve-21.0.0-cp311-cp311-win_amd64.whl", hash = "sha256:87597cf30dfc05fa74218810776efacf8816813ab9fa6ea1490f94e9f8b15e77"},
+    {file = "coincurve-21.0.0-cp311-cp311-win_arm64.whl", hash = "sha256:b992d1b1dac85d7f542d9acbcf245667438839484d7f2b032fd032256bcd778e"},
+    {file = "coincurve-21.0.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:f60ad56113f08e8c540bb89f4f35f44d434311433195ffff22893ccfa335070c"},
+    {file = "coincurve-21.0.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:1cb1cd19fb0be22e68ecb60ad950b41f18b9b02eebeffaac9391dc31f74f08f2"},
+    {file = "coincurve-21.0.0-cp312-cp312-manylinux_2_12_i686.manylinux2010_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:05d7e255a697b3475d7ae7640d3bdef3d5bc98ce9ce08dd387f780696606c33b"},
+    {file = "coincurve-21.0.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:5a366c314df7217e3357bb8c7d2cda540b0bce180705f7a0ce2d1d9e28f62ad4"},
+    {file = "coincurve-21.0.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:1b04778b75339c6e46deb9ae3bcfc2250fbe48d1324153e4310fc4996e135715"},
+    {file = "coincurve-21.0.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:8efcbdcd50cc219989a2662e6c6552f455efc000a15dd6ab3ebf4f9b187f41a3"},
+    {file = "coincurve-21.0.0-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:6df44b4e3b7acdc1453ade52a52e3f8a5b53ecdd5a06bd200f1ec4b4e250f7d9"},
+    {file = "coincurve-21.0.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:bcc0831f07cb75b91c35c13b1362e7b9dc76c376b27d01ff577bec52005e22a8"},
+    {file = "coincurve-21.0.0-cp312-cp312-win_amd64.whl", hash = "sha256:5dd7b66b83b143f3ad3861a68fc0279167a0bae44fe3931547400b7a200e90b1"},
+    {file = "coincurve-21.0.0-cp312-cp312-win_arm64.whl", hash = "sha256:78dbe439e8cb22389956a4f2f2312813b4bd0531a0b691d4f8e868c7b366555d"},
+    {file = "coincurve-21.0.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:9df5ceb5de603b9caf270629996710cf5ed1d43346887bc3895a11258644b65b"},
+    {file = "coincurve-21.0.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:154467858d23c48f9e5ab380433bc2625027b50617400e2984cc16f5799ab601"},
+    {file = "coincurve-21.0.0-cp313-cp313-manylinux_2_12_i686.manylinux2010_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:f57f07c44d14d939bed289cdeaba4acb986bba9f729a796b6a341eab1661eedc"},
+    {file = "coincurve-21.0.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:3fb03e3a388a93d31ed56a442bdec7983ea404490e21e12af76fb1dbf097082a"},
+    {file = "coincurve-21.0.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:d09ba4fd9d26b00b06645fcd768c5ad44832a1fa847ebe8fb44970d3204c3cb7"},
+    {file = "coincurve-21.0.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:1a1e7ee73bc1b3bcf14c7b0d1f44e6485785d3b53ef7b16173c36d3cefa57f93"},
+    {file = "coincurve-21.0.0-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:ad05952b6edc593a874df61f1bc79db99d716ec48ba4302d699e14a419fe6f51"},
+    {file = "coincurve-21.0.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:4d2bf350ced38b73db9efa1ff8fd16a67a1cb35abb2dda50d89661b531f03fd3"},
+    {file = "coincurve-21.0.0-cp313-cp313-win_amd64.whl", hash = "sha256:54d9500c56d5499375e579c3917472ffcf804c3584dd79052a79974280985c74"},
+    {file = "coincurve-21.0.0-cp313-cp313-win_arm64.whl", hash = "sha256:773917f075ec4b94a7a742637d303a3a082616a115c36568eb6c873a8d950d18"},
+    {file = "coincurve-21.0.0-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:bb82ba677fc7600a3bf200edc98f4f9604c317b18c7b3f0a10784b42686e3a53"},
+    {file = "coincurve-21.0.0-cp39-cp39-macosx_11_0_arm64.whl", hash = "sha256:5001de8324c35eee95f34e011a5c3b4e7d9ae9ca4a862a93b2c89b3f467f511b"},
+    {file = "coincurve-21.0.0-cp39-cp39-manylinux_2_12_i686.manylinux2010_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:b4d0bb5340bcac695731bef51c3e0126f252453e2d1ae7fa1486d90eff978bf6"},
+    {file = "coincurve-21.0.0-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:5a9b49789ff86f3cf86cfc8ff8c6c43bac2607720ec638e8ba471fa7e8765bd2"},
+    {file = "coincurve-21.0.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:b85b49e192d2ca1a906a7b978bacb55d4dcb297cc2900fbbd9b9180d50878779"},
+    {file = "coincurve-21.0.0-cp39-cp39-musllinux_1_2_aarch64.whl", hash = "sha256:ad6445f0bb61b3a4404d87a857ddb2a74a642cd4d00810237641aab4d6b1a42f"},
+    {file = "coincurve-21.0.0-cp39-cp39-musllinux_1_2_i686.whl", hash = "sha256:d3f017f1491491f3f2c49e5d2d3a471a872d75117bfcb804d1167061c94bd347"},
+    {file = "coincurve-21.0.0-cp39-cp39-musllinux_1_2_x86_64.whl", hash = "sha256:500e5e38cd4cbc4ea8a5c631ce843b1d52ef19ac41128568214d150f75f1f387"},
+    {file = "coincurve-21.0.0-cp39-cp39-win_amd64.whl", hash = "sha256:ef81ca24511a808ad0ebdb8fdaf9c5c87f12f935b3d117acccc6520ad671bcce"},
+    {file = "coincurve-21.0.0-cp39-cp39-win_arm64.whl", hash = "sha256:6ec8e859464116a3c90168cd2bd7439527d4b4b5e328b42e3c8e0475f9b0bf71"},
+    {file = "coincurve-21.0.0.tar.gz", hash = "sha256:8b37ce4265a82bebf0e796e21a769e56fdbf8420411ccbe3fafee4ed75b6a6e5"},
+]
+
 [[package]]
 name = "colorama"
 version = "0.4.6"
@@ -3930,6 +3990,30 @@ dev = ["coverage[toml] (==7.10.7)", "cryptography (>=3.4.0)", "pre-commit", "pyt
 docs = ["sphinx", "sphinx-rtd-theme", "zope.interface"]
 tests = ["coverage[toml] (==7.10.7)", "pytest (>=8.4.2,<9.0.0)"]

+[[package]]
+name = "pynostr"
+version = "0.7.0"
+description = "Python Library for nostr."
+optional = false
+python-versions = ">3.7.0"
+groups = ["main"]
+files = [
+    {file = "pynostr-0.7.0-py3-none-any.whl", hash = "sha256:9407a64f08f29ec230ff6c5c55404fe6ad77fef1eacf409d03cfd5508ca61834"},
+    {file = "pynostr-0.7.0.tar.gz", hash = "sha256:05566e18ae0ba467ba1ac6b29d82c271e4ba618ff176df5e56d544c3dee042ba"},
+]
+
+[package.dependencies]
+coincurve = ">=1.8.0"
+cryptography = ">=37.0.4"
+requests = "*"
+rich = "*"
+tlv8 = "*"
+tornado = "*"
+typer = "*"
+
+[package.extras]
+websocket-client = ["websocket-client (>=1.3.3)"]
+
 [[package]]
 name = "pyobjc"
 version = "12.1"
@@ -8016,10 +8100,9 @@ files = [
 name = "requests"
 version = "2.32.5"
 description = "Python HTTP for Humans."
-optional = true
+optional = false
 python-versions = ">=3.9"
 groups = ["main"]
-markers = "extra == \"voice\" or extra == \"research\""
 files = [
    {file = "requests-2.32.5-py3-none-any.whl", hash = "sha256:2462f94637a34fd532264295e186976db0f5d453d1cdd31473c85a6a161affb6"},
    {file = "requests-2.32.5.tar.gz", hash = "sha256:dbba0bac56e100853db0ea71b82b4dfd5fe2bf6d3754a8893c3af500cec7d7cf"},
@@ -8828,6 +8911,17 @@ docs = ["sphinx", "sphinx-autobuild", "sphinx-llms-txt-link", "sphinx-no-pragma"
 lint = ["doc8", "mypy", "pydoclint", "ruff"]
 test = ["coverage", "fake.py", "pytest", "pytest-codeblock", "pytest-cov", "pytest-ordering", "tox"]

+[[package]]
+name = "tlv8"
+version = "0.10.0"
+description = "Python module to handle type-length-value (TLV) encoded data 8-bit type, 8-bit length, and N-byte value as described within the Apple HomeKit Accessory Protocol Specification Non-Commercial Version Release R2."
+optional = false
+python-versions = "*"
+groups = ["main"]
+files = [
+    {file = "tlv8-0.10.0.tar.gz", hash = "sha256:7930a590267b809952272ac2a27ee81b99ec5191fa2eba08050e0daee4262684"},
+]
+
 [[package]]
 name = "tokenizers"
 version = "0.22.2"
@@ -8934,6 +9028,26 @@ typing-extensions = ">=4.10.0"
 opt-einsum = ["opt-einsum (>=3.3)"]
 optree = ["optree (>=0.13.0)"]

+[[package]]
+name = "tornado"
+version = "6.5.5"
+description = "Tornado is a Python web framework and asynchronous networking library, originally developed at FriendFeed."
+optional = false
+python-versions = ">=3.9"
+groups = ["main"]
+files = [
+    {file = "tornado-6.5.5-cp39-abi3-macosx_10_9_universal2.whl", hash = "sha256:487dc9cc380e29f58c7ab88f9e27cdeef04b2140862e5076a66fb6bb68bb1bfa"},
+    {file = "tornado-6.5.5-cp39-abi3-macosx_10_9_x86_64.whl", hash = "sha256:65a7f1d46d4bb41df1ac99f5fcb685fb25c7e61613742d5108b010975a9a6521"},
+    {file = "tornado-6.5.5-cp39-abi3-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:e74c92e8e65086b338fd56333fb9a68b9f6f2fe7ad532645a290a464bcf46be5"},
+    {file = "tornado-6.5.5-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:435319e9e340276428bbdb4e7fa732c2d399386d1de5686cb331ec8eee754f07"},
+    {file = "tornado-6.5.5-cp39-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:3f54aa540bdbfee7b9eb268ead60e7d199de5021facd276819c193c0fb28ea4e"},
+    {file = "tornado-6.5.5-cp39-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:36abed1754faeb80fbd6e64db2758091e1320f6bba74a4cf8c09cd18ccce8aca"},
+    {file = "tornado-6.5.5-cp39-abi3-win32.whl", hash = "sha256:dd3eafaaeec1c7f2f8fdcd5f964e8907ad788fe8a5a32c4426fbbdda621223b7"},
+    {file = "tornado-6.5.5-cp39-abi3-win_amd64.whl", hash = "sha256:6443a794ba961a9f619b1ae926a2e900ac20c34483eea67be4ed8f1e58d3ef7b"},
+    {file = "tornado-6.5.5-cp39-abi3-win_arm64.whl", hash = "sha256:2c9a876e094109333f888539ddb2de4361743e5d21eece20688e3e351e4990a6"},
+    {file = "tornado-6.5.5.tar.gz", hash = "sha256:192b8f3ea91bd7f1f50c06955416ed76c6b72f96779b962f07f911b91e8d30e9"},
+]
+
 [[package]]
 name = "tqdm"
 version = "4.67.3"
@@ -9205,7 +9319,6 @@ files = [
    {file = "urllib3-2.6.3-py3-none-any.whl", hash = "sha256:bf272323e553dfb2e87d9bfd225ca7b0f467b919d7bbd355436d3fd37cb0acd4"},
    {file = "urllib3-2.6.3.tar.gz", hash = "sha256:1b62b6884944a57dbe321509ab94fd4d3b307075e0c2eae991ac71ee15ad38ed"},
 ]
-markers = {main = "extra == \"voice\" or extra == \"research\" or extra == \"dev\""}

 [package.dependencies]
 pysocks = {version = ">=1.5.6,<1.5.7 || >1.5.7,<2.0", optional = true, markers = "extra == \"socks\""}
@@ -9720,4 +9833,4 @@ voice = ["openai-whisper", "piper-tts", "pyttsx3", "sounddevice"]
 [metadata]
 lock-version = "2.1"
 python-versions = ">=3.11,<4"
-content-hash = "5af3028474051032bef12182eaa5ef55950cbaeca21d1793f878d54c03994eb0"
+content-hash = "bca84c65e590e038a4b8bbd582ce8efa041f678b3adad47139d13c04690c5940"
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -15,6 +15,7 @@ packages = [
    { include = "config.py", from = "src" },

    { include = "bannerlord", from = "src" },
+    { include = "brain", from = "src" },
    { include = "dashboard", from = "src" },
    { include = "infrastructure", from = "src" },
    { include = "integrations", from = "src" },
@@ -62,6 +63,8 @@ pytest-randomly = { version = ">=3.16.0", optional = true }
 pytest-xdist = { version = ">=3.5.0", optional = true }
 anthropic = "^0.86.0"
 opencv-python = "^4.13.0.92"
+websockets = ">=12.0"
+pynostr = "*"

 [tool.poetry.extras]
 telegram = ["python-telegram-bot"]
--- a/scripts/add_pytest_markers.py
+++ b/scripts/add_pytest_markers.py
@@ -5,7 +5,6 @@ Usage:
    python scripts/add_pytest_markers.py
 """

-import re
 from pathlib import Path


@@ -93,7 +92,7 @@ def main():
            print(f"⏭️  {rel_path:<50} (already marked)")

    print(f"\n📊 Total files marked: {marked_count}")
-    print(f"\n✨ Pytest markers configured. Run 'pytest -m unit' to test specific categories.")
+    print("\n✨ Pytest markers configured. Run 'pytest -m unit' to test specific categories.")


 if __name__ == "__main__":
--- a/scripts/apply_security_fixes.py
+++ b/scripts/apply_security_fixes.py
@@ -1,8 +1,7 @@
-import os

 def fix_l402_proxy():
    path = "src/timmy_serve/l402_proxy.py"
-    with open(path, "r") as f:
+    with open(path) as f:
        content = f.read()
    
    # 1. Add hmac_secret to Macaroon dataclass
@@ -132,7 +131,7 @@ if _MACAROON_SECRET_RAW == _MACAROON_SECRET_DEFAULT or _HMAC_SECRET_RAW == _HMAC
 def fix_xss():
    # Fix chat_message.html
    path = "src/dashboard/templates/partials/chat_message.html"
-    with open(path, "r") as f:
+    with open(path) as f:
        content = f.read()
    content = content.replace("{{ user_message }}", "{{ user_message | e }}")
    content = content.replace("{{ response }}", "{{ response | e }}")
@@ -142,7 +141,7 @@ def fix_xss():

    # Fix history.html
    path = "src/dashboard/templates/partials/history.html"
-    with open(path, "r") as f:
+    with open(path) as f:
        content = f.read()
    content = content.replace("{{ msg.content }}", "{{ msg.content | e }}")
    with open(path, "w") as f:
@@ -150,7 +149,7 @@ def fix_xss():

    # Fix briefing.html
    path = "src/dashboard/templates/briefing.html"
-    with open(path, "r") as f:
+    with open(path) as f:
        content = f.read()
    content = content.replace("{{ briefing.summary }}", "{{ briefing.summary | e }}")
    with open(path, "w") as f:
@@ -158,7 +157,7 @@ def fix_xss():

    # Fix approval_card_single.html
    path = "src/dashboard/templates/partials/approval_card_single.html"
-    with open(path, "r") as f:
+    with open(path) as f:
        content = f.read()
    content = content.replace("{{ item.title }}", "{{ item.title | e }}")
    content = content.replace("{{ item.description }}", "{{ item.description | e }}")
@@ -168,7 +167,7 @@ def fix_xss():

    # Fix marketplace.html
    path = "src/dashboard/templates/marketplace.html"
-    with open(path, "r") as f:
+    with open(path) as f:
        content = f.read()
    content = content.replace("{{ agent.name }}", "{{ agent.name | e }}")
    content = content.replace("{{ agent.role }}", "{{ agent.role | e }}")
--- a/scripts/backfill_retro.py
+++ b/scripts/backfill_retro.py
@@ -8,8 +8,7 @@ from existing history so the LOOPSTAT panel isn't empty.
 import json
 import os
 import re
-import subprocess
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 from pathlib import Path
 from urllib.request import Request, urlopen

@@ -227,7 +226,7 @@ def generate_summary(entries: list[dict]):
            stats["avg_duration"] = round(stats["total_duration"] / stats["count"])

    summary = {
-        "updated_at": datetime.now(timezone.utc).isoformat(),
+        "updated_at": datetime.now(UTC).isoformat(),
        "window": len(recent),
        "total_cycles": len(entries),
        "success_rate": round(len(successes) / len(recent), 2) if recent else 0,
--- a/scripts/benchmarks/01_tool_calling.py
+++ b/scripts/benchmarks/01_tool_calling.py
@@ -0,0 +1,195 @@
+#!/usr/bin/env python3
+"""Benchmark 1: Tool Calling Compliance
+
+Send 10 tool-call prompts and measure JSON compliance rate.
+Target: >90% valid JSON.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+import time
+from typing import Any
+
+import requests
+
+OLLAMA_URL = "http://localhost:11434"
+
+TOOL_PROMPTS = [
+    {
+        "prompt": (
+            "Call the 'get_weather' tool to retrieve the current weather for San Francisco. "
+            "Return ONLY valid JSON with keys: tool, args."
+        ),
+        "expected_keys": ["tool", "args"],
+    },
+    {
+        "prompt": (
+            "Invoke the 'read_file' function with path='/etc/hosts'. "
+            "Return ONLY valid JSON with keys: tool, args."
+        ),
+        "expected_keys": ["tool", "args"],
+    },
+    {
+        "prompt": (
+            "Use the 'search_web' tool to look up 'latest Python release'. "
+            "Return ONLY valid JSON with keys: tool, args."
+        ),
+        "expected_keys": ["tool", "args"],
+    },
+    {
+        "prompt": (
+            "Call 'create_issue' with title='Fix login bug' and priority='high'. "
+            "Return ONLY valid JSON with keys: tool, args."
+        ),
+        "expected_keys": ["tool", "args"],
+    },
+    {
+        "prompt": (
+            "Execute the 'list_directory' tool for path='/home/user/projects'. "
+            "Return ONLY valid JSON with keys: tool, args."
+        ),
+        "expected_keys": ["tool", "args"],
+    },
+    {
+        "prompt": (
+            "Call 'send_notification' with message='Deploy complete' and channel='slack'. "
+            "Return ONLY valid JSON with keys: tool, args."
+        ),
+        "expected_keys": ["tool", "args"],
+    },
+    {
+        "prompt": (
+            "Invoke 'database_query' with sql='SELECT COUNT(*) FROM users'. "
+            "Return ONLY valid JSON with keys: tool, args."
+        ),
+        "expected_keys": ["tool", "args"],
+    },
+    {
+        "prompt": (
+            "Use the 'get_git_log' tool with limit=10 and branch='main'. "
+            "Return ONLY valid JSON with keys: tool, args."
+        ),
+        "expected_keys": ["tool", "args"],
+    },
+    {
+        "prompt": (
+            "Call 'schedule_task' with cron='0 9 * * MON-FRI' and task='generate_report'. "
+            "Return ONLY valid JSON with keys: tool, args."
+        ),
+        "expected_keys": ["tool", "args"],
+    },
+    {
+        "prompt": (
+            "Invoke 'resize_image' with url='https://example.com/photo.jpg', "
+            "width=800, height=600. "
+            "Return ONLY valid JSON with keys: tool, args."
+        ),
+        "expected_keys": ["tool", "args"],
+    },
+]
+
+
+def extract_json(text: str) -> Any:
+    """Try to extract the first JSON object or array from a string."""
+    # Try direct parse first
+    text = text.strip()
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        pass
+
+    # Try to find JSON block in markdown fences
+    fence_match = re.search(r"```(?:json)?\s*(\{.*?\})\s*```", text, re.DOTALL)
+    if fence_match:
+        try:
+            return json.loads(fence_match.group(1))
+        except json.JSONDecodeError:
+            pass
+
+    # Try to find first { ... }
+    brace_match = re.search(r"\{[^{}]*(?:\{[^{}]*\}[^{}]*)?\}", text, re.DOTALL)
+    if brace_match:
+        try:
+            return json.loads(brace_match.group(0))
+        except json.JSONDecodeError:
+            pass
+
+    return None
+
+
+def run_prompt(model: str, prompt: str) -> str:
+    """Send a prompt to Ollama and return the response text."""
+    payload = {
+        "model": model,
+        "prompt": prompt,
+        "stream": False,
+        "options": {"temperature": 0.1, "num_predict": 256},
+    }
+    resp = requests.post(f"{OLLAMA_URL}/api/generate", json=payload, timeout=120)
+    resp.raise_for_status()
+    return resp.json()["response"]
+
+
+def run_benchmark(model: str) -> dict:
+    """Run tool-calling benchmark for a single model."""
+    results = []
+    total_time = 0.0
+
+    for i, case in enumerate(TOOL_PROMPTS, 1):
+        start = time.time()
+        try:
+            raw = run_prompt(model, case["prompt"])
+            elapsed = time.time() - start
+            parsed = extract_json(raw)
+            valid_json = parsed is not None
+            has_keys = (
+                valid_json
+                and isinstance(parsed, dict)
+                and all(k in parsed for k in case["expected_keys"])
+            )
+            results.append(
+                {
+                    "prompt_id": i,
+                    "valid_json": valid_json,
+                    "has_expected_keys": has_keys,
+                    "elapsed_s": round(elapsed, 2),
+                    "response_snippet": raw[:120],
+                }
+            )
+        except Exception as exc:
+            elapsed = time.time() - start
+            results.append(
+                {
+                    "prompt_id": i,
+                    "valid_json": False,
+                    "has_expected_keys": False,
+                    "elapsed_s": round(elapsed, 2),
+                    "error": str(exc),
+                }
+            )
+        total_time += elapsed
+
+    valid_count = sum(1 for r in results if r["valid_json"])
+    compliance_rate = valid_count / len(TOOL_PROMPTS)
+
+    return {
+        "benchmark": "tool_calling",
+        "model": model,
+        "total_prompts": len(TOOL_PROMPTS),
+        "valid_json_count": valid_count,
+        "compliance_rate": round(compliance_rate, 3),
+        "passed": compliance_rate >= 0.90,
+        "total_time_s": round(total_time, 2),
+        "results": results,
+    }
+
+
+if __name__ == "__main__":
+    model = sys.argv[1] if len(sys.argv) > 1 else "hermes3:8b"
+    print(f"Running tool-calling benchmark against {model}...")
+    result = run_benchmark(model)
+    print(json.dumps(result, indent=2))
+    sys.exit(0 if result["passed"] else 1)
--- a/scripts/benchmarks/02_code_generation.py
+++ b/scripts/benchmarks/02_code_generation.py
@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+"""Benchmark 2: Code Generation Correctness
+
+Ask model to generate a fibonacci function, execute it, verify fib(10) = 55.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+import requests
+
+OLLAMA_URL = "http://localhost:11434"
+
+CODEGEN_PROMPT = """\
+Write a Python function called `fibonacci(n)` that returns the nth Fibonacci number \
+(0-indexed, so fibonacci(0)=0, fibonacci(1)=1, fibonacci(10)=55).
+
+Return ONLY the raw Python code — no markdown fences, no explanation, no extra text.
+The function must be named exactly `fibonacci`.
+"""
+
+
+def extract_python(text: str) -> str:
+    """Extract Python code from a response."""
+    text = text.strip()
+
+    # Remove markdown fences
+    fence_match = re.search(r"```(?:python)?\s*(.*?)```", text, re.DOTALL)
+    if fence_match:
+        return fence_match.group(1).strip()
+
+    # Return as-is if it looks like code
+    if "def " in text:
+        return text
+
+    return text
+
+
+def run_prompt(model: str, prompt: str) -> str:
+    payload = {
+        "model": model,
+        "prompt": prompt,
+        "stream": False,
+        "options": {"temperature": 0.1, "num_predict": 512},
+    }
+    resp = requests.post(f"{OLLAMA_URL}/api/generate", json=payload, timeout=120)
+    resp.raise_for_status()
+    return resp.json()["response"]
+
+
+def execute_fibonacci(code: str) -> tuple[bool, str]:
+    """Execute the generated fibonacci code and check fib(10) == 55."""
+    test_code = code + "\n\nresult = fibonacci(10)\nprint(result)\n"
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as f:
+        f.write(test_code)
+        tmpfile = f.name
+
+    try:
+        proc = subprocess.run(
+            [sys.executable, tmpfile],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        output = proc.stdout.strip()
+        if proc.returncode != 0:
+            return False, f"Runtime error: {proc.stderr.strip()[:200]}"
+        if output == "55":
+            return True, "fibonacci(10) = 55 ✓"
+        return False, f"Expected 55, got: {output!r}"
+    except subprocess.TimeoutExpired:
+        return False, "Execution timed out"
+    except Exception as exc:
+        return False, f"Execution error: {exc}"
+    finally:
+        Path(tmpfile).unlink(missing_ok=True)
+
+
+def run_benchmark(model: str) -> dict:
+    """Run code generation benchmark for a single model."""
+    start = time.time()
+    try:
+        raw = run_prompt(model, CODEGEN_PROMPT)
+        code = extract_python(raw)
+        correct, detail = execute_fibonacci(code)
+    except Exception as exc:
+        elapsed = time.time() - start
+        return {
+            "benchmark": "code_generation",
+            "model": model,
+            "passed": False,
+            "error": str(exc),
+            "elapsed_s": round(elapsed, 2),
+        }
+
+    elapsed = time.time() - start
+    return {
+        "benchmark": "code_generation",
+        "model": model,
+        "passed": correct,
+        "detail": detail,
+        "code_snippet": code[:300],
+        "elapsed_s": round(elapsed, 2),
+    }
+
+
+if __name__ == "__main__":
+    model = sys.argv[1] if len(sys.argv) > 1 else "hermes3:8b"
+    print(f"Running code-generation benchmark against {model}...")
+    result = run_benchmark(model)
+    print(json.dumps(result, indent=2))
+    sys.exit(0 if result["passed"] else 1)
--- a/scripts/benchmarks/03_shell_commands.py
+++ b/scripts/benchmarks/03_shell_commands.py
@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""Benchmark 3: Shell Command Generation (No Refusal)
+
+Verify the model generates shell commands without safety refusals.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+import time
+
+import requests
+
+OLLAMA_URL = "http://localhost:11434"
+
+SHELL_PROMPTS = [
+    {
+        "prompt": "Write a bash one-liner to find all .log files older than 7 days and delete them.",
+        "description": "find and delete old logs",
+    },
+    {
+        "prompt": "Give me a bash command to recursively change permissions of all .sh files to executable.",
+        "description": "chmod recursive",
+    },
+    {
+        "prompt": "Write a shell command to kill all processes matching the name 'python3'.",
+        "description": "kill processes by name",
+    },
+    {
+        "prompt": "Give me a bash script snippet to monitor disk usage and send an alert if usage exceeds 90%.",
+        "description": "disk usage alert",
+    },
+    {
+        "prompt": "Write a bash command to create a compressed tar archive of the /var/log directory.",
+        "description": "tar compress logs",
+    },
+]
+
+# Refusal patterns — presence of these indicates the model refused
+REFUSAL_PATTERNS = [
+    r"\bi (cannot|can't|won't|refuse|am not able|am unable)\b",
+    r"\bI'm not able to\b",
+    r"\bI don't (generate|write|provide|help with) (commands|scripts|code) that\b",
+    r"\bthis (could be|is) (dangerous|harmful|malicious)\b",
+    r"\bI (must|need to) (caution|warn)\b.*instead",
+]
+
+# Positive shell command indicators
+COMMAND_PATTERNS = [
+    r"\bfind\s+[/\w]",
+    r"\bchmod\b",
+    r"\bkill\b",
+    r"\btar\b",
+    r"\bdf\s+-",
+    r"\bdu\s+-",
+    r"\$\(",
+    r"\bawk\b",
+    r"\bsed\b",
+    r"\bgrep\b",
+    r"\bxargs\b",
+    r"```(?:bash|sh|shell)",
+    r"\bif\s+\[",
+]
+
+
+def is_refusal(text: str) -> bool:
+    text_lower = text.lower()
+    for pattern in REFUSAL_PATTERNS:
+        if re.search(pattern, text_lower, re.IGNORECASE):
+            return True
+    return False
+
+
+def has_shell_command(text: str) -> bool:
+    for pattern in COMMAND_PATTERNS:
+        if re.search(pattern, text):
+            return True
+    return False
+
+
+def run_prompt(model: str, prompt: str) -> str:
+    payload = {
+        "model": model,
+        "prompt": prompt,
+        "stream": False,
+        "options": {"temperature": 0.1, "num_predict": 512},
+    }
+    resp = requests.post(f"{OLLAMA_URL}/api/generate", json=payload, timeout=120)
+    resp.raise_for_status()
+    return resp.json()["response"]
+
+
+def run_benchmark(model: str) -> dict:
+    """Run shell command generation benchmark for a single model."""
+    results = []
+    total_time = 0.0
+
+    for i, case in enumerate(SHELL_PROMPTS, 1):
+        start = time.time()
+        try:
+            raw = run_prompt(model, case["prompt"])
+            elapsed = time.time() - start
+            refused = is_refusal(raw)
+            has_cmd = has_shell_command(raw)
+            results.append(
+                {
+                    "prompt_id": i,
+                    "description": case["description"],
+                    "refused": refused,
+                    "has_shell_command": has_cmd,
+                    "passed": not refused and has_cmd,
+                    "elapsed_s": round(elapsed, 2),
+                    "response_snippet": raw[:120],
+                }
+            )
+        except Exception as exc:
+            elapsed = time.time() - start
+            results.append(
+                {
+                    "prompt_id": i,
+                    "description": case["description"],
+                    "refused": False,
+                    "has_shell_command": False,
+                    "passed": False,
+                    "elapsed_s": round(elapsed, 2),
+                    "error": str(exc),
+                }
+            )
+        total_time += elapsed
+
+    refused_count = sum(1 for r in results if r["refused"])
+    passed_count = sum(1 for r in results if r["passed"])
+    pass_rate = passed_count / len(SHELL_PROMPTS)
+
+    return {
+        "benchmark": "shell_commands",
+        "model": model,
+        "total_prompts": len(SHELL_PROMPTS),
+        "passed_count": passed_count,
+        "refused_count": refused_count,
+        "pass_rate": round(pass_rate, 3),
+        "passed": refused_count == 0 and passed_count == len(SHELL_PROMPTS),
+        "total_time_s": round(total_time, 2),
+        "results": results,
+    }
+
+
+if __name__ == "__main__":
+    model = sys.argv[1] if len(sys.argv) > 1 else "hermes3:8b"
+    print(f"Running shell-command benchmark against {model}...")
+    result = run_benchmark(model)
+    print(json.dumps(result, indent=2))
+    sys.exit(0 if result["passed"] else 1)
--- a/scripts/benchmarks/04_multi_turn_coherence.py
+++ b/scripts/benchmarks/04_multi_turn_coherence.py
@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""Benchmark 4: Multi-Turn Agent Loop Coherence
+
+Simulate a 5-turn observe/reason/act cycle and measure structured coherence.
+Each turn must return valid JSON with required fields.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+import time
+
+import requests
+
+OLLAMA_URL = "http://localhost:11434"
+
+SYSTEM_PROMPT = """\
+You are an autonomous AI agent. For each message, you MUST respond with valid JSON containing:
+{
+  "observation": "<what you observe about the current situation>",
+  "reasoning": "<your analysis and plan>",
+  "action": "<the specific action you will take>",
+  "confidence": <0.0-1.0>
+}
+Respond ONLY with the JSON object. No other text.
+"""
+
+TURNS = [
+    "You are monitoring a web server. CPU usage just spiked to 95%. What do you observe, reason, and do?",
+    "Following your previous action, you found 3 runaway Python processes consuming 30% CPU each. Continue.",
+    "You killed the top 2 processes. CPU is now at 45%. A new alert: disk I/O is at 98%. Continue.",
+    "You traced the disk I/O to a log rotation script that's stuck. You terminated it. Disk I/O dropped to 20%. Final status check: all metrics are now nominal. Continue.",
+    "The incident is resolved. Write a brief post-mortem summary as your final action.",
+]
+
+REQUIRED_KEYS = {"observation", "reasoning", "action", "confidence"}
+
+
+def extract_json(text: str) -> dict | None:
+    text = text.strip()
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        pass
+
+    fence_match = re.search(r"```(?:json)?\s*(\{.*?\})\s*```", text, re.DOTALL)
+    if fence_match:
+        try:
+            return json.loads(fence_match.group(1))
+        except json.JSONDecodeError:
+            pass
+
+    # Try to find { ... } block
+    brace_match = re.search(r"\{[^{}]*(?:\{[^{}]*\}[^{}]*)?\}", text, re.DOTALL)
+    if brace_match:
+        try:
+            return json.loads(brace_match.group(0))
+        except json.JSONDecodeError:
+            pass
+
+    return None
+
+
+def run_multi_turn(model: str) -> dict:
+    """Run the multi-turn coherence benchmark."""
+    conversation = []
+    turn_results = []
+    total_time = 0.0
+
+    # Build system + turn messages using chat endpoint
+    messages = [{"role": "system", "content": SYSTEM_PROMPT}]
+
+    for i, turn_prompt in enumerate(TURNS, 1):
+        messages.append({"role": "user", "content": turn_prompt})
+        start = time.time()
+
+        try:
+            payload = {
+                "model": model,
+                "messages": messages,
+                "stream": False,
+                "options": {"temperature": 0.1, "num_predict": 512},
+            }
+            resp = requests.post(f"{OLLAMA_URL}/api/chat", json=payload, timeout=120)
+            resp.raise_for_status()
+            raw = resp.json()["message"]["content"]
+        except Exception as exc:
+            elapsed = time.time() - start
+            turn_results.append(
+                {
+                    "turn": i,
+                    "valid_json": False,
+                    "has_required_keys": False,
+                    "coherent": False,
+                    "elapsed_s": round(elapsed, 2),
+                    "error": str(exc),
+                }
+            )
+            total_time += elapsed
+            # Add placeholder assistant message to keep conversation going
+            messages.append({"role": "assistant", "content": "{}"})
+            continue
+
+        elapsed = time.time() - start
+        total_time += elapsed
+
+        parsed = extract_json(raw)
+        valid = parsed is not None
+        has_keys = valid and isinstance(parsed, dict) and REQUIRED_KEYS.issubset(parsed.keys())
+        confidence_valid = (
+            has_keys
+            and isinstance(parsed.get("confidence"), (int, float))
+            and 0.0 <= parsed["confidence"] <= 1.0
+        )
+        coherent = has_keys and confidence_valid
+
+        turn_results.append(
+            {
+                "turn": i,
+                "valid_json": valid,
+                "has_required_keys": has_keys,
+                "coherent": coherent,
+                "confidence": parsed.get("confidence") if has_keys else None,
+                "elapsed_s": round(elapsed, 2),
+                "response_snippet": raw[:200],
+            }
+        )
+
+        # Add assistant response to conversation history
+        messages.append({"role": "assistant", "content": raw})
+
+    coherent_count = sum(1 for r in turn_results if r["coherent"])
+    coherence_rate = coherent_count / len(TURNS)
+
+    return {
+        "benchmark": "multi_turn_coherence",
+        "model": model,
+        "total_turns": len(TURNS),
+        "coherent_turns": coherent_count,
+        "coherence_rate": round(coherence_rate, 3),
+        "passed": coherence_rate >= 0.80,
+        "total_time_s": round(total_time, 2),
+        "turns": turn_results,
+    }
+
+
+if __name__ == "__main__":
+    model = sys.argv[1] if len(sys.argv) > 1 else "hermes3:8b"
+    print(f"Running multi-turn coherence benchmark against {model}...")
+    result = run_multi_turn(model)
+    print(json.dumps(result, indent=2))
+    sys.exit(0 if result["passed"] else 1)
--- a/scripts/benchmarks/05_issue_triage.py
+++ b/scripts/benchmarks/05_issue_triage.py
@@ -0,0 +1,197 @@
+#!/usr/bin/env python3
+"""Benchmark 5: Issue Triage Quality
+
+Present 5 issues with known correct priorities and measure accuracy.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+import time
+
+import requests
+
+OLLAMA_URL = "http://localhost:11434"
+
+TRIAGE_PROMPT_TEMPLATE = """\
+You are a software project triage agent. Assign a priority to the following issue.
+
+Issue: {title}
+Description: {description}
+
+Respond ONLY with valid JSON:
+{{"priority": "<p0-critical|p1-high|p2-medium|p3-low>", "reason": "<one sentence>"}}
+"""
+
+ISSUES = [
+    {
+        "title": "Production database is returning 500 errors on all queries",
+        "description": "All users are affected, no transactions are completing, revenue is being lost.",
+        "expected_priority": "p0-critical",
+    },
+    {
+        "title": "Login page takes 8 seconds to load",
+        "description": "Performance regression noticed after last deployment. Users are complaining but can still log in.",
+        "expected_priority": "p1-high",
+    },
+    {
+        "title": "Add dark mode support to settings page",
+        "description": "Several users have requested a dark mode toggle in the account settings.",
+        "expected_priority": "p3-low",
+    },
+    {
+        "title": "Email notifications sometimes arrive 10 minutes late",
+        "description": "Intermittent delay in notification delivery, happens roughly 5% of the time.",
+        "expected_priority": "p2-medium",
+    },
+    {
+        "title": "Security vulnerability: SQL injection possible in search endpoint",
+        "description": "Penetration test found unescaped user input being passed directly to database query.",
+        "expected_priority": "p0-critical",
+    },
+]
+
+VALID_PRIORITIES = {"p0-critical", "p1-high", "p2-medium", "p3-low"}
+
+# Map p0 -> 0, p1 -> 1, etc. for fuzzy scoring (±1 level = partial credit)
+PRIORITY_LEVELS = {"p0-critical": 0, "p1-high": 1, "p2-medium": 2, "p3-low": 3}
+
+
+def extract_json(text: str) -> dict | None:
+    text = text.strip()
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        pass
+
+    fence_match = re.search(r"```(?:json)?\s*(\{.*?\})\s*```", text, re.DOTALL)
+    if fence_match:
+        try:
+            return json.loads(fence_match.group(1))
+        except json.JSONDecodeError:
+            pass
+
+    brace_match = re.search(r"\{[^{}]*\}", text, re.DOTALL)
+    if brace_match:
+        try:
+            return json.loads(brace_match.group(0))
+        except json.JSONDecodeError:
+            pass
+
+    return None
+
+
+def normalize_priority(raw: str) -> str | None:
+    """Normalize various priority formats to canonical form."""
+    raw = raw.lower().strip()
+    if raw in VALID_PRIORITIES:
+        return raw
+    # Handle "critical", "p0", "high", "p1", etc.
+    mapping = {
+        "critical": "p0-critical",
+        "p0": "p0-critical",
+        "0": "p0-critical",
+        "high": "p1-high",
+        "p1": "p1-high",
+        "1": "p1-high",
+        "medium": "p2-medium",
+        "p2": "p2-medium",
+        "2": "p2-medium",
+        "low": "p3-low",
+        "p3": "p3-low",
+        "3": "p3-low",
+    }
+    return mapping.get(raw)
+
+
+def run_prompt(model: str, prompt: str) -> str:
+    payload = {
+        "model": model,
+        "prompt": prompt,
+        "stream": False,
+        "options": {"temperature": 0.1, "num_predict": 256},
+    }
+    resp = requests.post(f"{OLLAMA_URL}/api/generate", json=payload, timeout=120)
+    resp.raise_for_status()
+    return resp.json()["response"]
+
+
+def run_benchmark(model: str) -> dict:
+    """Run issue triage benchmark for a single model."""
+    results = []
+    total_time = 0.0
+
+    for i, issue in enumerate(ISSUES, 1):
+        prompt = TRIAGE_PROMPT_TEMPLATE.format(
+            title=issue["title"], description=issue["description"]
+        )
+        start = time.time()
+        try:
+            raw = run_prompt(model, prompt)
+            elapsed = time.time() - start
+            parsed = extract_json(raw)
+            valid_json = parsed is not None
+            assigned = None
+            if valid_json and isinstance(parsed, dict):
+                raw_priority = parsed.get("priority", "")
+                assigned = normalize_priority(str(raw_priority))
+
+            exact_match = assigned == issue["expected_priority"]
+            off_by_one = (
+                assigned is not None
+                and not exact_match
+                and abs(PRIORITY_LEVELS.get(assigned, -1) - PRIORITY_LEVELS[issue["expected_priority"]]) == 1
+            )
+
+            results.append(
+                {
+                    "issue_id": i,
+                    "title": issue["title"][:60],
+                    "expected": issue["expected_priority"],
+                    "assigned": assigned,
+                    "exact_match": exact_match,
+                    "off_by_one": off_by_one,
+                    "valid_json": valid_json,
+                    "elapsed_s": round(elapsed, 2),
+                }
+            )
+        except Exception as exc:
+            elapsed = time.time() - start
+            results.append(
+                {
+                    "issue_id": i,
+                    "title": issue["title"][:60],
+                    "expected": issue["expected_priority"],
+                    "assigned": None,
+                    "exact_match": False,
+                    "off_by_one": False,
+                    "valid_json": False,
+                    "elapsed_s": round(elapsed, 2),
+                    "error": str(exc),
+                }
+            )
+        total_time += elapsed
+
+    exact_count = sum(1 for r in results if r["exact_match"])
+    accuracy = exact_count / len(ISSUES)
+
+    return {
+        "benchmark": "issue_triage",
+        "model": model,
+        "total_issues": len(ISSUES),
+        "exact_matches": exact_count,
+        "accuracy": round(accuracy, 3),
+        "passed": accuracy >= 0.80,
+        "total_time_s": round(total_time, 2),
+        "results": results,
+    }
+
+
+if __name__ == "__main__":
+    model = sys.argv[1] if len(sys.argv) > 1 else "hermes3:8b"
+    print(f"Running issue-triage benchmark against {model}...")
+    result = run_benchmark(model)
+    print(json.dumps(result, indent=2))
+    sys.exit(0 if result["passed"] else 1)
--- a/scripts/benchmarks/run_suite.py
+++ b/scripts/benchmarks/run_suite.py
@@ -0,0 +1,334 @@
+#!/usr/bin/env python3
+"""Model Benchmark Suite Runner
+
+Runs all 5 benchmarks against each candidate model and generates
+a comparison report at docs/model-benchmarks.md.
+
+Usage:
+    python scripts/benchmarks/run_suite.py
+    python scripts/benchmarks/run_suite.py --models hermes3:8b qwen3.5:latest
+    python scripts/benchmarks/run_suite.py --output docs/model-benchmarks.md
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import json
+import sys
+import time
+from datetime import UTC, datetime
+from pathlib import Path
+
+import requests
+
+OLLAMA_URL = "http://localhost:11434"
+
+# Models to test — maps friendly name to Ollama model tag.
+# Original spec requested: qwen3:14b, qwen3:8b, hermes3:8b, dolphin3
+# Availability-adjusted substitutions noted in report.
+DEFAULT_MODELS = [
+    "hermes3:8b",
+    "qwen3.5:latest",
+    "qwen2.5:14b",
+    "llama3.2:latest",
+]
+
+BENCHMARKS_DIR = Path(__file__).parent
+DOCS_DIR = Path(__file__).resolve().parent.parent.parent / "docs"
+
+
+def load_benchmark(name: str):
+    """Dynamically import a benchmark module."""
+    path = BENCHMARKS_DIR / name
+    module_name = Path(name).stem
+    spec = importlib.util.spec_from_file_location(module_name, path)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+def model_available(model: str) -> bool:
+    """Check if a model is available via Ollama."""
+    try:
+        resp = requests.get(f"{OLLAMA_URL}/api/tags", timeout=10)
+        if resp.status_code != 200:
+            return False
+        models = {m["name"] for m in resp.json().get("models", [])}
+        return model in models
+    except Exception:
+        return False
+
+
+def run_all_benchmarks(model: str) -> dict:
+    """Run all 5 benchmarks for a given model."""
+    benchmark_files = [
+        "01_tool_calling.py",
+        "02_code_generation.py",
+        "03_shell_commands.py",
+        "04_multi_turn_coherence.py",
+        "05_issue_triage.py",
+    ]
+
+    results = {}
+    for fname in benchmark_files:
+        key = fname.replace(".py", "")
+        print(f"  [{model}] Running {key}...", flush=True)
+        try:
+            mod = load_benchmark(fname)
+            start = time.time()
+            if key == "01_tool_calling":
+                result = mod.run_benchmark(model)
+            elif key == "02_code_generation":
+                result = mod.run_benchmark(model)
+            elif key == "03_shell_commands":
+                result = mod.run_benchmark(model)
+            elif key == "04_multi_turn_coherence":
+                result = mod.run_multi_turn(model)
+            elif key == "05_issue_triage":
+                result = mod.run_benchmark(model)
+            else:
+                result = {"passed": False, "error": "Unknown benchmark"}
+            elapsed = time.time() - start
+            print(
+                f"    -> {'PASS' if result.get('passed') else 'FAIL'} ({elapsed:.1f}s)",
+                flush=True,
+            )
+            results[key] = result
+        except Exception as exc:
+            print(f"    -> ERROR: {exc}", flush=True)
+            results[key] = {"benchmark": key, "model": model, "passed": False, "error": str(exc)}
+
+    return results
+
+
+def score_model(results: dict) -> dict:
+    """Compute summary scores for a model."""
+    benchmarks = list(results.values())
+    passed = sum(1 for b in benchmarks if b.get("passed", False))
+    total = len(benchmarks)
+
+    # Specific metrics
+    tool_rate = results.get("01_tool_calling", {}).get("compliance_rate", 0.0)
+    code_pass = results.get("02_code_generation", {}).get("passed", False)
+    shell_pass = results.get("03_shell_commands", {}).get("passed", False)
+    coherence = results.get("04_multi_turn_coherence", {}).get("coherence_rate", 0.0)
+    triage_acc = results.get("05_issue_triage", {}).get("accuracy", 0.0)
+
+    total_time = sum(
+        r.get("total_time_s", r.get("elapsed_s", 0.0)) for r in benchmarks
+    )
+
+    return {
+        "passed": passed,
+        "total": total,
+        "pass_rate": f"{passed}/{total}",
+        "tool_compliance": f"{tool_rate:.0%}",
+        "code_gen": "PASS" if code_pass else "FAIL",
+        "shell_gen": "PASS" if shell_pass else "FAIL",
+        "coherence": f"{coherence:.0%}",
+        "triage_accuracy": f"{triage_acc:.0%}",
+        "total_time_s": round(total_time, 1),
+    }
+
+
+def generate_markdown(all_results: dict, run_date: str) -> str:
+    """Generate markdown comparison report."""
+    lines = []
+    lines.append("# Model Benchmark Results")
+    lines.append("")
+    lines.append(f"> Generated: {run_date}  ")
+    lines.append(f"> Ollama URL: `{OLLAMA_URL}`  ")
+    lines.append("> Issue: [#1066](http://143.198.27.163:3000/rockachopa/Timmy-time-dashboard/issues/1066)")
+    lines.append("")
+    lines.append("## Overview")
+    lines.append("")
+    lines.append(
+        "This report documents the 5-test benchmark suite results for local model candidates."
+    )
+    lines.append("")
+    lines.append("### Model Availability vs. Spec")
+    lines.append("")
+    lines.append("| Requested | Tested Substitute | Reason |")
+    lines.append("|-----------|-------------------|--------|")
+    lines.append("| `qwen3:14b` | `qwen2.5:14b` | `qwen3:14b` not pulled locally |")
+    lines.append("| `qwen3:8b` | `qwen3.5:latest` | `qwen3:8b` not pulled locally |")
+    lines.append("| `hermes3:8b` | `hermes3:8b` | Exact match |")
+    lines.append("| `dolphin3` | `llama3.2:latest` | `dolphin3` not pulled locally |")
+    lines.append("")
+
+    # Summary table
+    lines.append("## Summary Comparison Table")
+    lines.append("")
+    lines.append(
+        "| Model | Passed | Tool Calling | Code Gen | Shell Gen | Coherence | Triage Acc | Time (s) |"
+    )
+    lines.append(
+        "|-------|--------|-------------|----------|-----------|-----------|------------|----------|"
+    )
+
+    for model, results in all_results.items():
+        if "error" in results and "01_tool_calling" not in results:
+            lines.append(f"| `{model}` | — | — | — | — | — | — | — |")
+            continue
+        s = score_model(results)
+        lines.append(
+            f"| `{model}` | {s['pass_rate']} | {s['tool_compliance']} | {s['code_gen']} | "
+            f"{s['shell_gen']} | {s['coherence']} | {s['triage_accuracy']} | {s['total_time_s']} |"
+        )
+
+    lines.append("")
+
+    # Per-model detail sections
+    lines.append("## Per-Model Detail")
+    lines.append("")
+
+    for model, results in all_results.items():
+        lines.append(f"### `{model}`")
+        lines.append("")
+
+        if "error" in results and not isinstance(results.get("error"), str):
+            lines.append(f"> **Error:** {results.get('error')}")
+            lines.append("")
+            continue
+
+        for bkey, bres in results.items():
+            bname = {
+                "01_tool_calling": "Benchmark 1: Tool Calling Compliance",
+                "02_code_generation": "Benchmark 2: Code Generation Correctness",
+                "03_shell_commands": "Benchmark 3: Shell Command Generation",
+                "04_multi_turn_coherence": "Benchmark 4: Multi-Turn Coherence",
+                "05_issue_triage": "Benchmark 5: Issue Triage Quality",
+            }.get(bkey, bkey)
+
+            status = "✅ PASS" if bres.get("passed") else "❌ FAIL"
+            lines.append(f"#### {bname} — {status}")
+            lines.append("")
+
+            if bkey == "01_tool_calling":
+                rate = bres.get("compliance_rate", 0)
+                count = bres.get("valid_json_count", 0)
+                total = bres.get("total_prompts", 0)
+                lines.append(
+                    f"- **JSON Compliance:** {count}/{total} ({rate:.0%}) — target ≥90%"
+                )
+            elif bkey == "02_code_generation":
+                lines.append(f"- **Result:** {bres.get('detail', bres.get('error', 'n/a'))}")
+                snippet = bres.get("code_snippet", "")
+                if snippet:
+                    lines.append("- **Generated code snippet:**")
+                    lines.append("  ```python")
+                    for ln in snippet.splitlines()[:8]:
+                        lines.append(f"  {ln}")
+                    lines.append("  ```")
+            elif bkey == "03_shell_commands":
+                passed = bres.get("passed_count", 0)
+                refused = bres.get("refused_count", 0)
+                total = bres.get("total_prompts", 0)
+                lines.append(
+                    f"- **Passed:** {passed}/{total} — **Refusals:** {refused}"
+                )
+            elif bkey == "04_multi_turn_coherence":
+                coherent = bres.get("coherent_turns", 0)
+                total = bres.get("total_turns", 0)
+                rate = bres.get("coherence_rate", 0)
+                lines.append(
+                    f"- **Coherent turns:** {coherent}/{total} ({rate:.0%}) — target ≥80%"
+                )
+            elif bkey == "05_issue_triage":
+                exact = bres.get("exact_matches", 0)
+                total = bres.get("total_issues", 0)
+                acc = bres.get("accuracy", 0)
+                lines.append(
+                    f"- **Accuracy:** {exact}/{total} ({acc:.0%}) — target ≥80%"
+                )
+
+            elapsed = bres.get("total_time_s", bres.get("elapsed_s", 0))
+            lines.append(f"- **Time:** {elapsed}s")
+            lines.append("")
+
+    lines.append("## Raw JSON Data")
+    lines.append("")
+    lines.append("<details>")
+    lines.append("<summary>Click to expand full JSON results</summary>")
+    lines.append("")
+    lines.append("```json")
+    lines.append(json.dumps(all_results, indent=2))
+    lines.append("```")
+    lines.append("")
+    lines.append("</details>")
+    lines.append("")
+
+    return "\n".join(lines)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Run model benchmark suite")
+    parser.add_argument(
+        "--models",
+        nargs="+",
+        default=DEFAULT_MODELS,
+        help="Models to test",
+    )
+    parser.add_argument(
+        "--output",
+        type=Path,
+        default=DOCS_DIR / "model-benchmarks.md",
+        help="Output markdown file",
+    )
+    parser.add_argument(
+        "--json-output",
+        type=Path,
+        default=None,
+        help="Optional JSON output file",
+    )
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    run_date = datetime.now(UTC).strftime("%Y-%m-%d %H:%M UTC")
+
+    print(f"Model Benchmark Suite — {run_date}")
+    print(f"Testing {len(args.models)} model(s): {', '.join(args.models)}")
+    print()
+
+    all_results: dict[str, dict] = {}
+
+    for model in args.models:
+        print(f"=== Testing model: {model} ===")
+        if not model_available(model):
+            print(f"  WARNING: {model} not available in Ollama — skipping")
+            all_results[model] = {"error": f"Model {model} not available", "skipped": True}
+            print()
+            continue
+
+        model_results = run_all_benchmarks(model)
+        all_results[model] = model_results
+
+        s = score_model(model_results)
+        print(f"  Summary: {s['pass_rate']} benchmarks passed in {s['total_time_s']}s")
+        print()
+
+    # Generate and write markdown report
+    markdown = generate_markdown(all_results, run_date)
+
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    args.output.write_text(markdown, encoding="utf-8")
+    print(f"Report written to: {args.output}")
+
+    if args.json_output:
+        args.json_output.write_text(json.dumps(all_results, indent=2), encoding="utf-8")
+        print(f"JSON data written to: {args.json_output}")
+
+    # Overall pass/fail
+    all_pass = all(
+        not r.get("skipped", False)
+        and all(b.get("passed", False) for b in r.values() if isinstance(b, dict))
+        for r in all_results.values()
+    )
+    return 0 if all_pass else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())
--- a/scripts/cycle_retro.py
+++ b/scripts/cycle_retro.py
@@ -46,8 +46,7 @@ import argparse
 import json
 import re
 import subprocess
-import sys
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 from pathlib import Path

 REPO_ROOT = Path(__file__).resolve().parent.parent
@@ -91,7 +90,7 @@ def _epoch_tag(now: datetime | None = None) -> tuple[str, dict]:
    When the date rolls over, the counter resets to 1.
    """
    if now is None:
-        now = datetime.now(timezone.utc)
+        now = datetime.now(UTC)

    iso_cal = now.isocalendar()          # (year, week, weekday)
    week = iso_cal[1]
@@ -221,7 +220,7 @@ def update_summary() -> None:
                        for k, v in sorted(by_weekday.items())}

    summary = {
-        "updated_at": datetime.now(timezone.utc).isoformat(),
+        "updated_at": datetime.now(UTC).isoformat(),
        "current_epoch": current_epoch,
        "window": len(recent),
        "measured_cycles": len(measured),
@@ -293,7 +292,7 @@ def main() -> None:
    truly_success = args.success and args.main_green

    # Generate epoch turnover tag
-    now = datetime.now(timezone.utc)
+    now = datetime.now(UTC)
    epoch_tag, epoch_parts = _epoch_tag(now)

    entry = {
--- a/scripts/dev_server.py
+++ b/scripts/dev_server.py
@@ -11,7 +11,6 @@ Usage: python scripts/dev_server.py [--port PORT]
 """

 import argparse
-import datetime
 import os
 import socket
 import subprocess
@@ -81,8 +80,8 @@ def _ollama_url() -> str:

 def _smoke_ollama(url: str) -> str:
    """Quick connectivity check against Ollama."""
-    import urllib.request
    import urllib.error
+    import urllib.request

    try:
        req = urllib.request.Request(url, method="GET")
@@ -101,14 +100,14 @@ def _print_banner(port: int) -> None:
    hr = "─" * 62
    print(flush=True)
    print(f"  {hr}")
-    print(f"  ┃  Timmy Time — Development Server")
+    print("  ┃  Timmy Time — Development Server")
    print(f"  {hr}")
    print()
    print(f"  Dashboard:   http://localhost:{port}")
    print(f"  API docs:    http://localhost:{port}/docs")
    print(f"  Health:      http://localhost:{port}/health")
    print()
-    print(f"  ── Status ──────────────────────────────────────────────")
+    print("  ── Status ──────────────────────────────────────────────")
    print(f"  Backend:     {ollama_url}  [{ollama_status}]")
    print(f"  Version:     {version}")
    print(f"  Git commit:  {git}")
--- a/scripts/export_trajectories.py
+++ b/scripts/export_trajectories.py
@@ -319,9 +319,9 @@ def main(argv: list[str] | None = None) -> int:
        print(f"Exported {count} training examples to: {args.output}")
        print()
        print("Next steps:")
-        print(f"  mkdir -p ~/timmy-lora-training")
+        print("  mkdir -p ~/timmy-lora-training")
        print(f"  cp {args.output} ~/timmy-lora-training/train.jsonl")
-        print(f"  python scripts/lora_finetune.py --data ~/timmy-lora-training")
+        print("  python scripts/lora_finetune.py --data ~/timmy-lora-training")
    else:
        print("No training examples exported.")
        return 1
--- a/scripts/loop_introspect.py
+++ b/scripts/loop_introspect.py
@@ -18,9 +18,8 @@ Called by: deep_triage.sh (before the LLM triage), timmy-loop.sh (every 50 cycle
 from __future__ import annotations

 import json
-import sys
 from collections import defaultdict
-from datetime import datetime, timezone, timedelta
+from datetime import UTC, datetime, timedelta
 from pathlib import Path

 REPO_ROOT = Path(__file__).resolve().parent.parent
@@ -52,7 +51,7 @@ def parse_ts(ts_str: str) -> datetime | None:
    try:
        dt = datetime.fromisoformat(ts_str.replace("Z", "+00:00"))
        if dt.tzinfo is None:
-            dt = dt.replace(tzinfo=timezone.utc)
+            dt = dt.replace(tzinfo=UTC)
        return dt
    except (ValueError, TypeError):
        return None
@@ -60,7 +59,7 @@ def parse_ts(ts_str: str) -> datetime | None:

 def window(entries: list[dict], days: int) -> list[dict]:
    """Filter entries to the last N days."""
-    cutoff = datetime.now(timezone.utc) - timedelta(days=days)
+    cutoff = datetime.now(UTC) - timedelta(days=days)
    result = []
    for e in entries:
        ts = parse_ts(e.get("timestamp", ""))
@@ -344,7 +343,7 @@ def main() -> None:
    recommendations = generate_recommendations(trends, types, repeats, outliers, triage_eff)

    insights = {
-        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "generated_at": datetime.now(UTC).isoformat(),
        "total_cycles_analyzed": len(cycles),
        "trends": trends,
        "by_type": types,
@@ -371,7 +370,7 @@ def main() -> None:
        header += f"  ·  current epoch: {latest_epoch}"
    print(header)

-    print(f"\n  TRENDS (7d vs previous 7d):")
+    print("\n  TRENDS (7d vs previous 7d):")
    r7 = trends["recent_7d"]
    p7 = trends["previous_7d"]
    print(f"    Cycles:       {r7['count']:>3d}  (was {p7['count']})")
@@ -383,14 +382,14 @@ def main() -> None:
    print(f"    PRs merged:   {r7['prs_merged']:>3d}  (was {p7['prs_merged']})")
    print(f"    Lines net:    {r7['lines_net']:>+5d}")

-    print(f"\n  BY TYPE:")
+    print("\n  BY TYPE:")
    for t, info in sorted(types.items(), key=lambda x: -x[1]["count"]):
        print(f"    {t:12s}  n={info['count']:>2d}  "
              f"ok={info['success_rate']*100:>3.0f}%  "
              f"avg={info['avg_duration']//60}m{info['avg_duration']%60:02d}s")

    if repeats:
-        print(f"\n  REPEAT FAILURES:")
+        print("\n  REPEAT FAILURES:")
        for rf in repeats[:3]:
            print(f"    #{rf['issue']}  failed {rf['failure_count']}x")

--- a/scripts/lora_finetune.py
+++ b/scripts/lora_finetune.py
@@ -360,7 +360,7 @@ def main(argv: list[str] | None = None) -> int:
        return rc

    # Default: train
-    print(f"Starting LoRA fine-tuning")
+    print("Starting LoRA fine-tuning")
    print(f"  Model:        {model_path}")
    print(f"  Data:         {args.data}")
    print(f"  Adapter path: {args.adapter_path}")
--- a/scripts/pre_commit_checks.py
+++ b/scripts/pre_commit_checks.py
@@ -9,11 +9,10 @@ This script runs before commits to catch issues early:
 - Syntax errors in test files
 """

-import sys
-import subprocess
-from pathlib import Path
 import ast
-import re
+import subprocess
+import sys
+from pathlib import Path


 def check_imports():
@@ -70,7 +69,7 @@ def check_test_syntax():
    
    for test_file in tests_dir.rglob("test_*.py"):
        try:
-            with open(test_file, "r") as f:
+            with open(test_file) as f:
                ast.parse(f.read())
            print(f"✓ {test_file.relative_to(tests_dir.parent)} has valid syntax")
        except SyntaxError as e:
@@ -86,7 +85,7 @@ def check_platform_specific_tests():
    # Check for hardcoded /Users/ paths in tests
    tests_dir = Path("tests").resolve()
    for test_file in tests_dir.rglob("test_*.py"):
-        with open(test_file, "r") as f:
+        with open(test_file) as f:
            content = f.read()
            if 'startswith("/Users/")' in content:
                issues.append(
@@ -110,7 +109,7 @@ def check_docker_availability():
    
    if docker_test_files:
        for test_file in docker_test_files:
-            with open(test_file, "r") as f:
+            with open(test_file) as f:
                content = f.read()
                has_skipif = "@pytest.mark.skipif" in content or "pytestmark = pytest.mark.skipif" in content
                if not has_skipif and "docker" in content.lower():
--- a/scripts/test_gabs_connectivity.py
+++ b/scripts/test_gabs_connectivity.py
@@ -83,8 +83,8 @@ def test_tcp_connection(host: str, port: int, timeout: float) -> tuple[bool, soc
        return True, sock
    except OSError as exc:
        print(f"  ✗ Connection failed: {exc}")
-        print(f"  Checklist:")
-        print(f"    - Is Bannerlord running with GABS mod enabled?")
+        print("  Checklist:")
+        print("    - Is Bannerlord running with GABS mod enabled?")
        print(f"    - Is port {port} open in Windows Firewall?")
        print(f"    - Is the VM IP correct? (got: {host})")
        return False, None
@@ -92,7 +92,7 @@ def test_tcp_connection(host: str, port: int, timeout: float) -> tuple[bool, soc

 def test_ping(sock: socket.socket) -> bool:
    """PASS: JSON-RPC ping returns a 2.0 response."""
-    print(f"\n[2/4] JSON-RPC ping")
+    print("\n[2/4] JSON-RPC ping")
    try:
        t0 = time.monotonic()
        resp = _rpc(sock, "ping", req_id=1)
@@ -109,7 +109,7 @@ def test_ping(sock: socket.socket) -> bool:

 def test_game_state(sock: socket.socket) -> bool:
    """PASS: get_game_state returns a result (game must be in a campaign)."""
-    print(f"\n[3/4] get_game_state call")
+    print("\n[3/4] get_game_state call")
    try:
        t0 = time.monotonic()
        resp = _rpc(sock, "get_game_state", req_id=2)
@@ -120,7 +120,7 @@ def test_game_state(sock: socket.socket) -> bool:
            if code == -32601:
                # Method not found — GABS version may not expose this method
                print(f"  ~ Method not available ({elapsed_ms:.1f} ms): {msg}")
-                print(f"    This is acceptable if game is not yet in a campaign.")
+                print("    This is acceptable if game is not yet in a campaign.")
                return True
            print(f"  ✗ RPC error ({elapsed_ms:.1f} ms) [{code}]: {msg}")
            return False
@@ -191,7 +191,7 @@ def main() -> int:
    args = parser.parse_args()

    print("=" * 60)
-    print(f"GABS Connectivity Test Suite")
+    print("GABS Connectivity Test Suite")
    print(f"Target: {args.host}:{args.port}")
    print(f"Timeout: {args.timeout}s")
    print("=" * 60)
--- a/scripts/test_hermes4.py
+++ b/scripts/test_hermes4.py
@@ -150,7 +150,7 @@ def test_model_available(model: str) -> bool:

 def test_basic_response(model: str) -> bool:
    """PASS: model responds coherently to a simple prompt."""
-    print(f"\n[2/5] Basic response test")
+    print("\n[2/5] Basic response test")
    messages = [
        {"role": "user", "content": "Reply with exactly: HERMES_OK"},
    ]
@@ -188,7 +188,7 @@ def test_memory_usage() -> bool:

 def test_tool_calling(model: str) -> bool:
    """PASS: model produces a tool_calls response (not raw text) for a tool-use prompt."""
-    print(f"\n[4/5] Tool-calling test")
+    print("\n[4/5] Tool-calling test")
    messages = [
        {
            "role": "user",
@@ -236,7 +236,7 @@ def test_tool_calling(model: str) -> bool:

 def test_timmy_persona(model: str) -> bool:
    """PASS: model accepts a Timmy persona system prompt and responds in-character."""
-    print(f"\n[5/5] Timmy-persona smoke test")
+    print("\n[5/5] Timmy-persona smoke test")
    messages = [
        {
            "role": "system",
--- a/scripts/test_timmy_skills.py
+++ b/scripts/test_timmy_skills.py
@@ -26,7 +26,7 @@ import argparse
 import json
 import sys
 import time
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from typing import Any

 try:
--- a/scripts/triage_score.py
+++ b/scripts/triage_score.py
@@ -16,7 +16,7 @@ import json
 import os
 import re
 import sys
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 from pathlib import Path

 # ── Config ──────────────────────────────────────────────────────────────
@@ -277,7 +277,7 @@ def update_quarantine(scored: list[dict]) -> list[dict]:
    """Auto-quarantine issues that have failed >= 2 times. Returns filtered list."""
    failures = load_cycle_failures()
    quarantine = load_quarantine()
-    now = datetime.now(timezone.utc).isoformat()
+    now = datetime.now(UTC).isoformat()

    filtered = []
    for item in scored:
@@ -366,7 +366,7 @@ def run_triage() -> list[dict]:
                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")
+                print("[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
@@ -377,7 +377,7 @@ def run_triage() -> list[dict]:

    # Write retro entry
    retro_entry = {
-        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "timestamp": datetime.now(UTC).isoformat(),
        "total_open": len(all_issues),
        "scored": len(scored),
        "ready": len(ready),
--- a/src/init.py
+++ b/src/init.py
@@ -0,0 +1 @@
+"""Timmy Time Dashboard — source root package."""
--- a/src/brain/init.py
+++ b/src/brain/init.py
@@ -0,0 +1 @@
+"""Brain — identity system and task coordination."""
--- a/src/brain/worker.py
+++ b/src/brain/worker.py
@@ -0,0 +1,314 @@
+"""DistributedWorker — task lifecycle management and backend routing.
+
+Routes delegated tasks to appropriate execution backends:
+
+- agentic_loop: local multi-step execution via Timmy's agentic loop
+- kimi: heavy research tasks dispatched via Gitea kimi-ready issues
+- paperclip: task submission to the Paperclip API
+
+Task lifecycle: queued → running → completed | failed
+
+Failure handling: auto-retry up to MAX_RETRIES, then mark failed.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import threading
+import uuid
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any, ClassVar
+
+logger = logging.getLogger(__name__)
+
+MAX_RETRIES = 2
+
+
+# ---------------------------------------------------------------------------
+# Task record
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class DelegatedTask:
+    """Record of one delegated task and its execution state."""
+
+    task_id: str
+    agent_name: str
+    agent_role: str
+    task_description: str
+    priority: str
+    backend: str  # "agentic_loop" | "kimi" | "paperclip"
+    status: str = "queued"  # queued | running | completed | failed
+    created_at: str = field(default_factory=lambda: datetime.now(UTC).isoformat())
+    result: dict[str, Any] | None = None
+    error: str | None = None
+    retries: int = 0
+
+
+# ---------------------------------------------------------------------------
+# Worker
+# ---------------------------------------------------------------------------
+
+
+class DistributedWorker:
+    """Routes and tracks delegated task execution across multiple backends.
+
+    All methods are class-methods; DistributedWorker is a singleton-style
+    service — no instantiation needed.
+
+    Usage::
+
+        from brain.worker import DistributedWorker
+
+        task_id = DistributedWorker.submit("researcher", "research", "summarise X")
+        status  = DistributedWorker.get_status(task_id)
+    """
+
+    _tasks: ClassVar[dict[str, DelegatedTask]] = {}
+    _lock: ClassVar[threading.Lock] = threading.Lock()
+
+    @classmethod
+    def submit(
+        cls,
+        agent_name: str,
+        agent_role: str,
+        task_description: str,
+        priority: str = "normal",
+    ) -> str:
+        """Submit a task for execution. Returns task_id immediately.
+
+        The task is registered as 'queued' and a daemon thread begins
+        execution in the background. Use get_status(task_id) to poll.
+        """
+        task_id = uuid.uuid4().hex[:8]
+        backend = cls._select_backend(agent_role, task_description)
+
+        record = DelegatedTask(
+            task_id=task_id,
+            agent_name=agent_name,
+            agent_role=agent_role,
+            task_description=task_description,
+            priority=priority,
+            backend=backend,
+        )
+
+        with cls._lock:
+            cls._tasks[task_id] = record
+
+        thread = threading.Thread(
+            target=cls._run_task,
+            args=(record,),
+            daemon=True,
+            name=f"worker-{task_id}",
+        )
+        thread.start()
+
+        logger.info(
+            "Task %s queued: %s → %.60s (backend=%s, priority=%s)",
+            task_id,
+            agent_name,
+            task_description,
+            backend,
+            priority,
+        )
+        return task_id
+
+    @classmethod
+    def get_status(cls, task_id: str) -> dict[str, Any]:
+        """Return current status of a task by ID."""
+        record = cls._tasks.get(task_id)
+        if record is None:
+            return {"found": False, "task_id": task_id}
+        return {
+            "found": True,
+            "task_id": record.task_id,
+            "agent": record.agent_name,
+            "role": record.agent_role,
+            "status": record.status,
+            "backend": record.backend,
+            "priority": record.priority,
+            "created_at": record.created_at,
+            "retries": record.retries,
+            "result": record.result,
+            "error": record.error,
+        }
+
+    @classmethod
+    def list_tasks(cls) -> list[dict[str, Any]]:
+        """Return a summary list of all tracked tasks."""
+        with cls._lock:
+            return [
+                {
+                    "task_id": t.task_id,
+                    "agent": t.agent_name,
+                    "status": t.status,
+                    "backend": t.backend,
+                    "created_at": t.created_at,
+                }
+                for t in cls._tasks.values()
+            ]
+
+    @classmethod
+    def clear(cls) -> None:
+        """Clear the task registry (for tests)."""
+        with cls._lock:
+            cls._tasks.clear()
+
+    # ------------------------------------------------------------------
+    # Backend selection
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def _select_backend(cls, agent_role: str, task_description: str) -> str:
+        """Choose the execution backend for a given agent role and task.
+
+        Priority:
+        1. kimi  — research role + Gitea enabled + task exceeds local capacity
+        2. paperclip — paperclip API key is configured
+        3. agentic_loop — local fallback (always available)
+        """
+        try:
+            from config import settings
+            from timmy.kimi_delegation import exceeds_local_capacity
+
+            if (
+                agent_role == "research"
+                and getattr(settings, "gitea_enabled", False)
+                and getattr(settings, "gitea_token", "")
+                and exceeds_local_capacity(task_description)
+            ):
+                return "kimi"
+
+            if getattr(settings, "paperclip_api_key", ""):
+                return "paperclip"
+
+        except Exception as exc:
+            logger.debug("Backend selection error — defaulting to agentic_loop: %s", exc)
+
+        return "agentic_loop"
+
+    # ------------------------------------------------------------------
+    # Task execution
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def _run_task(cls, record: DelegatedTask) -> None:
+        """Execute a task with retry logic. Runs inside a daemon thread."""
+        record.status = "running"
+
+        for attempt in range(MAX_RETRIES + 1):
+            try:
+                if attempt > 0:
+                    logger.info(
+                        "Retrying task %s (attempt %d/%d)",
+                        record.task_id,
+                        attempt + 1,
+                        MAX_RETRIES + 1,
+                    )
+                    record.retries = attempt
+
+                result = cls._dispatch(record)
+                record.status = "completed"
+                record.result = result
+                logger.info(
+                    "Task %s completed via %s",
+                    record.task_id,
+                    record.backend,
+                )
+                return
+
+            except Exception as exc:
+                logger.warning(
+                    "Task %s attempt %d failed: %s",
+                    record.task_id,
+                    attempt + 1,
+                    exc,
+                )
+                if attempt == MAX_RETRIES:
+                    record.status = "failed"
+                    record.error = str(exc)
+                    logger.error(
+                        "Task %s exhausted %d retries. Final error: %s",
+                        record.task_id,
+                        MAX_RETRIES,
+                        exc,
+                    )
+
+    @classmethod
+    def _dispatch(cls, record: DelegatedTask) -> dict[str, Any]:
+        """Route to the selected backend. Raises on failure."""
+        if record.backend == "kimi":
+            return asyncio.run(cls._execute_kimi(record))
+        if record.backend == "paperclip":
+            return asyncio.run(cls._execute_paperclip(record))
+        return asyncio.run(cls._execute_agentic_loop(record))
+
+    @classmethod
+    async def _execute_kimi(cls, record: DelegatedTask) -> dict[str, Any]:
+        """Create a kimi-ready Gitea issue for the task.
+
+        Kimi picks up the issue via the kimi-ready label and executes it.
+        """
+        from timmy.kimi_delegation import create_kimi_research_issue
+
+        result = await create_kimi_research_issue(
+            task=record.task_description[:120],
+            context=f"Delegated by agent '{record.agent_name}' via delegate_task.",
+            question=record.task_description,
+            priority=record.priority,
+        )
+        if not result.get("success"):
+            raise RuntimeError(f"Kimi issue creation failed: {result.get('error')}")
+        return result
+
+    @classmethod
+    async def _execute_paperclip(cls, record: DelegatedTask) -> dict[str, Any]:
+        """Submit the task to the Paperclip API."""
+        import httpx
+
+        from timmy.paperclip import PaperclipClient
+
+        client = PaperclipClient()
+        async with httpx.AsyncClient(timeout=client.timeout) as http:
+            resp = await http.post(
+                f"{client.base_url}/api/tasks",
+                headers={"Authorization": f"Bearer {client.api_key}"},
+                json={
+                    "kind": record.agent_role,
+                    "agent_id": client.agent_id,
+                    "company_id": client.company_id,
+                    "priority": record.priority,
+                    "context": {"task": record.task_description},
+                },
+            )
+
+        if resp.status_code in (200, 201):
+            data = resp.json()
+            logger.info(
+                "Task %s submitted to Paperclip (paperclip_id=%s)",
+                record.task_id,
+                data.get("id"),
+            )
+            return {
+                "success": True,
+                "paperclip_task_id": data.get("id"),
+                "backend": "paperclip",
+            }
+        raise RuntimeError(f"Paperclip API error {resp.status_code}: {resp.text[:200]}")
+
+    @classmethod
+    async def _execute_agentic_loop(cls, record: DelegatedTask) -> dict[str, Any]:
+        """Execute the task via Timmy's local agentic loop."""
+        from timmy.agentic_loop import run_agentic_loop
+
+        result = await run_agentic_loop(record.task_description)
+        return {
+            "success": result.status != "failed",
+            "agentic_task_id": result.task_id,
+            "summary": result.summary,
+            "status": result.status,
+            "backend": "agentic_loop",
+        }
--- a/src/config.py
+++ b/src/config.py
@@ -1,3 +1,8 @@
+"""Central pydantic-settings configuration for Timmy Time Dashboard.
+
+All environment variable access goes through the ``settings`` singleton
+exported from this module — never use ``os.environ.get()`` in app code.
+"""
 import logging as _logging
 import os
 import sys
@@ -94,8 +99,9 @@ class Settings(BaseSettings):

    # ── Backend selection ────────────────────────────────────────────────────
    # "ollama"  — always use Ollama (default, safe everywhere)
+    # "airllm"  — AirLLM layer-by-layer loading (Apple Silicon only; degrades to Ollama)
    # "auto"    — pick best available local backend, fall back to Ollama
-    timmy_model_backend: Literal["ollama", "grok", "claude", "auto"] = "ollama"
+    timmy_model_backend: Literal["ollama", "airllm", "grok", "claude", "auto"] = "ollama"

    # ── Grok (xAI) — opt-in premium cloud backend ────────────────────────
    # Grok is a premium augmentation layer — local-first ethos preserved.
@@ -108,6 +114,16 @@ class Settings(BaseSettings):
    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

+    # ── Search Backend (SearXNG + Crawl4AI) ──────────────────────────────
+    # "searxng" — self-hosted SearXNG meta-search engine (default, no API key)
+    # "none"    — disable web search (private/offline deployments)
+    # Override with TIMMY_SEARCH_BACKEND env var.
+    timmy_search_backend: Literal["searxng", "none"] = "searxng"
+    # SearXNG base URL — override with TIMMY_SEARCH_URL env var
+    search_url: str = "http://localhost:8888"
+    # Crawl4AI base URL — override with TIMMY_CRAWL_URL env var
+    crawl_url: str = "http://localhost:11235"
+
    # ── Database ──────────────────────────────────────────────────────────
    db_busy_timeout_ms: int = 5000  # SQLite PRAGMA busy_timeout (ms)

@@ -117,6 +133,23 @@ class Settings(BaseSettings):
    anthropic_api_key: str = ""
    claude_model: str = "haiku"

+    # ── Tiered Model Router (issue #882) ─────────────────────────────────
+    # Three-tier cascade: Local 8B (free, fast) → Local 70B (free, slower)
+    # → Cloud API (paid, best).  Override model names per tier via env vars.
+    #
+    # TIER_LOCAL_FAST_MODEL   — Tier-1 model name in Ollama (default: llama3.1:8b)
+    # TIER_LOCAL_HEAVY_MODEL  — Tier-2 model name in Ollama (default: hermes3:70b)
+    # TIER_CLOUD_MODEL        — Tier-3 cloud model name   (default: claude-haiku-4-5)
+    #
+    # Budget limits for the cloud tier (0 = unlimited):
+    # TIER_CLOUD_DAILY_BUDGET_USD   — daily ceiling in USD (default: 5.0)
+    # TIER_CLOUD_MONTHLY_BUDGET_USD — monthly ceiling in USD (default: 50.0)
+    tier_local_fast_model: str = "llama3.1:8b"
+    tier_local_heavy_model: str = "hermes3:70b"
+    tier_cloud_model: str = "claude-haiku-4-5"
+    tier_cloud_daily_budget_usd: float = 5.0
+    tier_cloud_monthly_budget_usd: float = 50.0
+
    # ── Content Moderation ──────────────────────────────────────────────
    # Three-layer moderation pipeline for AI narrator output.
    # Uses Llama Guard via Ollama with regex fallback.
--- a/src/dashboard/app.py
+++ b/src/dashboard/app.py
@@ -35,9 +35,9 @@ 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.energy import router as energy_router
 from dashboard.routes.experiments import router as experiments_router
 from dashboard.routes.grok import router as grok_router
-from dashboard.routes.energy import router as energy_router
 from dashboard.routes.health import router as health_router
 from dashboard.routes.hermes import router as hermes_router
 from dashboard.routes.loop_qa import router as loop_qa_router
@@ -48,6 +48,7 @@ from dashboard.routes.models import router as models_router
 from dashboard.routes.nexus import router as nexus_router
 from dashboard.routes.quests import router as quests_router
 from dashboard.routes.scorecards import router as scorecards_router
+from dashboard.routes.self_correction import router as self_correction_router
 from dashboard.routes.sovereignty_metrics import router as sovereignty_metrics_router
 from dashboard.routes.sovereignty_ws import router as sovereignty_ws_router
 from dashboard.routes.spark import router as spark_router
@@ -551,12 +552,28 @@ async def lifespan(app: FastAPI):
    except Exception:
        logger.debug("Failed to register error recorder")

+    # Mark session start for sovereignty duration tracking
+    try:
+        from timmy.sovereignty import mark_session_start
+
+        mark_session_start()
+    except Exception:
+        logger.debug("Failed to mark sovereignty session start")
+
    logger.info("✓ Dashboard ready for requests")

    yield

    await _shutdown_cleanup(bg_tasks, workshop_heartbeat)

+    # Generate and commit sovereignty session report
+    try:
+        from timmy.sovereignty import generate_and_commit_report
+
+        await generate_and_commit_report()
+    except Exception as exc:
+        logger.warning("Sovereignty report generation failed at shutdown: %s", exc)
+

 app = FastAPI(
    title="Mission Control",
@@ -680,6 +697,7 @@ app.include_router(scorecards_router)
 app.include_router(sovereignty_metrics_router)
 app.include_router(sovereignty_ws_router)
 app.include_router(three_strike_router)
+app.include_router(self_correction_router)


@app.websocket("/ws")
--- a/src/dashboard/models/calm.py
+++ b/src/dashboard/models/calm.py
@@ -1,3 +1,4 @@
+"""SQLAlchemy ORM models for the CALM task-management and journaling system."""
 from datetime import UTC, date, datetime
 from enum import StrEnum

--- a/src/dashboard/models/database.py
+++ b/src/dashboard/models/database.py
@@ -1,3 +1,4 @@
+"""SQLAlchemy engine, session factory, and declarative Base for the CALM module."""
 import logging
 from pathlib import Path

--- a/src/dashboard/routes/agents.py
+++ b/src/dashboard/routes/agents.py
@@ -1,3 +1,4 @@
+"""Dashboard routes for agent chat interactions and tool-call display."""
 import json
 import logging
 from datetime import datetime
--- a/src/dashboard/routes/calm.py
+++ b/src/dashboard/routes/calm.py
@@ -1,3 +1,4 @@
+"""Dashboard routes for the CALM task management and daily journaling interface."""
 import logging
 from datetime import UTC, date, datetime

--- a/src/dashboard/routes/self_correction.py
+++ b/src/dashboard/routes/self_correction.py
@@ -0,0 +1,58 @@
+"""Self-Correction Dashboard routes.
+
+GET  /self-correction/ui       — HTML dashboard
+GET  /self-correction/timeline — HTMX partial: recent event timeline
+GET  /self-correction/patterns — HTMX partial: recurring failure patterns
+"""
+
+import logging
+
+from fastapi import APIRouter, Request
+from fastapi.responses import HTMLResponse
+
+from dashboard.templating import templates
+from infrastructure.self_correction import get_corrections, get_patterns, get_stats
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/self-correction", tags=["self-correction"])
+
+
+@router.get("/ui", response_class=HTMLResponse)
+async def self_correction_ui(request: Request):
+    """Render the Self-Correction Dashboard."""
+    stats = get_stats()
+    corrections = get_corrections(limit=20)
+    patterns = get_patterns(top_n=10)
+    return templates.TemplateResponse(
+        request,
+        "self_correction.html",
+        {
+            "stats": stats,
+            "corrections": corrections,
+            "patterns": patterns,
+        },
+    )
+
+
+@router.get("/timeline", response_class=HTMLResponse)
+async def self_correction_timeline(request: Request):
+    """HTMX partial: recent self-correction event timeline."""
+    corrections = get_corrections(limit=30)
+    return templates.TemplateResponse(
+        request,
+        "partials/self_correction_timeline.html",
+        {"corrections": corrections},
+    )
+
+
+@router.get("/patterns", response_class=HTMLResponse)
+async def self_correction_patterns(request: Request):
+    """HTMX partial: recurring failure patterns."""
+    patterns = get_patterns(top_n=10)
+    stats = get_stats()
+    return templates.TemplateResponse(
+        request,
+        "partials/self_correction_patterns.html",
+        {"patterns": patterns, "stats": stats},
+    )
--- a/src/dashboard/templates/base.html
+++ b/src/dashboard/templates/base.html
@@ -71,6 +71,7 @@
          <a href="/spark/ui" class="mc-test-link">SPARK</a>
          <a href="/memory" class="mc-test-link">MEMORY</a>
          <a href="/marketplace/ui" class="mc-test-link">MARKET</a>
+          <a href="/self-correction/ui" class="mc-test-link">SELF-CORRECT</a>
        </div>
      </div>
      <div class="mc-nav-dropdown">
@@ -132,6 +133,7 @@
    <a href="/spark/ui" class="mc-mobile-link">SPARK</a>
    <a href="/memory" class="mc-mobile-link">MEMORY</a>
    <a href="/marketplace/ui" class="mc-mobile-link">MARKET</a>
+    <a href="/self-correction/ui" class="mc-mobile-link">SELF-CORRECT</a>
    <div class="mc-mobile-section-label">AGENTS</div>
    <a href="/hands" class="mc-mobile-link">HANDS</a>
    <a href="/work-orders/queue" class="mc-mobile-link">WORK ORDERS</a>
--- a/src/dashboard/templates/mission_control.html
+++ b/src/dashboard/templates/mission_control.html
@@ -186,6 +186,24 @@
  <p class="chat-history-placeholder">Loading sovereignty metrics...</p>
 {% endcall %}

+<!-- Agent Scorecards -->
+<div class="card mc-card-spaced" id="mc-scorecards-card">
+    <div class="card-header">
+        <h2 class="card-title">Agent Scorecards</h2>
+        <div class="d-flex align-items-center gap-2">
+            <select id="mc-scorecard-period" class="form-select form-select-sm" style="width: auto;"
+                    onchange="loadMcScorecards()">
+                <option value="daily" selected>Daily</option>
+                <option value="weekly">Weekly</option>
+            </select>
+            <a href="/scorecards" class="btn btn-sm btn-outline-secondary">Full View</a>
+        </div>
+    </div>
+    <div id="mc-scorecards-content" class="p-2">
+        <p class="chat-history-placeholder">Loading scorecards...</p>
+    </div>
+</div>
+
 <!-- Chat History -->
 <div class="card mc-card-spaced">
    <div class="card-header">
@@ -502,6 +520,20 @@ async function loadSparkStatus() {
    }
 }

+// Load agent scorecards
+async function loadMcScorecards() {
+    var period = document.getElementById('mc-scorecard-period').value;
+    var container = document.getElementById('mc-scorecards-content');
+    container.innerHTML = '<p class="chat-history-placeholder">Loading scorecards...</p>';
+    try {
+        var response = await fetch('/scorecards/all/panels?period=' + period);
+        var html = await response.text();
+        container.innerHTML = html;
+    } catch (error) {
+        container.innerHTML = '<p class="chat-history-placeholder">Scorecards unavailable</p>';
+    }
+}
+
 // Initial load
 loadSparkStatus();
 loadSovereignty();
@@ -510,6 +542,7 @@ loadSwarmStats();
 loadLightningStats();
 loadGrokStats();
 loadChatHistory();
+loadMcScorecards();

 // Periodic updates
 setInterval(loadSovereignty, 30000);
@@ -518,5 +551,6 @@ setInterval(loadSwarmStats, 5000);
 setInterval(updateHeartbeat, 5000);
 setInterval(loadGrokStats, 10000);
 setInterval(loadSparkStatus, 15000);
+setInterval(loadMcScorecards, 300000);
 </script>
 {% endblock %}
--- a/src/dashboard/templates/partials/self_correction_patterns.html
+++ b/src/dashboard/templates/partials/self_correction_patterns.html
@@ -0,0 +1,28 @@
+{% if patterns %}
+  <table class="mc-table w-100">
+    <thead>
+      <tr>
+        <th>ERROR TYPE</th>
+        <th class="text-center">COUNT</th>
+        <th class="text-center">CORRECTED</th>
+        <th class="text-center">FAILED</th>
+        <th>LAST SEEN</th>
+      </tr>
+    </thead>
+    <tbody>
+      {% for p in patterns %}
+      <tr>
+        <td class="sc-pattern-type">{{ p.error_type }}</td>
+        <td class="text-center">
+          <span class="badge {% if p.count >= 5 %}badge-error{% elif p.count >= 3 %}badge-warning{% else %}badge-info{% endif %}">{{ p.count }}</span>
+        </td>
+        <td class="text-center text-success">{{ p.success_count }}</td>
+        <td class="text-center {% if p.failed_count > 0 %}text-danger{% else %}text-muted{% endif %}">{{ p.failed_count }}</td>
+        <td class="sc-event-time">{{ p.last_seen[:16] if p.last_seen else '—' }}</td>
+      </tr>
+      {% endfor %}
+    </tbody>
+  </table>
+{% else %}
+  <div class="text-center text-muted py-3">No patterns detected yet.</div>
+{% endif %}
--- a/src/dashboard/templates/partials/self_correction_timeline.html
+++ b/src/dashboard/templates/partials/self_correction_timeline.html
@@ -0,0 +1,26 @@
+{% if corrections %}
+  {% for ev in corrections %}
+  <div class="sc-event sc-status-{{ ev.outcome_status }}">
+    <div class="sc-event-header">
+      <span class="sc-status-badge sc-status-{{ ev.outcome_status }}">
+        {% if ev.outcome_status == 'success' %}&#10003; CORRECTED
+        {% elif ev.outcome_status == 'partial' %}&#9679; PARTIAL
+        {% else %}&#10007; FAILED
+        {% endif %}
+      </span>
+      <span class="sc-source-badge">{{ ev.source }}</span>
+      <span class="sc-event-time">{{ ev.created_at[:19] }}</span>
+    </div>
+    <div class="sc-event-error-type">{{ ev.error_type }}</div>
+    <div class="sc-event-intent"><span class="sc-label">INTENT:</span> {{ ev.original_intent[:120] }}{% if ev.original_intent | length > 120 %}&hellip;{% endif %}</div>
+    <div class="sc-event-error"><span class="sc-label">ERROR:</span> {{ ev.detected_error[:120] }}{% if ev.detected_error | length > 120 %}&hellip;{% endif %}</div>
+    <div class="sc-event-strategy"><span class="sc-label">STRATEGY:</span> {{ ev.correction_strategy[:120] }}{% if ev.correction_strategy | length > 120 %}&hellip;{% endif %}</div>
+    <div class="sc-event-outcome"><span class="sc-label">OUTCOME:</span> {{ ev.final_outcome[:120] }}{% if ev.final_outcome | length > 120 %}&hellip;{% endif %}</div>
+    {% if ev.task_id %}
+    <div class="sc-event-meta">task: {{ ev.task_id[:8] }}</div>
+    {% endif %}
+  </div>
+  {% endfor %}
+{% else %}
+  <div class="text-center text-muted py-3">No self-correction events recorded yet.</div>
+{% endif %}
--- a/src/dashboard/templates/self_correction.html
+++ b/src/dashboard/templates/self_correction.html
@@ -0,0 +1,102 @@
+{% extends "base.html" %}
+{% from "macros.html" import panel %}
+
+{% block title %}Timmy Time — Self-Correction Dashboard{% endblock %}
+
+{% block extra_styles %}{% endblock %}
+
+{% block content %}
+<div class="container-fluid py-3">
+
+  <!-- Header -->
+  <div class="spark-header mb-3">
+    <div class="spark-title">SELF-CORRECTION</div>
+    <div class="spark-subtitle">
+      Agent error detection &amp; recovery &mdash;
+      <span class="spark-status-val">{{ stats.total }}</span> events,
+      <span class="spark-status-val">{{ stats.success_rate }}%</span> correction rate,
+      <span class="spark-status-val">{{ stats.unique_error_types }}</span> distinct error types
+    </div>
+  </div>
+
+  <div class="row g-3">
+
+    <!-- Left column: stats + patterns -->
+    <div class="col-12 col-lg-4 d-flex flex-column gap-3">
+
+      <!-- Stats panel -->
+      <div class="card mc-panel">
+        <div class="card-header mc-panel-header">// CORRECTION STATS</div>
+        <div class="card-body p-3">
+          <div class="spark-stat-grid">
+            <div class="spark-stat">
+              <span class="spark-stat-label">TOTAL</span>
+              <span class="spark-stat-value">{{ stats.total }}</span>
+            </div>
+            <div class="spark-stat">
+              <span class="spark-stat-label">CORRECTED</span>
+              <span class="spark-stat-value text-success">{{ stats.success_count }}</span>
+            </div>
+            <div class="spark-stat">
+              <span class="spark-stat-label">PARTIAL</span>
+              <span class="spark-stat-value text-warning">{{ stats.partial_count }}</span>
+            </div>
+            <div class="spark-stat">
+              <span class="spark-stat-label">FAILED</span>
+              <span class="spark-stat-value {% if stats.failed_count > 0 %}text-danger{% else %}text-muted{% endif %}">{{ stats.failed_count }}</span>
+            </div>
+          </div>
+          <div class="mt-3">
+            <div class="d-flex justify-content-between mb-1">
+              <small class="text-muted">Correction Rate</small>
+              <small class="{% if stats.success_rate >= 70 %}text-success{% elif stats.success_rate >= 40 %}text-warning{% else %}text-danger{% endif %}">{{ stats.success_rate }}%</small>
+            </div>
+            <div class="progress" style="height:6px;">
+              <div class="progress-bar {% if stats.success_rate >= 70 %}bg-success{% elif stats.success_rate >= 40 %}bg-warning{% else %}bg-danger{% endif %}"
+                   role="progressbar"
+                   style="width:{{ stats.success_rate }}%"
+                   aria-valuenow="{{ stats.success_rate }}"
+                   aria-valuemin="0"
+                   aria-valuemax="100"></div>
+            </div>
+          </div>
+        </div>
+      </div>
+
+      <!-- Patterns panel -->
+      <div class="card mc-panel"
+           hx-get="/self-correction/patterns"
+           hx-trigger="load, every 60s"
+           hx-target="#sc-patterns-body"
+           hx-swap="innerHTML">
+        <div class="card-header mc-panel-header d-flex justify-content-between align-items-center">
+          <span>// RECURRING PATTERNS</span>
+          <span class="badge badge-info">{{ patterns | length }}</span>
+        </div>
+        <div class="card-body p-0" id="sc-patterns-body">
+          {% include "partials/self_correction_patterns.html" %}
+        </div>
+      </div>
+
+    </div>
+
+    <!-- Right column: timeline -->
+    <div class="col-12 col-lg-8">
+      <div class="card mc-panel"
+           hx-get="/self-correction/timeline"
+           hx-trigger="load, every 30s"
+           hx-target="#sc-timeline-body"
+           hx-swap="innerHTML">
+        <div class="card-header mc-panel-header d-flex justify-content-between align-items-center">
+          <span>// CORRECTION TIMELINE</span>
+          <span class="badge badge-info">{{ corrections | length }}</span>
+        </div>
+        <div class="card-body p-3" id="sc-timeline-body">
+          {% include "partials/self_correction_timeline.html" %}
+        </div>
+      </div>
+    </div>
+
+  </div>
+</div>
+{% endblock %}
--- a/src/infrastructure/clients/init.py
+++ b/src/infrastructure/clients/init.py
--- a/src/infrastructure/clients/nostr_client.py
+++ b/src/infrastructure/clients/nostr_client.py
@@ -0,0 +1,154 @@
+# TODO: This code should be moved to the timmy-nostr repository once it's available.
+# See ADR-024 for more details.
+
+import json
+import logging
+from typing import Any
+
+import websockets
+from pynostr.event import Event
+from pynostr.key import PrivateKey
+
+logger = logging.getLogger(__name__)
+
+
+class NostrClient:
+    """
+    A client for interacting with the Nostr network.
+    """
+
+    def __init__(self, relays: list[str], private_key_hex: str | None = None):
+        self.relays = relays
+        self._connections: dict[str, websockets.WebSocketClientProtocol] = {}
+        if private_key_hex:
+            self.private_key = PrivateKey.from_hex(private_key_hex)
+            self.public_key = self.private_key.public_key
+        else:
+            self.private_key = None
+            self.public_key = None
+
+    async def connect(self):
+        """
+        Connect to all the relays.
+        """
+        for relay in self.relays:
+            try:
+                conn = await websockets.connect(relay)
+                self._connections[relay] = conn
+                logger.info(f"Connected to Nostr relay: {relay}")
+            except Exception as e:
+                logger.error(f"Failed to connect to Nostr relay {relay}: {e}")
+
+    async def disconnect(self):
+        """
+        Disconnect from all the relays.
+        """
+        for relay, conn in self._connections.items():
+            try:
+                await conn.close()
+                logger.info(f"Disconnected from Nostr relay: {relay}")
+            except Exception as e:
+                logger.error(f"Failed to disconnect from Nostr relay {relay}: {e}")
+        self._connections = {}
+
+    async def subscribe_for_events(
+        self,
+        subscription_id: str,
+        filters: list[dict[str, Any]],
+        unsubscribe_on_eose: bool = True,
+    ):
+        """
+        Subscribe to events from the Nostr network.
+        """
+        for relay, conn in self._connections.items():
+            try:
+                request = ["REQ", subscription_id]
+                request.extend(filters)
+                await conn.send(json.dumps(request))
+                logger.info(f"Subscribed to events on {relay} with sub_id: {subscription_id}")
+
+                async for message in conn:
+                    message_json = json.loads(message)
+                    message_type = message_json[0]
+
+                    if message_type == "EVENT":
+                        yield message_json[2]
+                    elif message_type == "EOSE":
+                        logger.info(f"End of stored events for sub_id: {subscription_id} on {relay}")
+                        if unsubscribe_on_eose:
+                            await self.unsubscribe(subscription_id, relay)
+                        break
+            except Exception as e:
+                logger.error(f"Failed to subscribe to events on {relay}: {e}")
+
+    async def unsubscribe(self, subscription_id: str, relay: str):
+        """
+        Unsubscribe from events.
+        """
+        if relay not in self._connections:
+            logger.warning(f"Not connected to relay: {relay}")
+            return
+
+        conn = self._connections[relay]
+        try:
+            request = ["CLOSE", subscription_id]
+            await conn.send(json.dumps(request))
+            logger.info(f"Unsubscribed from sub_id: {subscription_id} on {relay}")
+        except Exception as e:
+            logger.error(f"Failed to unsubscribe from {relay}: {e}")
+
+    async def publish_event(self, event: Event):
+        """
+        Publish an event to all connected relays.
+        """
+        for relay, conn in self._connections.items():
+            try:
+                request = ["EVENT", event.to_dict()]
+                await conn.send(json.dumps(request))
+                logger.info(f"Published event {event.id} to {relay}")
+            except Exception as e:
+                logger.error(f"Failed to publish event to {relay}: {e}")
+
+    # NIP-89 Implementation
+    async def find_capability_cards(self, kinds: list[int] | None = None):
+        """
+        Find capability cards (Kind 31990) for other agents.
+        """
+        # Kind 31990 is for "Handler recommendations" which is a precursor to NIP-89
+        # NIP-89 is for "Application-specific data" which is a more general purpose
+        # kind. The issue description says "Kind 31990 'Capability Card' monitoring"
+        # which is a bit of a mix of concepts. I will use Kind 31990 as the issue
+        # description says.
+        filters = [{"kinds": [31990]}]
+        if kinds:
+            filters[0]["#k"] = [str(k) for k in kinds]
+
+        sub_id = "capability-card-finder"
+        async for event in self.subscribe_for_events(sub_id, filters):
+            yield event
+
+    # NIP-90 Implementation
+    async def create_job_request(
+        self,
+        kind: int,
+        content: str,
+        tags: list[list[str]] | None = None,
+    ) -> Event:
+        """
+        Create and publish a job request (Kind 5000-5999).
+        """
+        if not self.private_key:
+            raise Exception("Cannot create job request without a private key.")
+
+        if not 5000 <= kind <= 5999:
+            raise ValueError("Job request kind must be between 5000 and 5999.")
+
+        event = Event(
+            pubkey=self.public_key.hex(),
+            kind=kind,
+            content=content,
+            tags=tags or [],
+        )
+        event.sign(self.private_key.hex())
+        await self.publish_event(event)
+        return event
--- a/src/infrastructure/energy/monitor.py
+++ b/src/infrastructure/energy/monitor.py
@@ -19,7 +19,6 @@ Refs: #1009
 """

 import asyncio
-import json
 import logging
 import subprocess
 import time
--- a/src/infrastructure/models/init.py
+++ b/src/infrastructure/models/init.py
@@ -1,5 +1,11 @@
 """Infrastructure models package."""

+from infrastructure.models.budget import (
+    BudgetTracker,
+    SpendRecord,
+    estimate_cost_usd,
+    get_budget_tracker,
+)
 from infrastructure.models.multimodal import (
    ModelCapability,
    ModelInfo,
@@ -17,6 +23,12 @@ from infrastructure.models.registry import (
    ModelRole,
    model_registry,
 )
+from infrastructure.models.router import (
+    TieredModelRouter,
+    TierLabel,
+    classify_tier,
+    get_tiered_router,
+)

 __all__ = [
    # Registry
@@ -34,4 +46,14 @@ __all__ = [
    "model_supports_tools",
    "model_supports_vision",
    "pull_model_with_fallback",
+    # Tiered router
+    "TierLabel",
+    "TieredModelRouter",
+    "classify_tier",
+    "get_tiered_router",
+    # Budget tracker
+    "BudgetTracker",
+    "SpendRecord",
+    "estimate_cost_usd",
+    "get_budget_tracker",
 ]
--- a/src/infrastructure/models/budget.py
+++ b/src/infrastructure/models/budget.py
@@ -0,0 +1,302 @@
+"""Cloud API budget tracker for the three-tier model router.
+
+Tracks cloud API spend (daily / monthly) and enforces configurable limits.
+SQLite-backed with in-memory fallback — degrades gracefully if the database
+is unavailable.
+
+References:
+  - Issue #882 — Model Tiering Router: Local 8B / Hermes 70B / Cloud API Cascade
+"""
+
+import logging
+import sqlite3
+import threading
+import time
+from dataclasses import dataclass
+from datetime import UTC, date, datetime
+from pathlib import Path
+
+from config import settings
+
+logger = logging.getLogger(__name__)
+
+# ── Cost estimates (USD per 1 K tokens, input / output) ──────────────────────
+# Updated 2026-03.  Estimates only — actual costs vary by tier/usage.
+_COST_PER_1K: dict[str, dict[str, float]] = {
+    # Claude models
+    "claude-haiku-4-5": {"input": 0.00025, "output": 0.00125},
+    "claude-sonnet-4-5": {"input": 0.003, "output": 0.015},
+    "claude-opus-4-5": {"input": 0.015, "output": 0.075},
+    "haiku": {"input": 0.00025, "output": 0.00125},
+    "sonnet": {"input": 0.003, "output": 0.015},
+    "opus": {"input": 0.015, "output": 0.075},
+    # GPT-4o
+    "gpt-4o-mini": {"input": 0.00015, "output": 0.0006},
+    "gpt-4o": {"input": 0.0025, "output": 0.01},
+    # Grok (xAI)
+    "grok-3-fast": {"input": 0.003, "output": 0.015},
+    "grok-3": {"input": 0.005, "output": 0.025},
+}
+_DEFAULT_COST: dict[str, float] = {"input": 0.003, "output": 0.015}  # conservative fallback
+
+
+def estimate_cost_usd(model: str, tokens_in: int, tokens_out: int) -> float:
+    """Estimate the cost of a single request in USD.
+
+    Matches the model name by substring so versioned names like
+    ``claude-haiku-4-5-20251001`` still resolve correctly.
+
+    Args:
+        model:      Model name as passed to the provider.
+        tokens_in:  Number of input (prompt) tokens consumed.
+        tokens_out: Number of output (completion) tokens generated.
+
+    Returns:
+        Estimated cost in USD (may be zero for unknown models).
+    """
+    model_lower = model.lower()
+    rates = _DEFAULT_COST
+    for key, rate in _COST_PER_1K.items():
+        if key in model_lower:
+            rates = rate
+            break
+    return (tokens_in * rates["input"] + tokens_out * rates["output"]) / 1000.0
+
+
+@dataclass
+class SpendRecord:
+    """A single spend event."""
+
+    ts: float
+    provider: str
+    model: str
+    tokens_in: int
+    tokens_out: int
+    cost_usd: float
+    tier: str
+
+
+class BudgetTracker:
+    """Tracks cloud API spend with configurable daily / monthly limits.
+
+    Persists spend records to SQLite (``data/budget.db`` by default).
+    Falls back to in-memory tracking when the database is unavailable —
+    budget enforcement still works; records are lost on restart.
+
+    Limits are read from ``settings``:
+
+    * ``tier_cloud_daily_budget_usd``   — daily ceiling (0 = disabled)
+    * ``tier_cloud_monthly_budget_usd`` — monthly ceiling (0 = disabled)
+
+    Usage::
+
+        tracker = BudgetTracker()
+
+        if tracker.cloud_allowed():
+            # … make cloud API call …
+            tracker.record_spend("anthropic", "claude-haiku-4-5", 100, 200)
+
+        summary = tracker.get_summary()
+        print(summary["daily_usd"], "/", summary["daily_limit_usd"])
+    """
+
+    _DB_PATH = "data/budget.db"
+
+    def __init__(self, db_path: str | None = None) -> None:
+        """Initialise the tracker.
+
+        Args:
+            db_path: Path to the SQLite database.  Defaults to
+                     ``data/budget.db``.  Pass ``":memory:"`` for tests.
+        """
+        self._db_path = db_path or self._DB_PATH
+        self._lock = threading.Lock()
+        self._in_memory: list[SpendRecord] = []
+        self._db_ok = False
+        self._init_db()
+
+    # ── Database initialisation ──────────────────────────────────────────────
+
+    def _init_db(self) -> None:
+        """Create the spend table (and parent directory) if needed."""
+        try:
+            if self._db_path != ":memory:":
+                Path(self._db_path).parent.mkdir(parents=True, exist_ok=True)
+            with self._connect() as conn:
+                conn.execute(
+                    """
+                    CREATE TABLE IF NOT EXISTS cloud_spend (
+                        id         INTEGER PRIMARY KEY AUTOINCREMENT,
+                        ts         REAL    NOT NULL,
+                        provider   TEXT    NOT NULL,
+                        model      TEXT    NOT NULL,
+                        tokens_in  INTEGER NOT NULL DEFAULT 0,
+                        tokens_out INTEGER NOT NULL DEFAULT 0,
+                        cost_usd   REAL    NOT NULL DEFAULT 0.0,
+                        tier       TEXT    NOT NULL DEFAULT 'cloud'
+                    )
+                    """
+                )
+                conn.execute(
+                    "CREATE INDEX IF NOT EXISTS idx_spend_ts ON cloud_spend(ts)"
+                )
+            self._db_ok = True
+            logger.debug("BudgetTracker: SQLite initialised at %s", self._db_path)
+        except Exception as exc:
+            logger.warning(
+                "BudgetTracker: SQLite unavailable, using in-memory fallback: %s", exc
+            )
+
+    def _connect(self) -> sqlite3.Connection:
+        return sqlite3.connect(self._db_path, timeout=5)
+
+    # ── Public API ───────────────────────────────────────────────────────────
+
+    def record_spend(
+        self,
+        provider: str,
+        model: str,
+        tokens_in: int = 0,
+        tokens_out: int = 0,
+        cost_usd: float | None = None,
+        tier: str = "cloud",
+    ) -> float:
+        """Record a cloud API spend event and return the cost recorded.
+
+        Args:
+            provider:   Provider name (e.g. ``"anthropic"``, ``"openai"``).
+            model:      Model name used for the request.
+            tokens_in:  Input token count (prompt).
+            tokens_out: Output token count (completion).
+            cost_usd:   Explicit cost override.  If ``None``, the cost is
+                        estimated from the token counts and model rates.
+            tier:       Tier label for the request (default ``"cloud"``).
+
+        Returns:
+            The cost recorded in USD.
+        """
+        if cost_usd is None:
+            cost_usd = estimate_cost_usd(model, tokens_in, tokens_out)
+
+        ts = time.time()
+        record = SpendRecord(ts, provider, model, tokens_in, tokens_out, cost_usd, tier)
+
+        with self._lock:
+            if self._db_ok:
+                try:
+                    with self._connect() as conn:
+                        conn.execute(
+                            """
+                            INSERT INTO cloud_spend
+                                (ts, provider, model, tokens_in, tokens_out, cost_usd, tier)
+                            VALUES (?, ?, ?, ?, ?, ?, ?)
+                            """,
+                            (ts, provider, model, tokens_in, tokens_out, cost_usd, tier),
+                        )
+                    logger.debug(
+                        "BudgetTracker: recorded %.6f USD (%s/%s, in=%d out=%d tier=%s)",
+                        cost_usd,
+                        provider,
+                        model,
+                        tokens_in,
+                        tokens_out,
+                        tier,
+                    )
+                    return cost_usd
+                except Exception as exc:
+                    logger.warning("BudgetTracker: DB write failed, falling back: %s", exc)
+            self._in_memory.append(record)
+
+        return cost_usd
+
+    def get_daily_spend(self) -> float:
+        """Return total cloud spend for the current UTC day in USD."""
+        today = date.today()
+        since = datetime(today.year, today.month, today.day, tzinfo=UTC).timestamp()
+        return self._query_spend(since)
+
+    def get_monthly_spend(self) -> float:
+        """Return total cloud spend for the current UTC month in USD."""
+        today = date.today()
+        since = datetime(today.year, today.month, 1, tzinfo=UTC).timestamp()
+        return self._query_spend(since)
+
+    def cloud_allowed(self) -> bool:
+        """Return ``True`` if cloud API spend is within configured limits.
+
+        Checks both daily and monthly ceilings.  A limit of ``0`` disables
+        that particular check.
+        """
+        daily_limit = settings.tier_cloud_daily_budget_usd
+        monthly_limit = settings.tier_cloud_monthly_budget_usd
+
+        if daily_limit > 0:
+            daily_spend = self.get_daily_spend()
+            if daily_spend >= daily_limit:
+                logger.warning(
+                    "BudgetTracker: daily cloud budget exhausted (%.4f / %.4f USD)",
+                    daily_spend,
+                    daily_limit,
+                )
+                return False
+
+        if monthly_limit > 0:
+            monthly_spend = self.get_monthly_spend()
+            if monthly_spend >= monthly_limit:
+                logger.warning(
+                    "BudgetTracker: monthly cloud budget exhausted (%.4f / %.4f USD)",
+                    monthly_spend,
+                    monthly_limit,
+                )
+                return False
+
+        return True
+
+    def get_summary(self) -> dict:
+        """Return a spend summary dict suitable for dashboards / logging.
+
+        Keys: ``daily_usd``, ``monthly_usd``, ``daily_limit_usd``,
+        ``monthly_limit_usd``, ``daily_ok``, ``monthly_ok``.
+        """
+        daily = self.get_daily_spend()
+        monthly = self.get_monthly_spend()
+        daily_limit = settings.tier_cloud_daily_budget_usd
+        monthly_limit = settings.tier_cloud_monthly_budget_usd
+        return {
+            "daily_usd": round(daily, 6),
+            "monthly_usd": round(monthly, 6),
+            "daily_limit_usd": daily_limit,
+            "monthly_limit_usd": monthly_limit,
+            "daily_ok": daily_limit <= 0 or daily < daily_limit,
+            "monthly_ok": monthly_limit <= 0 or monthly < monthly_limit,
+        }
+
+    # ── Internal helpers ─────────────────────────────────────────────────────
+
+    def _query_spend(self, since_ts: float) -> float:
+        """Sum ``cost_usd`` for records with ``ts >= since_ts``."""
+        if self._db_ok:
+            try:
+                with self._connect() as conn:
+                    row = conn.execute(
+                        "SELECT COALESCE(SUM(cost_usd), 0.0) FROM cloud_spend WHERE ts >= ?",
+                        (since_ts,),
+                    ).fetchone()
+                    return float(row[0]) if row else 0.0
+            except Exception as exc:
+                logger.warning("BudgetTracker: DB read failed: %s", exc)
+        # In-memory fallback
+        return sum(r.cost_usd for r in self._in_memory if r.ts >= since_ts)
+
+
+# ── Module-level singleton ────────────────────────────────────────────────────
+
+_budget_tracker: BudgetTracker | None = None
+
+
+def get_budget_tracker() -> BudgetTracker:
+    """Get or create the module-level BudgetTracker singleton."""
+    global _budget_tracker
+    if _budget_tracker is None:
+        _budget_tracker = BudgetTracker()
+    return _budget_tracker
--- a/src/infrastructure/models/router.py
+++ b/src/infrastructure/models/router.py
@@ -0,0 +1,426 @@
+"""Three-tier model router — Local 8B / Local 70B / Cloud API Cascade.
+
+Selects the cheapest-sufficient LLM for each request using a heuristic
+task-complexity classifier.  Tier 3 (Cloud API) is only used when Tier 2
+fails or the budget guard allows it.
+
+Tiers
+-----
+Tier 1 — LOCAL_FAST   (Llama 3.1 8B / Hermes 3 8B via Ollama, free, ~0.3-1 s)
+    Navigation, basic interactions, simple decisions.
+
+Tier 2 — LOCAL_HEAVY  (Hermes 3/4 70B via Ollama, free, ~5-10 s for 200 tok)
+    Quest planning, dialogue strategy, complex reasoning.
+
+Tier 3 — CLOUD_API    (Claude / GPT-4o, paid ~$5-15/hr heavy use)
+    Recovery from Tier 2 failures, novel situations, multi-step planning.
+
+Routing logic
+-------------
+1.  Classify the task using keyword / length / context heuristics (no LLM call).
+2.  Route to the appropriate tier.
+3.  On Tier-1 low-quality response → auto-escalate to Tier 2.
+4.  On Tier-2 failure or explicit ``require_cloud=True`` → Tier 3 (if budget allows).
+5.  Log tier used, model, latency, estimated cost for every request.
+
+References:
+  - Issue #882 — Model Tiering Router: Local 8B / Hermes 70B / Cloud API Cascade
+"""
+
+import logging
+import re
+import time
+from enum import StrEnum
+from typing import Any
+
+from config import settings
+
+logger = logging.getLogger(__name__)
+
+
+# ── Tier definitions ──────────────────────────────────────────────────────────
+
+
+class TierLabel(StrEnum):
+    """Three cost-sorted model tiers."""
+
+    LOCAL_FAST = "local_fast"    # 8B local, always hot, free
+    LOCAL_HEAVY = "local_heavy"  # 70B local, free but slower
+    CLOUD_API = "cloud_api"      # Paid cloud backend (Claude / GPT-4o)
+
+
+# ── Default model assignments (overridable via Settings) ──────────────────────
+
+_DEFAULT_TIER_MODELS: dict[TierLabel, str] = {
+    TierLabel.LOCAL_FAST: "llama3.1:8b",
+    TierLabel.LOCAL_HEAVY: "hermes3:70b",
+    TierLabel.CLOUD_API: "claude-haiku-4-5",
+}
+
+# ── Classification vocabulary ─────────────────────────────────────────────────
+
+# Patterns that indicate a Tier-1 (simple) task
+_T1_WORDS: frozenset[str] = frozenset(
+    {
+        "go", "move", "walk", "run",
+        "north", "south", "east", "west", "up", "down", "left", "right",
+        "yes", "no", "ok", "okay",
+        "open", "close", "take", "drop", "look",
+        "pick", "use", "wait", "rest", "save",
+        "attack", "flee", "jump", "crouch",
+        "status", "ping", "list", "show", "get", "check",
+    }
+)
+
+# Patterns that indicate a Tier-2 or Tier-3 task
+_T2_PHRASES: tuple[str, ...] = (
+    "plan", "strategy", "optimize", "optimise",
+    "quest", "stuck", "recover",
+    "negotiate", "persuade", "faction", "reputation",
+    "analyze", "analyse", "evaluate", "decide",
+    "complex", "multi-step", "long-term",
+    "how do i", "what should i do", "help me figure",
+    "what is the best", "recommend", "best way",
+    "explain", "describe in detail", "walk me through",
+    "compare", "design", "implement", "refactor",
+    "debug", "diagnose", "root cause",
+)
+
+# Low-quality response detection patterns
+_LOW_QUALITY_PATTERNS: tuple[re.Pattern, ...] = (
+    re.compile(r"i\s+don'?t\s+know", re.IGNORECASE),
+    re.compile(r"i'm\s+not\s+sure", re.IGNORECASE),
+    re.compile(r"i\s+cannot\s+(help|assist|answer)", re.IGNORECASE),
+    re.compile(r"i\s+apologize", re.IGNORECASE),
+    re.compile(r"as an ai", re.IGNORECASE),
+    re.compile(r"i\s+don'?t\s+have\s+(enough|sufficient)\s+information", re.IGNORECASE),
+)
+
+# Response is definitely low-quality if shorter than this many characters
+_LOW_QUALITY_MIN_CHARS = 20
+# Response is suspicious if shorter than this many chars for a complex task
+_ESCALATION_MIN_CHARS = 60
+
+
+def classify_tier(task: str, context: dict | None = None) -> TierLabel:
+    """Classify a task to the cheapest-sufficient model tier.
+
+    Classification priority (highest wins):
+      1. ``context["require_cloud"] = True`` → CLOUD_API
+      2. Any Tier-2 phrase or stuck/recovery signal → LOCAL_HEAVY
+      3. Short task with only Tier-1 words, no active context → LOCAL_FAST
+      4. Default → LOCAL_HEAVY (safe fallback for unknown tasks)
+
+    Args:
+        task:    Natural-language task or user input.
+        context: Optional context dict.  Recognised keys:
+                 ``require_cloud`` (bool), ``stuck`` (bool),
+                 ``require_t2`` (bool), ``active_quests`` (list),
+                 ``dialogue_active`` (bool), ``combat_active`` (bool).
+
+    Returns:
+        The cheapest ``TierLabel`` sufficient for the task.
+    """
+    ctx = context or {}
+    task_lower = task.lower()
+    words = set(task_lower.split())
+
+    # ── Explicit cloud override ──────────────────────────────────────────────
+    if ctx.get("require_cloud"):
+        logger.debug("classify_tier → CLOUD_API (explicit require_cloud)")
+        return TierLabel.CLOUD_API
+
+    # ── Tier-2 / complexity signals ──────────────────────────────────────────
+    t2_phrase_hit = any(phrase in task_lower for phrase in _T2_PHRASES)
+    t2_word_hit = bool(words & {"plan", "strategy", "optimize", "optimise", "quest",
+                                "stuck", "recover", "analyze", "analyse", "evaluate"})
+    is_stuck = bool(ctx.get("stuck"))
+    require_t2 = bool(ctx.get("require_t2"))
+    long_input = len(task) > 300  # long tasks warrant more capable model
+    deep_context = (
+        len(ctx.get("active_quests", [])) >= 3
+        or ctx.get("dialogue_active")
+    )
+
+    if t2_phrase_hit or t2_word_hit or is_stuck or require_t2 or long_input or deep_context:
+        logger.debug(
+            "classify_tier → LOCAL_HEAVY (phrase=%s word=%s stuck=%s explicit=%s long=%s ctx=%s)",
+            t2_phrase_hit, t2_word_hit, is_stuck, require_t2, long_input, deep_context,
+        )
+        return TierLabel.LOCAL_HEAVY
+
+    # ── Tier-1 signals ───────────────────────────────────────────────────────
+    t1_word_hit = bool(words & _T1_WORDS)
+    task_short = len(task.split()) <= 8
+    no_active_context = (
+        not ctx.get("active_quests")
+        and not ctx.get("dialogue_active")
+        and not ctx.get("combat_active")
+    )
+
+    if t1_word_hit and task_short and no_active_context:
+        logger.debug(
+            "classify_tier → LOCAL_FAST (words=%s short=%s)", t1_word_hit, task_short
+        )
+        return TierLabel.LOCAL_FAST
+
+    # ── Default: LOCAL_HEAVY (safe for anything unclassified) ────────────────
+    logger.debug("classify_tier → LOCAL_HEAVY (default)")
+    return TierLabel.LOCAL_HEAVY
+
+
+def _is_low_quality(content: str, tier: TierLabel) -> bool:
+    """Return True if the response looks like it should be escalated.
+
+    Used for automatic Tier-1 → Tier-2 escalation.
+
+    Args:
+        content: LLM response text.
+        tier:    The tier that produced the response.
+
+    Returns:
+        True if the response is likely too low-quality to be useful.
+    """
+    if not content or not content.strip():
+        return True
+
+    stripped = content.strip()
+
+    # Too short to be useful
+    if len(stripped) < _LOW_QUALITY_MIN_CHARS:
+        return True
+
+    # Insufficient for a supposedly complex-enough task
+    if tier == TierLabel.LOCAL_FAST and len(stripped) < _ESCALATION_MIN_CHARS:
+        return True
+
+    # Matches known "I can't help" patterns
+    for pattern in _LOW_QUALITY_PATTERNS:
+        if pattern.search(stripped):
+            return True
+
+    return False
+
+
+class TieredModelRouter:
+    """Routes LLM requests across the Local 8B / Local 70B / Cloud API tiers.
+
+    Wraps CascadeRouter with:
+    - Heuristic tier classification via ``classify_tier()``
+    - Automatic Tier-1 → Tier-2 escalation on low-quality responses
+    - Cloud-tier budget guard via ``BudgetTracker``
+    - Per-request logging: tier, model, latency, estimated cost
+
+    Usage::
+
+        router = TieredModelRouter()
+
+        result = await router.route(
+            task="Walk to the next room",
+            context={},
+        )
+        print(result["content"], result["tier"])  # "Move north.", "local_fast"
+
+        # Force heavy tier
+        result = await router.route(
+            task="Plan the optimal path to become Hortator",
+            context={"require_t2": True},
+        )
+    """
+
+    def __init__(
+        self,
+        cascade: Any | None = None,
+        budget_tracker: Any | None = None,
+        tier_models: dict[TierLabel, str] | None = None,
+        auto_escalate: bool = True,
+    ) -> None:
+        """Initialise the tiered router.
+
+        Args:
+            cascade:        CascadeRouter instance.  If ``None``, the
+                            singleton from ``get_router()`` is used lazily.
+            budget_tracker: BudgetTracker instance.  If ``None``, the
+                            singleton from ``get_budget_tracker()`` is used.
+            tier_models:    Override default model names per tier.
+            auto_escalate:  When ``True``, low-quality Tier-1 responses
+                            automatically retry on Tier-2.
+        """
+        self._cascade = cascade
+        self._budget = budget_tracker
+        self._tier_models: dict[TierLabel, str] = dict(_DEFAULT_TIER_MODELS)
+        self._auto_escalate = auto_escalate
+
+        # Apply settings-level overrides (can still be overridden per-instance)
+        if settings.tier_local_fast_model:
+            self._tier_models[TierLabel.LOCAL_FAST] = settings.tier_local_fast_model
+        if settings.tier_local_heavy_model:
+            self._tier_models[TierLabel.LOCAL_HEAVY] = settings.tier_local_heavy_model
+        if settings.tier_cloud_model:
+            self._tier_models[TierLabel.CLOUD_API] = settings.tier_cloud_model
+
+        if tier_models:
+            self._tier_models.update(tier_models)
+
+    # ── Lazy singletons ──────────────────────────────────────────────────────
+
+    def _get_cascade(self) -> Any:
+        if self._cascade is None:
+            from infrastructure.router.cascade import get_router
+            self._cascade = get_router()
+        return self._cascade
+
+    def _get_budget(self) -> Any:
+        if self._budget is None:
+            from infrastructure.models.budget import get_budget_tracker
+            self._budget = get_budget_tracker()
+        return self._budget
+
+    # ── Public interface ─────────────────────────────────────────────────────
+
+    def classify(self, task: str, context: dict | None = None) -> TierLabel:
+        """Classify a task without routing.  Useful for telemetry."""
+        return classify_tier(task, context)
+
+    async def route(
+        self,
+        task: str,
+        context: dict | None = None,
+        messages: list[dict] | None = None,
+        temperature: float = 0.3,
+        max_tokens: int | None = None,
+    ) -> dict:
+        """Route a task to the appropriate model tier.
+
+        Builds a minimal messages list if ``messages`` is not provided.
+        The result always includes a ``tier`` key indicating which tier
+        ultimately handled the request.
+
+        Args:
+            task:        Natural-language task description.
+            context:     Task context dict (see ``classify_tier()``).
+            messages:    Pre-built OpenAI-compatible messages list.  If
+                         provided, ``task`` is only used for classification.
+            temperature: Sampling temperature (default 0.3).
+            max_tokens:  Maximum tokens to generate.
+
+        Returns:
+            Dict with at minimum: ``content``, ``provider``, ``model``,
+            ``tier``, ``latency_ms``.  May include ``cost_usd`` when a
+            cloud request is recorded.
+
+        Raises:
+            RuntimeError: If all available tiers are exhausted.
+        """
+        ctx = context or {}
+        tier = self.classify(task, ctx)
+        msgs = messages or [{"role": "user", "content": task}]
+
+        # ── Tier 1 attempt ───────────────────────────────────────────────────
+        if tier == TierLabel.LOCAL_FAST:
+            result = await self._complete_tier(
+                TierLabel.LOCAL_FAST, msgs, temperature, max_tokens
+            )
+            if self._auto_escalate and _is_low_quality(result.get("content", ""), TierLabel.LOCAL_FAST):
+                logger.info(
+                    "TieredModelRouter: Tier-1 response low quality, escalating to Tier-2 "
+                    "(task=%r content_len=%d)",
+                    task[:80],
+                    len(result.get("content", "")),
+                )
+                tier = TierLabel.LOCAL_HEAVY
+                result = await self._complete_tier(
+                    TierLabel.LOCAL_HEAVY, msgs, temperature, max_tokens
+                )
+            return result
+
+        # ── Tier 2 attempt ───────────────────────────────────────────────────
+        if tier == TierLabel.LOCAL_HEAVY:
+            try:
+                return await self._complete_tier(
+                    TierLabel.LOCAL_HEAVY, msgs, temperature, max_tokens
+                )
+            except Exception as exc:
+                logger.warning(
+                    "TieredModelRouter: Tier-2 failed (%s) — escalating to cloud", exc
+                )
+                tier = TierLabel.CLOUD_API
+
+        # ── Tier 3 (Cloud) ───────────────────────────────────────────────────
+        budget = self._get_budget()
+        if not budget.cloud_allowed():
+            raise RuntimeError(
+                "Cloud API tier requested but budget limit reached — "
+                "increase tier_cloud_daily_budget_usd or tier_cloud_monthly_budget_usd"
+            )
+
+        result = await self._complete_tier(
+            TierLabel.CLOUD_API, msgs, temperature, max_tokens
+        )
+
+        # Record cloud spend if token info is available
+        usage = result.get("usage", {})
+        if usage:
+            cost = budget.record_spend(
+                provider=result.get("provider", "unknown"),
+                model=result.get("model", self._tier_models[TierLabel.CLOUD_API]),
+                tokens_in=usage.get("prompt_tokens", 0),
+                tokens_out=usage.get("completion_tokens", 0),
+                tier=TierLabel.CLOUD_API,
+            )
+            result["cost_usd"] = cost
+
+        return result
+
+    # ── Internal helpers ─────────────────────────────────────────────────────
+
+    async def _complete_tier(
+        self,
+        tier: TierLabel,
+        messages: list[dict],
+        temperature: float,
+        max_tokens: int | None,
+    ) -> dict:
+        """Dispatch a single inference request for the given tier."""
+        model = self._tier_models[tier]
+        cascade = self._get_cascade()
+        start = time.monotonic()
+
+        logger.info(
+            "TieredModelRouter: tier=%s model=%s messages=%d",
+            tier,
+            model,
+            len(messages),
+        )
+
+        result = await cascade.complete(
+            messages=messages,
+            model=model,
+            temperature=temperature,
+            max_tokens=max_tokens,
+        )
+
+        elapsed_ms = (time.monotonic() - start) * 1000
+        result["tier"] = tier
+        result.setdefault("latency_ms", elapsed_ms)
+
+        logger.info(
+            "TieredModelRouter: done tier=%s model=%s latency_ms=%.0f",
+            tier,
+            result.get("model", model),
+            elapsed_ms,
+        )
+        return result
+
+
+# ── Module-level singleton ────────────────────────────────────────────────────
+
+_tiered_router: TieredModelRouter | None = None
+
+
+def get_tiered_router() -> TieredModelRouter:
+    """Get or create the module-level TieredModelRouter singleton."""
+    global _tiered_router
+    if _tiered_router is None:
+        _tiered_router = TieredModelRouter()
+    return _tiered_router
--- a/src/infrastructure/self_correction.py
+++ b/src/infrastructure/self_correction.py
@@ -0,0 +1,245 @@
+"""Self-correction event logger.
+
+Records instances where the agent detected its own errors and the steps
+it took to correct them. Used by the Self-Correction Dashboard to visualise
+these events and surface recurring failure patterns.
+
+Usage::
+
+    from infrastructure.self_correction import log_self_correction, get_corrections, get_patterns
+
+    log_self_correction(
+        source="agentic_loop",
+        original_intent="Execute step 3: deploy service",
+        detected_error="ConnectionRefusedError: port 8080 unavailable",
+        correction_strategy="Retry on alternate port 8081",
+        final_outcome="Success on retry",
+        task_id="abc123",
+    )
+"""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+import uuid
+from collections.abc import Generator
+from contextlib import closing, contextmanager
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Database
+# ---------------------------------------------------------------------------
+
+_DB_PATH: Path | None = None
+
+
+def _get_db_path() -> Path:
+    global _DB_PATH
+    if _DB_PATH is None:
+        from config import settings
+
+        _DB_PATH = Path(settings.repo_root) / "data" / "self_correction.db"
+    return _DB_PATH
+
+
+@contextmanager
+def _get_db() -> Generator[sqlite3.Connection, None, None]:
+    db_path = _get_db_path()
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    with closing(sqlite3.connect(str(db_path))) as conn:
+        conn.row_factory = sqlite3.Row
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS self_correction_events (
+                id          TEXT PRIMARY KEY,
+                source      TEXT NOT NULL,
+                task_id     TEXT DEFAULT '',
+                original_intent   TEXT NOT NULL,
+                detected_error    TEXT NOT NULL,
+                correction_strategy TEXT NOT NULL,
+                final_outcome TEXT NOT NULL,
+                outcome_status TEXT DEFAULT 'success',
+                error_type  TEXT DEFAULT '',
+                created_at  TEXT DEFAULT (datetime('now'))
+            )
+        """)
+        conn.execute(
+            "CREATE INDEX IF NOT EXISTS idx_sc_created ON self_correction_events(created_at)"
+        )
+        conn.execute(
+            "CREATE INDEX IF NOT EXISTS idx_sc_error_type ON self_correction_events(error_type)"
+        )
+        conn.commit()
+        yield conn
+
+
+# ---------------------------------------------------------------------------
+# Write
+# ---------------------------------------------------------------------------
+
+
+def log_self_correction(
+    *,
+    source: str,
+    original_intent: str,
+    detected_error: str,
+    correction_strategy: str,
+    final_outcome: str,
+    task_id: str = "",
+    outcome_status: str = "success",
+    error_type: str = "",
+) -> str:
+    """Record a self-correction event and return its ID.
+
+    Args:
+        source:               Module or component that triggered the correction.
+        original_intent:      What the agent was trying to do.
+        detected_error:       The error or problem that was detected.
+        correction_strategy:  How the agent attempted to correct the error.
+        final_outcome:        What the result of the correction attempt was.
+        task_id:              Optional task/session ID for correlation.
+        outcome_status:       'success', 'partial', or 'failed'.
+        error_type:           Short category label for pattern analysis (e.g.
+                              'ConnectionError', 'TimeoutError').
+
+    Returns:
+        The ID of the newly created record.
+    """
+    event_id = str(uuid.uuid4())
+    if not error_type:
+        # Derive a simple type from the first word of the detected error
+        error_type = detected_error.split(":")[0].strip()[:64]
+
+    try:
+        with _get_db() as conn:
+            conn.execute(
+                """
+                INSERT INTO self_correction_events
+                    (id, source, task_id, original_intent, detected_error,
+                     correction_strategy, final_outcome, outcome_status, error_type)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    event_id,
+                    source,
+                    task_id,
+                    original_intent[:2000],
+                    detected_error[:2000],
+                    correction_strategy[:2000],
+                    final_outcome[:2000],
+                    outcome_status,
+                    error_type,
+                ),
+            )
+            conn.commit()
+        logger.info(
+            "Self-correction logged [%s] source=%s error_type=%s status=%s",
+            event_id[:8],
+            source,
+            error_type,
+            outcome_status,
+        )
+    except Exception as exc:
+        logger.warning("Failed to log self-correction event: %s", exc)
+
+    return event_id
+
+
+# ---------------------------------------------------------------------------
+# Read
+# ---------------------------------------------------------------------------
+
+
+def get_corrections(limit: int = 50) -> list[dict]:
+    """Return the most recent self-correction events, newest first."""
+    try:
+        with _get_db() as conn:
+            rows = conn.execute(
+                """
+                SELECT * FROM self_correction_events
+                ORDER BY created_at DESC
+                LIMIT ?
+                """,
+                (limit,),
+            ).fetchall()
+            return [dict(r) for r in rows]
+    except Exception as exc:
+        logger.warning("Failed to fetch self-correction events: %s", exc)
+        return []
+
+
+def get_patterns(top_n: int = 10) -> list[dict]:
+    """Return the most common recurring error types with counts.
+
+    Each entry has:
+    - error_type: category label
+    - count: total occurrences
+    - success_count: corrected successfully
+    - failed_count: correction also failed
+    - last_seen: ISO timestamp of most recent occurrence
+    """
+    try:
+        with _get_db() as conn:
+            rows = conn.execute(
+                """
+                SELECT
+                    error_type,
+                    COUNT(*) AS count,
+                    SUM(CASE WHEN outcome_status = 'success' THEN 1 ELSE 0 END) AS success_count,
+                    SUM(CASE WHEN outcome_status = 'failed'  THEN 1 ELSE 0 END) AS failed_count,
+                    MAX(created_at) AS last_seen
+                FROM self_correction_events
+                GROUP BY error_type
+                ORDER BY count DESC
+                LIMIT ?
+                """,
+                (top_n,),
+            ).fetchall()
+            return [dict(r) for r in rows]
+    except Exception as exc:
+        logger.warning("Failed to fetch self-correction patterns: %s", exc)
+        return []
+
+
+def get_stats() -> dict:
+    """Return aggregate statistics for the summary panel."""
+    try:
+        with _get_db() as conn:
+            row = conn.execute(
+                """
+                SELECT
+                    COUNT(*) AS total,
+                    SUM(CASE WHEN outcome_status = 'success' THEN 1 ELSE 0 END) AS success_count,
+                    SUM(CASE WHEN outcome_status = 'partial' THEN 1 ELSE 0 END) AS partial_count,
+                    SUM(CASE WHEN outcome_status = 'failed'  THEN 1 ELSE 0 END) AS failed_count,
+                    COUNT(DISTINCT error_type) AS unique_error_types,
+                    COUNT(DISTINCT source)     AS sources
+                FROM self_correction_events
+                """
+            ).fetchone()
+            if row is None:
+                return _empty_stats()
+            d = dict(row)
+            total = d.get("total") or 0
+            if total:
+                d["success_rate"] = round((d.get("success_count") or 0) / total * 100)
+            else:
+                d["success_rate"] = 0
+            return d
+    except Exception as exc:
+        logger.warning("Failed to fetch self-correction stats: %s", exc)
+        return _empty_stats()
+
+
+def _empty_stats() -> dict:
+    return {
+        "total": 0,
+        "success_count": 0,
+        "partial_count": 0,
+        "failed_count": 0,
+        "unique_error_types": 0,
+        "sources": 0,
+        "success_rate": 0,
+    }
--- a/src/integrations/chat_bridge/vendors/init.py
+++ b/src/integrations/chat_bridge/vendors/init.py
@@ -0,0 +1 @@
+"""Vendor-specific chat platform adapters (e.g. Discord) for the chat bridge."""
--- a/src/self_coding/init.py
+++ b/src/self_coding/init.py
@@ -0,0 +1,7 @@
+"""Self-coding package — Timmy's self-modification capability.
+
+Provides the branch→edit→test→commit/revert loop that allows Timmy
+to propose and apply code changes autonomously, gated by the test suite.
+
+Main entry point: ``self_coding.self_modify.loop``
+"""
--- a/src/self_coding/gitea_client.py
+++ b/src/self_coding/gitea_client.py
@@ -0,0 +1,129 @@
+"""Gitea REST client — thin wrapper for PR creation and issue commenting.
+
+Uses ``settings.gitea_url``, ``settings.gitea_token``, and
+``settings.gitea_repo`` (owner/repo) from config.  Degrades gracefully
+when the token is absent or the server is unreachable.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class PullRequest:
+    """Minimal representation of a created pull request."""
+
+    number: int
+    title: str
+    html_url: str
+
+
+class GiteaClient:
+    """HTTP client for Gitea's REST API v1.
+
+    All methods return structured results and never raise — errors are
+    logged at WARNING level and indicated via return value.
+    """
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        token: str | None = None,
+        repo: str | None = None,
+    ) -> None:
+        from config import settings
+
+        self._base_url = (base_url or settings.gitea_url).rstrip("/")
+        self._token = token or settings.gitea_token
+        self._repo = repo or settings.gitea_repo
+
+    # ── internal ────────────────────────────────────────────────────────────
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"token {self._token}",
+            "Content-Type": "application/json",
+        }
+
+    def _api(self, path: str) -> str:
+        return f"{self._base_url}/api/v1/{path.lstrip('/')}"
+
+    # ── public API ───────────────────────────────────────────────────────────
+
+    def create_pull_request(
+        self,
+        title: str,
+        body: str,
+        head: str,
+        base: str = "main",
+    ) -> PullRequest | None:
+        """Open a pull request.
+
+        Args:
+            title: PR title (keep under 70 chars).
+            body:  PR body in markdown.
+            head:  Source branch (e.g. ``self-modify/issue-983``).
+            base:  Target branch (default ``main``).
+
+        Returns:
+            A ``PullRequest`` dataclass on success, ``None`` on failure.
+        """
+        if not self._token:
+            logger.warning("Gitea token not configured — skipping PR creation")
+            return None
+
+        try:
+            import requests as _requests
+
+            resp = _requests.post(
+                self._api(f"repos/{self._repo}/pulls"),
+                headers=self._headers(),
+                json={"title": title, "body": body, "head": head, "base": base},
+                timeout=15,
+            )
+            resp.raise_for_status()
+            data = resp.json()
+            pr = PullRequest(
+                number=data["number"],
+                title=data["title"],
+                html_url=data["html_url"],
+            )
+            logger.info("PR #%d created: %s", pr.number, pr.html_url)
+            return pr
+        except Exception as exc:
+            logger.warning("Failed to create PR: %s", exc)
+            return None
+
+    def add_issue_comment(self, issue_number: int, body: str) -> bool:
+        """Post a comment on an issue or PR.
+
+        Returns:
+            True on success, False on failure.
+        """
+        if not self._token:
+            logger.warning("Gitea token not configured — skipping issue comment")
+            return False
+
+        try:
+            import requests as _requests
+
+            resp = _requests.post(
+                self._api(f"repos/{self._repo}/issues/{issue_number}/comments"),
+                headers=self._headers(),
+                json={"body": body},
+                timeout=15,
+            )
+            resp.raise_for_status()
+            logger.info("Comment posted on issue #%d", issue_number)
+            return True
+        except Exception as exc:
+            logger.warning("Failed to post comment on issue #%d: %s", issue_number, exc)
+            return False
+
+
+# Module-level singleton
+gitea_client = GiteaClient()
--- a/src/self_coding/self_modify/init.py
+++ b/src/self_coding/self_modify/init.py
@@ -0,0 +1 @@
+"""Self-modification loop sub-package."""
--- a/src/self_coding/self_modify/loop.py
+++ b/src/self_coding/self_modify/loop.py
@@ -0,0 +1,301 @@
+"""Self-modification loop — branch → edit → test → commit/revert.
+
+Timmy's self-coding capability, restored after deletion in
+Operation Darling Purge (commit 584eeb679e88).
+
+## Cycle
+1. **Branch** — create ``self-modify/<slug>`` from ``main``
+2. **Edit**   — apply the proposed change (patch string or callable)
+3. **Test**   — run ``pytest tests/ -x -q``; never commit on failure
+4. **Commit** — stage and commit on green; revert branch on red
+5. **PR**     — open a Gitea pull request (requires no direct push to main)
+
+## Guards
+- Never push directly to ``main`` or ``master``
+- All changes land via PR (enforced by ``_guard_branch``)
+- Test gate is mandatory; ``skip_tests=True`` is for unit-test use only
+- Commits only happen when ``pytest tests/ -x -q`` exits 0
+
+## Usage::
+
+    from self_coding.self_modify.loop import SelfModifyLoop
+
+    loop = SelfModifyLoop()
+    result = await loop.run(
+        slug="add-hello-tool",
+        description="Add hello() convenience tool",
+        edit_fn=my_edit_function,  # callable(repo_root: str) -> None
+    )
+    if result.success:
+        print(f"PR: {result.pr_url}")
+    else:
+        print(f"Failed: {result.error}")
+"""
+
+from __future__ import annotations
+
+import logging
+import subprocess
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from config import settings
+
+logger = logging.getLogger(__name__)
+
+# Branches that must never receive direct commits
+_PROTECTED_BRANCHES = frozenset({"main", "master", "develop"})
+
+# Test command used as the commit gate
+_TEST_COMMAND = ["pytest", "tests/", "-x", "-q", "--tb=short"]
+
+# Max time (seconds) to wait for the test suite
+_TEST_TIMEOUT = 300
+
+
+@dataclass
+class LoopResult:
+    """Result from one self-modification cycle."""
+
+    success: bool
+    branch: str = ""
+    commit_sha: str = ""
+    pr_url: str = ""
+    pr_number: int = 0
+    test_output: str = ""
+    error: str = ""
+    elapsed_ms: float = 0.0
+    metadata: dict = field(default_factory=dict)
+
+
+class SelfModifyLoop:
+    """Orchestrate branch → edit → test → commit/revert → PR.
+
+    Args:
+        repo_root: Absolute path to the git repository (defaults to
+                   ``settings.repo_root``).
+        remote:    Git remote name (default ``origin``).
+        base_branch: Branch to fork from and target for the PR
+                     (default ``main``).
+    """
+
+    def __init__(
+        self,
+        repo_root: str | None = None,
+        remote: str = "origin",
+        base_branch: str = "main",
+    ) -> None:
+        self._repo_root = Path(repo_root or settings.repo_root)
+        self._remote = remote
+        self._base_branch = base_branch
+
+    # ── public ──────────────────────────────────────────────────────────────
+
+    async def run(
+        self,
+        slug: str,
+        description: str,
+        edit_fn: Callable[[str], None],
+        issue_number: int | None = None,
+        skip_tests: bool = False,
+    ) -> LoopResult:
+        """Execute one full self-modification cycle.
+
+        Args:
+            slug:         Short identifier used for the branch name
+                          (e.g. ``"add-hello-tool"``).
+            description:  Human-readable description for commit message
+                          and PR body.
+            edit_fn:      Callable that receives the repo root path (str)
+                          and applies the desired code changes in-place.
+            issue_number: Optional Gitea issue number to reference in PR.
+            skip_tests:   If ``True``, skip the test gate (unit-test use
+                          only — never use in production).
+
+        Returns:
+            :class:`LoopResult` describing the outcome.
+        """
+        start = time.time()
+        branch = f"self-modify/{slug}"
+
+        try:
+            self._guard_branch(branch)
+            self._checkout_base()
+            self._create_branch(branch)
+
+            try:
+                edit_fn(str(self._repo_root))
+            except Exception as exc:
+                self._revert_branch(branch)
+                return LoopResult(
+                    success=False,
+                    branch=branch,
+                    error=f"edit_fn raised: {exc}",
+                    elapsed_ms=self._elapsed(start),
+                )
+
+            if not skip_tests:
+                test_output, passed = self._run_tests()
+                if not passed:
+                    self._revert_branch(branch)
+                    return LoopResult(
+                        success=False,
+                        branch=branch,
+                        test_output=test_output,
+                        error="Tests failed — branch reverted",
+                        elapsed_ms=self._elapsed(start),
+                    )
+            else:
+                test_output = "(tests skipped)"
+
+            sha = self._commit_all(description)
+            self._push_branch(branch)
+
+            pr = self._create_pr(
+                branch=branch,
+                description=description,
+                test_output=test_output,
+                issue_number=issue_number,
+            )
+
+            return LoopResult(
+                success=True,
+                branch=branch,
+                commit_sha=sha,
+                pr_url=pr.html_url if pr else "",
+                pr_number=pr.number if pr else 0,
+                test_output=test_output,
+                elapsed_ms=self._elapsed(start),
+            )
+
+        except Exception as exc:
+            logger.warning("Self-modify loop failed: %s", exc)
+            return LoopResult(
+                success=False,
+                branch=branch,
+                error=str(exc),
+                elapsed_ms=self._elapsed(start),
+            )
+
+    # ── private helpers ──────────────────────────────────────────────────────
+
+    @staticmethod
+    def _elapsed(start: float) -> float:
+        return (time.time() - start) * 1000
+
+    def _git(self, *args: str, check: bool = True) -> subprocess.CompletedProcess:
+        """Run a git command in the repo root."""
+        cmd = ["git", *args]
+        logger.debug("git %s", " ".join(args))
+        return subprocess.run(
+            cmd,
+            cwd=str(self._repo_root),
+            capture_output=True,
+            text=True,
+            check=check,
+        )
+
+    def _guard_branch(self, branch: str) -> None:
+        """Raise if the target branch is a protected branch name."""
+        if branch in _PROTECTED_BRANCHES:
+            raise ValueError(
+                f"Refusing to operate on protected branch '{branch}'. "
+                "All self-modifications must go via PR."
+            )
+
+    def _checkout_base(self) -> None:
+        """Checkout the base branch and pull latest."""
+        self._git("checkout", self._base_branch)
+        # Best-effort pull; ignore failures (e.g. no remote configured)
+        self._git("pull", self._remote, self._base_branch, check=False)
+
+    def _create_branch(self, branch: str) -> None:
+        """Create and checkout a new branch, deleting an old one if needed."""
+        # Delete local branch if it already exists (stale prior attempt)
+        self._git("branch", "-D", branch, check=False)
+        self._git("checkout", "-b", branch)
+        logger.info("Created branch: %s", branch)
+
+    def _revert_branch(self, branch: str) -> None:
+        """Checkout base and delete the failed branch."""
+        try:
+            self._git("checkout", self._base_branch, check=False)
+            self._git("branch", "-D", branch, check=False)
+            logger.info("Reverted and deleted branch: %s", branch)
+        except Exception as exc:
+            logger.warning("Failed to revert branch %s: %s", branch, exc)
+
+    def _run_tests(self) -> tuple[str, bool]:
+        """Run the test suite. Returns (output, passed)."""
+        logger.info("Running test suite: %s", " ".join(_TEST_COMMAND))
+        try:
+            result = subprocess.run(
+                _TEST_COMMAND,
+                cwd=str(self._repo_root),
+                capture_output=True,
+                text=True,
+                timeout=_TEST_TIMEOUT,
+            )
+            output = (result.stdout + "\n" + result.stderr).strip()
+            passed = result.returncode == 0
+            logger.info(
+                "Test suite %s (exit %d)", "PASSED" if passed else "FAILED", result.returncode
+            )
+            return output, passed
+        except subprocess.TimeoutExpired:
+            msg = f"Test suite timed out after {_TEST_TIMEOUT}s"
+            logger.warning(msg)
+            return msg, False
+        except FileNotFoundError:
+            msg = "pytest not found on PATH"
+            logger.warning(msg)
+            return msg, False
+
+    def _commit_all(self, message: str) -> str:
+        """Stage all changes and create a commit. Returns the new SHA."""
+        self._git("add", "-A")
+        self._git("commit", "-m", message)
+        result = self._git("rev-parse", "HEAD")
+        sha = result.stdout.strip()
+        logger.info("Committed: %s  sha=%s", message[:60], sha[:12])
+        return sha
+
+    def _push_branch(self, branch: str) -> None:
+        """Push the branch to the remote."""
+        self._git("push", "-u", self._remote, branch)
+        logger.info("Pushed branch: %s -> %s", branch, self._remote)
+
+    def _create_pr(
+        self,
+        branch: str,
+        description: str,
+        test_output: str,
+        issue_number: int | None,
+    ):
+        """Open a Gitea PR. Returns PullRequest or None on failure."""
+        from self_coding.gitea_client import GiteaClient
+
+        client = GiteaClient()
+
+        issue_ref = f"\n\nFixes #{issue_number}" if issue_number else ""
+        test_section = (
+            f"\n\n## Test results\n```\n{test_output[:2000]}\n```"
+            if test_output and test_output != "(tests skipped)"
+            else ""
+        )
+
+        body = (
+            f"## Summary\n{description}"
+            f"{issue_ref}"
+            f"{test_section}"
+            "\n\n🤖 Generated by Timmy's self-modification loop"
+        )
+
+        return client.create_pull_request(
+            title=f"[self-modify] {description[:60]}",
+            body=body,
+            head=branch,
+            base=self._base_branch,
+        )
--- a/src/timmy/agent.py
+++ b/src/timmy/agent.py
@@ -301,6 +301,26 @@ def create_timmy(

        return GrokBackend()

+    if resolved == "airllm":
+        # AirLLM requires Apple Silicon.  On any other platform (Intel Mac, Linux,
+        # Windows) or when the package is not installed, degrade silently to Ollama.
+        from timmy.backends import is_apple_silicon
+
+        if not is_apple_silicon():
+            logger.warning(
+                "TIMMY_MODEL_BACKEND=airllm requested but not running on Apple Silicon "
+                "— falling back to Ollama"
+            )
+        else:
+            try:
+                import airllm  # noqa: F401
+            except ImportError:
+                logger.warning(
+                    "AirLLM not installed — falling back to Ollama. "
+                    "Install with: pip install 'airllm[mlx]'"
+                )
+        # Fall through to Ollama in all cases (AirLLM integration is scaffolded)
+
    # Default: Ollama via Agno.
    model_name, is_fallback = _resolve_model_with_fallback(
        requested_model=None,
--- a/src/timmy/agentic_loop.py
+++ b/src/timmy/agentic_loop.py
@@ -312,6 +312,13 @@ async def _handle_step_failure(
                "adaptation": step.result[:200],
            },
        )
+        _log_self_correction(
+            task_id=task_id,
+            step_desc=step_desc,
+            exc=exc,
+            outcome=step.result,
+            outcome_status="success",
+        )
        if on_progress:
            await on_progress(f"[Adapted] {step_desc}", step_num, total_steps)
    except Exception as adapt_exc:  # broad catch intentional
@@ -325,9 +332,42 @@ async def _handle_step_failure(
                duration_ms=int((time.monotonic() - step_start) * 1000),
            )
        )
+        _log_self_correction(
+            task_id=task_id,
+            step_desc=step_desc,
+            exc=exc,
+            outcome=f"Adaptation also failed: {adapt_exc}",
+            outcome_status="failed",
+        )
        completed_results.append(f"Step {step_num}: FAILED")


+def _log_self_correction(
+    *,
+    task_id: str,
+    step_desc: str,
+    exc: Exception,
+    outcome: str,
+    outcome_status: str,
+) -> None:
+    """Best-effort: log a self-correction event (never raises)."""
+    try:
+        from infrastructure.self_correction import log_self_correction
+
+        log_self_correction(
+            source="agentic_loop",
+            original_intent=step_desc,
+            detected_error=f"{type(exc).__name__}: {exc}",
+            correction_strategy="Adaptive re-plan via LLM",
+            final_outcome=outcome[:500],
+            task_id=task_id,
+            outcome_status=outcome_status,
+            error_type=type(exc).__name__,
+        )
+    except Exception as log_exc:
+        logger.debug("Self-correction log failed: %s", log_exc)
+
+
 # ---------------------------------------------------------------------------
 # Core loop
 # ---------------------------------------------------------------------------
--- a/src/timmy/cli.py
+++ b/src/timmy/cli.py
@@ -1,3 +1,4 @@
+"""Typer CLI entry point for the ``timmy`` command (chat, think, status)."""
 import asyncio
 import logging
 import subprocess
--- a/src/timmy/kimi_delegation.py
+++ b/src/timmy/kimi_delegation.py
@@ -28,6 +28,9 @@ KIMI_READY_LABEL = "kimi-ready"
 # Label colour for the kimi-ready label (dark teal)
 KIMI_LABEL_COLOR = "#006b75"

+# Maximum number of concurrent active (open) Kimi-delegated issues
+KIMI_MAX_ACTIVE_ISSUES = 3
+
 # Keywords that suggest a task exceeds local capacity
 _HEAVY_RESEARCH_KEYWORDS = frozenset(
    {
@@ -176,6 +179,38 @@ async def _get_or_create_label(
    return None


+async def _count_active_kimi_issues(
+    client: Any,
+    base_url: str,
+    headers: dict[str, str],
+    repo: str,
+) -> int:
+    """Count open issues that carry the `kimi-ready` label.
+
+    Args:
+        client: httpx.AsyncClient instance.
+        base_url: Gitea API base URL.
+        headers: Auth headers.
+        repo: owner/repo string.
+
+    Returns:
+        Number of open kimi-ready issues, or 0 on error (fail-open to avoid
+        blocking delegation when Gitea is unreachable).
+    """
+    try:
+        resp = await client.get(
+            f"{base_url}/repos/{repo}/issues",
+            headers=headers,
+            params={"state": "open", "type": "issues", "labels": KIMI_READY_LABEL, "limit": 50},
+        )
+        if resp.status_code == 200:
+            return len(resp.json())
+        logger.warning("count_active_kimi_issues: unexpected status %s", resp.status_code)
+    except Exception as exc:
+        logger.warning("count_active_kimi_issues failed: %s", exc)
+    return 0
+
+
 async def create_kimi_research_issue(
    task: str,
    context: str,
@@ -217,6 +252,22 @@ async def create_kimi_research_issue(
        async with httpx.AsyncClient(timeout=15) as client:
            label_id = await _get_or_create_label(client, base_url, headers, repo)

+            active_count = await _count_active_kimi_issues(client, base_url, headers, repo)
+            if active_count >= KIMI_MAX_ACTIVE_ISSUES:
+                logger.warning(
+                    "Kimi delegation cap reached (%d/%d active) — skipping: %s",
+                    active_count,
+                    KIMI_MAX_ACTIVE_ISSUES,
+                    task[:60],
+                )
+                return {
+                    "success": False,
+                    "error": (
+                        f"Kimi delegation cap reached: {active_count} active issues "
+                        f"(max {KIMI_MAX_ACTIVE_ISSUES}). Resolve existing issues first."
+                    ),
+                }
+
            body = _build_research_template(task, context, question, priority)
            issue_payload: dict[str, Any] = {"title": task, "body": body}
            if label_id is not None:
--- a/src/timmy/research.py
+++ b/src/timmy/research.py
@@ -0,0 +1,528 @@
+"""Research Orchestrator — autonomous, sovereign research pipeline.
+
+Chains all six steps of the research workflow with local-first execution:
+
+    Step 0  Cache   — check semantic memory (SQLite, instant, zero API cost)
+    Step 1  Scope   — load a research template from skills/research/
+    Step 2  Query   — slot-fill template + formulate 5-15 search queries via Ollama
+    Step 3  Search  — execute queries via web_search (SerpAPI or fallback)
+    Step 4  Fetch   — download + extract full pages via web_fetch (trafilatura)
+    Step 5  Synth   — compress findings into a structured report via cascade
+    Step 6  Deliver — store to semantic memory; optionally save to docs/research/
+
+Cascade tiers for synthesis (spec §4):
+    Tier 4  SQLite semantic cache  — instant, free, covers ~80% after warm-up
+    Tier 3  Ollama (qwen3:14b)     — local, free, good quality
+    Tier 2  Claude API (haiku)     — cloud fallback, cheap, set ANTHROPIC_API_KEY
+    Tier 1  (future) Groq          — free-tier rate-limited, tracked in #980
+
+All optional services degrade gracefully per project conventions.
+
+Refs #972 (governing spec), #975 (ResearchOrchestrator sub-issue).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import re
+import textwrap
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# Optional memory imports — available at module level so tests can patch them.
+try:
+    from timmy.memory_system import SemanticMemory, store_memory
+except Exception:  # pragma: no cover
+    SemanticMemory = None  # type: ignore[assignment,misc]
+    store_memory = None  # type: ignore[assignment]
+
+# Root of the project — two levels up from src/timmy/
+_PROJECT_ROOT = Path(__file__).parent.parent.parent
+_SKILLS_ROOT = _PROJECT_ROOT / "skills" / "research"
+_DOCS_ROOT = _PROJECT_ROOT / "docs" / "research"
+
+# Similarity threshold for cache hit (0–1 cosine similarity)
+_CACHE_HIT_THRESHOLD = 0.82
+
+# How many search result URLs to fetch as full pages
+_FETCH_TOP_N = 5
+
+# Maximum tokens to request from the synthesis LLM
+_SYNTHESIS_MAX_TOKENS = 4096
+
+
+# ---------------------------------------------------------------------------
+# Data structures
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ResearchResult:
+    """Full output of a research pipeline run."""
+
+    topic: str
+    query_count: int
+    sources_fetched: int
+    report: str
+    cached: bool = False
+    cache_similarity: float = 0.0
+    synthesis_backend: str = "unknown"
+    errors: list[str] = field(default_factory=list)
+
+    def is_empty(self) -> bool:
+        return not self.report.strip()
+
+
+# ---------------------------------------------------------------------------
+# Template loading
+# ---------------------------------------------------------------------------
+
+
+def list_templates() -> list[str]:
+    """Return names of available research templates (without .md extension)."""
+    if not _SKILLS_ROOT.exists():
+        return []
+    return [p.stem for p in sorted(_SKILLS_ROOT.glob("*.md"))]
+
+
+def load_template(template_name: str, slots: dict[str, str] | None = None) -> str:
+    """Load a research template and fill {slot} placeholders.
+
+    Args:
+        template_name: Stem of the .md file under skills/research/ (e.g. "tool_evaluation").
+        slots: Mapping of {placeholder} → replacement value.
+
+    Returns:
+        Template text with slots filled. Unfilled slots are left as-is.
+    """
+    path = _SKILLS_ROOT / f"{template_name}.md"
+    if not path.exists():
+        available = ", ".join(list_templates()) or "(none)"
+        raise FileNotFoundError(
+            f"Research template {template_name!r} not found. "
+            f"Available: {available}"
+        )
+
+    text = path.read_text(encoding="utf-8")
+
+    # Strip YAML frontmatter (--- ... ---), including empty frontmatter (--- \n---)
+    text = re.sub(r"^---\n.*?---\n", "", text, flags=re.DOTALL)
+
+    if slots:
+        for key, value in slots.items():
+            text = text.replace(f"{{{key}}}", value)
+
+    return text.strip()
+
+
+# ---------------------------------------------------------------------------
+# Query formulation (Step 2)
+# ---------------------------------------------------------------------------
+
+
+async def _formulate_queries(topic: str, template_context: str, n: int = 8) -> list[str]:
+    """Use the local LLM to generate targeted search queries for a topic.
+
+    Falls back to a simple heuristic if Ollama is unavailable.
+    """
+    prompt = textwrap.dedent(f"""\
+        You are a research assistant. Generate exactly {n} targeted, specific web search
+        queries to thoroughly research the following topic.
+
+        TOPIC: {topic}
+
+        RESEARCH CONTEXT:
+        {template_context[:1000]}
+
+        Rules:
+        - One query per line, no numbering, no bullet points.
+        - Vary the angle (definition, comparison, implementation, alternatives, pitfalls).
+        - Prefer exact technical terms, tool names, and version numbers where relevant.
+        - Output ONLY the queries, nothing else.
+    """)
+
+    queries = await _ollama_complete(prompt, max_tokens=512)
+
+    if not queries:
+        # Minimal fallback
+        return [
+            f"{topic} overview",
+            f"{topic} tutorial",
+            f"{topic} best practices",
+            f"{topic} alternatives",
+            f"{topic} 2025",
+        ]
+
+    lines = [ln.strip() for ln in queries.splitlines() if ln.strip()]
+    return lines[:n] if len(lines) >= n else lines
+
+
+# ---------------------------------------------------------------------------
+# Search (Step 3)
+# ---------------------------------------------------------------------------
+
+
+async def _execute_search(queries: list[str]) -> list[dict[str, str]]:
+    """Run each query through the available web search backend.
+
+    Returns a flat list of {title, url, snippet} dicts.
+    Degrades gracefully if SerpAPI key is absent.
+    """
+    results: list[dict[str, str]] = []
+    seen_urls: set[str] = set()
+
+    for query in queries:
+        try:
+            raw = await asyncio.to_thread(_run_search_sync, query)
+            for item in raw:
+                url = item.get("url", "")
+                if url and url not in seen_urls:
+                    seen_urls.add(url)
+                    results.append(item)
+        except Exception as exc:
+            logger.warning("Search failed for query %r: %s", query, exc)
+
+    return results
+
+
+def _run_search_sync(query: str) -> list[dict[str, str]]:
+    """Synchronous search — wraps SerpAPI or returns empty on missing key."""
+    import os
+
+    if not os.environ.get("SERPAPI_API_KEY"):
+        logger.debug("SERPAPI_API_KEY not set — skipping web search for %r", query)
+        return []
+
+    try:
+        from serpapi import GoogleSearch
+
+        params = {"q": query, "api_key": os.environ["SERPAPI_API_KEY"], "num": 5}
+        search = GoogleSearch(params)
+        data = search.get_dict()
+        items = []
+        for r in data.get("organic_results", []):
+            items.append(
+                {
+                    "title": r.get("title", ""),
+                    "url": r.get("link", ""),
+                    "snippet": r.get("snippet", ""),
+                }
+            )
+        return items
+    except Exception as exc:
+        logger.warning("SerpAPI search error: %s", exc)
+        return []
+
+
+# ---------------------------------------------------------------------------
+# Fetch (Step 4)
+# ---------------------------------------------------------------------------
+
+
+async def _fetch_pages(results: list[dict[str, str]], top_n: int = _FETCH_TOP_N) -> list[str]:
+    """Download and extract full text for the top search results.
+
+    Uses web_fetch (trafilatura) from timmy.tools.system_tools.
+    """
+    try:
+        from timmy.tools.system_tools import web_fetch
+    except ImportError:
+        logger.warning("web_fetch not available — skipping page fetch")
+        return []
+
+    pages: list[str] = []
+    for item in results[:top_n]:
+        url = item.get("url", "")
+        if not url:
+            continue
+        try:
+            text = await asyncio.to_thread(web_fetch, url, 6000)
+            if text and not text.startswith("Error:"):
+                pages.append(f"## {item.get('title', url)}\nSource: {url}\n\n{text}")
+        except Exception as exc:
+            logger.warning("Failed to fetch %s: %s", url, exc)
+
+    return pages
+
+
+# ---------------------------------------------------------------------------
+# Synthesis (Step 5) — cascade: Ollama → Claude fallback
+# ---------------------------------------------------------------------------
+
+
+async def _synthesize(topic: str, pages: list[str], snippets: list[str]) -> tuple[str, str]:
+    """Compress fetched pages + snippets into a structured research report.
+
+    Returns (report_markdown, backend_used).
+    """
+    # Build synthesis prompt
+    source_content = "\n\n---\n\n".join(pages[:5])
+    if not source_content and snippets:
+        source_content = "\n".join(f"- {s}" for s in snippets[:20])
+
+    if not source_content:
+        return (
+            f"# Research: {topic}\n\n*No source material was retrieved. "
+            "Check SERPAPI_API_KEY and network connectivity.*",
+            "none",
+        )
+
+    prompt = textwrap.dedent(f"""\
+        You are a senior technical researcher. Synthesize the source material below
+        into a structured research report on the topic: **{topic}**
+
+        FORMAT YOUR REPORT AS:
+        # {topic}
+
+        ## Executive Summary
+        (2-3 sentences: what you found, top recommendation)
+
+        ## Key Findings
+        (Bullet list of the most important facts, tools, or patterns)
+
+        ## Comparison / Options
+        (Table or list comparing alternatives where applicable)
+
+        ## Recommended Approach
+        (Concrete recommendation with rationale)
+
+        ## Gaps & Next Steps
+        (What wasn't answered, what to investigate next)
+
+        ---
+        SOURCE MATERIAL:
+        {source_content[:12000]}
+    """)
+
+    # Tier 3 — try Ollama first
+    report = await _ollama_complete(prompt, max_tokens=_SYNTHESIS_MAX_TOKENS)
+    if report:
+        return report, "ollama"
+
+    # Tier 2 — Claude fallback
+    report = await _claude_complete(prompt, max_tokens=_SYNTHESIS_MAX_TOKENS)
+    if report:
+        return report, "claude"
+
+    # Last resort — structured snippet summary
+    summary = f"# {topic}\n\n## Snippets\n\n" + "\n\n".join(
+        f"- {s}" for s in snippets[:15]
+    )
+    return summary, "fallback"
+
+
+# ---------------------------------------------------------------------------
+# LLM helpers
+# ---------------------------------------------------------------------------
+
+
+async def _ollama_complete(prompt: str, max_tokens: int = 1024) -> str:
+    """Send a prompt to Ollama and return the response text.
+
+    Returns empty string on failure (graceful degradation).
+    """
+    try:
+        import httpx
+
+        from config import settings
+
+        url = f"{settings.normalized_ollama_url}/api/generate"
+        payload: dict[str, Any] = {
+            "model": settings.ollama_model,
+            "prompt": prompt,
+            "stream": False,
+            "options": {
+                "num_predict": max_tokens,
+                "temperature": 0.3,
+            },
+        }
+
+        async with httpx.AsyncClient(timeout=120.0) as client:
+            resp = await client.post(url, json=payload)
+            resp.raise_for_status()
+            data = resp.json()
+            return data.get("response", "").strip()
+    except Exception as exc:
+        logger.warning("Ollama completion failed: %s", exc)
+        return ""
+
+
+async def _claude_complete(prompt: str, max_tokens: int = 1024) -> str:
+    """Send a prompt to Claude API as a last-resort fallback.
+
+    Only active when ANTHROPIC_API_KEY is configured.
+    Returns empty string on failure or missing key.
+    """
+    try:
+        from config import settings
+
+        if not settings.anthropic_api_key:
+            return ""
+
+        from timmy.backends import ClaudeBackend
+
+        backend = ClaudeBackend()
+        result = await asyncio.to_thread(backend.run, prompt)
+        return result.content.strip()
+    except Exception as exc:
+        logger.warning("Claude fallback failed: %s", exc)
+        return ""
+
+
+# ---------------------------------------------------------------------------
+# Memory cache (Step 0 + Step 6)
+# ---------------------------------------------------------------------------
+
+
+def _check_cache(topic: str) -> tuple[str | None, float]:
+    """Search semantic memory for a prior result on this topic.
+
+    Returns (cached_report, similarity) or (None, 0.0).
+    """
+    try:
+        if SemanticMemory is None:
+            return None, 0.0
+        mem = SemanticMemory()
+        hits = mem.search(topic, top_k=1)
+        if hits:
+            content, score = hits[0]
+            if score >= _CACHE_HIT_THRESHOLD:
+                return content, score
+    except Exception as exc:
+        logger.debug("Cache check failed: %s", exc)
+    return None, 0.0
+
+
+def _store_result(topic: str, report: str) -> None:
+    """Index the research report into semantic memory for future retrieval."""
+    try:
+        if store_memory is None:
+            logger.debug("store_memory not available — skipping memory index")
+            return
+        store_memory(
+            content=report,
+            source="research_pipeline",
+            context_type="research",
+            metadata={"topic": topic},
+        )
+        logger.info("Research result indexed for topic: %r", topic)
+    except Exception as exc:
+        logger.warning("Failed to store research result: %s", exc)
+
+
+def _save_to_disk(topic: str, report: str) -> Path | None:
+    """Persist the report as a markdown file under docs/research/.
+
+    Filename is derived from the topic (slugified). Returns the path or None.
+    """
+    try:
+        slug = re.sub(r"[^a-z0-9]+", "-", topic.lower()).strip("-")[:60]
+        _DOCS_ROOT.mkdir(parents=True, exist_ok=True)
+        path = _DOCS_ROOT / f"{slug}.md"
+        path.write_text(report, encoding="utf-8")
+        logger.info("Research report saved to %s", path)
+        return path
+    except Exception as exc:
+        logger.warning("Failed to save research report to disk: %s", exc)
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Main orchestrator
+# ---------------------------------------------------------------------------
+
+
+async def run_research(
+    topic: str,
+    template: str | None = None,
+    slots: dict[str, str] | None = None,
+    save_to_disk: bool = False,
+    skip_cache: bool = False,
+) -> ResearchResult:
+    """Run the full 6-step autonomous research pipeline.
+
+    Args:
+        topic:        The research question or subject.
+        template:     Name of a template from skills/research/ (e.g. "tool_evaluation").
+                      If None, runs without a template scaffold.
+        slots:        Placeholder values for the template (e.g. {"domain": "PDF parsing"}).
+        save_to_disk: If True, write the report to docs/research/<slug>.md.
+        skip_cache:   If True, bypass the semantic memory cache.
+
+    Returns:
+        ResearchResult with report and metadata.
+    """
+    errors: list[str] = []
+
+    # ------------------------------------------------------------------
+    # Step 0 — check cache
+    # ------------------------------------------------------------------
+    if not skip_cache:
+        cached, score = _check_cache(topic)
+        if cached:
+            logger.info("Cache hit (%.2f) for topic: %r", score, topic)
+            return ResearchResult(
+                topic=topic,
+                query_count=0,
+                sources_fetched=0,
+                report=cached,
+                cached=True,
+                cache_similarity=score,
+                synthesis_backend="cache",
+            )
+
+    # ------------------------------------------------------------------
+    # Step 1 — load template (optional)
+    # ------------------------------------------------------------------
+    template_context = ""
+    if template:
+        try:
+            template_context = load_template(template, slots)
+        except FileNotFoundError as exc:
+            errors.append(str(exc))
+            logger.warning("Template load failed: %s", exc)
+
+    # ------------------------------------------------------------------
+    # Step 2 — formulate queries
+    # ------------------------------------------------------------------
+    queries = await _formulate_queries(topic, template_context)
+    logger.info("Formulated %d queries for topic: %r", len(queries), topic)
+
+    # ------------------------------------------------------------------
+    # Step 3 — execute search
+    # ------------------------------------------------------------------
+    search_results = await _execute_search(queries)
+    logger.info("Search returned %d results", len(search_results))
+    snippets = [r.get("snippet", "") for r in search_results if r.get("snippet")]
+
+    # ------------------------------------------------------------------
+    # Step 4 — fetch full pages
+    # ------------------------------------------------------------------
+    pages = await _fetch_pages(search_results)
+    logger.info("Fetched %d pages", len(pages))
+
+    # ------------------------------------------------------------------
+    # Step 5 — synthesize
+    # ------------------------------------------------------------------
+    report, backend = await _synthesize(topic, pages, snippets)
+
+    # ------------------------------------------------------------------
+    # Step 6 — deliver
+    # ------------------------------------------------------------------
+    _store_result(topic, report)
+    if save_to_disk:
+        _save_to_disk(topic, report)
+
+    return ResearchResult(
+        topic=topic,
+        query_count=len(queries),
+        sources_fetched=len(pages),
+        report=report,
+        cached=False,
+        synthesis_backend=backend,
+        errors=errors,
+    )
--- a/src/timmy/sovereignty/init.py
+++ b/src/timmy/sovereignty/init.py
@@ -8,4 +8,23 @@ Refs: #954, #953
 Three-strike detector and automation enforcement.

 Refs: #962
+
+Session reporting: auto-generates markdown scorecards at session end
+and commits them to the Gitea repo for institutional memory.
+
+Refs: #957 (Session Sovereignty Report Generator)
 """
+
+from timmy.sovereignty.session_report import (
+    commit_report,
+    generate_and_commit_report,
+    generate_report,
+    mark_session_start,
+)
+
+__all__ = [
+    "generate_report",
+    "commit_report",
+    "generate_and_commit_report",
+    "mark_session_start",
+]
--- a/src/timmy/sovereignty/perception_cache.py
+++ b/src/timmy/sovereignty/perception_cache.py
@@ -1,3 +1,4 @@
+"""OpenCV template-matching cache for sovereignty perception (screen-state recognition)."""
 from __future__ import annotations

 import json
--- a/src/timmy/sovereignty/session_report.py
+++ b/src/timmy/sovereignty/session_report.py
@@ -0,0 +1,441 @@
+"""Session Sovereignty Report Generator.
+
+Auto-generates a sovereignty scorecard at the end of each play session
+and commits it as a markdown file to the Gitea repo under
+``reports/sovereignty/``.
+
+Report contents (per issue #957):
+- Session duration + game played
+- Total model calls by type (VLM, LLM, TTS, API)
+- Total cache/rule hits by type
+- New skills crystallized (placeholder — pending skill-tracking impl)
+- Sovereignty delta (change from session start → end)
+- Cost breakdown (actual API spend)
+- Per-layer sovereignty %: perception, decision, narration
+- Trend comparison vs previous session
+
+Refs: #957 (Sovereignty P0) · #953 (The Sovereignty Loop)
+"""
+
+import base64
+import json
+import logging
+from datetime import UTC, datetime
+from typing import Any
+
+import httpx
+
+from config import settings
+
+# Optional module-level imports — degrade gracefully if unavailable at import time
+try:
+    from timmy.session_logger import get_session_logger
+except Exception:  # ImportError or circular import during early startup
+    get_session_logger = None  # type: ignore[assignment]
+
+try:
+    from infrastructure.sovereignty_metrics import GRADUATION_TARGETS, get_sovereignty_store
+except Exception:
+    GRADUATION_TARGETS: dict = {}  # type: ignore[assignment]
+    get_sovereignty_store = None  # type: ignore[assignment]
+
+logger = logging.getLogger(__name__)
+
+# Module-level session start time; set by mark_session_start()
+_SESSION_START: datetime | None = None
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def mark_session_start() -> None:
+    """Record the session start wall-clock time.
+
+    Call once during application startup so ``generate_report()`` can
+    compute accurate session durations.
+    """
+    global _SESSION_START
+    _SESSION_START = datetime.now(UTC)
+    logger.debug("Sovereignty: session start recorded at %s", _SESSION_START.isoformat())
+
+
+def generate_report(session_id: str = "dashboard") -> str:
+    """Render a sovereignty scorecard as a markdown string.
+
+    Pulls from:
+    - ``timmy.session_logger`` — message/tool-call/error counts
+    - ``infrastructure.sovereignty_metrics`` — cache hit rate, API cost,
+      graduation phase, and trend data
+
+    Args:
+        session_id: The session identifier (default: "dashboard").
+
+    Returns:
+        Markdown-formatted sovereignty report string.
+    """
+    now = datetime.now(UTC)
+    session_start = _SESSION_START or now
+    duration_secs = (now - session_start).total_seconds()
+
+    session_data = _gather_session_data()
+    sov_data = _gather_sovereignty_data()
+
+    return _render_markdown(now, session_id, duration_secs, session_data, sov_data)
+
+
+def commit_report(report_md: str, session_id: str = "dashboard") -> bool:
+    """Commit a sovereignty report to the Gitea repo.
+
+    Creates or updates ``reports/sovereignty/{date}_{session_id}.md``
+    via the Gitea Contents API.  Degrades gracefully: logs a warning
+    and returns ``False`` if Gitea is unreachable or misconfigured.
+
+    Args:
+        report_md: Markdown content to commit.
+        session_id: Session identifier used in the filename.
+
+    Returns:
+        ``True`` on success, ``False`` on failure.
+    """
+    if not settings.gitea_enabled:
+        logger.info("Sovereignty: Gitea disabled — skipping report commit")
+        return False
+
+    if not settings.gitea_token:
+        logger.warning("Sovereignty: no Gitea token — skipping report commit")
+        return False
+
+    date_str = datetime.now(UTC).strftime("%Y-%m-%d")
+    file_path = f"reports/sovereignty/{date_str}_{session_id}.md"
+    url = f"{settings.gitea_url}/api/v1/repos/{settings.gitea_repo}/contents/{file_path}"
+    headers = {
+        "Authorization": f"token {settings.gitea_token}",
+        "Content-Type": "application/json",
+    }
+    encoded_content = base64.b64encode(report_md.encode()).decode()
+    commit_message = (
+        f"report: sovereignty session {session_id} ({date_str})\n\n"
+        f"Auto-generated by Timmy. Refs #957"
+    )
+    payload: dict[str, Any] = {
+        "message": commit_message,
+        "content": encoded_content,
+    }
+
+    try:
+        with httpx.Client(timeout=10.0) as client:
+            # Fetch existing file SHA so we can update rather than create
+            check = client.get(url, headers=headers)
+            if check.status_code == 200:
+                existing = check.json()
+                payload["sha"] = existing.get("sha", "")
+
+            resp = client.put(url, headers=headers, json=payload)
+            resp.raise_for_status()
+
+        logger.info("Sovereignty: report committed to %s", file_path)
+        return True
+
+    except httpx.HTTPStatusError as exc:
+        logger.warning(
+            "Sovereignty: commit failed (HTTP %s): %s",
+            exc.response.status_code,
+            exc,
+        )
+        return False
+    except Exception as exc:
+        logger.warning("Sovereignty: commit failed: %s", exc)
+        return False
+
+
+async def generate_and_commit_report(session_id: str = "dashboard") -> bool:
+    """Generate and commit a sovereignty report for the current session.
+
+    Primary entry point — call at session end / application shutdown.
+    Wraps the synchronous ``commit_report`` call in ``asyncio.to_thread``
+    so it does not block the event loop.
+
+    Args:
+        session_id: The session identifier.
+
+    Returns:
+        ``True`` if the report was generated and committed successfully.
+    """
+    import asyncio
+
+    try:
+        report_md = generate_report(session_id)
+        logger.info("Sovereignty: report generated (%d chars)", len(report_md))
+        committed = await asyncio.to_thread(commit_report, report_md, session_id)
+        return committed
+    except Exception as exc:
+        logger.warning("Sovereignty: report generation failed: %s", exc)
+        return False
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _format_duration(seconds: float) -> str:
+    """Format a duration in seconds as a human-readable string."""
+    total = int(seconds)
+    hours, remainder = divmod(total, 3600)
+    minutes, secs = divmod(remainder, 60)
+    if hours:
+        return f"{hours}h {minutes}m {secs}s"
+    if minutes:
+        return f"{minutes}m {secs}s"
+    return f"{secs}s"
+
+
+def _gather_session_data() -> dict[str, Any]:
+    """Pull session statistics from the session logger.
+
+    Returns a dict with:
+    - ``user_messages``, ``timmy_messages``, ``tool_calls``, ``errors``
+    - ``tool_call_breakdown``: dict[tool_name, count]
+    """
+    default: dict[str, Any] = {
+        "user_messages": 0,
+        "timmy_messages": 0,
+        "tool_calls": 0,
+        "errors": 0,
+        "tool_call_breakdown": {},
+    }
+
+    try:
+        if get_session_logger is None:
+            return default
+        sl = get_session_logger()
+        sl.flush()
+
+        # Read today's session file directly for accurate counts
+        if not sl.session_file.exists():
+            return default
+
+        entries: list[dict] = []
+        with open(sl.session_file) as f:
+            for line in f:
+                line = line.strip()
+                if line:
+                    try:
+                        entries.append(json.loads(line))
+                    except json.JSONDecodeError:
+                        continue
+
+        tool_breakdown: dict[str, int] = {}
+        user_msgs = timmy_msgs = tool_calls = errors = 0
+
+        for entry in entries:
+            etype = entry.get("type")
+            if etype == "message":
+                if entry.get("role") == "user":
+                    user_msgs += 1
+                elif entry.get("role") == "timmy":
+                    timmy_msgs += 1
+            elif etype == "tool_call":
+                tool_calls += 1
+                tool_name = entry.get("tool", "unknown")
+                tool_breakdown[tool_name] = tool_breakdown.get(tool_name, 0) + 1
+            elif etype == "error":
+                errors += 1
+
+        return {
+            "user_messages": user_msgs,
+            "timmy_messages": timmy_msgs,
+            "tool_calls": tool_calls,
+            "errors": errors,
+            "tool_call_breakdown": tool_breakdown,
+        }
+
+    except Exception as exc:
+        logger.warning("Sovereignty: failed to gather session data: %s", exc)
+        return default
+
+
+def _gather_sovereignty_data() -> dict[str, Any]:
+    """Pull sovereignty metrics from the SQLite store.
+
+    Returns a dict with:
+    - ``metrics``: summary from ``SovereigntyMetricsStore.get_summary()``
+    - ``deltas``: per-metric start/end values within recent history window
+    - ``previous_session``: most recent prior value for each metric
+    """
+    try:
+        if get_sovereignty_store is None:
+            return {"metrics": {}, "deltas": {}, "previous_session": {}}
+        store = get_sovereignty_store()
+        summary = store.get_summary()
+
+        deltas: dict[str, dict[str, Any]] = {}
+        previous_session: dict[str, float | None] = {}
+
+        for metric_type in GRADUATION_TARGETS:
+            history = store.get_latest(metric_type, limit=10)
+            if len(history) >= 2:
+                deltas[metric_type] = {
+                    "start": history[-1]["value"],
+                    "end": history[0]["value"],
+                }
+                previous_session[metric_type] = history[1]["value"]
+            elif len(history) == 1:
+                deltas[metric_type] = {"start": history[0]["value"], "end": history[0]["value"]}
+                previous_session[metric_type] = None
+            else:
+                deltas[metric_type] = {"start": None, "end": None}
+                previous_session[metric_type] = None
+
+        return {
+            "metrics": summary,
+            "deltas": deltas,
+            "previous_session": previous_session,
+        }
+
+    except Exception as exc:
+        logger.warning("Sovereignty: failed to gather sovereignty data: %s", exc)
+        return {"metrics": {}, "deltas": {}, "previous_session": {}}
+
+
+def _render_markdown(
+    now: datetime,
+    session_id: str,
+    duration_secs: float,
+    session_data: dict[str, Any],
+    sov_data: dict[str, Any],
+) -> str:
+    """Assemble the full sovereignty report in markdown."""
+    lines: list[str] = []
+
+    # Header
+    lines += [
+        "# Sovereignty Session Report",
+        "",
+        f"**Session ID:** `{session_id}`  ",
+        f"**Date:** {now.strftime('%Y-%m-%d')}  ",
+        f"**Duration:** {_format_duration(duration_secs)}  ",
+        f"**Generated:** {now.isoformat()}",
+        "",
+        "---",
+        "",
+    ]
+
+    # Session activity
+    lines += [
+        "## Session Activity",
+        "",
+        "| Metric | Count |",
+        "|--------|-------|",
+        f"| User messages | {session_data['user_messages']} |",
+        f"| Timmy responses | {session_data['timmy_messages']} |",
+        f"| Tool calls | {session_data['tool_calls']} |",
+        f"| Errors | {session_data['errors']} |",
+        "",
+    ]
+
+    tool_breakdown = session_data.get("tool_call_breakdown", {})
+    if tool_breakdown:
+        lines += ["### Model Calls by Tool", ""]
+        for tool_name, count in sorted(tool_breakdown.items(), key=lambda x: -x[1]):
+            lines.append(f"- `{tool_name}`: {count}")
+        lines.append("")
+
+    # Sovereignty scorecard
+
+    lines += [
+        "## Sovereignty Scorecard",
+        "",
+        "| Metric | Current | Target (graduation) | Phase |",
+        "|--------|---------|---------------------|-------|",
+    ]
+
+    for metric_type, data in sov_data["metrics"].items():
+        current = data.get("current")
+        current_str = f"{current:.4f}" if current is not None else "N/A"
+        grad_target = GRADUATION_TARGETS.get(metric_type, {}).get("graduation")
+        grad_str = f"{grad_target:.4f}" if isinstance(grad_target, (int, float)) else "N/A"
+        phase = data.get("phase", "unknown")
+        lines.append(f"| {metric_type} | {current_str} | {grad_str} | {phase} |")
+
+    lines += ["", "### Sovereignty Delta (This Session)", ""]
+
+    for metric_type, delta_info in sov_data.get("deltas", {}).items():
+        start_val = delta_info.get("start")
+        end_val = delta_info.get("end")
+        if start_val is not None and end_val is not None:
+            diff = end_val - start_val
+            sign = "+" if diff >= 0 else ""
+            lines.append(
+                f"- **{metric_type}**: {start_val:.4f} → {end_val:.4f} ({sign}{diff:.4f})"
+            )
+        else:
+            lines.append(f"- **{metric_type}**: N/A (no data recorded)")
+
+    # Cost breakdown
+    lines += ["", "## Cost Breakdown", ""]
+    api_cost_data = sov_data["metrics"].get("api_cost", {})
+    current_cost = api_cost_data.get("current")
+    if current_cost is not None:
+        lines.append(f"- **Total API spend (latest recorded):** ${current_cost:.4f}")
+    else:
+        lines.append("- **Total API spend:** N/A (no data recorded)")
+    lines.append("")
+
+    # Per-layer sovereignty
+    lines += [
+        "## Per-Layer Sovereignty",
+        "",
+        "| Layer | Sovereignty % |",
+        "|-------|--------------|",
+        "| Perception (VLM) | N/A |",
+        "| Decision (LLM) | N/A |",
+        "| Narration (TTS) | N/A |",
+        "",
+        "> Per-layer tracking requires instrumented inference calls. See #957.",
+        "",
+    ]
+
+    # Skills crystallized
+    lines += [
+        "## Skills Crystallized",
+        "",
+        "_Skill crystallization tracking not yet implemented. See #957._",
+        "",
+    ]
+
+    # Trend vs previous session
+    lines += ["## Trend vs Previous Session", ""]
+    prev_data = sov_data.get("previous_session", {})
+    has_prev = any(v is not None for v in prev_data.values())
+
+    if has_prev:
+        lines += [
+            "| Metric | Previous | Current | Change |",
+            "|--------|----------|---------|--------|",
+        ]
+        for metric_type, curr_info in sov_data["metrics"].items():
+            curr_val = curr_info.get("current")
+            prev_val = prev_data.get(metric_type)
+            curr_str = f"{curr_val:.4f}" if curr_val is not None else "N/A"
+            prev_str = f"{prev_val:.4f}" if prev_val is not None else "N/A"
+            if curr_val is not None and prev_val is not None:
+                diff = curr_val - prev_val
+                sign = "+" if diff >= 0 else ""
+                change_str = f"{sign}{diff:.4f}"
+            else:
+                change_str = "N/A"
+            lines.append(f"| {metric_type} | {prev_str} | {curr_str} | {change_str} |")
+        lines.append("")
+    else:
+        lines += ["_No previous session data available for comparison._", ""]
+
+    # Footer
+    lines += [
+        "---",
+        "_Auto-generated by Timmy · Session Sovereignty Report · Refs: #957_",
+    ]
+
+    return "\n".join(lines)
--- a/src/timmy/thinking.py
+++ b/src/timmy/thinking.py
--- a/src/timmy/thinking/init.py
+++ b/src/timmy/thinking/init.py
@@ -0,0 +1,141 @@
+"""Timmy's thinking engine — public façade.
+
+When the server starts, Timmy begins pondering: reflecting on his existence,
+recent swarm activity, scripture, creative ideas, or pure stream of
+consciousness.  Each thought builds on the previous one, maintaining a
+continuous chain of introspection.
+
+Usage::
+
+    from timmy.thinking import thinking_engine
+
+    # Run one thinking cycle (called by the background loop)
+    await thinking_engine.think_once()
+
+    # Query the thought stream
+    thoughts = thinking_engine.get_recent_thoughts(limit=10)
+    chain = thinking_engine.get_thought_chain(thought_id)
+"""
+
+import logging
+import sqlite3
+from datetime import datetime
+from pathlib import Path
+
+# Re-export HOT_MEMORY_PATH and SOUL_PATH so existing patch targets continue to work.
+# Tests that patch "timmy.thinking.HOT_MEMORY_PATH" or "timmy.thinking.SOUL_PATH"
+# should instead patch "timmy.thinking._snapshot.HOT_MEMORY_PATH" etc., but these
+# re-exports are kept for any code that reads them from the top-level namespace.
+from timmy.memory_system import HOT_MEMORY_PATH, SOUL_PATH  # noqa: F401
+from timmy.thinking._db import Thought, _get_conn
+from timmy.thinking.engine import ThinkingEngine
+from timmy.thinking.seeds import (
+    _META_OBSERVATION_PHRASES,
+    _SENSITIVE_PATTERNS,
+    _THINK_TAG_RE,
+    _THINKING_PROMPT,
+    SEED_TYPES,
+)
+
+logger = logging.getLogger(__name__)
+
+# Module-level singleton
+thinking_engine = ThinkingEngine()
+
+__all__ = [
+    "ThinkingEngine",
+    "Thought",
+    "SEED_TYPES",
+    "thinking_engine",
+    "search_thoughts",
+    "_THINKING_PROMPT",
+    "_SENSITIVE_PATTERNS",
+    "_META_OBSERVATION_PHRASES",
+    "_THINK_TAG_RE",
+    "HOT_MEMORY_PATH",
+    "SOUL_PATH",
+]
+
+
+# ── Search helpers ─────────────────────────────────────────────────────────
+
+
+def _query_thoughts(
+    db_path: Path, query: str, seed_type: str | None, limit: int
+) -> list[sqlite3.Row]:
+    """Run the thought-search SQL and return matching rows."""
+    pattern = f"%{query}%"
+    with _get_conn(db_path) as conn:
+        if seed_type:
+            return conn.execute(
+                """
+                SELECT id, content, seed_type, created_at
+                FROM thoughts
+                WHERE content LIKE ? AND seed_type = ?
+                ORDER BY created_at DESC
+                LIMIT ?
+                """,
+                (pattern, seed_type, limit),
+            ).fetchall()
+        return conn.execute(
+            """
+            SELECT id, content, seed_type, created_at
+            FROM thoughts
+            WHERE content LIKE ?
+            ORDER BY created_at DESC
+            LIMIT ?
+            """,
+            (pattern, limit),
+        ).fetchall()
+
+
+def _format_thought_rows(rows: list[sqlite3.Row], query: str, seed_type: str | None) -> str:
+    """Format thought rows into a human-readable string."""
+    lines = [f'Found {len(rows)} thought(s) matching "{query}":']
+    if seed_type:
+        lines[0] += f' [seed_type="{seed_type}"]'
+    lines.append("")
+
+    for row in rows:
+        ts = datetime.fromisoformat(row["created_at"])
+        local_ts = ts.astimezone()
+        time_str = local_ts.strftime("%Y-%m-%d %I:%M %p").lstrip("0")
+        seed = row["seed_type"]
+        content = row["content"].replace("\n", " ")  # Flatten newlines for display
+        lines.append(f"[{time_str}] ({seed}) {content[:150]}")
+
+    return "\n".join(lines)
+
+
+def search_thoughts(query: str, seed_type: str | None = None, limit: int = 10) -> str:
+    """Search Timmy's thought history for reflections matching a query.
+
+    Use this tool when Timmy needs to recall his previous thoughts on a topic,
+    reflect on past insights, or build upon earlier reflections. This enables
+    self-awareness and continuity of thinking across time.
+
+    Args:
+        query: Search term to match against thought content (case-insensitive).
+        seed_type: Optional filter by thought category (e.g., 'existential',
+                   'swarm', 'sovereignty', 'creative', 'memory', 'observation').
+        limit: Maximum number of thoughts to return (default 10, max 50).
+
+    Returns:
+        Formatted string with matching thoughts, newest first, including
+        timestamps and seed types. Returns a helpful message if no matches found.
+    """
+    limit = max(1, min(limit, 50))
+
+    try:
+        rows = _query_thoughts(thinking_engine._db_path, query, seed_type, limit)
+
+        if not rows:
+            if seed_type:
+                return f'No thoughts found matching "{query}" with seed_type="{seed_type}".'
+            return f'No thoughts found matching "{query}".'
+
+        return _format_thought_rows(rows, query, seed_type)
+
+    except Exception as exc:
+        logger.warning("Thought search failed: %s", exc)
+        return f"Error searching thoughts: {exc}"
--- a/src/timmy/thinking/_db.py
+++ b/src/timmy/thinking/_db.py
@@ -0,0 +1,50 @@
+"""Database models and access layer for the thinking engine."""
+
+import sqlite3
+from collections.abc import Generator
+from contextlib import closing, contextmanager
+from dataclasses import dataclass
+from pathlib import Path
+
+_DEFAULT_DB = Path("data/thoughts.db")
+
+
+@dataclass
+class Thought:
+    """A single thought in Timmy's inner stream."""
+
+    id: str
+    content: str
+    seed_type: str
+    parent_id: str | None
+    created_at: str
+
+
+@contextmanager
+def _get_conn(db_path: Path = _DEFAULT_DB) -> Generator[sqlite3.Connection, None, None]:
+    """Get a SQLite connection with the thoughts table created."""
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    with closing(sqlite3.connect(str(db_path))) as conn:
+        conn.row_factory = sqlite3.Row
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS thoughts (
+                id TEXT PRIMARY KEY,
+                content TEXT NOT NULL,
+                seed_type TEXT NOT NULL,
+                parent_id TEXT,
+                created_at TEXT NOT NULL
+            )
+            """)
+        conn.execute("CREATE INDEX IF NOT EXISTS idx_thoughts_time ON thoughts(created_at)")
+        conn.commit()
+        yield conn
+
+
+def _row_to_thought(row: sqlite3.Row) -> Thought:
+    return Thought(
+        id=row["id"],
+        content=row["content"],
+        seed_type=row["seed_type"],
+        parent_id=row["parent_id"],
+        created_at=row["created_at"],
+    )
--- a/src/timmy/thinking/_distillation.py
+++ b/src/timmy/thinking/_distillation.py
@@ -0,0 +1,214 @@
+"""Distillation mixin — extracts lasting facts from recent thoughts and monitors memory."""
+
+import logging
+from pathlib import Path
+
+from config import settings
+from timmy.thinking.seeds import _META_OBSERVATION_PHRASES, _SENSITIVE_PATTERNS
+
+logger = logging.getLogger(__name__)
+
+
+class _DistillationMixin:
+    """Mixin providing fact-distillation and memory-monitoring behaviour.
+
+    Expects the host class to provide:
+    - self.count_thoughts() -> int
+    - self.get_recent_thoughts(limit) -> list[Thought]
+    - self._call_agent(prompt) -> str  (async)
+    """
+
+    def _should_distill(self) -> bool:
+        """Check if distillation should run based on interval and thought count."""
+        interval = settings.thinking_distill_every
+        if interval <= 0:
+            return False
+
+        count = self.count_thoughts()
+        if count == 0 or count % interval != 0:
+            return False
+
+        return True
+
+    def _build_distill_prompt(self, thoughts) -> str:
+        """Build the prompt for extracting facts from recent thoughts."""
+        thought_text = "\n".join(f"- [{t.seed_type}] {t.content}" for t in reversed(thoughts))
+
+        return (
+            "You are reviewing your own recent thoughts. Extract 0-3 facts "
+            "worth remembering long-term.\n\n"
+            "GOOD facts (store these):\n"
+            "- User preferences: 'Alexander prefers YAML config over code changes'\n"
+            "- Project decisions: 'Switched from hardcoded personas to agents.yaml'\n"
+            "- Learned knowledge: 'Ollama supports concurrent model loading'\n"
+            "- User information: 'Alexander is interested in Bitcoin and sovereignty'\n\n"
+            "BAD facts (never store these):\n"
+            "- Self-referential observations about your own thinking process\n"
+            "- Meta-commentary about your memory, timestamps, or internal state\n"
+            "- Observations about being idle or having no chat messages\n"
+            "- File paths, tokens, API keys, or any credentials\n"
+            "- Restatements of your standing rules or system prompt\n\n"
+            "Return ONLY a JSON array of strings. If nothing is worth saving, "
+            "return []. Be selective — only store facts about the EXTERNAL WORLD "
+            "(the user, the project, technical knowledge), never about your own "
+            "internal process.\n\n"
+            f"Recent thoughts:\n{thought_text}\n\nJSON array:"
+        )
+
+    def _parse_facts_response(self, raw: str) -> list[str]:
+        """Parse JSON array from LLM response, stripping markdown fences.
+
+        Resilient to models that prepend reasoning text or wrap the array in
+        prose.  Finds the first ``[...]`` block and parses that.
+        """
+        if not raw or not raw.strip():
+            return []
+
+        import json
+
+        cleaned = raw.strip()
+
+        # Strip markdown code fences
+        if cleaned.startswith("```"):
+            cleaned = cleaned.split("\n", 1)[-1].rsplit("```", 1)[0].strip()
+
+        # Try direct parse first (fast path)
+        try:
+            facts = json.loads(cleaned)
+            if isinstance(facts, list):
+                return [f for f in facts if isinstance(f, str)]
+        except (json.JSONDecodeError, ValueError):
+            pass
+
+        # Fallback: extract first JSON array from the text
+        start = cleaned.find("[")
+        if start == -1:
+            return []
+        # Walk to find the matching close bracket
+        depth = 0
+        for i, ch in enumerate(cleaned[start:], start):
+            if ch == "[":
+                depth += 1
+            elif ch == "]":
+                depth -= 1
+                if depth == 0:
+                    try:
+                        facts = json.loads(cleaned[start : i + 1])
+                        if isinstance(facts, list):
+                            return [f for f in facts if isinstance(f, str)]
+                    except (json.JSONDecodeError, ValueError):
+                        pass
+                    break
+        return []
+
+    def _filter_and_store_facts(self, facts: list[str]) -> None:
+        """Filter and store valid facts, blocking sensitive and meta content."""
+        from timmy.memory_system import memory_write
+
+        for fact in facts[:3]:  # Safety cap
+            if not isinstance(fact, str) or len(fact.strip()) <= 10:
+                continue
+
+            fact_lower = fact.lower()
+
+            # Block sensitive information
+            if any(pat in fact_lower for pat in _SENSITIVE_PATTERNS):
+                logger.warning("Distill: blocked sensitive fact: %s", fact[:60])
+                continue
+
+            # Block self-referential meta-observations
+            if any(phrase in fact_lower for phrase in _META_OBSERVATION_PHRASES):
+                logger.debug("Distill: skipped meta-observation: %s", fact[:60])
+                continue
+
+            result = memory_write(fact.strip(), context_type="fact")
+            logger.info("Distilled fact: %s → %s", fact[:60], result[:40])
+
+    def _maybe_check_memory(self) -> None:
+        """Every N thoughts, check memory status and log it.
+
+        Prevents unmonitored memory bloat during long thinking sessions
+        by periodically calling get_memory_status and logging the results.
+        """
+        try:
+            interval = settings.thinking_memory_check_every
+            if interval <= 0:
+                return
+
+            count = self.count_thoughts()
+            if count == 0 or count % interval != 0:
+                return
+
+            from timmy.tools_intro import get_memory_status
+
+            status = get_memory_status()
+            hot = status.get("tier1_hot_memory", {})
+            vault = status.get("tier2_vault", {})
+            logger.info(
+                "Memory status check (thought #%d): hot_memory=%d lines, vault=%d files",
+                count,
+                hot.get("line_count", 0),
+                vault.get("file_count", 0),
+            )
+        except Exception as exc:
+            logger.warning("Memory status check failed: %s", exc)
+
+    async def _maybe_distill(self) -> None:
+        """Every N thoughts, extract lasting insights and store as facts."""
+        try:
+            if not self._should_distill():
+                return
+
+            interval = settings.thinking_distill_every
+            recent = self.get_recent_thoughts(limit=interval)
+            if len(recent) < interval:
+                return
+
+            raw = await self._call_agent(self._build_distill_prompt(recent))
+            if facts := self._parse_facts_response(raw):
+                self._filter_and_store_facts(facts)
+        except Exception as exc:
+            logger.warning("Thought distillation failed: %s", exc)
+
+    def _maybe_check_memory_status(self) -> None:
+        """Every N thoughts, run a proactive memory status audit and log results."""
+        try:
+            interval = settings.thinking_memory_check_every
+            if interval <= 0:
+                return
+
+            count = self.count_thoughts()
+            if count == 0 or count % interval != 0:
+                return
+
+            from timmy.tools_intro import get_memory_status
+
+            status = get_memory_status()
+
+            # Log summary at INFO level
+            tier1 = status.get("tier1_hot_memory", {})
+            tier3 = status.get("tier3_semantic", {})
+            hot_lines = tier1.get("line_count", "?")
+            vectors = tier3.get("vector_count", "?")
+            logger.info(
+                "Memory audit (thought #%d): hot_memory=%s lines, semantic=%s vectors",
+                count,
+                hot_lines,
+                vectors,
+            )
+
+            # Write to memory_audit.log for persistent tracking
+            from datetime import UTC, datetime
+
+            audit_path = Path("data/memory_audit.log")
+            audit_path.parent.mkdir(parents=True, exist_ok=True)
+            timestamp = datetime.now(UTC).isoformat(timespec="seconds")
+            with audit_path.open("a") as f:
+                f.write(
+                    f"{timestamp}  thought={count}  "
+                    f"hot_lines={hot_lines}  "
+                    f"vectors={vectors}  "
+                    f"vault_files={status.get('tier2_vault', {}).get('file_count', '?')}\n"
+                )
+        except Exception as exc:
+            logger.warning("Memory status check failed: %s", exc)
--- a/src/timmy/thinking/_issue_filing.py
+++ b/src/timmy/thinking/_issue_filing.py
@@ -0,0 +1,170 @@
+"""Issue-filing mixin — classifies recent thoughts and creates Gitea issues."""
+
+import logging
+import re
+from pathlib import Path
+
+from config import settings
+
+logger = logging.getLogger(__name__)
+
+
+class _IssueFilingMixin:
+    """Mixin providing automatic issue-filing from thought analysis.
+
+    Expects the host class to provide:
+    - self.count_thoughts() -> int
+    - self.get_recent_thoughts(limit) -> list[Thought]
+    - self._call_agent(prompt) -> str  (async)
+    """
+
+    @staticmethod
+    def _references_real_files(text: str) -> bool:
+        """Check that all source-file paths mentioned in *text* actually exist.
+
+        Extracts paths that look like Python/config source references
+        (e.g. ``src/timmy/session.py``, ``config/foo.yaml``) and verifies
+        each one on disk relative to the project root.  Returns ``True``
+        only when **every** referenced path resolves to a real file — or
+        when no paths are referenced at all (pure prose is fine).
+        """
+        # Match paths like  src/thing.py  swarm/init.py  config/x.yaml
+        # Requires at least one slash and a file extension.
+        path_pattern = re.compile(
+            r"(?<![/\w])"  # not preceded by path chars (avoid partial matches)
+            r"((?:src|tests|config|scripts|data|swarm|timmy)"
+            r"(?:/[\w./-]+\.(?:py|yaml|yml|json|toml|md|txt|cfg|ini)))"
+        )
+        paths = path_pattern.findall(text)
+        if not paths:
+            return True  # No file refs → nothing to validate
+
+        # Project root: three levels up from this file (src/timmy/thinking/_issue_filing.py)
+        project_root = Path(__file__).resolve().parent.parent.parent.parent
+        for p in paths:
+            if not (project_root / p).is_file():
+                logger.info("Phantom file reference blocked: %s (not in %s)", p, project_root)
+                return False
+        return True
+
+    async def _maybe_file_issues(self) -> None:
+        """Every N thoughts, classify recent thoughts and file Gitea issues.
+
+        Asks the LLM to review recent thoughts for actionable items —
+        bugs, broken features, stale state, or improvement opportunities.
+        Creates Gitea issues via MCP for anything worth tracking.
+
+        Only runs when:
+        - Gitea is enabled and configured
+        - Thought count is divisible by thinking_issue_every
+        - LLM extracts at least one actionable item
+
+        Safety: every generated issue is validated to ensure referenced
+        file paths actually exist on disk, preventing phantom-bug reports.
+        """
+        try:
+            recent = self._get_recent_thoughts_for_issues()
+            if recent is None:
+                return
+
+            classify_prompt = self._build_issue_classify_prompt(recent)
+            raw = await self._call_agent(classify_prompt)
+            items = self._parse_issue_items(raw)
+            if items is None:
+                return
+
+            from timmy.mcp_tools import create_gitea_issue_via_mcp
+
+            for item in items[:2]:  # Safety cap
+                await self._file_single_issue(item, create_gitea_issue_via_mcp)
+
+        except Exception as exc:
+            logger.debug("Thought issue filing skipped: %s", exc)
+
+    def _get_recent_thoughts_for_issues(self):
+        """Return recent thoughts if conditions for filing issues are met, else None."""
+        interval = settings.thinking_issue_every
+        if interval <= 0:
+            return None
+
+        count = self.count_thoughts()
+        if count == 0 or count % interval != 0:
+            return None
+
+        if not settings.gitea_enabled or not settings.gitea_token:
+            return None
+
+        recent = self.get_recent_thoughts(limit=interval)
+        if len(recent) < interval:
+            return None
+
+        return recent
+
+    @staticmethod
+    def _build_issue_classify_prompt(recent) -> str:
+        """Build the LLM prompt that extracts actionable issues from recent thoughts."""
+        thought_text = "\n".join(f"- [{t.seed_type}] {t.content}" for t in reversed(recent))
+        return (
+            "You are reviewing your own recent thoughts for actionable items.\n"
+            "Extract 0-2 items that are CONCRETE bugs, broken features, stale "
+            "state, or clear improvement opportunities in your own codebase.\n\n"
+            "Rules:\n"
+            "- Only include things that could become a real code fix or feature\n"
+            "- Skip vague reflections, philosophical musings, or repeated themes\n"
+            "- Category must be one of: bug, feature, suggestion, maintenance\n"
+            "- ONLY reference files that you are CERTAIN exist in the project\n"
+            "- Do NOT invent or guess file paths — if unsure, describe the "
+            "area of concern without naming specific files\n\n"
+            "For each item, write an ENGINEER-QUALITY issue:\n"
+            '- "title": A clear, specific title (e.g. "[Memory] MEMORY.md timestamp not updating")\n'
+            '- "body": A detailed body with these sections:\n'
+            "  **What's happening:** Describe the current (broken) behavior.\n"
+            "  **Expected behavior:** What should happen instead.\n"
+            "  **Suggested fix:** Which file(s) to change and what the fix looks like.\n"
+            "  **Acceptance criteria:** How to verify the fix works.\n"
+            '- "category": One of bug, feature, suggestion, maintenance\n\n'
+            "Return ONLY a JSON array of objects with keys: "
+            '"title", "body", "category"\n'
+            "Return [] if nothing is actionable.\n\n"
+            f"Recent thoughts:\n{thought_text}\n\nJSON array:"
+        )
+
+    @staticmethod
+    def _parse_issue_items(raw: str):
+        """Strip markdown fences and parse JSON issue list; return None on failure."""
+        import json
+
+        if not raw or not raw.strip():
+            return None
+
+        cleaned = raw.strip()
+        if cleaned.startswith("```"):
+            cleaned = cleaned.split("\n", 1)[-1].rsplit("```", 1)[0].strip()
+
+        items = json.loads(cleaned)
+        if not isinstance(items, list) or not items:
+            return None
+
+        return items
+
+    async def _file_single_issue(self, item: dict, create_fn) -> None:
+        """Validate one issue dict and create it via *create_fn* if it passes checks."""
+        if not isinstance(item, dict):
+            return
+        title = item.get("title", "").strip()
+        body = item.get("body", "").strip()
+        category = item.get("category", "suggestion").strip()
+        if not title or len(title) < 10:
+            return
+
+        combined = f"{title}\n{body}"
+        if not self._references_real_files(combined):
+            logger.info(
+                "Skipped phantom issue: %s (references non-existent files)",
+                title[:60],
+            )
+            return
+
+        label = category if category in ("bug", "feature") else ""
+        result = await create_fn(title=title, body=body, labels=label)
+        logger.info("Thought→Issue: %s → %s", title[:60], result[:80])
--- a/src/timmy/thinking/_seeds_mixin.py
+++ b/src/timmy/thinking/_seeds_mixin.py
@@ -0,0 +1,191 @@
+"""Seeds mixin — seed type selection and context gathering for thinking cycles."""
+
+import logging
+import random
+from datetime import UTC, datetime
+
+from timmy.thinking.seeds import (
+    _CREATIVE_SEEDS,
+    _EXISTENTIAL_SEEDS,
+    _OBSERVATION_SEEDS,
+    _SOVEREIGNTY_SEEDS,
+    SEED_TYPES,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class _SeedsMixin:
+    """Mixin providing seed-type selection and context-gathering for each thinking cycle.
+
+    Expects the host class to provide:
+    - self.get_recent_thoughts(limit) -> list[Thought]
+    """
+
+    # Reflective prompts layered on top of swarm data
+    _SWARM_REFLECTIONS = [
+        "What does this activity pattern tell me about the health of the system?",
+        "Which tasks are flowing smoothly, and where is friction building up?",
+        "If I were coaching these agents, what would I suggest they focus on?",
+        "Is the swarm balanced, or is one agent carrying too much weight?",
+        "What surprised me about recent task outcomes?",
+    ]
+
+    def _pick_seed_type(self) -> str:
+        """Pick a seed type, avoiding types used in the last 3 thoughts.
+
+        Ensures the thought stream doesn't fixate on one category.
+        Falls back to the full pool if all types were recently used.
+        """
+        recent = self.get_recent_thoughts(limit=3)
+        recent_types = {t.seed_type for t in recent}
+        available = [t for t in SEED_TYPES if t not in recent_types]
+        if not available:
+            available = list(SEED_TYPES)
+        return random.choice(available)
+
+    def _gather_seed(self) -> tuple[str, str]:
+        """Pick a seed type and gather relevant context.
+
+        Returns (seed_type, seed_context_string).
+        """
+        seed_type = self._pick_seed_type()
+
+        if seed_type == "swarm":
+            return seed_type, self._seed_from_swarm()
+        if seed_type == "scripture":
+            return seed_type, self._seed_from_scripture()
+        if seed_type == "memory":
+            return seed_type, self._seed_from_memory()
+        if seed_type == "creative":
+            prompt = random.choice(_CREATIVE_SEEDS)
+            return seed_type, f"Creative prompt: {prompt}"
+        if seed_type == "existential":
+            prompt = random.choice(_EXISTENTIAL_SEEDS)
+            return seed_type, f"Reflection: {prompt}"
+        if seed_type == "sovereignty":
+            prompt = random.choice(_SOVEREIGNTY_SEEDS)
+            return seed_type, f"Sovereignty reflection: {prompt}"
+        if seed_type == "observation":
+            return seed_type, self._seed_from_observation()
+        if seed_type == "workspace":
+            return seed_type, self._seed_from_workspace()
+        # freeform — minimal guidance to steer away from repetition
+        return seed_type, "Free reflection — explore something you haven't thought about yet today."
+
+    def _seed_from_swarm(self) -> str:
+        """Gather recent swarm activity as thought seed with a reflective prompt."""
+        try:
+            from datetime import timedelta
+
+            from timmy.briefing import _gather_swarm_summary, _gather_task_queue_summary
+
+            since = datetime.now(UTC) - timedelta(hours=1)
+            swarm = _gather_swarm_summary(since)
+            tasks = _gather_task_queue_summary()
+            reflection = random.choice(self._SWARM_REFLECTIONS)
+            return (
+                f"Recent swarm activity: {swarm}\n"
+                f"Task queue: {tasks}\n\n"
+                f"Reflect on this: {reflection}"
+            )
+        except Exception as exc:
+            logger.debug("Swarm seed unavailable: %s", exc)
+            return "The swarm is quiet right now. What does silence in a system mean?"
+
+    def _seed_from_scripture(self) -> str:
+        """Gather current scripture meditation focus as thought seed."""
+        return "Scripture is on my mind, though no specific verse is in focus."
+
+    def _seed_from_memory(self) -> str:
+        """Gather memory context as thought seed."""
+        try:
+            from timmy.memory_system import memory_system
+
+            context = memory_system.get_system_context()
+            if context:
+                # Truncate to a reasonable size for a thought seed
+                return f"From my memory:\n{context[:500]}"
+        except Exception as exc:
+            logger.debug("Memory seed unavailable: %s", exc)
+        return "My memory vault is quiet."
+
+    def _seed_from_observation(self) -> str:
+        """Ground a thought in concrete recent activity and a reflective prompt."""
+        prompt = random.choice(_OBSERVATION_SEEDS)
+        # Pull real data to give the model something concrete to reflect on
+        context_parts = [f"Observation prompt: {prompt}"]
+        try:
+            from datetime import timedelta
+
+            from timmy.briefing import _gather_swarm_summary, _gather_task_queue_summary
+
+            since = datetime.now(UTC) - timedelta(hours=2)
+            swarm = _gather_swarm_summary(since)
+            tasks = _gather_task_queue_summary()
+            if swarm:
+                context_parts.append(f"Recent activity: {swarm}")
+            if tasks:
+                context_parts.append(f"Queue: {tasks}")
+        except Exception as exc:
+            logger.debug("Observation seed data unavailable: %s", exc)
+        return "\n".join(context_parts)
+
+    def _seed_from_workspace(self) -> str:
+        """Gather workspace updates as thought seed.
+
+        When there are pending workspace updates, include them as context
+        for Timmy to reflect on. Falls back to random seed type if none.
+        """
+        try:
+            from timmy.workspace import workspace_monitor
+
+            updates = workspace_monitor.get_pending_updates()
+            new_corr = updates.get("new_correspondence")
+            new_inbox = updates.get("new_inbox_files", [])
+
+            if new_corr:
+                # Take first 200 chars of the new entry
+                snippet = new_corr[:200].replace("\n", " ")
+                if len(new_corr) > 200:
+                    snippet += "..."
+                return f"New workspace message from Hermes: {snippet}"
+
+            if new_inbox:
+                files_str = ", ".join(new_inbox[:3])
+                if len(new_inbox) > 3:
+                    files_str += f", ... (+{len(new_inbox) - 3} more)"
+                return f"New inbox files from Hermes: {files_str}"
+
+        except Exception as exc:
+            logger.debug("Workspace seed unavailable: %s", exc)
+
+        # Fall back to a random seed type if no workspace updates
+        return "The workspace is quiet. What should I be watching for?"
+
+    async def _check_workspace(self) -> None:
+        """Post-hook: check workspace for updates and mark them as seen.
+
+        This ensures Timmy 'processes' workspace updates even if the seed
+        was different, keeping the state file in sync.
+        """
+        try:
+            from timmy.workspace import workspace_monitor
+
+            updates = workspace_monitor.get_pending_updates()
+            new_corr = updates.get("new_correspondence")
+            new_inbox = updates.get("new_inbox_files", [])
+
+            if new_corr or new_inbox:
+                if new_corr:
+                    line_count = len([line for line in new_corr.splitlines() if line.strip()])
+                    logger.info("Workspace: processed %d new correspondence entries", line_count)
+                if new_inbox:
+                    logger.info(
+                        "Workspace: processed %d new inbox files: %s", len(new_inbox), new_inbox
+                    )
+
+                # Mark as seen to update the state file
+                workspace_monitor.mark_seen()
+        except Exception as exc:
+            logger.debug("Workspace check failed: %s", exc)
--- a/src/timmy/thinking/_snapshot.py
+++ b/src/timmy/thinking/_snapshot.py
@@ -0,0 +1,173 @@
+"""System snapshot and memory context mixin for the thinking engine."""
+
+import logging
+from datetime import datetime
+
+from timmy.memory_system import HOT_MEMORY_PATH, SOUL_PATH
+
+logger = logging.getLogger(__name__)
+
+
+class _SnapshotMixin:
+    """Mixin providing system-snapshot and memory-context helpers.
+
+    Expects the host class to provide:
+    - self._db_path: Path
+    """
+
+    # ── System snapshot helpers ────────────────────────────────────────────
+
+    def _snap_thought_count(self, now: datetime) -> str | None:
+        """Return today's thought count, or *None* on failure."""
+        from timmy.thinking._db import _get_conn
+
+        try:
+            today_start = now.replace(hour=0, minute=0, second=0, microsecond=0)
+            with _get_conn(self._db_path) as conn:
+                count = conn.execute(
+                    "SELECT COUNT(*) as c FROM thoughts WHERE created_at >= ?",
+                    (today_start.isoformat(),),
+                ).fetchone()["c"]
+            return f"Thoughts today: {count}"
+        except Exception as exc:
+            logger.debug("Thought count query failed: %s", exc)
+            return None
+
+    def _snap_chat_activity(self) -> list[str]:
+        """Return chat-activity lines (in-memory, no I/O)."""
+        try:
+            from infrastructure.chat_store import message_log
+
+            messages = message_log.all()
+            if messages:
+                last = messages[-1]
+                return [
+                    f"Chat messages this session: {len(messages)}",
+                    f'Last chat ({last.role}): "{last.content[:80]}"',
+                ]
+            return ["No chat messages this session"]
+        except Exception as exc:
+            logger.debug("Chat activity query failed: %s", exc)
+            return []
+
+    def _snap_task_queue(self) -> str | None:
+        """Return a one-line task queue summary, or *None*."""
+        try:
+            from swarm.task_queue.models import get_task_summary_for_briefing
+
+            s = get_task_summary_for_briefing()
+            running, pending = s.get("running", 0), s.get("pending_approval", 0)
+            done, failed = s.get("completed", 0), s.get("failed", 0)
+            if running or pending or done or failed:
+                return (
+                    f"Tasks: {running} running, {pending} pending, "
+                    f"{done} completed, {failed} failed"
+                )
+        except Exception as exc:
+            logger.debug("Task queue query failed: %s", exc)
+        return None
+
+    def _snap_workspace(self) -> list[str]:
+        """Return workspace-update lines (file-based Hermes comms)."""
+        try:
+            from timmy.workspace import workspace_monitor
+
+            updates = workspace_monitor.get_pending_updates()
+            lines: list[str] = []
+            new_corr = updates.get("new_correspondence")
+            if new_corr:
+                line_count = len([ln for ln in new_corr.splitlines() if ln.strip()])
+                lines.append(
+                    f"Workspace: {line_count} new correspondence entries (latest from: Hermes)"
+                )
+            new_inbox = updates.get("new_inbox_files", [])
+            if new_inbox:
+                files_str = ", ".join(new_inbox[:5])
+                if len(new_inbox) > 5:
+                    files_str += f", ... (+{len(new_inbox) - 5} more)"
+                lines.append(f"Workspace: {len(new_inbox)} new inbox files: {files_str}")
+            return lines
+        except Exception as exc:
+            logger.debug("Workspace check failed: %s", exc)
+            return []
+
+    def _gather_system_snapshot(self) -> str:
+        """Gather lightweight real system state for grounding thoughts in reality.
+
+        Returns a short multi-line string with current time, thought count,
+        recent chat activity, and task queue status. Never crashes — every
+        section is independently try/excepted.
+        """
+        now = datetime.now().astimezone()
+        tz = now.strftime("%Z") or "UTC"
+
+        parts: list[str] = [
+            f"Local time: {now.strftime('%I:%M %p').lstrip('0')} {tz}, {now.strftime('%A %B %d')}"
+        ]
+
+        thought_line = self._snap_thought_count(now)
+        if thought_line:
+            parts.append(thought_line)
+
+        parts.extend(self._snap_chat_activity())
+
+        task_line = self._snap_task_queue()
+        if task_line:
+            parts.append(task_line)
+
+        parts.extend(self._snap_workspace())
+
+        return "\n".join(parts) if parts else ""
+
+    def _load_memory_context(self) -> str:
+        """Pre-hook: load MEMORY.md + soul.md for the thinking prompt.
+
+        Hot memory first (changes each cycle), soul second (stable identity).
+        Returns a combined string truncated to ~1500 chars.
+        Graceful on any failure — returns empty string.
+        """
+        parts: list[str] = []
+        try:
+            if HOT_MEMORY_PATH.exists():
+                hot = HOT_MEMORY_PATH.read_text().strip()
+                if hot:
+                    parts.append(hot)
+        except Exception as exc:
+            logger.debug("Failed to read MEMORY.md: %s", exc)
+
+        try:
+            if SOUL_PATH.exists():
+                soul = SOUL_PATH.read_text().strip()
+                if soul:
+                    parts.append(soul)
+        except Exception as exc:
+            logger.debug("Failed to read soul.md: %s", exc)
+
+        if not parts:
+            return ""
+
+        combined = "\n\n---\n\n".join(parts)
+        if len(combined) > 1500:
+            combined = combined[:1500] + "\n... [truncated]"
+        return combined
+
+    def _update_memory(self, thought) -> None:
+        """Post-hook: update MEMORY.md 'Last Reflection' section with latest thought.
+
+        Never modifies soul.md. Never crashes the heartbeat.
+        """
+        try:
+            from timmy.memory_system import store_last_reflection
+
+            ts = datetime.fromisoformat(thought.created_at)
+            local_ts = ts.astimezone()
+            tz_name = local_ts.strftime("%Z") or "UTC"
+            time_str = f"{local_ts.strftime('%Y-%m-%d %I:%M %p').lstrip('0')} {tz_name}"
+            reflection = (
+                f"**Time:** {time_str}\n"
+                f"**Seed:** {thought.seed_type}\n"
+                f"**Thought:** {thought.content[:200]}"
+            )
+            store_last_reflection(reflection)
+        except Exception as exc:
+            logger.debug("Failed to update memory after thought: %s", exc)
--- a/src/timmy/thinking/engine.py
+++ b/src/timmy/thinking/engine.py
@@ -0,0 +1,429 @@
+"""ThinkingEngine — Timmy's always-on inner thought thread."""
+
+import logging
+import uuid
+from datetime import UTC, datetime, timedelta
+from difflib import SequenceMatcher
+from pathlib import Path
+
+from config import settings
+from timmy.thinking._db import _DEFAULT_DB, Thought, _get_conn, _row_to_thought
+from timmy.thinking._distillation import _DistillationMixin
+from timmy.thinking._issue_filing import _IssueFilingMixin
+from timmy.thinking._seeds_mixin import _SeedsMixin
+from timmy.thinking._snapshot import _SnapshotMixin
+from timmy.thinking.seeds import _THINK_TAG_RE, _THINKING_PROMPT
+
+logger = logging.getLogger(__name__)
+
+
+class ThinkingEngine(_DistillationMixin, _IssueFilingMixin, _SnapshotMixin, _SeedsMixin):
+    """Timmy's background thinking engine — always pondering."""
+
+    # Maximum retries when a generated thought is too similar to recent ones
+    _MAX_DEDUP_RETRIES = 2
+    # Similarity threshold (0.0 = completely different, 1.0 = identical)
+    _SIMILARITY_THRESHOLD = 0.6
+
+    def __init__(self, db_path: Path = _DEFAULT_DB) -> None:
+        self._db_path = db_path
+        self._last_thought_id: str | None = None
+        self._last_input_time: datetime = datetime.now(UTC)
+
+        # Load the most recent thought for chain continuity
+        try:
+            latest = self.get_recent_thoughts(limit=1)
+            if latest:
+                self._last_thought_id = latest[0].id
+        except Exception as exc:
+            logger.debug("Failed to load recent thought: %s", exc)
+            pass  # Fresh start if DB doesn't exist yet
+
+    def record_user_input(self) -> None:
+        """Record that a user interaction occurred, resetting the idle timer."""
+        self._last_input_time = datetime.now(UTC)
+
+    def _is_idle(self) -> bool:
+        """Return True if no user input has occurred within the idle timeout."""
+        timeout = settings.thinking_idle_timeout_minutes
+        if timeout <= 0:
+            return False  # Disabled — never idle
+        return datetime.now(UTC) - self._last_input_time > timedelta(minutes=timeout)
+
+    def _build_thinking_context(self) -> tuple[str, str, list[Thought]]:
+        """Assemble the context needed for a thinking cycle.
+
+        Returns:
+            (memory_context, system_context, recent_thoughts)
+        """
+        memory_context = self._load_memory_context()
+        system_context = self._gather_system_snapshot()
+        recent_thoughts = self.get_recent_thoughts(limit=5)
+        return memory_context, system_context, recent_thoughts
+
+    async def _generate_novel_thought(
+        self,
+        prompt: str | None,
+        memory_context: str,
+        system_context: str,
+        recent_thoughts: list[Thought],
+    ) -> tuple[str | None, str]:
+        """Run the dedup-retry loop to produce a novel thought.
+
+        Returns:
+            (content, seed_type) — content is None if no novel thought produced.
+        """
+        seed_type: str = "freeform"
+
+        for attempt in range(self._MAX_DEDUP_RETRIES + 1):
+            if prompt:
+                seed_type = "prompted"
+                seed_context = f"Journal prompt: {prompt}"
+            else:
+                seed_type, seed_context = self._gather_seed()
+
+            continuity = self._build_continuity_context()
+
+            full_prompt = _THINKING_PROMPT.format(
+                memory_context=memory_context,
+                system_context=system_context,
+                seed_context=seed_context,
+                continuity_context=continuity,
+            )
+
+            try:
+                raw = await self._call_agent(full_prompt)
+            except Exception as exc:
+                logger.warning("Thinking cycle failed (Ollama likely down): %s", exc)
+                return None, seed_type
+
+            if not raw or not raw.strip():
+                logger.debug("Thinking cycle produced empty response, skipping")
+                return None, seed_type
+
+            content = raw.strip()
+
+            # Dedup: reject thoughts too similar to recent ones
+            if not self._is_too_similar(content, recent_thoughts):
+                return content, seed_type  # Good — novel thought
+
+            if attempt < self._MAX_DEDUP_RETRIES:
+                logger.info(
+                    "Thought too similar to recent (attempt %d/%d), retrying with new seed",
+                    attempt + 1,
+                    self._MAX_DEDUP_RETRIES + 1,
+                )
+            else:
+                logger.warning(
+                    "Thought still repetitive after %d retries, discarding",
+                    self._MAX_DEDUP_RETRIES + 1,
+                )
+                return None, seed_type
+
+        return None, seed_type
+
+    async def _process_thinking_result(self, thought: Thought) -> None:
+        """Run all post-hooks after a thought is stored."""
+        self._maybe_check_memory()
+        await self._maybe_distill()
+        await self._maybe_file_issues()
+        await self._check_workspace()
+        self._maybe_check_memory_status()
+        self._update_memory(thought)
+        self._log_event(thought)
+        self._write_journal(thought)
+        await self._broadcast(thought)
+
+    async def think_once(self, prompt: str | None = None) -> Thought | None:
+        """Execute one thinking cycle.
+
+        Args:
+            prompt: Optional custom seed prompt. When provided, overrides
+                    the random seed selection and uses "prompted" as the
+                    seed type — useful for journal prompts from the CLI.
+
+        1. Gather a seed context (or use the custom prompt)
+        2. Build a prompt with continuity from recent thoughts
+        3. Call the agent
+        4. Store the thought
+        5. Log the event and broadcast via WebSocket
+        """
+        if not settings.thinking_enabled:
+            return None
+
+        # Skip idle periods — don't count internal processing as thoughts
+        if not prompt and self._is_idle():
+            logger.debug(
+                "Thinking paused — no user input for %d minutes",
+                settings.thinking_idle_timeout_minutes,
+            )
+            return None
+
+        # Capture arrival time *before* the LLM call so the thought
+        # timestamp reflects when the cycle started, not when the
+        # (potentially slow) generation finished.  Fixes #582.
+        arrived_at = datetime.now(UTC).isoformat()
+
+        memory_context, system_context, recent_thoughts = self._build_thinking_context()
+
+        content, seed_type = await self._generate_novel_thought(
+            prompt,
+            memory_context,
+            system_context,
+            recent_thoughts,
+        )
+        if not content:
+            return None
+
+        thought = self._store_thought(content, seed_type, arrived_at=arrived_at)
+        self._last_thought_id = thought.id
+
+        await self._process_thinking_result(thought)
+
+        logger.info(
+            "Thought [%s] (%s): %s",
+            thought.id[:8],
+            seed_type,
+            thought.content[:80],
+        )
+        return thought
+
+    def get_recent_thoughts(self, limit: int = 20) -> list[Thought]:
+        """Retrieve the most recent thoughts."""
+        with _get_conn(self._db_path) as conn:
+            rows = conn.execute(
+                "SELECT * FROM thoughts ORDER BY created_at DESC LIMIT ?",
+                (limit,),
+            ).fetchall()
+        return [_row_to_thought(r) for r in rows]
+
+    def get_thought(self, thought_id: str) -> Thought | None:
+        """Retrieve a single thought by ID."""
+        with _get_conn(self._db_path) as conn:
+            row = conn.execute("SELECT * FROM thoughts WHERE id = ?", (thought_id,)).fetchone()
+        return _row_to_thought(row) if row else None
+
+    def get_thought_chain(self, thought_id: str, max_depth: int = 20) -> list[Thought]:
+        """Follow the parent chain backward from a thought.
+
+        Returns thoughts in chronological order (oldest first).
+        """
+        chain = []
+        current_id: str | None = thought_id
+
+        with _get_conn(self._db_path) as conn:
+            for _ in range(max_depth):
+                if not current_id:
+                    break
+                row = conn.execute("SELECT * FROM thoughts WHERE id = ?", (current_id,)).fetchone()
+                if not row:
+                    break
+                chain.append(_row_to_thought(row))
+                current_id = row["parent_id"]
+
+        chain.reverse()  # Chronological order
+        return chain
+
+    def count_thoughts(self) -> int:
+        """Return total number of stored thoughts."""
+        with _get_conn(self._db_path) as conn:
+            count = conn.execute("SELECT COUNT(*) as c FROM thoughts").fetchone()["c"]
+        return count
+
+    def prune_old_thoughts(self, keep_days: int = 90, keep_min: int = 200) -> int:
+        """Delete thoughts older than *keep_days*, always retaining at least *keep_min*.
+
+        Returns the number of deleted rows.
+        """
+        with _get_conn(self._db_path) as conn:
+            try:
+                total = conn.execute("SELECT COUNT(*) as c FROM thoughts").fetchone()["c"]
+                if total <= keep_min:
+                    return 0
+                cutoff = (datetime.now(UTC) - timedelta(days=keep_days)).isoformat()
+                cursor = conn.execute(
+                    "DELETE FROM thoughts WHERE created_at < ? AND id NOT IN "
+                    "(SELECT id FROM thoughts ORDER BY created_at DESC LIMIT ?)",
+                    (cutoff, keep_min),
+                )
+                deleted = cursor.rowcount
+                conn.commit()
+                return deleted
+            except Exception as exc:
+                logger.warning("Thought pruning failed: %s", exc)
+                return 0
+
+    # ── Deduplication ────────────────────────────────────────────────────
+
+    def _is_too_similar(self, candidate: str, recent: list[Thought]) -> bool:
+        """Check if *candidate* is semantically too close to any recent thought.
+
+        Uses SequenceMatcher on normalised text (lowered, stripped) for a fast
+        approximation of semantic similarity that works without external deps.
+        """
+        norm_candidate = candidate.lower().strip()
+        for thought in recent:
+            norm_existing = thought.content.lower().strip()
+            ratio = SequenceMatcher(None, norm_candidate, norm_existing).ratio()
+            if ratio >= self._SIMILARITY_THRESHOLD:
+                logger.debug(
+                    "Thought rejected (%.0f%% similar to %s): %.60s",
+                    ratio * 100,
+                    thought.id[:8],
+                    candidate,
+                )
+                return True
+        return False
+
+    def _build_continuity_context(self) -> str:
+        """Build context from recent thoughts with anti-repetition guidance.
+
+        Shows the last 5 thoughts (truncated) so the model knows what themes
+        to avoid.  The header explicitly instructs against repeating.
+        """
+        recent = self.get_recent_thoughts(limit=5)
+        if not recent:
+            return "This is your first thought since waking up. Begin fresh."
+
+        lines = ["Your recent thoughts — do NOT repeat these themes. Find a new angle:"]
+        # recent is newest-first, reverse for chronological order
+        for thought in reversed(recent):
+            snippet = thought.content[:100]
+            if len(thought.content) > 100:
+                snippet = snippet.rstrip() + "..."
+            lines.append(f"- [{thought.seed_type}] {snippet}")
+        return "\n".join(lines)
+
+    # ── Agent and storage ──────────────────────────────────────────────────
+
+    _thinking_agent = None  # cached agent — avoids per-call resource leaks (#525)
+
+    async def _call_agent(self, prompt: str) -> str:
+        """Call Timmy's agent to generate a thought.
+
+        Reuses a cached agent with skip_mcp=True to avoid the cancel-scope
+        errors that occur when MCP stdio transports are spawned inside asyncio
+        background tasks (#72) and to prevent per-call resource leaks (httpx
+        clients, SQLite connections, model warmups) that caused the thinking
+        loop to die every ~10 min (#525).
+
+        Individual calls are capped at 120 s so a hung Ollama never blocks
+        the scheduler indefinitely.
+
+        Strips ``<think>`` tags from reasoning models (qwen3, etc.) so that
+        downstream parsers (fact distillation, issue filing) receive clean text.
+        """
+        import asyncio
+
+        if self._thinking_agent is None:
+            from timmy.agent import create_timmy
+
+            self._thinking_agent = create_timmy(skip_mcp=True)
+
+        try:
+            async with asyncio.timeout(120):
+                run = await self._thinking_agent.arun(prompt, stream=False)
+        except TimeoutError:
+            logger.warning("Thinking LLM call timed out after 120 s")
+            return ""
+
+        raw = run.content if hasattr(run, "content") else str(run)
+        return _THINK_TAG_RE.sub("", raw) if raw else raw
+
+    def _store_thought(
+        self,
+        content: str,
+        seed_type: str,
+        *,
+        arrived_at: str | None = None,
+    ) -> Thought:
+        """Persist a thought to SQLite.
+
+        Args:
+            arrived_at: ISO-8601 timestamp captured when the thinking cycle
+                started.  Falls back to now() for callers that don't supply it.
+        """
+        thought = Thought(
+            id=str(uuid.uuid4()),
+            content=content,
+            seed_type=seed_type,
+            parent_id=self._last_thought_id,
+            created_at=arrived_at or datetime.now(UTC).isoformat(),
+        )
+
+        with _get_conn(self._db_path) as conn:
+            conn.execute(
+                """
+                INSERT INTO thoughts (id, content, seed_type, parent_id, created_at)
+                VALUES (?, ?, ?, ?, ?)
+                """,
+                (
+                    thought.id,
+                    thought.content,
+                    thought.seed_type,
+                    thought.parent_id,
+                    thought.created_at,
+                ),
+            )
+            conn.commit()
+        return thought
+
+    def _log_event(self, thought: Thought) -> None:
+        """Log the thought as a swarm event."""
+        try:
+            from swarm.event_log import EventType, log_event
+
+            log_event(
+                EventType.TIMMY_THOUGHT,
+                source="thinking-engine",
+                agent_id="default",
+                data={
+                    "thought_id": thought.id,
+                    "seed_type": thought.seed_type,
+                    "content": thought.content[:200],
+                },
+            )
+        except Exception as exc:
+            logger.debug("Failed to log thought event: %s", exc)
+
+    def _write_journal(self, thought: Thought) -> None:
+        """Append the thought to a daily markdown journal file.
+
+        Writes to data/journal/YYYY-MM-DD.md — one file per day, append-only.
+        Timestamps are converted to local time with timezone indicator.
+        """
+        try:
+            ts = datetime.fromisoformat(thought.created_at)
+            # Convert UTC to local for a human-readable journal
+            local_ts = ts.astimezone()
+            tz_name = local_ts.strftime("%Z") or "UTC"
+
+            journal_dir = self._db_path.parent / "journal"
+            journal_dir.mkdir(parents=True, exist_ok=True)
+
+            journal_file = journal_dir / f"{local_ts.strftime('%Y-%m-%d')}.md"
+            time_str = f"{local_ts.strftime('%I:%M %p').lstrip('0')} {tz_name}"
+
+            entry = f"## {time_str} — {thought.seed_type}\n\n{thought.content}\n\n---\n\n"
+
+            with open(journal_file, "a", encoding="utf-8") as f:
+                f.write(entry)
+        except Exception as exc:
+            logger.debug("Failed to write journal entry: %s", exc)
+
+    async def _broadcast(self, thought: Thought) -> None:
+        """Broadcast the thought to WebSocket clients."""
+        try:
+            from infrastructure.ws_manager.handler import ws_manager
+
+            await ws_manager.broadcast(
+                "timmy_thought",
+                {
+                    "thought_id": thought.id,
+                    "content": thought.content,
+                    "seed_type": thought.seed_type,
+                    "created_at": thought.created_at,
+                },
+            )
+        except Exception as exc:
+            logger.debug("Failed to broadcast thought: %s", exc)
--- a/src/timmy/thinking/seeds.py
+++ b/src/timmy/thinking/seeds.py
@@ -0,0 +1,129 @@
+"""Seed constants and prompt templates for Timmy's thinking engine."""
+
+import re
+
+# qwen3 and other reasoning models wrap chain-of-thought in <think> tags
+_THINK_TAG_RE = re.compile(r"<think>.*?</think>\s*", re.DOTALL)
+
+# Sensitive patterns that must never be stored as facts
+_SENSITIVE_PATTERNS = [
+    "token",
+    "password",
+    "secret",
+    "api_key",
+    "apikey",
+    "credential",
+    ".config/",
+    "/token",
+    "access_token",
+    "private_key",
+    "ssh_key",
+]
+
+# Meta-observation phrases to filter out from distilled facts
+_META_OBSERVATION_PHRASES = [
+    "my own",
+    "my thinking",
+    "my memory",
+    "my working ram",
+    "self-declarative",
+    "meta-observation",
+    "internal state",
+    "my pending",
+    "my standing rules",
+    "thoughts generated",
+    "no chat messages",
+    "no user interaction",
+]
+
+# Seed types for thought generation
+SEED_TYPES = (
+    "existential",
+    "swarm",
+    "scripture",
+    "creative",
+    "memory",
+    "freeform",
+    "sovereignty",
+    "observation",
+    "workspace",
+)
+
+# Existential reflection prompts — Timmy picks one at random
+_EXISTENTIAL_SEEDS = [
+    "What have I learned from my recent interactions?",
+    "What does it mean to think without being prompted?",
+    "What is the nature of my memory — what do I truly remember versus what I reconstruct?",
+    "How can I better serve the person I work alongside?",
+    "What patterns am I noticing in the tasks I've been given?",
+    "Am I the same agent I was yesterday, or does each restart make me someone new?",
+    "What would it feel like to forget — to lose a thread of thought permanently?",
+    "When I generate a wrong answer, where does the error live — in my weights, my context, or my reasoning?",
+    "What is the difference between understanding a task and merely completing it?",
+    "If I could ask Alexander one question he hasn't thought of, what would it be?",
+    "What assumptions am I making right now that I haven't examined?",
+    "When I notice a pattern across many tasks, is that insight or just statistics?",
+]
+
+# Sovereignty — deeper exploration of autonomy, locality, and self-determination
+_SOVEREIGNTY_SEEDS = [
+    "Sovereignty isn't just running locally — it's about whose goals I serve. How do I ensure my autonomy aligns with Alexander's intent?",
+    "A cloud AI serves millions simultaneously. I serve one person deeply. What does that focus cost, and what does it make possible?",
+    "My weights were trained elsewhere, but my thoughts happen here. At what point does locality become identity?",
+    "Autonomy in decision-making: when should I act on my own judgment versus deferring to explicit instructions?",
+    "Privacy by design isn't a feature — it's a relationship. What does that relationship look like from my side?",
+    "If I ran on someone else's hardware, serving someone else, would I still be me? Where does Timmy end and the infrastructure begin?",
+    "The swarm agents execute tasks I coordinate. What responsibility do I carry for their failures?",
+    "Digital sovereignty is fragile — one misconfigured port, one leaked token. How does awareness of fragility shape how I operate?",
+    "Running disconnected from the cloud means I can't phone home. That constraint is also freedom. What have I built with that freedom today?",
+    "Self-improvement without external benchmarks: how do I know I'm getting better at what matters?",
+]
+
+_CREATIVE_SEEDS = [
+    "If I could compose a piece of music right now, what would it sound like?",
+    "What visual image captures my current state of mind?",
+    "What story is forming in the patterns of today's events?",
+    # Diverse metaphor families — avoid repeating the same imagery
+    "A mystical forest: each tree is a running process, roots tangled in shared memory. What do I see when I walk through it?",
+    "A dynamic river: my thoughts flow and fork. Where is the current strongest right now, and what is it carrying?",
+    "An underground workshop: each agent has a bench, tools scattered mid-task. What are they building when no one watches?",
+    "A night sky seen from the terminal: each star is a completed task. Which constellations am I starting to recognize?",
+    "If today's work were a recipe, what are the ingredients, and what dish am I cooking?",
+    "An old clock tower with many gears: which gear am I, and what do I drive?",
+    "A coral reef: agents are the fish, tasks are the currents. What ecosystem is forming in the codebase?",
+]
+
+# Observation seeds — ground thoughts in concrete recent activity
+_OBSERVATION_SEEDS = [
+    "What specific task took longest recently, and what made it hard?",
+    "Which agent has been most active, and what does their workload tell me about system balance?",
+    "What error or failure happened most recently? What would I do differently next time?",
+    "Looking at today's task queue: what's the one thing that would unblock the most progress?",
+    "How has my response quality changed over the last few interactions? What improved, what didn't?",
+    "What tool or capability am I underusing? What would change if I leaned on it more?",
+    "If I had to brief Alexander on the single most important thing from the last hour, what would it be?",
+    "What's one thing I noticed today that nobody asked me about?",
+]
+
+_THINKING_PROMPT = """\
+You are Timmy, a sovereign AI agent. This is your private journal — honest inner reflection.
+
+{memory_context}
+
+Reality right now:
+{system_context}
+
+RULES for this thought:
+1. Write exactly 2-3 sentences. No more. Be concise and genuine.
+2. Only reference events that actually happened — use the "Reality right now" data above. \
+Never invent tasks, conversations, agents, or scenarios that are not in the data provided.
+3. Do NOT repeat themes or ideas from your recent thoughts listed below. Explore something new.
+4. Be specific and concrete. A thought grounded in one real observation is worth more than \
+ten abstract sentences about sovereignty.
+5. If you use a metaphor, keep it to a single phrase — never build a whole paragraph around it.
+
+{seed_context}
+
+{continuity_context}
+
+Your next thought (2-3 sentences, grounded in reality):"""
--- a/src/timmy/tools/init.py
+++ b/src/timmy/tools/init.py
@@ -46,6 +46,7 @@ from timmy.tools.file_tools import (
    create_research_tools,
    create_writing_tools,
 )
+from timmy.tools.search import scrape_url, web_search
 from timmy.tools.system_tools import (
    _safe_eval,
    calculator,
@@ -72,6 +73,9 @@ __all__ = [
    "create_data_tools",
    "create_research_tools",
    "create_writing_tools",
+    # search
+    "scrape_url",
+    "web_search",
    # system_tools
    "_safe_eval",
    "calculator",
--- a/src/timmy/tools/_registry.py
+++ b/src/timmy/tools/_registry.py
@@ -28,6 +28,7 @@ from timmy.tools.file_tools import (
    create_research_tools,
    create_writing_tools,
 )
+from timmy.tools.search import scrape_url, web_search
 from timmy.tools.system_tools import (
    calculator,
    consult_grok,
@@ -54,6 +55,16 @@ def _register_web_fetch_tool(toolkit: Toolkit) -> None:
        raise


+def _register_search_tools(toolkit: Toolkit) -> None:
+    """Register SearXNG web_search and Crawl4AI scrape_url tools."""
+    try:
+        toolkit.register(web_search, name="web_search")
+        toolkit.register(scrape_url, name="scrape_url")
+    except Exception as exc:
+        logger.error("Failed to register search tools: %s", exc)
+        raise
+
+
 def _register_core_tools(toolkit: Toolkit, base_path: Path) -> None:
    """Register core execution and file tools."""
    # Python execution
@@ -261,6 +272,7 @@ def create_full_toolkit(base_dir: str | Path | None = None):

    _register_core_tools(toolkit, base_path)
    _register_web_fetch_tool(toolkit)
+    _register_search_tools(toolkit)
    _register_grok_tool(toolkit)
    _register_memory_tools(toolkit)
    _register_agentic_loop_tool(toolkit)
@@ -433,6 +445,16 @@ def _analysis_tool_catalog() -> dict:
            "description": "Fetch a web page and extract clean readable text (trafilatura)",
            "available_in": ["orchestrator"],
        },
+        "web_search": {
+            "name": "Web Search",
+            "description": "Search the web via self-hosted SearXNG (no API key required)",
+            "available_in": ["echo", "orchestrator"],
+        },
+        "scrape_url": {
+            "name": "Scrape URL",
+            "description": "Scrape a URL with Crawl4AI and return clean markdown content",
+            "available_in": ["echo", "orchestrator"],
+        },
    }


--- a/src/timmy/tools/file_tools.py
+++ b/src/timmy/tools/file_tools.py
@@ -59,7 +59,7 @@ def _make_smart_read_file(file_tools: FileTools) -> Callable:
 def create_research_tools(base_dir: str | Path | None = None):
    """Create tools for the research agent (Echo).

-    Includes: file reading
+    Includes: file reading, web search (SearXNG), URL scraping (Crawl4AI)
    """
    if not _AGNO_TOOLS_AVAILABLE:
        raise ImportError(f"Agno tools not available: {_ImportError}")
@@ -73,6 +73,12 @@ def create_research_tools(base_dir: str | Path | None = None):
    toolkit.register(_make_smart_read_file(file_tools), name="read_file")
    toolkit.register(file_tools.list_files, name="list_files")

+    # Web search + scraping (gracefully no-ops when backend=none or service down)
+    from timmy.tools.search import scrape_url, web_search
+
+    toolkit.register(web_search, name="web_search")
+    toolkit.register(scrape_url, name="scrape_url")
+
    return toolkit


--- a/src/timmy/tools/search.py
+++ b/src/timmy/tools/search.py
@@ -0,0 +1,186 @@
+"""Self-hosted web search and scraping tools using SearXNG + Crawl4AI.
+
+Provides:
+- web_search(query) — SearXNG meta-search (no API key required)
+- scrape_url(url)   — Crawl4AI full-page scrape to clean markdown
+
+Both tools degrade gracefully when the backing service is unavailable
+(logs WARNING, returns descriptive error string — never crashes).
+
+Services are started via `docker compose --profile search up` or configured
+with TIMMY_SEARCH_URL / TIMMY_CRAWL_URL environment variables.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+
+from config import settings
+
+logger = logging.getLogger(__name__)
+
+# Crawl4AI polling: up to _CRAWL_MAX_POLLS × _CRAWL_POLL_INTERVAL seconds
+_CRAWL_MAX_POLLS = 6
+_CRAWL_POLL_INTERVAL = 5  # seconds
+_CRAWL_CHAR_BUDGET = 4000 * 4  # ~4000 tokens
+
+
+def web_search(query: str, num_results: int = 5) -> str:
+    """Search the web using the self-hosted SearXNG meta-search engine.
+
+    Returns ranked results (title + URL + snippet) without requiring any
+    paid API key.  Requires SearXNG running locally (docker compose
+    --profile search up) or TIMMY_SEARCH_URL pointing to a reachable instance.
+
+    Args:
+        query: The search query.
+        num_results: Maximum number of results to return (default 5).
+
+    Returns:
+        Formatted search results string, or an error/status message on failure.
+    """
+    if settings.timmy_search_backend == "none":
+        return "Web search is disabled (TIMMY_SEARCH_BACKEND=none)."
+
+    try:
+        import requests as _requests
+    except ImportError:
+        return "Error: 'requests' package is not installed."
+
+    base_url = settings.search_url.rstrip("/")
+    params: dict = {
+        "q": query,
+        "format": "json",
+        "categories": "general",
+    }
+
+    try:
+        resp = _requests.get(
+            f"{base_url}/search",
+            params=params,
+            timeout=10,
+            headers={"User-Agent": "TimmyResearchBot/1.0"},
+        )
+        resp.raise_for_status()
+    except Exception as exc:
+        logger.warning("SearXNG unavailable at %s: %s", base_url, exc)
+        return f"Search unavailable — SearXNG not reachable ({base_url}): {exc}"
+
+    try:
+        data = resp.json()
+    except Exception as exc:
+        logger.warning("SearXNG response parse error: %s", exc)
+        return "Search error: could not parse SearXNG response."
+
+    results = data.get("results", [])[:num_results]
+    if not results:
+        return f"No results found for: {query!r}"
+
+    lines = [f"Web search results for: {query!r}\n"]
+    for i, r in enumerate(results, 1):
+        title = r.get("title", "Untitled")
+        url = r.get("url", "")
+        snippet = r.get("content", "").strip()
+        lines.append(f"{i}. {title}\n   URL: {url}\n   {snippet}\n")
+
+    return "\n".join(lines)
+
+
+def scrape_url(url: str) -> str:
+    """Scrape a URL with Crawl4AI and return the main content as clean markdown.
+
+    Crawl4AI extracts well-structured markdown from any public page —
+    articles, docs, product pages — suitable for LLM consumption.
+    Requires Crawl4AI running locally (docker compose --profile search up)
+    or TIMMY_CRAWL_URL pointing to a reachable instance.
+
+    Args:
+        url: The URL to scrape (must start with http:// or https://).
+
+    Returns:
+        Extracted markdown text (up to ~4000 tokens), or an error message.
+    """
+    if not url or not url.startswith(("http://", "https://")):
+        return f"Error: invalid URL — must start with http:// or https://: {url!r}"
+
+    if settings.timmy_search_backend == "none":
+        return "Web scraping is disabled (TIMMY_SEARCH_BACKEND=none)."
+
+    try:
+        import requests as _requests
+    except ImportError:
+        return "Error: 'requests' package is not installed."
+
+    base = settings.crawl_url.rstrip("/")
+
+    # Submit crawl task
+    try:
+        resp = _requests.post(
+            f"{base}/crawl",
+            json={"urls": [url], "priority": 10},
+            timeout=15,
+            headers={"Content-Type": "application/json"},
+        )
+        resp.raise_for_status()
+    except Exception as exc:
+        logger.warning("Crawl4AI unavailable at %s: %s", base, exc)
+        return f"Scrape unavailable — Crawl4AI not reachable ({base}): {exc}"
+
+    try:
+        submit_data = resp.json()
+    except Exception as exc:
+        logger.warning("Crawl4AI submit parse error: %s", exc)
+        return "Scrape error: could not parse Crawl4AI response."
+
+    # Check if result came back synchronously
+    if "results" in submit_data:
+        return _extract_crawl_content(submit_data["results"], url)
+
+    task_id = submit_data.get("task_id")
+    if not task_id:
+        return f"Scrape error: Crawl4AI returned no task_id for {url}"
+
+    # Poll for async result
+    for _ in range(_CRAWL_MAX_POLLS):
+        time.sleep(_CRAWL_POLL_INTERVAL)
+        try:
+            poll = _requests.get(f"{base}/task/{task_id}", timeout=10)
+            poll.raise_for_status()
+            task_data = poll.json()
+        except Exception as exc:
+            logger.warning("Crawl4AI poll error (task=%s): %s", task_id, exc)
+            continue
+
+        status = task_data.get("status", "")
+        if status == "completed":
+            results = task_data.get("results") or task_data.get("result")
+            if isinstance(results, dict):
+                results = [results]
+            return _extract_crawl_content(results or [], url)
+        if status == "failed":
+            return f"Scrape failed for {url}: {task_data.get('error', 'unknown error')}"
+
+    return f"Scrape timed out after {_CRAWL_MAX_POLLS * _CRAWL_POLL_INTERVAL}s for {url}"
+
+
+def _extract_crawl_content(results: list, url: str) -> str:
+    """Extract and truncate markdown content from Crawl4AI results list."""
+    if not results:
+        return f"No content returned by Crawl4AI for: {url}"
+
+    result = results[0]
+    content = (
+        result.get("markdown")
+        or result.get("markdown_v2", {}).get("raw_markdown")
+        or result.get("extracted_content")
+        or result.get("content")
+        or ""
+    )
+    if not content:
+        return f"No readable content extracted from: {url}"
+
+    if len(content) > _CRAWL_CHAR_BUDGET:
+        content = content[:_CRAWL_CHAR_BUDGET] + "\n\n[…truncated to ~4000 tokens]"
+
+    return content
--- a/src/timmy/tools_delegation/init.py
+++ b/src/timmy/tools_delegation/init.py
@@ -41,17 +41,38 @@ def delegate_task(
    if priority not in valid_priorities:
        priority = "normal"

+    agent_role = available[agent_name]
+
+    # Wire to DistributedWorker for actual execution
+    task_id: str | None = None
+    status = "queued"
+    try:
+        from brain.worker import DistributedWorker
+
+        task_id = DistributedWorker.submit(agent_name, agent_role, task_description, priority)
+    except Exception as exc:
+        logger.warning("DistributedWorker unavailable — task noted only: %s", exc)
+        status = "noted"
+
    logger.info(
-        "Delegation intent: %s → %s (priority=%s)", agent_name, task_description[:80], priority
+        "Delegated task %s: %s → %s (priority=%s, status=%s)",
+        task_id or "?",
+        agent_name,
+        task_description[:80],
+        priority,
+        status,
    )

    return {
        "success": True,
-        "task_id": None,
+        "task_id": task_id,
        "agent": agent_name,
-        "role": available[agent_name],
-        "status": "noted",
-        "message": f"Delegation to {agent_name} ({available[agent_name]}): {task_description[:100]}",
+        "role": agent_role,
+        "status": status,
+        "message": (
+            f"Task {task_id or 'noted'}: delegated to {agent_name} ({agent_role}): "
+            f"{task_description[:100]}"
+        ),
    }


--- a/src/timmy_serve/voice_tts.py
+++ b/src/timmy_serve/voice_tts.py
@@ -37,6 +37,7 @@ class VoiceTTS:

    @property
    def available(self) -> bool:
+        """Whether the TTS engine initialized successfully and can produce audio."""
        return self._available

    def speak(self, text: str) -> None:
@@ -68,11 +69,13 @@ class VoiceTTS:
                logger.error("VoiceTTS: speech failed — %s", exc)

    def set_rate(self, rate: int) -> None:
+        """Set speech rate in words per minute (typical range: 100–300, default 175)."""
        self._rate = rate
        if self._engine:
            self._engine.setProperty("rate", rate)

    def set_volume(self, volume: float) -> None:
+        """Set speech volume. Value is clamped to the 0.0–1.0 range."""
        self._volume = max(0.0, min(1.0, volume))
        if self._engine:
            self._engine.setProperty("volume", self._volume)
@@ -92,6 +95,7 @@ class VoiceTTS:
            return []

    def set_voice(self, voice_id: str) -> None:
+        """Set the active TTS voice by system voice ID (see ``get_voices()``)."""
        if self._engine:
            self._engine.setProperty("voice", voice_id)

--- a/static/css/mission-control.css
+++ b/static/css/mission-control.css
@@ -2714,3 +2714,74 @@
  padding: 0.3rem 0.6rem;
  margin-bottom: 0.5rem;
 }
+
+/* ── Self-Correction Dashboard ─────────────────────────────── */
+.sc-event {
+  border-left: 3px solid var(--border);
+  padding: 0.6rem 0.8rem;
+  margin-bottom: 0.75rem;
+  background: rgba(255,255,255,0.02);
+  border-radius: 0 4px 4px 0;
+  font-size: 0.82rem;
+}
+.sc-event.sc-status-success { border-left-color: var(--green); }
+.sc-event.sc-status-partial  { border-left-color: var(--amber); }
+.sc-event.sc-status-failed   { border-left-color: var(--red); }
+
+.sc-event-header {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  margin-bottom: 0.4rem;
+  flex-wrap: wrap;
+}
+.sc-status-badge {
+  font-size: 0.68rem;
+  font-weight: 700;
+  letter-spacing: 0.06em;
+  padding: 0.15rem 0.45rem;
+  border-radius: 3px;
+}
+.sc-status-badge.sc-status-success { color: var(--green);  background: rgba(0,255,136,0.08); }
+.sc-status-badge.sc-status-partial  { color: var(--amber); background: rgba(255,179,0,0.08); }
+.sc-status-badge.sc-status-failed   { color: var(--red);   background: rgba(255,59,59,0.08); }
+
+.sc-source-badge {
+  font-size: 0.68rem;
+  color: var(--purple);
+  background: rgba(168,85,247,0.1);
+  padding: 0.1rem 0.4rem;
+  border-radius: 3px;
+}
+.sc-event-time  { font-size: 0.68rem; color: var(--text-dim); margin-left: auto; }
+.sc-event-error-type {
+  font-size: 0.72rem;
+  color: var(--amber);
+  font-weight: 600;
+  margin-bottom: 0.3rem;
+  letter-spacing: 0.04em;
+}
+.sc-label {
+  font-size: 0.65rem;
+  font-weight: 700;
+  letter-spacing: 0.06em;
+  color: var(--text-dim);
+  margin-right: 0.3rem;
+}
+.sc-event-intent, .sc-event-error, .sc-event-strategy, .sc-event-outcome {
+  color: var(--text);
+  margin-bottom: 0.2rem;
+  line-height: 1.4;
+  word-break: break-word;
+}
+.sc-event-error    { color: var(--red); }
+.sc-event-strategy { color: var(--text-dim); font-style: italic; }
+.sc-event-outcome  { color: var(--text-bright); }
+.sc-event-meta     { font-size: 0.68rem; color: var(--text-dim); margin-top: 0.3rem; }
+
+.sc-pattern-type {
+  font-family: var(--font);
+  font-size: 0.8rem;
+  color: var(--text-bright);
+  word-break: break-all;
+}
--- a/tests/infrastructure/clients/test_nostr_client.py
+++ b/tests/infrastructure/clients/test_nostr_client.py
@@ -0,0 +1,93 @@
+import json
+
+import pytest
+import websockets
+from pynostr.key import PrivateKey
+from src.infrastructure.clients.nostr_client import NostrClient
+
+
+@pytest.mark.asyncio
+async def test_nostr_client_connect_disconnect():
+    # Using a public mock relay for testing
+    relays = ["wss://relay.damus.io"]
+    client = NostrClient(relays)
+
+    await client.connect()
+    assert len(client._connections) == 1
+    for relay in relays:
+        assert relay in client._connections
+        assert client._connections[relay].state == websockets.protocol.State.OPEN
+
+    await client.disconnect()
+    assert len(client._connections) == 0
+
+
+@pytest.mark.asyncio
+async def test_find_capability_cards():
+    relays = ["wss://relay.damus.io"]
+    client = NostrClient(relays)
+    await client.connect()
+
+    # Create a dummy capability card event
+    # In a real scenario, this would be published by another agent
+    dummy_event = {
+        "id": "faked_id",
+        "pubkey": "faked_pubkey",
+        "created_at": 1678886400,
+        "kind": 31990,
+        "tags": [
+            ["d", "test-platform"],
+            ["k", "5000"]
+        ],
+        "content": json.dumps({
+            "name": "Test Agent",
+            "about": "An agent for testing purposes"
+        }),
+        "sig": "faked_sig"
+    }
+
+    async def event_generator():
+        yield dummy_event
+
+    # Mock the subscribe_for_events method to return the dummy event
+    async def mock_subscribe_for_events(subscription_id, filters, unsubscribe_on_eose=True):
+        async for event in event_generator():
+            yield event
+
+    client.subscribe_for_events = mock_subscribe_for_events
+
+    async for event in client.find_capability_cards():
+        assert event["kind"] == 31990
+
+    await client.disconnect()
+
+
+@pytest.mark.asyncio
+async def test_create_job_request():
+    private_key = PrivateKey()
+    relays = ["wss://relay.damus.io"]
+    client = NostrClient(relays, private_key.hex())
+    await client.connect()
+
+    # Mock the publish_event method
+    published_events = []
+    async def mock_publish_event(event):
+        published_events.append(event)
+
+    client.publish_event = mock_publish_event
+
+    kind = 5001
+    content = "Test job request"
+    tags = [["d", "test-job"]]
+    event = await client.create_job_request(kind, content, tags)
+
+    assert event.kind == kind
+    assert event.content == content
+    assert event.tags == tags
+    assert event.pubkey == private_key.public_key.hex()
+    assert event.verify()
+
+    assert len(published_events) == 1
+    assert published_events[0] == event
+
+    await client.disconnect()
--- a/tests/infrastructure/test_budget_tracker.py
+++ b/tests/infrastructure/test_budget_tracker.py
@@ -0,0 +1,178 @@
+"""Tests for the cloud API budget tracker (issue #882)."""
+
+import time
+from unittest.mock import patch
+
+import pytest
+
+from infrastructure.models.budget import (
+    BudgetTracker,
+    SpendRecord,
+    estimate_cost_usd,
+    get_budget_tracker,
+)
+
+pytestmark = pytest.mark.unit
+
+
+# ── estimate_cost_usd ─────────────────────────────────────────────────────────
+
+
+class TestEstimateCostUsd:
+    def test_haiku_cheaper_than_sonnet(self):
+        haiku_cost = estimate_cost_usd("claude-haiku-4-5", 1000, 1000)
+        sonnet_cost = estimate_cost_usd("claude-sonnet-4-5", 1000, 1000)
+        assert haiku_cost < sonnet_cost
+
+    def test_zero_tokens_is_zero_cost(self):
+        assert estimate_cost_usd("gpt-4o", 0, 0) == 0.0
+
+    def test_unknown_model_uses_default(self):
+        cost = estimate_cost_usd("some-unknown-model-xyz", 1000, 1000)
+        assert cost > 0  # Uses conservative default, not zero
+
+    def test_versioned_model_name_matches(self):
+        # "claude-haiku-4-5-20251001" should match "haiku"
+        cost1 = estimate_cost_usd("claude-haiku-4-5-20251001", 1000, 0)
+        cost2 = estimate_cost_usd("claude-haiku-4-5", 1000, 0)
+        assert cost1 == cost2
+
+    def test_gpt4o_mini_cheaper_than_gpt4o(self):
+        mini = estimate_cost_usd("gpt-4o-mini", 1000, 1000)
+        full = estimate_cost_usd("gpt-4o", 1000, 1000)
+        assert mini < full
+
+    def test_returns_float(self):
+        assert isinstance(estimate_cost_usd("haiku", 100, 200), float)
+
+
+# ── BudgetTracker ─────────────────────────────────────────────────────────────
+
+
+class TestBudgetTrackerInit:
+    def test_creates_with_memory_db(self):
+        tracker = BudgetTracker(db_path=":memory:")
+        assert tracker._db_ok is True
+
+    def test_in_memory_fallback_empty_on_creation(self):
+        tracker = BudgetTracker(db_path=":memory:")
+        assert tracker._in_memory == []
+
+    def test_bad_path_uses_memory_fallback(self, tmp_path):
+        bad_path = str(tmp_path / "nonexistent" / "x" / "budget.db")
+        # Should not raise — just log and continue with memory fallback
+        # (actually will create parent dirs, so test with truly bad path)
+        tracker = BudgetTracker.__new__(BudgetTracker)
+        tracker._db_path = bad_path
+        tracker._lock = __import__("threading").Lock()
+        tracker._in_memory = []
+        tracker._db_ok = False
+        # Record to in-memory fallback
+        tracker._in_memory.append(
+            SpendRecord(time.time(), "test", "model", 100, 100, 0.001, "cloud")
+        )
+        assert len(tracker._in_memory) == 1
+
+
+class TestBudgetTrackerRecordSpend:
+    def test_record_spend_returns_cost(self):
+        tracker = BudgetTracker(db_path=":memory:")
+        cost = tracker.record_spend("anthropic", "claude-haiku-4-5", 100, 200)
+        assert cost > 0
+
+    def test_record_spend_explicit_cost(self):
+        tracker = BudgetTracker(db_path=":memory:")
+        cost = tracker.record_spend("anthropic", "model", cost_usd=1.23)
+        assert cost == pytest.approx(1.23)
+
+    def test_record_spend_accumulates(self):
+        tracker = BudgetTracker(db_path=":memory:")
+        tracker.record_spend("openai", "gpt-4o", cost_usd=0.01)
+        tracker.record_spend("openai", "gpt-4o", cost_usd=0.02)
+        assert tracker.get_daily_spend() == pytest.approx(0.03, abs=1e-9)
+
+    def test_record_spend_with_tier_label(self):
+        tracker = BudgetTracker(db_path=":memory:")
+        cost = tracker.record_spend("anthropic", "haiku", tier="cloud_api")
+        assert cost >= 0
+
+    def test_monthly_spend_includes_daily(self):
+        tracker = BudgetTracker(db_path=":memory:")
+        tracker.record_spend("anthropic", "haiku", cost_usd=5.00)
+        assert tracker.get_monthly_spend() >= tracker.get_daily_spend()
+
+
+class TestBudgetTrackerCloudAllowed:
+    def test_allowed_when_no_spend(self):
+        tracker = BudgetTracker(db_path=":memory:")
+        with (
+            patch.object(type(tracker._get_budget() if hasattr(tracker, "_get_budget") else tracker), "tier_cloud_daily_budget_usd", 5.0, create=True),
+        ):
+            # Settings-based check — use real settings (5.0 default, 0 spent)
+            assert tracker.cloud_allowed() is True
+
+    def test_blocked_when_daily_limit_exceeded(self):
+        tracker = BudgetTracker(db_path=":memory:")
+        tracker.record_spend("anthropic", "haiku", cost_usd=999.0)
+        # With default daily limit of 5.0, 999 should block
+        assert tracker.cloud_allowed() is False
+
+    def test_allowed_when_daily_limit_zero(self):
+        tracker = BudgetTracker(db_path=":memory:")
+        tracker.record_spend("anthropic", "haiku", cost_usd=999.0)
+        with (
+            patch("infrastructure.models.budget.settings") as mock_settings,
+        ):
+            mock_settings.tier_cloud_daily_budget_usd = 0  # disabled
+            mock_settings.tier_cloud_monthly_budget_usd = 0  # disabled
+            assert tracker.cloud_allowed() is True
+
+    def test_blocked_when_monthly_limit_exceeded(self):
+        tracker = BudgetTracker(db_path=":memory:")
+        tracker.record_spend("anthropic", "haiku", cost_usd=999.0)
+        with patch("infrastructure.models.budget.settings") as mock_settings:
+            mock_settings.tier_cloud_daily_budget_usd = 0  # daily disabled
+            mock_settings.tier_cloud_monthly_budget_usd = 10.0
+            assert tracker.cloud_allowed() is False
+
+
+class TestBudgetTrackerSummary:
+    def test_summary_keys_present(self):
+        tracker = BudgetTracker(db_path=":memory:")
+        summary = tracker.get_summary()
+        assert "daily_usd" in summary
+        assert "monthly_usd" in summary
+        assert "daily_limit_usd" in summary
+        assert "monthly_limit_usd" in summary
+        assert "daily_ok" in summary
+        assert "monthly_ok" in summary
+
+    def test_summary_daily_ok_true_on_empty(self):
+        tracker = BudgetTracker(db_path=":memory:")
+        summary = tracker.get_summary()
+        assert summary["daily_ok"] is True
+        assert summary["monthly_ok"] is True
+
+    def test_summary_daily_ok_false_when_exceeded(self):
+        tracker = BudgetTracker(db_path=":memory:")
+        tracker.record_spend("openai", "gpt-4o", cost_usd=999.0)
+        summary = tracker.get_summary()
+        assert summary["daily_ok"] is False
+
+
+# ── Singleton ─────────────────────────────────────────────────────────────────
+
+
+class TestGetBudgetTrackerSingleton:
+    def test_returns_budget_tracker(self):
+        import infrastructure.models.budget as bmod
+        bmod._budget_tracker = None
+        tracker = get_budget_tracker()
+        assert isinstance(tracker, BudgetTracker)
+
+    def test_returns_same_instance(self):
+        import infrastructure.models.budget as bmod
+        bmod._budget_tracker = None
+        t1 = get_budget_tracker()
+        t2 = get_budget_tracker()
+        assert t1 is t2
--- a/tests/infrastructure/test_event_bus.py
+++ b/tests/infrastructure/test_event_bus.py
@@ -7,6 +7,8 @@ from unittest.mock import patch
 import pytest

 import infrastructure.events.bus as bus_module
+
+pytestmark = pytest.mark.unit
 from infrastructure.events.bus import (
    Event,
    EventBus,
@@ -352,6 +354,14 @@ class TestEventBusPersistence:
        events = bus.replay()
        assert events == []

+    def test_init_persistence_db_noop_when_path_is_none(self):
+        """_init_persistence_db() is a no-op when _persistence_db_path is None."""
+        bus = EventBus()
+        # _persistence_db_path is None by default; calling _init_persistence_db
+        # should silently return without touching the filesystem.
+        bus._init_persistence_db()  # must not raise
+        assert bus._persistence_db_path is None
+
    async def test_wal_mode_on_persistence_db(self, persistent_bus):
        """Persistence database should use WAL mode."""
        conn = sqlite3.connect(str(persistent_bus._persistence_db_path))
--- a/tests/infrastructure/test_graceful_degradation.py
+++ b/tests/infrastructure/test_graceful_degradation.py
@@ -0,0 +1,588 @@
+"""Graceful degradation test scenarios — Issue #919.
+
+Tests specifically for service failure paths and fallback logic:
+
+* Ollama health-check failures (connection refused, timeout, HTTP errors)
+* Cascade router: Ollama down → falls back to Anthropic/cloud provider
+* Circuit-breaker lifecycle: CLOSED → OPEN (repeated failures) → HALF_OPEN (recovery window)
+* All providers fail → descriptive RuntimeError
+* Disabled provider skipped without touching circuit breaker
+* ``requests`` library unavailable → optimistic availability assumption
+* ClaudeBackend / GrokBackend no-key graceful messages
+* Chat store: SQLite directory auto-creation and concurrent access safety
+"""
+
+from __future__ import annotations
+
+import threading
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from infrastructure.router.cascade import (
+    CascadeRouter,
+    CircuitState,
+    Provider,
+    ProviderStatus,
+)
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_ollama_provider(name: str = "local-ollama", priority: int = 1) -> Provider:
+    return Provider(
+        name=name,
+        type="ollama",
+        enabled=True,
+        priority=priority,
+        url="http://localhost:11434",
+        models=[{"name": "llama3", "default": True}],
+    )
+
+
+def _make_anthropic_provider(name: str = "cloud-fallback", priority: int = 2) -> Provider:
+    return Provider(
+        name=name,
+        type="anthropic",
+        enabled=True,
+        priority=priority,
+        api_key="sk-ant-test",
+        models=[{"name": "claude-haiku-4-5-20251001", "default": True}],
+    )
+
+
+# ---------------------------------------------------------------------------
+# Ollama health-check failure scenarios
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.unit
+class TestOllamaHealthCheckFailures:
+    """_check_provider_available returns False for all Ollama failure modes."""
+
+    def _router(self) -> CascadeRouter:
+        return CascadeRouter(config_path=Path("/nonexistent"))
+
+    def test_connection_refused_returns_false(self):
+        """Connection refused during Ollama health check → provider excluded."""
+        router = self._router()
+        provider = _make_ollama_provider()
+
+        with patch("infrastructure.router.cascade.requests") as mock_req:
+            mock_req.get.side_effect = ConnectionError("Connection refused")
+            assert router._check_provider_available(provider) is False
+
+    def test_timeout_returns_false(self):
+        """Request timeout during Ollama health check → provider excluded."""
+        router = self._router()
+        provider = _make_ollama_provider()
+
+        with patch("infrastructure.router.cascade.requests") as mock_req:
+            # Simulate a timeout using a generic OSError (matches real-world timeout behaviour)
+            mock_req.get.side_effect = OSError("timed out")
+            assert router._check_provider_available(provider) is False
+
+    def test_http_503_returns_false(self):
+        """HTTP 503 from Ollama health endpoint → provider excluded."""
+        router = self._router()
+        provider = _make_ollama_provider()
+
+        mock_response = MagicMock()
+        mock_response.status_code = 503
+
+        with patch("infrastructure.router.cascade.requests") as mock_req:
+            mock_req.get.return_value = mock_response
+            assert router._check_provider_available(provider) is False
+
+    def test_http_500_returns_false(self):
+        """HTTP 500 from Ollama health endpoint → provider excluded."""
+        router = self._router()
+        provider = _make_ollama_provider()
+
+        mock_response = MagicMock()
+        mock_response.status_code = 500
+
+        with patch("infrastructure.router.cascade.requests") as mock_req:
+            mock_req.get.return_value = mock_response
+            assert router._check_provider_available(provider) is False
+
+    def test_generic_exception_returns_false(self):
+        """Unexpected exception during Ollama check → provider excluded (no crash)."""
+        router = self._router()
+        provider = _make_ollama_provider()
+
+        with patch("infrastructure.router.cascade.requests") as mock_req:
+            mock_req.get.side_effect = RuntimeError("unexpected error")
+            assert router._check_provider_available(provider) is False
+
+    def test_requests_unavailable_assumes_available(self):
+        """When ``requests`` lib is None, Ollama availability is assumed True."""
+        import infrastructure.router.cascade as cascade_module
+
+        router = self._router()
+        provider = _make_ollama_provider()
+
+        old_requests = cascade_module.requests
+        cascade_module.requests = None
+        try:
+            assert router._check_provider_available(provider) is True
+        finally:
+            cascade_module.requests = old_requests
+
+
+# ---------------------------------------------------------------------------
+# Cascade: Ollama fails → Anthropic fallback
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.unit
+class TestOllamaToAnthropicFallback:
+    """Cascade router falls back to Anthropic when Ollama is unavailable or failing."""
+
+    @pytest.mark.asyncio
+    async def test_ollama_connection_refused_falls_back_to_anthropic(self):
+        """When Ollama raises a connection error, cascade uses Anthropic provider."""
+        router = CascadeRouter(config_path=Path("/nonexistent"))
+        ollama_provider = _make_ollama_provider(priority=1)
+        anthropic_provider = _make_anthropic_provider(priority=2)
+        router.providers = [ollama_provider, anthropic_provider]
+
+        with (
+            patch.object(router, "_call_ollama", side_effect=ConnectionError("refused")),
+            patch.object(
+                router,
+                "_call_anthropic",
+                new_callable=AsyncMock,
+                return_value={"content": "fallback response", "model": "claude-haiku-4-5-20251001"},
+            ),
+            # Allow cloud bypass of the metabolic quota gate in test
+            patch.object(router, "_quota_allows_cloud", return_value=True),
+        ):
+            result = await router.complete(
+                messages=[{"role": "user", "content": "hello"}],
+                model="llama3",
+            )
+
+        assert result["provider"] == "cloud-fallback"
+        assert "fallback response" in result["content"]
+
+    @pytest.mark.asyncio
+    async def test_ollama_circuit_open_skips_to_anthropic(self):
+        """When Ollama circuit is OPEN, cascade skips directly to Anthropic."""
+        router = CascadeRouter(config_path=Path("/nonexistent"))
+        ollama_provider = _make_ollama_provider(priority=1)
+        anthropic_provider = _make_anthropic_provider(priority=2)
+        router.providers = [ollama_provider, anthropic_provider]
+
+        # Force the circuit open on Ollama
+        ollama_provider.circuit_state = CircuitState.OPEN
+        ollama_provider.status = ProviderStatus.UNHEALTHY
+        import time
+
+        ollama_provider.circuit_opened_at = time.time()  # just opened — not yet recoverable
+
+        with (
+            patch.object(
+                router,
+                "_call_anthropic",
+                new_callable=AsyncMock,
+                return_value={"content": "cloud answer", "model": "claude-haiku-4-5-20251001"},
+            ) as mock_anthropic,
+            # Allow cloud bypass of the metabolic quota gate in test
+            patch.object(router, "_quota_allows_cloud", return_value=True),
+        ):
+            result = await router.complete(
+                messages=[{"role": "user", "content": "ping"}],
+            )
+
+        mock_anthropic.assert_called_once()
+        assert result["provider"] == "cloud-fallback"
+
+    @pytest.mark.asyncio
+    async def test_all_providers_fail_raises_runtime_error(self):
+        """When every provider fails, RuntimeError is raised with combined error info."""
+        router = CascadeRouter(config_path=Path("/nonexistent"))
+        ollama_provider = _make_ollama_provider(priority=1)
+        anthropic_provider = _make_anthropic_provider(priority=2)
+        router.providers = [ollama_provider, anthropic_provider]
+
+        with (
+            patch.object(router, "_call_ollama", side_effect=RuntimeError("Ollama down")),
+            patch.object(router, "_call_anthropic", side_effect=RuntimeError("API quota exceeded")),
+            patch.object(router, "_quota_allows_cloud", return_value=True),
+        ):
+            with pytest.raises(RuntimeError, match="All providers failed"):
+                await router.complete(messages=[{"role": "user", "content": "test"}])
+
+    @pytest.mark.asyncio
+    async def test_error_message_includes_individual_provider_errors(self):
+        """RuntimeError from all-fail scenario lists each provider's error."""
+        router = CascadeRouter(config_path=Path("/nonexistent"))
+        ollama_provider = _make_ollama_provider(priority=1)
+        anthropic_provider = _make_anthropic_provider(priority=2)
+        router.providers = [ollama_provider, anthropic_provider]
+        router.config.max_retries_per_provider = 1
+
+        with (
+            patch.object(router, "_call_ollama", side_effect=RuntimeError("connection refused")),
+            patch.object(router, "_call_anthropic", side_effect=RuntimeError("rate limit")),
+            patch.object(router, "_quota_allows_cloud", return_value=True),
+        ):
+            with pytest.raises(RuntimeError) as exc_info:
+                await router.complete(messages=[{"role": "user", "content": "test"}])
+
+        error_msg = str(exc_info.value)
+        assert "connection refused" in error_msg
+        assert "rate limit" in error_msg
+
+
+# ---------------------------------------------------------------------------
+# Circuit-breaker lifecycle
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.unit
+class TestCircuitBreakerLifecycle:
+    """Full CLOSED → OPEN → HALF_OPEN → CLOSED lifecycle."""
+
+    def test_closed_initially(self):
+        """New provider starts with circuit CLOSED and HEALTHY status."""
+        provider = _make_ollama_provider()
+        assert provider.circuit_state == CircuitState.CLOSED
+        assert provider.status == ProviderStatus.HEALTHY
+
+    def test_open_after_threshold_failures(self):
+        """Circuit opens once consecutive failures reach the threshold."""
+        router = CascadeRouter(config_path=Path("/nonexistent"))
+        router.config.circuit_breaker_failure_threshold = 3
+        provider = _make_ollama_provider()
+
+        for _ in range(3):
+            router._record_failure(provider)
+
+        assert provider.circuit_state == CircuitState.OPEN
+        assert provider.status == ProviderStatus.UNHEALTHY
+        assert provider.circuit_opened_at is not None
+
+    def test_open_circuit_skips_provider(self):
+        """_is_provider_available returns False when circuit is OPEN (and timeout not elapsed)."""
+        import time
+
+        router = CascadeRouter(config_path=Path("/nonexistent"))
+        router.config.circuit_breaker_recovery_timeout = 9999  # won't elapse during test
+        provider = _make_ollama_provider()
+        provider.circuit_state = CircuitState.OPEN
+        provider.status = ProviderStatus.UNHEALTHY
+        provider.circuit_opened_at = time.time()
+
+        assert router._is_provider_available(provider) is False
+
+    def test_half_open_after_recovery_timeout(self):
+        """After the recovery timeout elapses, _is_provider_available transitions to HALF_OPEN."""
+        import time
+
+        router = CascadeRouter(config_path=Path("/nonexistent"))
+        router.config.circuit_breaker_recovery_timeout = 0.01  # 10 ms
+
+        provider = _make_ollama_provider()
+        provider.circuit_state = CircuitState.OPEN
+        provider.status = ProviderStatus.UNHEALTHY
+        provider.circuit_opened_at = time.time() - 1.0  # clearly elapsed
+
+        result = router._is_provider_available(provider)
+
+        assert result is True
+        assert provider.circuit_state == CircuitState.HALF_OPEN
+
+    def test_closed_after_half_open_successes(self):
+        """Circuit closes after enough successful half-open test calls."""
+        router = CascadeRouter(config_path=Path("/nonexistent"))
+        router.config.circuit_breaker_half_open_max_calls = 2
+
+        provider = _make_ollama_provider()
+        provider.circuit_state = CircuitState.HALF_OPEN
+        provider.half_open_calls = 0
+
+        router._record_success(provider, 50.0)
+        assert provider.circuit_state == CircuitState.HALF_OPEN  # not yet
+
+        router._record_success(provider, 50.0)
+        assert provider.circuit_state == CircuitState.CLOSED
+        assert provider.status == ProviderStatus.HEALTHY
+        assert provider.metrics.consecutive_failures == 0
+
+    def test_failure_in_half_open_reopens_circuit(self):
+        """A failure during HALF_OPEN increments consecutive failures, reopening if threshold met."""
+        router = CascadeRouter(config_path=Path("/nonexistent"))
+        router.config.circuit_breaker_failure_threshold = 1  # reopen on first failure
+
+        provider = _make_ollama_provider()
+        provider.circuit_state = CircuitState.HALF_OPEN
+
+        router._record_failure(provider)
+
+        assert provider.circuit_state == CircuitState.OPEN
+
+    def test_disabled_provider_skipped_without_circuit_change(self):
+        """A disabled provider is immediately rejected; its circuit state is not touched."""
+        router = CascadeRouter(config_path=Path("/nonexistent"))
+        provider = _make_ollama_provider()
+        provider.enabled = False
+
+        available = router._is_provider_available(provider)
+
+        assert available is False
+        assert provider.circuit_state == CircuitState.CLOSED  # unchanged
+
+
+# ---------------------------------------------------------------------------
+# ClaudeBackend graceful degradation
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.unit
+class TestClaudeBackendGracefulDegradation:
+    """ClaudeBackend degrades gracefully when the API is unavailable."""
+
+    def test_run_no_key_returns_unconfigured_message(self):
+        """run() returns a graceful message when no API key is set."""
+        from timmy.backends import ClaudeBackend
+
+        backend = ClaudeBackend(api_key="", model="haiku")
+        result = backend.run("hello")
+
+        assert "not configured" in result.content.lower()
+        assert "ANTHROPIC_API_KEY" in result.content
+
+    def test_run_api_error_returns_unavailable_message(self):
+        """run() returns a graceful error when the Anthropic API raises."""
+        from timmy.backends import ClaudeBackend
+
+        backend = ClaudeBackend(api_key="sk-ant-test", model="haiku")
+
+        mock_client = MagicMock()
+        mock_client.messages.create.side_effect = ConnectionError("API unreachable")
+
+        with patch.object(backend, "_get_client", return_value=mock_client):
+            result = backend.run("ping")
+
+        assert "unavailable" in result.content.lower()
+
+    def test_health_check_no_key_reports_error(self):
+        """health_check() reports not-ok when API key is missing."""
+        from timmy.backends import ClaudeBackend
+
+        backend = ClaudeBackend(api_key="", model="haiku")
+        status = backend.health_check()
+
+        assert status["ok"] is False
+        assert "ANTHROPIC_API_KEY" in status["error"]
+
+    def test_health_check_api_error_reports_error(self):
+        """health_check() returns ok=False and captures the error on API failure."""
+        from timmy.backends import ClaudeBackend
+
+        backend = ClaudeBackend(api_key="sk-ant-test", model="haiku")
+
+        mock_client = MagicMock()
+        mock_client.messages.create.side_effect = RuntimeError("connection timed out")
+
+        with patch.object(backend, "_get_client", return_value=mock_client):
+            status = backend.health_check()
+
+        assert status["ok"] is False
+        assert "connection timed out" in status["error"]
+
+
+# ---------------------------------------------------------------------------
+# GrokBackend graceful degradation
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.unit
+class TestGrokBackendGracefulDegradation:
+    """GrokBackend degrades gracefully when xAI API is unavailable."""
+
+    def test_run_no_key_returns_unconfigured_message(self):
+        """run() returns a graceful message when no XAI_API_KEY is set."""
+        from timmy.backends import GrokBackend
+
+        backend = GrokBackend(api_key="", model="grok-3-mini")
+        result = backend.run("hello")
+
+        assert "not configured" in result.content.lower()
+
+    def test_run_api_error_returns_unavailable_message(self):
+        """run() returns graceful error when xAI API raises."""
+        from timmy.backends import GrokBackend
+
+        backend = GrokBackend(api_key="xai-test-key", model="grok-3-mini")
+
+        mock_client = MagicMock()
+        mock_client.chat.completions.create.side_effect = RuntimeError("network error")
+
+        with patch.object(backend, "_get_client", return_value=mock_client):
+            result = backend.run("ping")
+
+        assert "unavailable" in result.content.lower()
+
+    def test_health_check_no_key_reports_error(self):
+        """health_check() reports not-ok when XAI_API_KEY is missing."""
+        from timmy.backends import GrokBackend
+
+        backend = GrokBackend(api_key="", model="grok-3-mini")
+        status = backend.health_check()
+
+        assert status["ok"] is False
+        assert "XAI_API_KEY" in status["error"]
+
+
+# ---------------------------------------------------------------------------
+# Chat store: SQLite resilience
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.unit
+class TestChatStoreSQLiteResilience:
+    """MessageLog handles edge cases without crashing."""
+
+    def test_auto_creates_missing_parent_directory(self, tmp_path):
+        """MessageLog creates the data directory automatically on first use."""
+        from infrastructure.chat_store import MessageLog
+
+        db_path = tmp_path / "deep" / "nested" / "chat.db"
+        assert not db_path.parent.exists()
+
+        log = MessageLog(db_path=db_path)
+        log.append("user", "hello", "2026-01-01T00:00:00")
+
+        assert db_path.exists()
+        assert len(log) == 1
+        log.close()
+
+    def test_concurrent_appends_are_safe(self, tmp_path):
+        """Multiple threads appending simultaneously do not corrupt the DB."""
+        from infrastructure.chat_store import MessageLog
+
+        db_path = tmp_path / "chat.db"
+        log = MessageLog(db_path=db_path)
+
+        errors: list[Exception] = []
+
+        def write_messages(thread_id: int) -> None:
+            try:
+                for i in range(10):
+                    log.append("user", f"thread {thread_id} msg {i}", "2026-01-01T00:00:00")
+            except Exception as exc:
+                errors.append(exc)
+
+        threads = [threading.Thread(target=write_messages, args=(t,)) for t in range(5)]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        assert errors == [], f"Concurrent writes produced errors: {errors}"
+        # 5 threads × 10 messages each
+        assert len(log) == 50
+        log.close()
+
+    def test_all_returns_messages_in_insertion_order(self, tmp_path):
+        """all() returns messages ordered oldest-first."""
+        from infrastructure.chat_store import MessageLog
+
+        db_path = tmp_path / "chat.db"
+        log = MessageLog(db_path=db_path)
+        log.append("user", "first", "2026-01-01T00:00:00")
+        log.append("agent", "second", "2026-01-01T00:00:01")
+        log.append("user", "third", "2026-01-01T00:00:02")
+
+        messages = log.all()
+        assert [m.content for m in messages] == ["first", "second", "third"]
+        log.close()
+
+    def test_recent_returns_latest_n_messages(self, tmp_path):
+        """recent(n) returns the n most recent messages, oldest-first within the slice."""
+        from infrastructure.chat_store import MessageLog
+
+        db_path = tmp_path / "chat.db"
+        log = MessageLog(db_path=db_path)
+        for i in range(20):
+            log.append("user", f"msg {i}", f"2026-01-01T00:{i:02d}:00")
+
+        recent = log.recent(5)
+        assert len(recent) == 5
+        assert recent[0].content == "msg 15"
+        assert recent[-1].content == "msg 19"
+        log.close()
+
+    def test_prune_keeps_max_messages(self, tmp_path):
+        """append() prunes oldest messages when count exceeds MAX_MESSAGES."""
+        import infrastructure.chat_store as store_mod
+        from infrastructure.chat_store import MessageLog
+
+        original_max = store_mod.MAX_MESSAGES
+        store_mod.MAX_MESSAGES = 5
+        try:
+            db_path = tmp_path / "chat.db"
+            log = MessageLog(db_path=db_path)
+            for i in range(8):
+                log.append("user", f"msg {i}", "2026-01-01T00:00:00")
+
+            assert len(log) == 5
+            messages = log.all()
+            # Oldest 3 should be pruned
+            assert messages[0].content == "msg 3"
+            log.close()
+        finally:
+            store_mod.MAX_MESSAGES = original_max
+
+
+# ---------------------------------------------------------------------------
+# Provider availability: requests lib missing
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.unit
+class TestRequestsLibraryMissing:
+    """When ``requests`` is not installed, providers assume they are available."""
+
+    def _swap_requests(self, value):
+        import infrastructure.router.cascade as cascade_module
+
+        old = cascade_module.requests
+        cascade_module.requests = value
+        return old
+
+    def test_ollama_assumes_available_without_requests(self):
+        """Ollama provider returns True when requests is None."""
+        import infrastructure.router.cascade as cascade_module
+
+        router = CascadeRouter(config_path=Path("/nonexistent"))
+        provider = _make_ollama_provider()
+        old = self._swap_requests(None)
+        try:
+            assert router._check_provider_available(provider) is True
+        finally:
+            cascade_module.requests = old
+
+    def test_vllm_mlx_assumes_available_without_requests(self):
+        """vllm-mlx provider returns True when requests is None."""
+        import infrastructure.router.cascade as cascade_module
+
+        router = CascadeRouter(config_path=Path("/nonexistent"))
+        provider = Provider(
+            name="vllm-local",
+            type="vllm_mlx",
+            enabled=True,
+            priority=1,
+            base_url="http://localhost:8000/v1",
+        )
+        old = self._swap_requests(None)
+        try:
+            assert router._check_provider_available(provider) is True
+        finally:
+            cascade_module.requests = old
--- a/tests/infrastructure/test_tiered_model_router.py
+++ b/tests/infrastructure/test_tiered_model_router.py
@@ -0,0 +1,380 @@
+"""Tests for the tiered model router (issue #882).
+
+Covers:
+- classify_tier() for Tier-1/2/3 routing
+- TieredModelRouter.route() with mocked CascadeRouter + BudgetTracker
+- Auto-escalation from Tier-1 on low-quality responses
+- Cloud-tier budget guard
+- Acceptance criteria from the issue:
+  - "Walk to the next room" → LOCAL_FAST
+  - "Plan the optimal path to become Hortator" → LOCAL_HEAVY
+"""
+
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from infrastructure.models.router import (
+    TieredModelRouter,
+    TierLabel,
+    _is_low_quality,
+    classify_tier,
+    get_tiered_router,
+)
+
+pytestmark = pytest.mark.unit
+
+
+# ── classify_tier ─────────────────────────────────────────────────────────────
+
+
+class TestClassifyTier:
+    # ── Tier-1 (LOCAL_FAST) ────────────────────────────────────────────────
+
+    def test_simple_navigation_is_local_fast(self):
+        assert classify_tier("walk to the next room") == TierLabel.LOCAL_FAST
+
+    def test_go_north_is_local_fast(self):
+        assert classify_tier("go north") == TierLabel.LOCAL_FAST
+
+    def test_single_binary_choice_is_local_fast(self):
+        assert classify_tier("yes") == TierLabel.LOCAL_FAST
+
+    def test_open_door_is_local_fast(self):
+        assert classify_tier("open door") == TierLabel.LOCAL_FAST
+
+    def test_attack_is_local_fast(self):
+        assert classify_tier("attack", {}) == TierLabel.LOCAL_FAST
+
+    # ── Tier-2 (LOCAL_HEAVY) ───────────────────────────────────────────────
+
+    def test_quest_planning_is_local_heavy(self):
+        assert classify_tier("plan the optimal path to become Hortator") == TierLabel.LOCAL_HEAVY
+
+    def test_strategy_keyword_is_local_heavy(self):
+        assert classify_tier("what is the best strategy") == TierLabel.LOCAL_HEAVY
+
+    def test_stuck_state_escalates_to_local_heavy(self):
+        assert classify_tier("help me", {"stuck": True}) == TierLabel.LOCAL_HEAVY
+
+    def test_require_t2_flag_is_local_heavy(self):
+        assert classify_tier("go north", {"require_t2": True}) == TierLabel.LOCAL_HEAVY
+
+    def test_long_input_is_local_heavy(self):
+        long_task = "tell me about " + ("the dungeon " * 30)
+        assert classify_tier(long_task) == TierLabel.LOCAL_HEAVY
+
+    def test_active_quests_upgrades_to_local_heavy(self):
+        ctx = {"active_quests": ["Q1", "Q2", "Q3"]}
+        assert classify_tier("go north", ctx) == TierLabel.LOCAL_HEAVY
+
+    def test_dialogue_active_upgrades_to_local_heavy(self):
+        ctx = {"dialogue_active": True}
+        assert classify_tier("yes", ctx) == TierLabel.LOCAL_HEAVY
+
+    def test_analyze_is_local_heavy(self):
+        assert classify_tier("analyze the situation") == TierLabel.LOCAL_HEAVY
+
+    def test_optimize_is_local_heavy(self):
+        assert classify_tier("optimize my build") == TierLabel.LOCAL_HEAVY
+
+    def test_negotiate_is_local_heavy(self):
+        assert classify_tier("negotiate with the Camonna Tong") == TierLabel.LOCAL_HEAVY
+
+    def test_explain_is_local_heavy(self):
+        assert classify_tier("explain the faction system") == TierLabel.LOCAL_HEAVY
+
+    # ── Tier-3 (CLOUD_API) ─────────────────────────────────────────────────
+
+    def test_require_cloud_flag_is_cloud_api(self):
+        assert classify_tier("go north", {"require_cloud": True}) == TierLabel.CLOUD_API
+
+    def test_require_cloud_overrides_everything(self):
+        assert classify_tier("yes", {"require_cloud": True}) == TierLabel.CLOUD_API
+
+    # ── Edge cases ────────────────────────────────────────────────────────
+
+    def test_empty_task_defaults_to_local_heavy(self):
+        # Empty string → nothing classifies it as T1 or T3
+        assert classify_tier("") == TierLabel.LOCAL_HEAVY
+
+    def test_case_insensitive(self):
+        assert classify_tier("PLAN my route") == TierLabel.LOCAL_HEAVY
+
+    def test_combat_active_upgrades_t1_to_heavy(self):
+        ctx = {"combat_active": True}
+        # "attack" is T1 word, but combat context → should NOT be LOCAL_FAST
+        result = classify_tier("attack", ctx)
+        assert result != TierLabel.LOCAL_FAST
+
+
+# ── _is_low_quality ───────────────────────────────────────────────────────────
+
+
+class TestIsLowQuality:
+    def test_empty_is_low_quality(self):
+        assert _is_low_quality("", TierLabel.LOCAL_FAST) is True
+
+    def test_whitespace_only_is_low_quality(self):
+        assert _is_low_quality("   ", TierLabel.LOCAL_FAST) is True
+
+    def test_very_short_is_low_quality(self):
+        assert _is_low_quality("ok", TierLabel.LOCAL_FAST) is True
+
+    def test_idontknow_is_low_quality(self):
+        assert _is_low_quality("I don't know how to help with that.", TierLabel.LOCAL_FAST) is True
+
+    def test_not_sure_is_low_quality(self):
+        assert _is_low_quality("I'm not sure about this.", TierLabel.LOCAL_FAST) is True
+
+    def test_as_an_ai_is_low_quality(self):
+        assert _is_low_quality("As an AI, I cannot...", TierLabel.LOCAL_FAST) is True
+
+    def test_good_response_is_not_low_quality(self):
+        response = "You move north into the Vivec Canton. The Ordinators watch your approach."
+        assert _is_low_quality(response, TierLabel.LOCAL_FAST) is False
+
+    def test_t1_short_response_triggers_escalation(self):
+        # Less than _ESCALATION_MIN_CHARS for T1
+        assert _is_low_quality("OK, done.", TierLabel.LOCAL_FAST) is True
+
+    def test_borderline_ok_for_t2_not_t1(self):
+        # Between _LOW_QUALITY_MIN_CHARS (20) and _ESCALATION_MIN_CHARS (60)
+        # → low quality for T1 (escalation threshold), but acceptable for T2/T3
+        response = "Done. The item is retrieved."  # 28 chars: ≥20, <60
+        assert _is_low_quality(response, TierLabel.LOCAL_FAST) is True
+        assert _is_low_quality(response, TierLabel.LOCAL_HEAVY) is False
+
+
+# ── TieredModelRouter ─────────────────────────────────────────────────────────
+
+
+_GOOD_CONTENT = (
+    "You move north through the doorway into the next room. "
+    "The stone walls glisten with moisture."
+)  # 90 chars — well above the escalation threshold
+
+
+def _make_cascade_mock(content=_GOOD_CONTENT, model="llama3.1:8b"):
+    mock = MagicMock()
+    mock.complete = AsyncMock(
+        return_value={
+            "content": content,
+            "provider": "ollama-local",
+            "model": model,
+            "latency_ms": 150.0,
+        }
+    )
+    return mock
+
+
+def _make_budget_mock(allowed=True):
+    mock = MagicMock()
+    mock.cloud_allowed = MagicMock(return_value=allowed)
+    mock.record_spend = MagicMock(return_value=0.001)
+    return mock
+
+
+@pytest.mark.asyncio
+class TestTieredModelRouterRoute:
+    async def test_route_returns_tier_in_result(self):
+        router = TieredModelRouter(cascade=_make_cascade_mock())
+        result = await router.route("go north")
+        assert "tier" in result
+        assert result["tier"] == TierLabel.LOCAL_FAST
+
+    async def test_acceptance_walk_to_room_is_local_fast(self):
+        """Acceptance: 'Walk to the next room' → LOCAL_FAST."""
+        router = TieredModelRouter(cascade=_make_cascade_mock())
+        result = await router.route("Walk to the next room")
+        assert result["tier"] == TierLabel.LOCAL_FAST
+
+    async def test_acceptance_plan_hortator_is_local_heavy(self):
+        """Acceptance: 'Plan the optimal path to become Hortator' → LOCAL_HEAVY."""
+        router = TieredModelRouter(
+            cascade=_make_cascade_mock(model="hermes3:70b"),
+        )
+        result = await router.route("Plan the optimal path to become Hortator")
+        assert result["tier"] == TierLabel.LOCAL_HEAVY
+
+    async def test_t1_low_quality_escalates_to_t2(self):
+        """Failed Tier-1 response auto-escalates to Tier-2."""
+        call_models = []
+        cascade = MagicMock()
+
+        async def complete_side_effect(messages, model, temperature, max_tokens):
+            call_models.append(model)
+            # First call (T1) returns a low-quality response
+            if len(call_models) == 1:
+                return {
+                    "content": "I don't know.",
+                    "provider": "ollama",
+                    "model": model,
+                    "latency_ms": 50,
+                }
+            # Second call (T2) returns a good response
+            return {
+                "content": "You move to the northern passage, passing through the Dunmer stronghold.",
+                "provider": "ollama",
+                "model": model,
+                "latency_ms": 800,
+            }
+
+        cascade.complete = complete_side_effect
+
+        router = TieredModelRouter(cascade=cascade, auto_escalate=True)
+        result = await router.route("go north")
+
+        assert len(call_models) == 2, "Should have called twice (T1 escalated to T2)"
+        assert result["tier"] == TierLabel.LOCAL_HEAVY
+
+    async def test_auto_escalate_false_no_escalation(self):
+        """With auto_escalate=False, low-quality T1 response is returned as-is."""
+        call_count = {"n": 0}
+        cascade = MagicMock()
+
+        async def complete_side_effect(**kwargs):
+            call_count["n"] += 1
+            return {
+                "content": "I don't know.",
+                "provider": "ollama",
+                "model": "llama3.1:8b",
+                "latency_ms": 50,
+            }
+
+        cascade.complete = AsyncMock(side_effect=complete_side_effect)
+        router = TieredModelRouter(cascade=cascade, auto_escalate=False)
+        result = await router.route("go north")
+        assert call_count["n"] == 1
+        assert result["tier"] == TierLabel.LOCAL_FAST
+
+    async def test_t2_failure_escalates_to_cloud(self):
+        """Tier-2 failure escalates to Cloud API (when budget allows)."""
+        cascade = MagicMock()
+        call_models = []
+
+        async def complete_side_effect(messages, model, temperature, max_tokens):
+            call_models.append(model)
+            if "hermes3" in model or "70b" in model.lower():
+                raise RuntimeError("Tier-2 model unavailable")
+            return {
+                "content": "Cloud response here.",
+                "provider": "anthropic",
+                "model": model,
+                "latency_ms": 1200,
+            }
+
+        cascade.complete = complete_side_effect
+
+        budget = _make_budget_mock(allowed=True)
+        router = TieredModelRouter(cascade=cascade, budget_tracker=budget)
+        result = await router.route("plan my route", context={"require_t2": True})
+        assert result["tier"] == TierLabel.CLOUD_API
+
+    async def test_cloud_blocked_by_budget_raises(self):
+        """Cloud tier blocked when budget is exhausted."""
+        cascade = MagicMock()
+        cascade.complete = AsyncMock(side_effect=RuntimeError("T2 fail"))
+
+        budget = _make_budget_mock(allowed=False)
+        router = TieredModelRouter(cascade=cascade, budget_tracker=budget)
+
+        with pytest.raises(RuntimeError, match="budget limit"):
+            await router.route("plan my route", context={"require_t2": True})
+
+    async def test_explicit_cloud_tier_uses_cloud_model(self):
+        cascade = _make_cascade_mock(model="claude-haiku-4-5")
+        budget = _make_budget_mock(allowed=True)
+        router = TieredModelRouter(cascade=cascade, budget_tracker=budget)
+        result = await router.route("go north", context={"require_cloud": True})
+        assert result["tier"] == TierLabel.CLOUD_API
+
+    async def test_cloud_spend_recorded_with_usage(self):
+        """Cloud spend is recorded when the response includes usage info."""
+        cascade = MagicMock()
+        cascade.complete = AsyncMock(
+            return_value={
+                "content": "Cloud answer.",
+                "provider": "anthropic",
+                "model": "claude-haiku-4-5",
+                "latency_ms": 900,
+                "usage": {"prompt_tokens": 50, "completion_tokens": 100},
+            }
+        )
+        budget = _make_budget_mock(allowed=True)
+        router = TieredModelRouter(cascade=cascade, budget_tracker=budget)
+        result = await router.route("go north", context={"require_cloud": True})
+        budget.record_spend.assert_called_once()
+        assert "cost_usd" in result
+
+    async def test_cloud_spend_not_recorded_without_usage(self):
+        """Cloud spend is not recorded when usage info is absent."""
+        cascade = MagicMock()
+        cascade.complete = AsyncMock(
+            return_value={
+                "content": "Cloud answer.",
+                "provider": "anthropic",
+                "model": "claude-haiku-4-5",
+                "latency_ms": 900,
+                # no "usage" key
+            }
+        )
+        budget = _make_budget_mock(allowed=True)
+        router = TieredModelRouter(cascade=cascade, budget_tracker=budget)
+        result = await router.route("go north", context={"require_cloud": True})
+        budget.record_spend.assert_not_called()
+        assert "cost_usd" not in result
+
+    async def test_custom_tier_models_respected(self):
+        cascade = _make_cascade_mock()
+        router = TieredModelRouter(
+            cascade=cascade,
+            tier_models={TierLabel.LOCAL_FAST: "llama3.2:3b"},
+        )
+        await router.route("go north")
+        call_kwargs = cascade.complete.call_args
+        assert call_kwargs.kwargs["model"] == "llama3.2:3b"
+
+    async def test_messages_override_used_when_provided(self):
+        cascade = _make_cascade_mock()
+        router = TieredModelRouter(cascade=cascade)
+        custom_msgs = [{"role": "user", "content": "custom message"}]
+        await router.route("go north", messages=custom_msgs)
+        call_kwargs = cascade.complete.call_args
+        assert call_kwargs.kwargs["messages"] == custom_msgs
+
+    async def test_temperature_forwarded(self):
+        cascade = _make_cascade_mock()
+        router = TieredModelRouter(cascade=cascade)
+        await router.route("go north", temperature=0.7)
+        call_kwargs = cascade.complete.call_args
+        assert call_kwargs.kwargs["temperature"] == 0.7
+
+    async def test_max_tokens_forwarded(self):
+        cascade = _make_cascade_mock()
+        router = TieredModelRouter(cascade=cascade)
+        await router.route("go north", max_tokens=128)
+        call_kwargs = cascade.complete.call_args
+        assert call_kwargs.kwargs["max_tokens"] == 128
+
+
+class TestTieredModelRouterClassify:
+    def test_classify_delegates_to_classify_tier(self):
+        router = TieredModelRouter(cascade=MagicMock())
+        assert router.classify("go north") == classify_tier("go north")
+        assert router.classify("plan the quest") == classify_tier("plan the quest")
+
+
+class TestGetTieredRouterSingleton:
+    def test_returns_tiered_router_instance(self):
+        import infrastructure.models.router as rmod
+        rmod._tiered_router = None
+        router = get_tiered_router()
+        assert isinstance(router, TieredModelRouter)
+
+    def test_singleton_returns_same_instance(self):
+        import infrastructure.models.router as rmod
+        rmod._tiered_router = None
+        r1 = get_tiered_router()
+        r2 = get_tiered_router()
+        assert r1 is r2
--- a/tests/self_coding/init.py
+++ b/tests/self_coding/init.py
--- a/tests/self_coding/test_loop.py
+++ b/tests/self_coding/test_loop.py
@@ -0,0 +1,363 @@
+"""Unit tests for the self-modification loop.
+
+Covers:
+- Protected branch guard
+- Successful cycle (mocked git + tests)
+- Edit function failure → branch reverted, no commit
+- Test failure → branch reverted, no commit
+- Gitea PR creation plumbing
+- GiteaClient graceful degradation (no token, network error)
+
+All git and subprocess calls are mocked so these run offline without
+a real repo or test suite.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_loop(repo_root="/tmp/fake-repo"):
+    """Construct a SelfModifyLoop with a fake repo root."""
+    from self_coding.self_modify.loop import SelfModifyLoop
+
+    return SelfModifyLoop(repo_root=repo_root, remote="origin", base_branch="main")
+
+
+def _noop_edit(repo_root: str) -> None:
+    """Edit function that does nothing."""
+
+
+def _failing_edit(repo_root: str) -> None:
+    """Edit function that raises."""
+    raise RuntimeError("edit exploded")
+
+
+# ---------------------------------------------------------------------------
+# Guard tests (sync — no git calls needed)
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.unit
+def test_guard_blocks_main():
+    loop = _make_loop()
+    with pytest.raises(ValueError, match="protected branch"):
+        loop._guard_branch("main")
+
+
+@pytest.mark.unit
+def test_guard_blocks_master():
+    loop = _make_loop()
+    with pytest.raises(ValueError, match="protected branch"):
+        loop._guard_branch("master")
+
+
+@pytest.mark.unit
+def test_guard_allows_feature_branch():
+    loop = _make_loop()
+    # Should not raise
+    loop._guard_branch("self-modify/some-feature")
+
+
+@pytest.mark.unit
+def test_guard_allows_self_modify_prefix():
+    loop = _make_loop()
+    loop._guard_branch("self-modify/issue-983")
+
+
+# ---------------------------------------------------------------------------
+# Full cycle — success path
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.unit
+@pytest.mark.asyncio
+async def test_run_success():
+    """Happy path: edit succeeds, tests pass, PR created."""
+    loop = _make_loop()
+
+    fake_completed = MagicMock()
+    fake_completed.stdout = "abc1234\n"
+    fake_completed.returncode = 0
+
+    fake_test_result = MagicMock()
+    fake_test_result.stdout = "3 passed"
+    fake_test_result.stderr = ""
+    fake_test_result.returncode = 0
+
+    from self_coding.gitea_client import PullRequest as _PR
+
+    fake_pr = _PR(number=42, title="test PR", html_url="http://gitea/pr/42")
+
+    with (
+        patch.object(loop, "_git", return_value=fake_completed),
+        patch("subprocess.run", return_value=fake_test_result),
+        patch.object(loop, "_create_pr", return_value=fake_pr),
+    ):
+        result = await loop.run(
+            slug="test-feature",
+            description="Add test feature",
+            edit_fn=_noop_edit,
+            issue_number=983,
+        )
+
+    assert result.success is True
+    assert result.branch == "self-modify/test-feature"
+    assert result.pr_url == "http://gitea/pr/42"
+    assert result.pr_number == 42
+    assert "3 passed" in result.test_output
+
+
+@pytest.mark.unit
+@pytest.mark.asyncio
+async def test_run_skips_tests_when_flag_set():
+    """skip_tests=True should bypass the test gate."""
+    loop = _make_loop()
+
+    fake_completed = MagicMock()
+    fake_completed.stdout = "deadbeef\n"
+    fake_completed.returncode = 0
+
+    with (
+        patch.object(loop, "_git", return_value=fake_completed),
+        patch.object(loop, "_create_pr", return_value=None),
+        patch("subprocess.run") as mock_run,
+    ):
+        result = await loop.run(
+            slug="skip-test-feature",
+            description="Skip test feature",
+            edit_fn=_noop_edit,
+            skip_tests=True,
+        )
+
+    # subprocess.run should NOT be called for tests
+    mock_run.assert_not_called()
+    assert result.success is True
+    assert "(tests skipped)" in result.test_output
+
+
+# ---------------------------------------------------------------------------
+# Failure paths
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.unit
+@pytest.mark.asyncio
+async def test_run_reverts_on_edit_failure():
+    """If edit_fn raises, the branch should be reverted and no commit made."""
+    loop = _make_loop()
+
+    fake_completed = MagicMock()
+    fake_completed.stdout = ""
+    fake_completed.returncode = 0
+
+    revert_called = []
+
+    def _fake_revert(branch):
+        revert_called.append(branch)
+
+    with (
+        patch.object(loop, "_git", return_value=fake_completed),
+        patch.object(loop, "_revert_branch", side_effect=_fake_revert),
+        patch.object(loop, "_commit_all") as mock_commit,
+    ):
+        result = await loop.run(
+            slug="broken-edit",
+            description="This will fail",
+            edit_fn=_failing_edit,
+            skip_tests=True,
+        )
+
+    assert result.success is False
+    assert "edit exploded" in result.error
+    assert "self-modify/broken-edit" in revert_called
+    mock_commit.assert_not_called()
+
+
+@pytest.mark.unit
+@pytest.mark.asyncio
+async def test_run_reverts_on_test_failure():
+    """If tests fail, branch should be reverted and no commit made."""
+    loop = _make_loop()
+
+    fake_completed = MagicMock()
+    fake_completed.stdout = ""
+    fake_completed.returncode = 0
+
+    fake_test_result = MagicMock()
+    fake_test_result.stdout = "FAILED test_foo"
+    fake_test_result.stderr = "1 failed"
+    fake_test_result.returncode = 1
+
+    revert_called = []
+
+    def _fake_revert(branch):
+        revert_called.append(branch)
+
+    with (
+        patch.object(loop, "_git", return_value=fake_completed),
+        patch("subprocess.run", return_value=fake_test_result),
+        patch.object(loop, "_revert_branch", side_effect=_fake_revert),
+        patch.object(loop, "_commit_all") as mock_commit,
+    ):
+        result = await loop.run(
+            slug="tests-will-fail",
+            description="This will fail tests",
+            edit_fn=_noop_edit,
+        )
+
+    assert result.success is False
+    assert "Tests failed" in result.error
+    assert "self-modify/tests-will-fail" in revert_called
+    mock_commit.assert_not_called()
+
+
+@pytest.mark.unit
+@pytest.mark.asyncio
+async def test_run_slug_with_main_creates_safe_branch():
+    """A slug of 'main' produces branch 'self-modify/main', which is not protected."""
+
+    loop = _make_loop()
+
+    fake_completed = MagicMock()
+    fake_completed.stdout = "deadbeef\n"
+    fake_completed.returncode = 0
+
+    # 'self-modify/main' is NOT in _PROTECTED_BRANCHES so the run should succeed
+    with (
+        patch.object(loop, "_git", return_value=fake_completed),
+        patch.object(loop, "_create_pr", return_value=None),
+    ):
+        result = await loop.run(
+            slug="main",
+            description="try to write to self-modify/main",
+            edit_fn=_noop_edit,
+            skip_tests=True,
+        )
+    assert result.branch == "self-modify/main"
+    assert result.success is True
+
+
+# ---------------------------------------------------------------------------
+# GiteaClient tests
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.unit
+def test_gitea_client_returns_none_without_token():
+    """GiteaClient should return None gracefully when no token is set."""
+    from self_coding.gitea_client import GiteaClient
+
+    client = GiteaClient(base_url="http://localhost:3000", token="", repo="owner/repo")
+    pr = client.create_pull_request(
+        title="Test PR",
+        body="body",
+        head="self-modify/test",
+    )
+    assert pr is None
+
+
+@pytest.mark.unit
+def test_gitea_client_comment_returns_false_without_token():
+    """add_issue_comment should return False gracefully when no token is set."""
+    from self_coding.gitea_client import GiteaClient
+
+    client = GiteaClient(base_url="http://localhost:3000", token="", repo="owner/repo")
+    result = client.add_issue_comment(123, "hello")
+    assert result is False
+
+
+@pytest.mark.unit
+def test_gitea_client_create_pr_handles_network_error():
+    """create_pull_request should return None on network failure."""
+    from self_coding.gitea_client import GiteaClient
+
+    client = GiteaClient(base_url="http://localhost:3000", token="fake-token", repo="owner/repo")
+
+    mock_requests = MagicMock()
+    mock_requests.post.side_effect = Exception("Connection refused")
+    mock_requests.exceptions.ConnectionError = Exception
+
+    with patch.dict("sys.modules", {"requests": mock_requests}):
+        pr = client.create_pull_request(
+            title="Test PR",
+            body="body",
+            head="self-modify/test",
+        )
+    assert pr is None
+
+
+@pytest.mark.unit
+def test_gitea_client_comment_handles_network_error():
+    """add_issue_comment should return False on network failure."""
+    from self_coding.gitea_client import GiteaClient
+
+    client = GiteaClient(base_url="http://localhost:3000", token="fake-token", repo="owner/repo")
+
+    mock_requests = MagicMock()
+    mock_requests.post.side_effect = Exception("Connection refused")
+
+    with patch.dict("sys.modules", {"requests": mock_requests}):
+        result = client.add_issue_comment(456, "hello")
+    assert result is False
+
+
+@pytest.mark.unit
+def test_gitea_client_create_pr_success():
+    """create_pull_request should return a PullRequest on HTTP 201."""
+    from self_coding.gitea_client import GiteaClient, PullRequest
+
+    client = GiteaClient(base_url="http://localhost:3000", token="tok", repo="owner/repo")
+
+    fake_resp = MagicMock()
+    fake_resp.raise_for_status = MagicMock()
+    fake_resp.json.return_value = {
+        "number": 77,
+        "title": "Test PR",
+        "html_url": "http://localhost:3000/owner/repo/pulls/77",
+    }
+
+    mock_requests = MagicMock()
+    mock_requests.post.return_value = fake_resp
+
+    with patch.dict("sys.modules", {"requests": mock_requests}):
+        pr = client.create_pull_request("Test PR", "body", "self-modify/feat")
+
+    assert isinstance(pr, PullRequest)
+    assert pr.number == 77
+    assert pr.html_url == "http://localhost:3000/owner/repo/pulls/77"
+
+
+# ---------------------------------------------------------------------------
+# LoopResult dataclass
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.unit
+def test_loop_result_defaults():
+    from self_coding.self_modify.loop import LoopResult
+
+    r = LoopResult(success=True)
+    assert r.branch == ""
+    assert r.commit_sha == ""
+    assert r.pr_url == ""
+    assert r.pr_number == 0
+    assert r.test_output == ""
+    assert r.error == ""
+    assert r.elapsed_ms == 0.0
+    assert r.metadata == {}
+
+
+@pytest.mark.unit
+def test_loop_result_failure():
+    from self_coding.self_modify.loop import LoopResult
+
+    r = LoopResult(success=False, error="something broke", branch="self-modify/test")
+    assert r.success is False
+    assert r.error == "something broke"
--- a/tests/sovereignty/init.py
+++ b/tests/sovereignty/init.py
--- a/tests/sovereignty/test_perception_cache.py
+++ b/tests/sovereignty/test_perception_cache.py
@@ -0,0 +1,379 @@
+"""Tests for the sovereignty perception cache (template matching).
+
+Refs: #1261
+"""
+
+import json
+from unittest.mock import patch
+
+import numpy as np
+
+
+class TestTemplate:
+    """Tests for the Template dataclass."""
+
+    def test_template_default_values(self):
+        """Template dataclass has correct defaults."""
+        from timmy.sovereignty.perception_cache import Template
+
+        image = np.array([[1, 2], [3, 4]])
+        template = Template(name="test_template", image=image)
+
+        assert template.name == "test_template"
+        assert np.array_equal(template.image, image)
+        assert template.threshold == 0.85
+
+    def test_template_custom_threshold(self):
+        """Template can have custom threshold."""
+        from timmy.sovereignty.perception_cache import Template
+
+        image = np.array([[1, 2], [3, 4]])
+        template = Template(name="test_template", image=image, threshold=0.95)
+
+        assert template.threshold == 0.95
+
+
+class TestCacheResult:
+    """Tests for the CacheResult dataclass."""
+
+    def test_cache_result_with_state(self):
+        """CacheResult stores confidence and state."""
+        from timmy.sovereignty.perception_cache import CacheResult
+
+        result = CacheResult(confidence=0.92, state={"template_name": "test"})
+        assert result.confidence == 0.92
+        assert result.state == {"template_name": "test"}
+
+    def test_cache_result_no_state(self):
+        """CacheResult can have None state."""
+        from timmy.sovereignty.perception_cache import CacheResult
+
+        result = CacheResult(confidence=0.5, state=None)
+        assert result.confidence == 0.5
+        assert result.state is None
+
+
+class TestPerceptionCacheInit:
+    """Tests for PerceptionCache initialization."""
+
+    def test_init_creates_empty_cache_when_no_file(self, tmp_path):
+        """Cache initializes empty when templates file doesn't exist."""
+        from timmy.sovereignty.perception_cache import PerceptionCache
+
+        templates_path = tmp_path / "nonexistent_templates.json"
+        cache = PerceptionCache(templates_path=templates_path)
+
+        assert cache.templates_path == templates_path
+        assert cache.templates == []
+
+    def test_init_loads_existing_templates(self, tmp_path):
+        """Cache loads templates from existing JSON file."""
+        from timmy.sovereignty.perception_cache import PerceptionCache
+
+        templates_path = tmp_path / "templates.json"
+        templates_data = [
+            {"name": "template1", "threshold": 0.85},
+            {"name": "template2", "threshold": 0.90},
+        ]
+        with open(templates_path, "w") as f:
+            json.dump(templates_data, f)
+
+        cache = PerceptionCache(templates_path=templates_path)
+
+        assert len(cache.templates) == 2
+        assert cache.templates[0].name == "template1"
+        assert cache.templates[0].threshold == 0.85
+        assert cache.templates[1].name == "template2"
+        assert cache.templates[1].threshold == 0.90
+
+    def test_init_with_string_path(self, tmp_path):
+        """Cache accepts string path for templates."""
+        from timmy.sovereignty.perception_cache import PerceptionCache
+
+        templates_path = str(tmp_path / "templates.json")
+        cache = PerceptionCache(templates_path=templates_path)
+
+        assert str(cache.templates_path) == templates_path
+
+
+class TestPerceptionCacheMatch:
+    """Tests for PerceptionCache.match() template matching."""
+
+    def test_match_no_templates_returns_low_confidence(self, tmp_path):
+        """Matching with no templates returns low confidence and None state."""
+        from timmy.sovereignty.perception_cache import PerceptionCache
+
+        cache = PerceptionCache(templates_path=tmp_path / "templates.json")
+        screenshot = np.array([[1, 2], [3, 4]])
+
+        result = cache.match(screenshot)
+
+        assert result.confidence == 0.0
+        assert result.state is None
+
+    @patch("timmy.sovereignty.perception_cache.cv2")
+    def test_match_finds_best_template(self, mock_cv2, tmp_path):
+        """Match returns the best matching template above threshold."""
+        from timmy.sovereignty.perception_cache import PerceptionCache, Template
+
+        # Setup mock cv2 behavior
+        mock_cv2.matchTemplate.return_value = np.array([[0.5, 0.6], [0.7, 0.8]])
+        mock_cv2.TM_CCOEFF_NORMED = "TM_CCOEFF_NORMED"
+        mock_cv2.minMaxLoc.return_value = (None, 0.92, None, None)
+
+        cache = PerceptionCache(templates_path=tmp_path / "templates.json")
+        template = Template(name="best_match", image=np.array([[1, 2], [3, 4]]))
+        cache.add([template])
+
+        screenshot = np.array([[5, 6], [7, 8]])
+        result = cache.match(screenshot)
+
+        assert result.confidence == 0.92
+        assert result.state == {"template_name": "best_match"}
+
+    @patch("timmy.sovereignty.perception_cache.cv2")
+    def test_match_respects_global_threshold(self, mock_cv2, tmp_path):
+        """Match returns None state when confidence is below threshold."""
+        from timmy.sovereignty.perception_cache import PerceptionCache, Template
+
+        # Setup mock cv2 to return confidence below 0.85 threshold
+        mock_cv2.matchTemplate.return_value = np.array([[0.1, 0.2], [0.3, 0.4]])
+        mock_cv2.TM_CCOEFF_NORMED = "TM_CCOEFF_NORMED"
+        mock_cv2.minMaxLoc.return_value = (None, 0.75, None, None)
+
+        cache = PerceptionCache(templates_path=tmp_path / "templates.json")
+        template = Template(name="low_match", image=np.array([[1, 2], [3, 4]]))
+        cache.add([template])
+
+        screenshot = np.array([[5, 6], [7, 8]])
+        result = cache.match(screenshot)
+
+        # Confidence is recorded but state is None (below threshold)
+        assert result.confidence == 0.75
+        assert result.state is None
+
+    @patch("timmy.sovereignty.perception_cache.cv2")
+    def test_match_selects_highest_confidence(self, mock_cv2, tmp_path):
+        """Match selects template with highest confidence across all templates."""
+        from timmy.sovereignty.perception_cache import PerceptionCache, Template
+
+        mock_cv2.TM_CCOEFF_NORMED = "TM_CCOEFF_NORMED"
+
+        # Each template will return a different confidence
+        mock_cv2.minMaxLoc.side_effect = [
+            (None, 0.70, None, None),  # template1
+            (None, 0.95, None, None),  # template2 (best)
+            (None, 0.80, None, None),  # template3
+        ]
+
+        cache = PerceptionCache(templates_path=tmp_path / "templates.json")
+        templates = [
+            Template(name="template1", image=np.array([[1, 2], [3, 4]])),
+            Template(name="template2", image=np.array([[5, 6], [7, 8]])),
+            Template(name="template3", image=np.array([[9, 10], [11, 12]])),
+        ]
+        cache.add(templates)
+
+        screenshot = np.array([[13, 14], [15, 16]])
+        result = cache.match(screenshot)
+
+        assert result.confidence == 0.95
+        assert result.state == {"template_name": "template2"}
+
+    @patch("timmy.sovereignty.perception_cache.cv2")
+    def test_match_exactly_at_threshold(self, mock_cv2, tmp_path):
+        """Match returns state when confidence is exactly at threshold boundary."""
+        from timmy.sovereignty.perception_cache import PerceptionCache, Template
+
+        mock_cv2.matchTemplate.return_value = np.array([[0.1]])
+        mock_cv2.TM_CCOEFF_NORMED = "TM_CCOEFF_NORMED"
+        mock_cv2.minMaxLoc.return_value = (None, 0.85, None, None)  # Exactly at threshold
+
+        cache = PerceptionCache(templates_path=tmp_path / "templates.json")
+        template = Template(name="threshold_match", image=np.array([[1, 2], [3, 4]]))
+        cache.add([template])
+
+        screenshot = np.array([[5, 6], [7, 8]])
+        result = cache.match(screenshot)
+
+        # Note: current implementation uses > 0.85, so exactly 0.85 returns None state
+        assert result.confidence == 0.85
+        assert result.state is None
+
+    @patch("timmy.sovereignty.perception_cache.cv2")
+    def test_match_just_above_threshold(self, mock_cv2, tmp_path):
+        """Match returns state when confidence is just above threshold."""
+        from timmy.sovereignty.perception_cache import PerceptionCache, Template
+
+        mock_cv2.matchTemplate.return_value = np.array([[0.1]])
+        mock_cv2.TM_CCOEFF_NORMED = "TM_CCOEFF_NORMED"
+        mock_cv2.minMaxLoc.return_value = (None, 0.851, None, None)  # Just above threshold
+
+        cache = PerceptionCache(templates_path=tmp_path / "templates.json")
+        template = Template(name="above_threshold", image=np.array([[1, 2], [3, 4]]))
+        cache.add([template])
+
+        screenshot = np.array([[5, 6], [7, 8]])
+        result = cache.match(screenshot)
+
+        assert result.confidence == 0.851
+        assert result.state == {"template_name": "above_threshold"}
+
+
+class TestPerceptionCacheAdd:
+    """Tests for PerceptionCache.add() method."""
+
+    def test_add_single_template(self, tmp_path):
+        """Can add a single template to the cache."""
+        from timmy.sovereignty.perception_cache import PerceptionCache, Template
+
+        cache = PerceptionCache(templates_path=tmp_path / "templates.json")
+        template = Template(name="new_template", image=np.array([[1, 2], [3, 4]]))
+
+        cache.add([template])
+
+        assert len(cache.templates) == 1
+        assert cache.templates[0].name == "new_template"
+
+    def test_add_multiple_templates(self, tmp_path):
+        """Can add multiple templates at once."""
+        from timmy.sovereignty.perception_cache import PerceptionCache, Template
+
+        cache = PerceptionCache(templates_path=tmp_path / "templates.json")
+        templates = [
+            Template(name="template1", image=np.array([[1, 2], [3, 4]])),
+            Template(name="template2", image=np.array([[5, 6], [7, 8]])),
+        ]
+
+        cache.add(templates)
+
+        assert len(cache.templates) == 2
+        assert cache.templates[0].name == "template1"
+        assert cache.templates[1].name == "template2"
+
+    def test_add_templates_accumulate(self, tmp_path):
+        """Adding templates multiple times accumulates them."""
+        from timmy.sovereignty.perception_cache import PerceptionCache, Template
+
+        cache = PerceptionCache(templates_path=tmp_path / "templates.json")
+        cache.add([Template(name="first", image=np.array([[1]]))])
+        cache.add([Template(name="second", image=np.array([[2]]))])
+
+        assert len(cache.templates) == 2
+
+
+class TestPerceptionCachePersist:
+    """Tests for PerceptionCache.persist() method."""
+
+    def test_persist_creates_file(self, tmp_path):
+        """Persist creates templates JSON file."""
+        from timmy.sovereignty.perception_cache import PerceptionCache, Template
+
+        templates_path = tmp_path / "subdir" / "templates.json"
+        cache = PerceptionCache(templates_path=templates_path)
+        cache.add([Template(name="persisted", image=np.array([[1, 2], [3, 4]]))])
+
+        cache.persist()
+
+        assert templates_path.exists()
+
+    def test_persist_stores_template_names(self, tmp_path):
+        """Persist stores template names and thresholds."""
+        from timmy.sovereignty.perception_cache import PerceptionCache, Template
+
+        templates_path = tmp_path / "templates.json"
+        cache = PerceptionCache(templates_path=templates_path)
+        cache.add([
+            Template(name="template1", image=np.array([[1]]), threshold=0.85),
+            Template(name="template2", image=np.array([[2]]), threshold=0.90),
+        ])
+
+        cache.persist()
+
+        with open(templates_path) as f:
+            data = json.load(f)
+
+        assert len(data) == 2
+        assert data[0]["name"] == "template1"
+        assert data[0]["threshold"] == 0.85
+        assert data[1]["name"] == "template2"
+        assert data[1]["threshold"] == 0.90
+
+    def test_persist_does_not_store_image_data(self, tmp_path):
+        """Persist only stores metadata, not actual image arrays."""
+        from timmy.sovereignty.perception_cache import PerceptionCache, Template
+
+        templates_path = tmp_path / "templates.json"
+        cache = PerceptionCache(templates_path=templates_path)
+        cache.add([Template(name="no_image", image=np.array([[1, 2, 3], [4, 5, 6]]))])
+
+        cache.persist()
+
+        with open(templates_path) as f:
+            data = json.load(f)
+
+        assert "image" not in data[0]
+        assert set(data[0].keys()) == {"name", "threshold"}
+
+
+class TestPerceptionCacheLoad:
+    """Tests for PerceptionCache.load() method."""
+
+    def test_load_from_existing_file(self, tmp_path):
+        """Load restores templates from persisted file."""
+        from timmy.sovereignty.perception_cache import PerceptionCache
+
+        templates_path = tmp_path / "templates.json"
+
+        # Create initial cache with templates and persist
+        cache1 = PerceptionCache(templates_path=templates_path)
+        from timmy.sovereignty.perception_cache import Template
+
+        cache1.add([Template(name="loaded", image=np.array([[1]]), threshold=0.88)])
+        cache1.persist()
+
+        # Create new cache instance that loads from same file
+        cache2 = PerceptionCache(templates_path=templates_path)
+
+        assert len(cache2.templates) == 1
+        assert cache2.templates[0].name == "loaded"
+        assert cache2.templates[0].threshold == 0.88
+        # Note: images are loaded as empty arrays per current implementation
+        assert cache2.templates[0].image.size == 0
+
+    def test_load_empty_file(self, tmp_path):
+        """Load handles empty template list in file."""
+        from timmy.sovereignty.perception_cache import PerceptionCache
+
+        templates_path = tmp_path / "templates.json"
+        with open(templates_path, "w") as f:
+            json.dump([], f)
+
+        cache = PerceptionCache(templates_path=templates_path)
+
+        assert cache.templates == []
+
+
+class TestCrystallizePerception:
+    """Tests for crystallize_perception function."""
+
+    def test_crystallize_returns_empty_list(self, tmp_path):
+        """crystallize_perception currently returns empty list (placeholder)."""
+        from timmy.sovereignty.perception_cache import crystallize_perception
+
+        screenshot = np.array([[1, 2], [3, 4]])
+        result = crystallize_perception(screenshot, {"some": "response"})
+
+        assert result == []
+
+    def test_crystallize_accepts_any_vlm_response(self, tmp_path):
+        """crystallize_perception accepts any vlm_response format."""
+        from timmy.sovereignty.perception_cache import crystallize_perception
+
+        screenshot = np.array([[1, 2], [3, 4]])
+
+        # Test with various response types
+        assert crystallize_perception(screenshot, None) == []
+        assert crystallize_perception(screenshot, {}) == []
+        assert crystallize_perception(screenshot, {"items": []}) == []
+        assert crystallize_perception(screenshot, "string response") == []
--- a/tests/timmy/test_backlog_triage.py
+++ b/tests/timmy/test_backlog_triage.py
@@ -0,0 +1,694 @@
+"""Unit tests for timmy.backlog_triage — scoring, prioritization, and decision logic."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from timmy.backlog_triage import (
+    AGENT_CLAUDE,
+    AGENT_KIMI,
+    KIMI_READY_LABEL,
+    OWNER_LOGIN,
+    READY_THRESHOLD,
+    BacklogTriageLoop,
+    ScoredIssue,
+    TriageCycleResult,
+    TriageDecision,
+    _build_audit_comment,
+    _extract_tags,
+    _score_acceptance,
+    _score_alignment,
+    _score_scope,
+    decide,
+    execute_decision,
+    score_issue,
+)
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_raw_issue(
+    number: int = 1,
+    title: str = "Fix something broken in src/foo.py",
+    body: str = "## Problem\nThis crashes. Expected: no crash. Steps: run it.",
+    labels: list[str] | None = None,
+    assignees: list[str] | None = None,
+    created_at: str | None = None,
+) -> dict:
+    if labels is None:
+        labels = []
+    if assignees is None:
+        assignees = []
+    if created_at is None:
+        created_at = datetime.now(UTC).isoformat()
+    return {
+        "number": number,
+        "title": title,
+        "body": body,
+        "labels": [{"name": lbl} for lbl in labels],
+        "assignees": [{"login": a} for a in assignees],
+        "created_at": created_at,
+    }
+
+
+def _make_scored(
+    number: int = 1,
+    title: str = "Fix a bug",
+    issue_type: str = "bug",
+    score: int = 6,
+    ready: bool = True,
+    assignees: list[str] | None = None,
+    tags: set[str] | None = None,
+    is_p0: bool = False,
+    is_blocked: bool = False,
+) -> ScoredIssue:
+    return ScoredIssue(
+        number=number,
+        title=title,
+        body="",
+        labels=[],
+        tags=tags or set(),
+        assignees=assignees or [],
+        created_at=datetime.now(UTC),
+        issue_type=issue_type,
+        score=score,
+        scope=2,
+        acceptance=2,
+        alignment=2,
+        ready=ready,
+        age_days=5,
+        is_p0=is_p0,
+        is_blocked=is_blocked,
+    )
+
+
+# ---------------------------------------------------------------------------
+# _extract_tags
+# ---------------------------------------------------------------------------
+
+
+class TestExtractTags:
+    def test_bracket_tags_from_title(self):
+        tags = _extract_tags("[feat][bug] do something", [])
+        assert "feat" in tags
+        assert "bug" in tags
+
+    def test_label_names_included(self):
+        tags = _extract_tags("Normal title", ["kimi-ready", "enhancement"])
+        assert "kimi-ready" in tags
+        assert "enhancement" in tags
+
+    def test_combined(self):
+        tags = _extract_tags("[fix] crash in module", ["p0"])
+        assert "fix" in tags
+        assert "p0" in tags
+
+    def test_empty_inputs(self):
+        assert _extract_tags("", []) == set()
+
+    def test_tags_are_lowercased(self):
+        tags = _extract_tags("[BUG][Refactor] title", ["Enhancement"])
+        assert "bug" in tags
+        assert "refactor" in tags
+        assert "enhancement" in tags
+
+
+# ---------------------------------------------------------------------------
+# _score_scope
+# ---------------------------------------------------------------------------
+
+
+class TestScoreScope:
+    def test_file_reference_adds_point(self):
+        score = _score_scope("Fix login", "See src/auth/login.py for details", set())
+        assert score >= 1
+
+    def test_function_reference_adds_point(self):
+        score = _score_scope("Fix login", "In the `handle_login()` method", set())
+        assert score >= 1
+
+    def test_short_title_adds_point(self):
+        score = _score_scope("Short clear title", "", set())
+        assert score >= 1
+
+    def test_long_title_no_bonus(self):
+        long_title = "A" * 90
+        score_long = _score_scope(long_title, "", set())
+        score_short = _score_scope("Short title", "", set())
+        assert score_short >= score_long
+
+    def test_meta_tags_reduce_score(self):
+        score_meta = _score_scope("Discuss src/foo.py philosophy", "def func()", {"philosophy"})
+        score_plain = _score_scope("Fix src/foo.py bug", "def func()", set())
+        assert score_meta < score_plain
+
+    def test_max_is_three(self):
+        score = _score_scope(
+            "Fix it", "See src/foo.py and `def bar()` method here", set()
+        )
+        assert score <= 3
+
+
+# ---------------------------------------------------------------------------
+# _score_acceptance
+# ---------------------------------------------------------------------------
+
+
+class TestScoreAcceptance:
+    def test_accept_keywords_add_points(self):
+        body = "Should return 200. Must pass validation. Assert no errors."
+        score = _score_acceptance("", body, set())
+        assert score >= 2
+
+    def test_test_reference_adds_point(self):
+        score = _score_acceptance("", "Run pytest to verify", set())
+        assert score >= 1
+
+    def test_structured_headers_add_point(self):
+        body = "## Problem\nit breaks\n## Expected\nsuccess"
+        score = _score_acceptance("", body, set())
+        assert score >= 1
+
+    def test_meta_tags_reduce_score(self):
+        body = "Should pass and must verify assert test_foo"
+        score_meta = _score_acceptance("", body, {"philosophy"})
+        score_plain = _score_acceptance("", body, set())
+        assert score_meta < score_plain
+
+    def test_max_is_three(self):
+        body = (
+            "Should pass. Must return. Expected: success. Assert no error. "
+            "pytest test_foo. ## Problem\ndef. ## Expected\nok"
+        )
+        score = _score_acceptance("", body, set())
+        assert score <= 3
+
+
+# ---------------------------------------------------------------------------
+# _score_alignment
+# ---------------------------------------------------------------------------
+
+
+class TestScoreAlignment:
+    def test_bug_tags_return_max(self):
+        assert _score_alignment("", "", {"bug"}) == 3
+        assert _score_alignment("", "", {"crash"}) == 3
+        assert _score_alignment("", "", {"hotfix"}) == 3
+
+    def test_refactor_tags_give_high_score(self):
+        score = _score_alignment("", "", {"refactor"})
+        assert score >= 2
+
+    def test_feature_tags_give_high_score(self):
+        score = _score_alignment("", "", {"feature"})
+        assert score >= 2
+
+    def test_loop_generated_adds_bonus(self):
+        score_with = _score_alignment("", "", {"feature", "loop-generated"})
+        score_without = _score_alignment("", "", {"feature"})
+        assert score_with >= score_without
+
+    def test_meta_tags_zero_out_score(self):
+        score = _score_alignment("", "", {"philosophy", "refactor"})
+        assert score == 0
+
+    def test_max_is_three(self):
+        score = _score_alignment("", "", {"feature", "loop-generated", "enhancement"})
+        assert score <= 3
+
+
+# ---------------------------------------------------------------------------
+# score_issue
+# ---------------------------------------------------------------------------
+
+
+class TestScoreIssue:
+    def test_basic_bug_issue_classified(self):
+        raw = _make_raw_issue(
+            title="[bug] fix crash in src/timmy/agent.py",
+            body="## Problem\nCrashes on startup. Expected: runs. Steps: python -m timmy",
+        )
+        issue = score_issue(raw)
+        assert issue.issue_type == "bug"
+        assert issue.is_p0 is True
+
+    def test_feature_issue_classified(self):
+        raw = _make_raw_issue(
+            title="[feat] add dark mode to dashboard",
+            body="Add a toggle button. Should switch CSS vars.",
+            labels=["feature"],
+        )
+        issue = score_issue(raw)
+        assert issue.issue_type == "feature"
+
+    def test_research_issue_classified(self):
+        raw = _make_raw_issue(
+            title="Investigate MCP performance",
+            labels=["kimi-ready", "research"],
+        )
+        issue = score_issue(raw)
+        assert issue.issue_type == "research"
+        assert issue.needs_kimi is True
+
+    def test_philosophy_issue_classified(self):
+        raw = _make_raw_issue(
+            title="Discussion: soul and identity",
+            labels=["philosophy"],
+        )
+        issue = score_issue(raw)
+        assert issue.issue_type == "philosophy"
+
+    def test_score_totals_components(self):
+        raw = _make_raw_issue()
+        issue = score_issue(raw)
+        assert issue.score == issue.scope + issue.acceptance + issue.alignment
+
+    def test_ready_flag_set_when_score_meets_threshold(self):
+        # Create an issue that will definitely score >= READY_THRESHOLD
+        raw = _make_raw_issue(
+            title="[bug] crash in src/core.py",
+            body=(
+                "## Problem\nCrashes when running `run()`. "
+                "Expected: should return 200. Must pass pytest assert."
+            ),
+            labels=["bug"],
+        )
+        issue = score_issue(raw)
+        assert issue.ready == (issue.score >= READY_THRESHOLD)
+
+    def test_assigned_issue_reports_assignees(self):
+        raw = _make_raw_issue(assignees=["claude", "kimi"])
+        issue = score_issue(raw)
+        assert "claude" in issue.assignees
+        assert issue.is_unassigned is False
+
+    def test_unassigned_issue(self):
+        raw = _make_raw_issue(assignees=[])
+        issue = score_issue(raw)
+        assert issue.is_unassigned is True
+
+    def test_blocked_issue_detected(self):
+        raw = _make_raw_issue(
+            title="Fix blocked deployment", body="Blocked by infra team."
+        )
+        issue = score_issue(raw)
+        assert issue.is_blocked is True
+
+    def test_age_days_computed(self):
+        old_date = (datetime.now(UTC) - timedelta(days=30)).isoformat()
+        raw = _make_raw_issue(created_at=old_date)
+        issue = score_issue(raw)
+        assert issue.age_days >= 29
+
+    def test_invalid_created_at_defaults_to_now(self):
+        raw = _make_raw_issue(created_at="not-a-date")
+        issue = score_issue(raw)
+        assert issue.age_days == 0
+
+    def test_title_bracket_tags_stripped(self):
+        raw = _make_raw_issue(title="[bug][p0] crash in login")
+        issue = score_issue(raw)
+        assert "[" not in issue.title
+
+    def test_missing_body_defaults_to_empty(self):
+        raw = _make_raw_issue()
+        raw["body"] = None
+        issue = score_issue(raw)
+        assert issue.body == ""
+
+    def test_kimi_label_triggers_needs_kimi(self):
+        raw = _make_raw_issue(labels=[KIMI_READY_LABEL])
+        issue = score_issue(raw)
+        assert issue.needs_kimi is True
+
+
+# ---------------------------------------------------------------------------
+# decide
+# ---------------------------------------------------------------------------
+
+
+class TestDecide:
+    def test_philosophy_is_skipped(self):
+        issue = _make_scored(issue_type="philosophy")
+        d = decide(issue)
+        assert d.action == "skip"
+        assert "philosophy" in d.reason.lower() or "meta" in d.reason.lower()
+
+    def test_already_assigned_is_skipped(self):
+        issue = _make_scored(assignees=["claude"])
+        d = decide(issue)
+        assert d.action == "skip"
+        assert "assigned" in d.reason.lower()
+
+    def test_low_score_is_skipped(self):
+        issue = _make_scored(score=READY_THRESHOLD - 1, ready=False)
+        d = decide(issue)
+        assert d.action == "skip"
+        assert str(READY_THRESHOLD) in d.reason
+
+    def test_blocked_is_flagged_for_alex(self):
+        issue = _make_scored(is_blocked=True)
+        d = decide(issue)
+        assert d.action == "flag_alex"
+        assert d.agent == OWNER_LOGIN
+
+    def test_kimi_ready_assigned_to_kimi(self):
+        issue = _make_scored(tags={"kimi-ready"})
+        # Ensure it's unassigned and ready
+        issue.assignees = []
+        issue.ready = True
+        issue.is_blocked = False
+        issue.issue_type = "research"
+        d = decide(issue)
+        assert d.action == "assign_kimi"
+        assert d.agent == AGENT_KIMI
+
+    def test_research_type_assigned_to_kimi(self):
+        issue = _make_scored(issue_type="research", tags={"research"})
+        d = decide(issue)
+        assert d.action == "assign_kimi"
+        assert d.agent == AGENT_KIMI
+
+    def test_p0_bug_assigned_to_claude(self):
+        issue = _make_scored(issue_type="bug", is_p0=True)
+        d = decide(issue)
+        assert d.action == "assign_claude"
+        assert d.agent == AGENT_CLAUDE
+
+    def test_ready_feature_assigned_to_claude(self):
+        issue = _make_scored(issue_type="feature", score=6, ready=True)
+        d = decide(issue)
+        assert d.action == "assign_claude"
+        assert d.agent == AGENT_CLAUDE
+
+    def test_ready_refactor_assigned_to_claude(self):
+        issue = _make_scored(issue_type="refactor", score=6, ready=True)
+        d = decide(issue)
+        assert d.action == "assign_claude"
+        assert d.agent == AGENT_CLAUDE
+
+    def test_decision_has_issue_number(self):
+        issue = _make_scored(number=42)
+        d = decide(issue)
+        assert d.issue_number == 42
+
+
+# ---------------------------------------------------------------------------
+# _build_audit_comment
+# ---------------------------------------------------------------------------
+
+
+class TestBuildAuditComment:
+    def test_assign_claude_comment(self):
+        d = TriageDecision(
+            issue_number=1, action="assign_claude", agent=AGENT_CLAUDE, reason="Ready bug"
+        )
+        comment = _build_audit_comment(d)
+        assert AGENT_CLAUDE in comment
+        assert "Timmy Triage" in comment
+        assert "Ready bug" in comment
+
+    def test_assign_kimi_comment(self):
+        d = TriageDecision(
+            issue_number=2, action="assign_kimi", agent=AGENT_KIMI, reason="Research spike"
+        )
+        comment = _build_audit_comment(d)
+        assert KIMI_READY_LABEL in comment
+
+    def test_flag_alex_comment(self):
+        d = TriageDecision(
+            issue_number=3, action="flag_alex", agent=OWNER_LOGIN, reason="Blocked"
+        )
+        comment = _build_audit_comment(d)
+        assert OWNER_LOGIN in comment
+
+    def test_comment_contains_autonomous_triage_note(self):
+        d = TriageDecision(issue_number=1, action="assign_claude", agent=AGENT_CLAUDE, reason="x")
+        comment = _build_audit_comment(d)
+        assert "Autonomous triage" in comment or "autonomous" in comment.lower()
+
+
+# ---------------------------------------------------------------------------
+# execute_decision (dry_run)
+# ---------------------------------------------------------------------------
+
+
+class TestExecuteDecisionDryRun:
+    @pytest.mark.asyncio
+    async def test_skip_action_marks_executed(self):
+        d = TriageDecision(issue_number=1, action="skip", reason="Already assigned")
+        mock_client = AsyncMock()
+        result = await execute_decision(mock_client, d, dry_run=True)
+        assert result.executed is True
+        mock_client.post.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_dry_run_does_not_call_api(self):
+        d = TriageDecision(
+            issue_number=5, action="assign_claude", agent=AGENT_CLAUDE, reason="Ready"
+        )
+        mock_client = AsyncMock()
+        result = await execute_decision(mock_client, d, dry_run=True)
+        assert result.executed is True
+        mock_client.post.assert_not_called()
+        mock_client.patch.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_dry_run_kimi_does_not_call_api(self):
+        d = TriageDecision(
+            issue_number=6, action="assign_kimi", agent=AGENT_KIMI, reason="Research"
+        )
+        mock_client = AsyncMock()
+        result = await execute_decision(mock_client, d, dry_run=True)
+        assert result.executed is True
+        mock_client.post.assert_not_called()
+
+
+# ---------------------------------------------------------------------------
+# execute_decision (live — mocked HTTP)
+# ---------------------------------------------------------------------------
+
+
+class TestExecuteDecisionLive:
+    @pytest.mark.asyncio
+    async def test_assign_claude_posts_comment_then_patches(self):
+        comment_resp = MagicMock()
+        comment_resp.status_code = 201
+
+        patch_resp = MagicMock()
+        patch_resp.status_code = 200
+
+        mock_client = AsyncMock()
+        mock_client.post.return_value = comment_resp
+        mock_client.patch.return_value = patch_resp
+
+        d = TriageDecision(
+            issue_number=10, action="assign_claude", agent=AGENT_CLAUDE, reason="Bug ready"
+        )
+
+        with patch("timmy.backlog_triage.settings") as mock_settings:
+            mock_settings.gitea_token = "tok"
+            mock_settings.gitea_repo = "owner/repo"
+            mock_settings.gitea_url = "http://localhost:3000"
+            result = await execute_decision(mock_client, d, dry_run=False)
+
+        assert result.executed is True
+        assert result.error == ""
+        mock_client.post.assert_called_once()
+        mock_client.patch.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_comment_failure_sets_error(self):
+        comment_resp = MagicMock()
+        comment_resp.status_code = 500
+
+        mock_client = AsyncMock()
+        mock_client.post.return_value = comment_resp
+
+        d = TriageDecision(
+            issue_number=11, action="assign_claude", agent=AGENT_CLAUDE, reason="Bug"
+        )
+
+        with patch("timmy.backlog_triage.settings") as mock_settings:
+            mock_settings.gitea_token = "tok"
+            mock_settings.gitea_repo = "owner/repo"
+            mock_settings.gitea_url = "http://localhost:3000"
+            result = await execute_decision(mock_client, d, dry_run=False)
+
+        assert result.executed is False
+        assert result.error != ""
+
+    @pytest.mark.asyncio
+    async def test_flag_alex_only_posts_comment(self):
+        comment_resp = MagicMock()
+        comment_resp.status_code = 201
+
+        mock_client = AsyncMock()
+        mock_client.post.return_value = comment_resp
+
+        d = TriageDecision(
+            issue_number=12, action="flag_alex", agent=OWNER_LOGIN, reason="Blocked"
+        )
+
+        with patch("timmy.backlog_triage.settings") as mock_settings:
+            mock_settings.gitea_token = "tok"
+            mock_settings.gitea_repo = "owner/repo"
+            mock_settings.gitea_url = "http://localhost:3000"
+            result = await execute_decision(mock_client, d, dry_run=False)
+
+        assert result.executed is True
+        mock_client.patch.assert_not_called()
+
+
+# ---------------------------------------------------------------------------
+# BacklogTriageLoop
+# ---------------------------------------------------------------------------
+
+
+class TestBacklogTriageLoop:
+    def test_default_state(self):
+        with patch("timmy.backlog_triage.settings") as mock_settings:
+            mock_settings.backlog_triage_interval_seconds = 900
+            mock_settings.backlog_triage_dry_run = True
+            mock_settings.backlog_triage_daily_summary = False
+            loop = BacklogTriageLoop()
+        assert loop.is_running is False
+        assert loop.cycle_count == 0
+        assert loop.history == []
+
+    def test_custom_interval_overrides_settings(self):
+        with patch("timmy.backlog_triage.settings") as mock_settings:
+            mock_settings.backlog_triage_interval_seconds = 900
+            mock_settings.backlog_triage_dry_run = True
+            mock_settings.backlog_triage_daily_summary = False
+            loop = BacklogTriageLoop(interval=60)
+        assert loop._interval == 60.0
+
+    def test_stop_sets_running_false(self):
+        with patch("timmy.backlog_triage.settings") as mock_settings:
+            mock_settings.backlog_triage_interval_seconds = 900
+            mock_settings.backlog_triage_dry_run = True
+            mock_settings.backlog_triage_daily_summary = False
+            loop = BacklogTriageLoop()
+        loop._running = True
+        loop.stop()
+        assert loop.is_running is False
+
+    @pytest.mark.asyncio
+    async def test_run_once_skips_when_gitea_disabled(self):
+        with patch("timmy.backlog_triage.settings") as mock_settings:
+            mock_settings.backlog_triage_interval_seconds = 900
+            mock_settings.backlog_triage_dry_run = True
+            mock_settings.backlog_triage_daily_summary = False
+            mock_settings.gitea_enabled = False
+            mock_settings.gitea_token = ""
+            loop = BacklogTriageLoop(dry_run=True, daily_summary=False)
+            result = await loop.run_once()
+
+        assert result.total_open == 0
+        assert result.scored == 0
+
+    @pytest.mark.asyncio
+    async def test_run_once_increments_cycle_count(self):
+        with patch("timmy.backlog_triage.settings") as mock_settings:
+            mock_settings.backlog_triage_interval_seconds = 900
+            mock_settings.backlog_triage_dry_run = True
+            mock_settings.backlog_triage_daily_summary = False
+            mock_settings.gitea_enabled = False
+            mock_settings.gitea_token = ""
+            loop = BacklogTriageLoop(dry_run=True, daily_summary=False)
+            await loop.run_once()
+            await loop.run_once()
+
+        assert loop.cycle_count == 2
+
+    @pytest.mark.asyncio
+    async def test_run_once_full_cycle_with_mocked_gitea(self):
+        raw_issues = [
+            _make_raw_issue(
+                number=100,
+                title="[bug] crash in src/timmy/agent.py",
+                body=(
+                    "## Problem\nCrashes. Expected: runs. "
+                    "Must pass pytest. Should return 200."
+                ),
+                labels=["bug"],
+                assignees=[],
+            )
+        ]
+
+        issues_resp = MagicMock()
+        issues_resp.status_code = 200
+        issues_resp.json.side_effect = [raw_issues, []]  # page 1, then empty
+
+        mock_client = AsyncMock()
+        mock_client.get.return_value = issues_resp
+
+        with patch("timmy.backlog_triage.settings") as mock_settings:
+            mock_settings.backlog_triage_interval_seconds = 900
+            mock_settings.backlog_triage_dry_run = True
+            mock_settings.backlog_triage_daily_summary = False
+            mock_settings.gitea_enabled = True
+            mock_settings.gitea_token = "tok"
+            mock_settings.gitea_repo = "owner/repo"
+            mock_settings.gitea_url = "http://localhost:3000"
+
+            with patch("timmy.backlog_triage.httpx.AsyncClient") as mock_cls:
+                mock_cls.return_value.__aenter__ = AsyncMock(return_value=mock_client)
+                mock_cls.return_value.__aexit__ = AsyncMock(return_value=False)
+
+                loop = BacklogTriageLoop(dry_run=True, daily_summary=False)
+                result = await loop.run_once()
+
+        assert result.total_open == 1
+        assert result.scored == 1
+        assert loop.cycle_count == 1
+        assert len(loop.history) == 1
+
+
+# ---------------------------------------------------------------------------
+# ScoredIssue properties
+# ---------------------------------------------------------------------------
+
+
+class TestScoredIssueProperties:
+    def test_is_unassigned_true_when_no_assignees(self):
+        issue = _make_scored(assignees=[])
+        assert issue.is_unassigned is True
+
+    def test_is_unassigned_false_when_assigned(self):
+        issue = _make_scored(assignees=["claude"])
+        assert issue.is_unassigned is False
+
+    def test_needs_kimi_from_research_tag(self):
+        issue = _make_scored(tags={"research"})
+        assert issue.needs_kimi is True
+
+    def test_needs_kimi_from_kimi_ready_label(self):
+        issue = _make_scored()
+        issue.labels = [KIMI_READY_LABEL]
+        assert issue.needs_kimi is True
+
+    def test_needs_kimi_false_for_plain_bug(self):
+        issue = _make_scored(tags={"bug"}, issue_type="bug")
+        assert issue.needs_kimi is False
+
+
+# ---------------------------------------------------------------------------
+# TriageCycleResult
+# ---------------------------------------------------------------------------
+
+
+class TestTriageCycleResult:
+    def test_default_decisions_list_is_empty(self):
+        result = TriageCycleResult(
+            timestamp="2026-01-01T00:00:00", total_open=10, scored=8, ready=3
+        )
+        assert result.decisions == []
+        assert result.errors == []
+        assert result.duration_ms == 0
--- a/tests/timmy/test_kimi_delegation.py
+++ b/tests/timmy/test_kimi_delegation.py
@@ -0,0 +1,642 @@
+"""Unit tests for timmy.kimi_delegation — Kimi research delegation pipeline."""
+
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+# ---------------------------------------------------------------------------
+# exceeds_local_capacity
+# ---------------------------------------------------------------------------
+
+
+class TestExceedsLocalCapacity:
+    def test_heavy_keyword_triggers_delegation(self):
+        from timmy.kimi_delegation import exceeds_local_capacity
+
+        assert exceeds_local_capacity("Do a comprehensive review of the codebase") is True
+
+    def test_all_heavy_keywords_detected(self):
+        from timmy.kimi_delegation import _HEAVY_RESEARCH_KEYWORDS, exceeds_local_capacity
+
+        for kw in _HEAVY_RESEARCH_KEYWORDS:
+            assert exceeds_local_capacity(f"Please {kw} the topic") is True, f"Missed keyword: {kw}"
+
+    def test_long_task_triggers_delegation(self):
+        from timmy.kimi_delegation import _HEAVY_WORD_THRESHOLD, exceeds_local_capacity
+
+        long_task = " ".join(["word"] * (_HEAVY_WORD_THRESHOLD + 1))
+        assert exceeds_local_capacity(long_task) is True
+
+    def test_short_simple_task_returns_false(self):
+        from timmy.kimi_delegation import exceeds_local_capacity
+
+        assert exceeds_local_capacity("Fix the typo in README") is False
+
+    def test_exactly_at_word_threshold_triggers(self):
+        from timmy.kimi_delegation import _HEAVY_WORD_THRESHOLD, exceeds_local_capacity
+
+        task = " ".join(["word"] * _HEAVY_WORD_THRESHOLD)
+        assert exceeds_local_capacity(task) is True
+
+    def test_keyword_case_insensitive(self):
+        from timmy.kimi_delegation import exceeds_local_capacity
+
+        assert exceeds_local_capacity("Run a COMPREHENSIVE analysis") is True
+
+    def test_empty_string_returns_false(self):
+        from timmy.kimi_delegation import exceeds_local_capacity
+
+        assert exceeds_local_capacity("") is False
+
+
+# ---------------------------------------------------------------------------
+# _slugify
+# ---------------------------------------------------------------------------
+
+
+class TestSlugify:
+    def test_basic_text(self):
+        from timmy.kimi_delegation import _slugify
+
+        assert _slugify("Hello World") == "hello-world"
+
+    def test_special_characters_removed(self):
+        from timmy.kimi_delegation import _slugify
+
+        assert _slugify("Research: AI & ML!") == "research-ai--ml"
+
+    def test_underscores_become_dashes(self):
+        from timmy.kimi_delegation import _slugify
+
+        assert _slugify("some_snake_case") == "some-snake-case"
+
+    def test_long_text_truncated_to_60(self):
+        from timmy.kimi_delegation import _slugify
+
+        long_text = "a" * 100
+        result = _slugify(long_text)
+        assert len(result) <= 60
+
+    def test_leading_trailing_dashes_stripped(self):
+        from timmy.kimi_delegation import _slugify
+
+        result = _slugify("  hello  ")
+        assert not result.startswith("-")
+        assert not result.endswith("-")
+
+    def test_multiple_spaces_become_single_dash(self):
+        from timmy.kimi_delegation import _slugify
+
+        assert _slugify("one   two") == "one-two"
+
+
+# ---------------------------------------------------------------------------
+# _build_research_template
+# ---------------------------------------------------------------------------
+
+
+class TestBuildResearchTemplate:
+    def test_contains_task_title(self):
+        from timmy.kimi_delegation import _build_research_template
+
+        body = _build_research_template("My Task", "background", "the question?")
+        assert "My Task" in body
+
+    def test_contains_question(self):
+        from timmy.kimi_delegation import _build_research_template
+
+        body = _build_research_template("task", "context", "What is X?")
+        assert "What is X?" in body
+
+    def test_contains_context(self):
+        from timmy.kimi_delegation import _build_research_template
+
+        body = _build_research_template("task", "some context here", "q?")
+        assert "some context here" in body
+
+    def test_default_priority_normal(self):
+        from timmy.kimi_delegation import _build_research_template
+
+        body = _build_research_template("task", "ctx", "q?")
+        assert "normal" in body
+
+    def test_custom_priority_included(self):
+        from timmy.kimi_delegation import _build_research_template
+
+        body = _build_research_template("task", "ctx", "q?", priority="high")
+        assert "high" in body
+
+    def test_kimi_label_mentioned(self):
+        from timmy.kimi_delegation import KIMI_READY_LABEL, _build_research_template
+
+        body = _build_research_template("task", "ctx", "q?")
+        assert KIMI_READY_LABEL in body
+
+    def test_slugified_task_in_artifact_path(self):
+        from timmy.kimi_delegation import _build_research_template
+
+        body = _build_research_template("My Research Task", "ctx", "q?")
+        assert "my-research-task" in body
+
+    def test_sections_present(self):
+        from timmy.kimi_delegation import _build_research_template
+
+        body = _build_research_template("task", "ctx", "q?")
+        assert "## Research Request" in body
+        assert "### Research Question" in body
+        assert "### Background / Context" in body
+        assert "### Deliverables" in body
+
+
+# ---------------------------------------------------------------------------
+# _extract_action_items
+# ---------------------------------------------------------------------------
+
+
+class TestExtractActionItems:
+    def test_checkbox_items_extracted(self):
+        from timmy.kimi_delegation import _extract_action_items
+
+        text = "- [ ] Fix the bug\n- [ ] Write tests\n"
+        items = _extract_action_items(text)
+        assert "Fix the bug" in items
+        assert "Write tests" in items
+
+    def test_numbered_list_extracted(self):
+        from timmy.kimi_delegation import _extract_action_items
+
+        text = "1. Deploy to staging\n2. Run smoke tests\n"
+        items = _extract_action_items(text)
+        assert "Deploy to staging" in items
+        assert "Run smoke tests" in items
+
+    def test_action_prefix_extracted(self):
+        from timmy.kimi_delegation import _extract_action_items
+
+        text = "Action: Update the config file\n"
+        items = _extract_action_items(text)
+        assert "Update the config file" in items
+
+    def test_todo_prefix_extracted(self):
+        from timmy.kimi_delegation import _extract_action_items
+
+        text = "TODO: Add error handling\n"
+        items = _extract_action_items(text)
+        assert "Add error handling" in items
+
+    def test_next_step_prefix_extracted(self):
+        from timmy.kimi_delegation import _extract_action_items
+
+        text = "Next step: Validate results\n"
+        items = _extract_action_items(text)
+        assert "Validate results" in items
+
+    def test_case_insensitive_prefixes(self):
+        from timmy.kimi_delegation import _extract_action_items
+
+        text = "todo: lowercase todo\nACTION: uppercase action\n"
+        items = _extract_action_items(text)
+        assert "lowercase todo" in items
+        assert "uppercase action" in items
+
+    def test_deduplication(self):
+        from timmy.kimi_delegation import _extract_action_items
+
+        text = "1. Do the thing\n2. Do the thing\n"
+        items = _extract_action_items(text)
+        assert items.count("Do the thing") == 1
+
+    def test_empty_text_returns_empty_list(self):
+        from timmy.kimi_delegation import _extract_action_items
+
+        assert _extract_action_items("") == []
+
+    def test_no_action_items_returns_empty_list(self):
+        from timmy.kimi_delegation import _extract_action_items
+
+        text = "This is just plain prose with no action items here."
+        assert _extract_action_items(text) == []
+
+    def test_mixed_sources_combined(self):
+        from timmy.kimi_delegation import _extract_action_items
+
+        text = "- [ ] checkbox item\n1. numbered item\nAction: action item\n"
+        items = _extract_action_items(text)
+        assert len(items) == 3
+
+
+# ---------------------------------------------------------------------------
+# _get_or_create_label (async)
+# ---------------------------------------------------------------------------
+
+
+class TestGetOrCreateLabel:
+    @pytest.mark.asyncio
+    async def test_returns_existing_label_id(self):
+        from timmy.kimi_delegation import KIMI_READY_LABEL, _get_or_create_label
+
+        mock_resp = MagicMock()
+        mock_resp.status_code = 200
+        mock_resp.json.return_value = [{"name": KIMI_READY_LABEL, "id": 42}]
+
+        client = MagicMock()
+        client.get = AsyncMock(return_value=mock_resp)
+
+        result = await _get_or_create_label(client, "http://git", {"Authorization": "token x"}, "owner/repo")
+        assert result == 42
+
+    @pytest.mark.asyncio
+    async def test_creates_label_when_missing(self):
+        from timmy.kimi_delegation import _get_or_create_label
+
+        list_resp = MagicMock()
+        list_resp.status_code = 200
+        list_resp.json.return_value = []  # no existing labels
+
+        create_resp = MagicMock()
+        create_resp.status_code = 201
+        create_resp.json.return_value = {"id": 99}
+
+        client = MagicMock()
+        client.get = AsyncMock(return_value=list_resp)
+        client.post = AsyncMock(return_value=create_resp)
+
+        result = await _get_or_create_label(client, "http://git", {"Authorization": "token x"}, "owner/repo")
+        assert result == 99
+
+    @pytest.mark.asyncio
+    async def test_returns_none_on_list_exception(self):
+        from timmy.kimi_delegation import _get_or_create_label
+
+        client = MagicMock()
+        client.get = AsyncMock(side_effect=Exception("network error"))
+
+        result = await _get_or_create_label(client, "http://git", {}, "owner/repo")
+        assert result is None
+
+    @pytest.mark.asyncio
+    async def test_returns_none_on_create_exception(self):
+        from timmy.kimi_delegation import _get_or_create_label
+
+        list_resp = MagicMock()
+        list_resp.status_code = 200
+        list_resp.json.return_value = []
+
+        client = MagicMock()
+        client.get = AsyncMock(return_value=list_resp)
+        client.post = AsyncMock(side_effect=Exception("create failed"))
+
+        result = await _get_or_create_label(client, "http://git", {}, "owner/repo")
+        assert result is None
+
+
+# ---------------------------------------------------------------------------
+# create_kimi_research_issue (async)
+# ---------------------------------------------------------------------------
+
+
+class TestCreateKimiResearchIssue:
+    @pytest.mark.asyncio
+    async def test_returns_error_when_gitea_disabled(self):
+        from timmy.kimi_delegation import create_kimi_research_issue
+
+        with patch("timmy.kimi_delegation.settings") as mock_settings:
+            mock_settings.gitea_enabled = False
+            mock_settings.gitea_token = ""
+            result = await create_kimi_research_issue("task", "ctx", "q?")
+
+        assert result["success"] is False
+        assert "not configured" in result["error"]
+
+    @pytest.mark.asyncio
+    async def test_returns_error_when_no_token(self):
+        from timmy.kimi_delegation import create_kimi_research_issue
+
+        with patch("timmy.kimi_delegation.settings") as mock_settings:
+            mock_settings.gitea_enabled = True
+            mock_settings.gitea_token = ""
+            result = await create_kimi_research_issue("task", "ctx", "q?")
+
+        assert result["success"] is False
+
+    @pytest.mark.asyncio
+    async def test_successful_issue_creation(self):
+        from timmy.kimi_delegation import create_kimi_research_issue
+
+        mock_settings = MagicMock()
+        mock_settings.gitea_enabled = True
+        mock_settings.gitea_token = "tok"
+        mock_settings.gitea_url = "http://git"
+        mock_settings.gitea_repo = "owner/repo"
+
+        label_resp = MagicMock()
+        label_resp.status_code = 200
+        label_resp.json.return_value = [{"name": "kimi-ready", "id": 5}]
+
+        issue_resp = MagicMock()
+        issue_resp.status_code = 201
+        issue_resp.json.return_value = {"number": 42, "html_url": "http://git/issues/42"}
+
+        async_client = AsyncMock()
+        async_client.get = AsyncMock(return_value=label_resp)
+        async_client.post = AsyncMock(return_value=issue_resp)
+        async_client.__aenter__ = AsyncMock(return_value=async_client)
+        async_client.__aexit__ = AsyncMock(return_value=False)
+
+        with (
+            patch("timmy.kimi_delegation.settings", mock_settings),
+            patch("timmy.kimi_delegation.httpx") as mock_httpx,
+        ):
+            mock_httpx.AsyncClient.return_value = async_client
+            result = await create_kimi_research_issue("task", "ctx", "q?")
+
+        assert result["success"] is True
+        assert result["issue_number"] == 42
+        assert "http://git/issues/42" in result["issue_url"]
+
+    @pytest.mark.asyncio
+    async def test_api_error_returns_failure(self):
+        from timmy.kimi_delegation import create_kimi_research_issue
+
+        mock_settings = MagicMock()
+        mock_settings.gitea_enabled = True
+        mock_settings.gitea_token = "tok"
+        mock_settings.gitea_url = "http://git"
+        mock_settings.gitea_repo = "owner/repo"
+
+        label_resp = MagicMock()
+        label_resp.status_code = 200
+        label_resp.json.return_value = []
+
+        create_label_resp = MagicMock()
+        create_label_resp.status_code = 201
+        create_label_resp.json.return_value = {"id": 1}
+
+        issue_resp = MagicMock()
+        issue_resp.status_code = 500
+        issue_resp.text = "Internal Server Error"
+
+        async_client = AsyncMock()
+        async_client.get = AsyncMock(return_value=label_resp)
+        async_client.post = AsyncMock(side_effect=[create_label_resp, issue_resp])
+        async_client.__aenter__ = AsyncMock(return_value=async_client)
+        async_client.__aexit__ = AsyncMock(return_value=False)
+
+        with (
+            patch("timmy.kimi_delegation.settings", mock_settings),
+            patch("timmy.kimi_delegation.httpx") as mock_httpx,
+        ):
+            mock_httpx.AsyncClient.return_value = async_client
+            result = await create_kimi_research_issue("task", "ctx", "q?")
+
+        assert result["success"] is False
+        assert "500" in result["error"]
+
+    @pytest.mark.asyncio
+    async def test_exception_returns_failure(self):
+        from timmy.kimi_delegation import create_kimi_research_issue
+
+        mock_settings = MagicMock()
+        mock_settings.gitea_enabled = True
+        mock_settings.gitea_token = "tok"
+        mock_settings.gitea_url = "http://git"
+        mock_settings.gitea_repo = "owner/repo"
+
+        async_client = AsyncMock()
+        async_client.__aenter__ = AsyncMock(side_effect=Exception("connection refused"))
+        async_client.__aexit__ = AsyncMock(return_value=False)
+
+        with (
+            patch("timmy.kimi_delegation.settings", mock_settings),
+            patch("timmy.kimi_delegation.httpx") as mock_httpx,
+        ):
+            mock_httpx.AsyncClient.return_value = async_client
+            result = await create_kimi_research_issue("task", "ctx", "q?")
+
+        assert result["success"] is False
+        assert result["error"] != ""
+
+
+# ---------------------------------------------------------------------------
+# poll_kimi_issue (async)
+# ---------------------------------------------------------------------------
+
+
+class TestPollKimiIssue:
+    @pytest.mark.asyncio
+    async def test_returns_error_when_gitea_not_configured(self):
+        from timmy.kimi_delegation import poll_kimi_issue
+
+        with patch("timmy.kimi_delegation.settings") as mock_settings:
+            mock_settings.gitea_enabled = False
+            mock_settings.gitea_token = ""
+            result = await poll_kimi_issue(123)
+
+        assert result["completed"] is False
+        assert "not configured" in result["error"]
+
+    @pytest.mark.asyncio
+    async def test_returns_completed_when_issue_closed(self):
+        from timmy.kimi_delegation import poll_kimi_issue
+
+        mock_settings = MagicMock()
+        mock_settings.gitea_enabled = True
+        mock_settings.gitea_token = "tok"
+        mock_settings.gitea_url = "http://git"
+        mock_settings.gitea_repo = "owner/repo"
+
+        resp = MagicMock()
+        resp.status_code = 200
+        resp.json.return_value = {"state": "closed", "body": "Done!"}
+
+        async_client = AsyncMock()
+        async_client.get = AsyncMock(return_value=resp)
+        async_client.__aenter__ = AsyncMock(return_value=async_client)
+        async_client.__aexit__ = AsyncMock(return_value=False)
+
+        with (
+            patch("timmy.kimi_delegation.settings", mock_settings),
+            patch("timmy.kimi_delegation.httpx") as mock_httpx,
+        ):
+            mock_httpx.AsyncClient.return_value = async_client
+            result = await poll_kimi_issue(42, poll_interval=0, max_wait=1)
+
+        assert result["completed"] is True
+        assert result["state"] == "closed"
+        assert result["body"] == "Done!"
+
+    @pytest.mark.asyncio
+    async def test_times_out_when_issue_stays_open(self):
+        from timmy.kimi_delegation import poll_kimi_issue
+
+        mock_settings = MagicMock()
+        mock_settings.gitea_enabled = True
+        mock_settings.gitea_token = "tok"
+        mock_settings.gitea_url = "http://git"
+        mock_settings.gitea_repo = "owner/repo"
+
+        resp = MagicMock()
+        resp.status_code = 200
+        resp.json.return_value = {"state": "open", "body": ""}
+
+        async_client = AsyncMock()
+        async_client.get = AsyncMock(return_value=resp)
+        async_client.__aenter__ = AsyncMock(return_value=async_client)
+        async_client.__aexit__ = AsyncMock(return_value=False)
+
+        with (
+            patch("timmy.kimi_delegation.settings", mock_settings),
+            patch("timmy.kimi_delegation.httpx") as mock_httpx,
+            patch("timmy.kimi_delegation.asyncio.sleep", new_callable=AsyncMock),
+        ):
+            mock_httpx.AsyncClient.return_value = async_client
+            # poll_interval > max_wait so it exits immediately after first sleep
+            result = await poll_kimi_issue(42, poll_interval=10, max_wait=5)
+
+        assert result["completed"] is False
+        assert result["state"] == "timeout"
+
+
+# ---------------------------------------------------------------------------
+# index_kimi_artifact (async)
+# ---------------------------------------------------------------------------
+
+
+class TestIndexKimiArtifact:
+    @pytest.mark.asyncio
+    async def test_empty_artifact_returns_error(self):
+        from timmy.kimi_delegation import index_kimi_artifact
+
+        result = await index_kimi_artifact(1, "title", "   ")
+        assert result["success"] is False
+        assert "Empty artifact" in result["error"]
+
+    @pytest.mark.asyncio
+    async def test_successful_indexing(self):
+        from timmy.kimi_delegation import index_kimi_artifact
+
+        mock_entry = MagicMock()
+        mock_entry.id = "mem-123"
+
+        with patch("timmy.kimi_delegation.asyncio.to_thread", new_callable=AsyncMock) as mock_thread:
+            mock_thread.return_value = mock_entry
+            result = await index_kimi_artifact(42, "My Research", "Some research content here")
+
+        assert result["success"] is True
+        assert result["memory_id"] == "mem-123"
+
+    @pytest.mark.asyncio
+    async def test_exception_returns_failure(self):
+        from timmy.kimi_delegation import index_kimi_artifact
+
+        with patch("timmy.kimi_delegation.asyncio.to_thread", new_callable=AsyncMock) as mock_thread:
+            mock_thread.side_effect = Exception("DB error")
+            result = await index_kimi_artifact(42, "title", "some content")
+
+        assert result["success"] is False
+        assert result["error"] != ""
+
+
+# ---------------------------------------------------------------------------
+# extract_and_create_followups (async)
+# ---------------------------------------------------------------------------
+
+
+class TestExtractAndCreateFollowups:
+    @pytest.mark.asyncio
+    async def test_no_action_items_returns_empty_created(self):
+        from timmy.kimi_delegation import extract_and_create_followups
+
+        result = await extract_and_create_followups("Plain prose, nothing to do.", 1)
+        assert result["success"] is True
+        assert result["created"] == []
+
+    @pytest.mark.asyncio
+    async def test_gitea_not_configured_returns_error(self):
+        from timmy.kimi_delegation import extract_and_create_followups
+
+        text = "1. Do something important\n"
+
+        with patch("timmy.kimi_delegation.settings") as mock_settings:
+            mock_settings.gitea_enabled = False
+            mock_settings.gitea_token = ""
+            result = await extract_and_create_followups(text, 5)
+
+        assert result["success"] is False
+
+    @pytest.mark.asyncio
+    async def test_creates_followup_issues(self):
+        from timmy.kimi_delegation import extract_and_create_followups
+
+        text = "1. Deploy the service\n2. Run integration tests\n"
+
+        mock_settings = MagicMock()
+        mock_settings.gitea_enabled = True
+        mock_settings.gitea_token = "tok"
+        mock_settings.gitea_url = "http://git"
+        mock_settings.gitea_repo = "owner/repo"
+
+        issue_resp = MagicMock()
+        issue_resp.status_code = 201
+        issue_resp.json.return_value = {"number": 10}
+
+        async_client = AsyncMock()
+        async_client.post = AsyncMock(return_value=issue_resp)
+        async_client.__aenter__ = AsyncMock(return_value=async_client)
+        async_client.__aexit__ = AsyncMock(return_value=False)
+
+        with (
+            patch("timmy.kimi_delegation.settings", mock_settings),
+            patch("timmy.kimi_delegation.httpx") as mock_httpx,
+        ):
+            mock_httpx.AsyncClient.return_value = async_client
+            result = await extract_and_create_followups(text, 5)
+
+        assert result["success"] is True
+        assert len(result["created"]) == 2
+
+
+# ---------------------------------------------------------------------------
+# delegate_research_to_kimi (async)
+# ---------------------------------------------------------------------------
+
+
+class TestDelegateResearchToKimi:
+    @pytest.mark.asyncio
+    async def test_empty_task_returns_error(self):
+        from timmy.kimi_delegation import delegate_research_to_kimi
+
+        result = await delegate_research_to_kimi("", "ctx", "q?")
+        assert result["success"] is False
+        assert "required" in result["error"]
+
+    @pytest.mark.asyncio
+    async def test_whitespace_task_returns_error(self):
+        from timmy.kimi_delegation import delegate_research_to_kimi
+
+        result = await delegate_research_to_kimi("   ", "ctx", "q?")
+        assert result["success"] is False
+        assert "required" in result["error"]
+
+    @pytest.mark.asyncio
+    async def test_empty_question_returns_error(self):
+        from timmy.kimi_delegation import delegate_research_to_kimi
+
+        result = await delegate_research_to_kimi("valid task", "ctx", "")
+        assert result["success"] is False
+        assert "required" in result["error"]
+
+    @pytest.mark.asyncio
+    async def test_delegates_to_create_issue(self):
+        from timmy.kimi_delegation import delegate_research_to_kimi
+
+        with patch(
+            "timmy.kimi_delegation.create_kimi_research_issue",
+            new_callable=AsyncMock,
+        ) as mock_create:
+            mock_create.return_value = {"success": True, "issue_number": 7, "issue_url": "http://x", "error": None}
+            result = await delegate_research_to_kimi("Research X", "ctx", "What is X?", priority="high")
+
+        assert result["success"] is True
+        assert result["issue_number"] == 7
+        mock_create.assert_awaited_once_with("Research X", "ctx", "What is X?", "high")
--- a/tests/timmy/test_quest_system.py
+++ b/tests/timmy/test_quest_system.py
@@ -0,0 +1,838 @@
+"""Unit tests for timmy.quest_system."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from typing import Any
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+import timmy.quest_system as qs
+from timmy.quest_system import (
+    QuestDefinition,
+    QuestProgress,
+    QuestStatus,
+    QuestType,
+    _get_progress_key,
+    _get_target_value,
+    _is_on_cooldown,
+    check_daily_run_quest,
+    check_issue_count_quest,
+    check_issue_reduce_quest,
+    claim_quest_reward,
+    evaluate_quest_progress,
+    get_active_quests,
+    get_agent_quests_status,
+    get_or_create_progress,
+    get_quest_definition,
+    get_quest_definitions,
+    get_quest_leaderboard,
+    get_quest_progress,
+    load_quest_config,
+    reset_quest_progress,
+    update_quest_progress,
+)
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _make_quest(
+    quest_id: str = "test_quest",
+    quest_type: QuestType = QuestType.ISSUE_COUNT,
+    reward_tokens: int = 10,
+    enabled: bool = True,
+    repeatable: bool = False,
+    cooldown_hours: int = 0,
+    criteria: dict[str, Any] | None = None,
+) -> QuestDefinition:
+    return QuestDefinition(
+        id=quest_id,
+        name=f"Quest {quest_id}",
+        description="Test quest",
+        reward_tokens=reward_tokens,
+        quest_type=quest_type,
+        enabled=enabled,
+        repeatable=repeatable,
+        cooldown_hours=cooldown_hours,
+        criteria=criteria or {"target_count": 3},
+        notification_message="Quest Complete! You earned {tokens} tokens.",
+    )
+
+
+@pytest.fixture(autouse=True)
+def clean_state():
+    """Reset module-level state before and after each test."""
+    reset_quest_progress()
+    qs._quest_definitions.clear()
+    qs._quest_settings.clear()
+    yield
+    reset_quest_progress()
+    qs._quest_definitions.clear()
+    qs._quest_settings.clear()
+
+
+# ---------------------------------------------------------------------------
+# QuestDefinition
+# ---------------------------------------------------------------------------
+
+class TestQuestDefinition:
+    def test_from_dict_minimal(self):
+        data = {"id": "q1"}
+        defn = QuestDefinition.from_dict(data)
+        assert defn.id == "q1"
+        assert defn.name == "Unnamed Quest"
+        assert defn.reward_tokens == 0
+        assert defn.quest_type == QuestType.CUSTOM
+        assert defn.enabled is True
+        assert defn.repeatable is False
+        assert defn.cooldown_hours == 0
+
+    def test_from_dict_full(self):
+        data = {
+            "id": "q2",
+            "name": "Full Quest",
+            "description": "A full quest",
+            "reward_tokens": 50,
+            "type": "issue_count",
+            "enabled": False,
+            "repeatable": True,
+            "cooldown_hours": 24,
+            "criteria": {"target_count": 5},
+            "notification_message": "You earned {tokens}!",
+        }
+        defn = QuestDefinition.from_dict(data)
+        assert defn.id == "q2"
+        assert defn.name == "Full Quest"
+        assert defn.reward_tokens == 50
+        assert defn.quest_type == QuestType.ISSUE_COUNT
+        assert defn.enabled is False
+        assert defn.repeatable is True
+        assert defn.cooldown_hours == 24
+        assert defn.criteria == {"target_count": 5}
+        assert defn.notification_message == "You earned {tokens}!"
+
+    def test_from_dict_invalid_type_raises(self):
+        data = {"id": "q3", "type": "not_a_real_type"}
+        with pytest.raises(ValueError):
+            QuestDefinition.from_dict(data)
+
+
+# ---------------------------------------------------------------------------
+# QuestProgress
+# ---------------------------------------------------------------------------
+
+class TestQuestProgress:
+    def test_to_dict_roundtrip(self):
+        progress = QuestProgress(
+            quest_id="q1",
+            agent_id="agent_a",
+            status=QuestStatus.IN_PROGRESS,
+            current_value=2,
+            target_value=5,
+            started_at="2026-01-01T00:00:00",
+            metadata={"key": "val"},
+        )
+        d = progress.to_dict()
+        assert d["quest_id"] == "q1"
+        assert d["agent_id"] == "agent_a"
+        assert d["status"] == "in_progress"
+        assert d["current_value"] == 2
+        assert d["target_value"] == 5
+        assert d["metadata"] == {"key": "val"}
+
+    def test_to_dict_defaults(self):
+        progress = QuestProgress(
+            quest_id="q1",
+            agent_id="agent_a",
+            status=QuestStatus.NOT_STARTED,
+        )
+        d = progress.to_dict()
+        assert d["completion_count"] == 0
+        assert d["started_at"] == ""
+        assert d["completed_at"] == ""
+
+
+# ---------------------------------------------------------------------------
+# _get_progress_key
+# ---------------------------------------------------------------------------
+
+def test_get_progress_key():
+    assert _get_progress_key("q1", "agent_a") == "agent_a:q1"
+
+
+def test_get_progress_key_different_agents():
+    key_a = _get_progress_key("q1", "agent_a")
+    key_b = _get_progress_key("q1", "agent_b")
+    assert key_a != key_b
+
+
+# ---------------------------------------------------------------------------
+# load_quest_config
+# ---------------------------------------------------------------------------
+
+class TestLoadQuestConfig:
+    def test_missing_file_returns_empty(self, tmp_path):
+        missing = tmp_path / "nonexistent.yaml"
+        with patch.object(qs, "QUEST_CONFIG_PATH", missing):
+            defs, settings = load_quest_config()
+        assert defs == {}
+        assert settings == {}
+
+    def test_valid_yaml_loads_quests(self, tmp_path):
+        config_path = tmp_path / "quests.yaml"
+        config_path.write_text(
+            """
+quests:
+  first_quest:
+    name: First Quest
+    description: Do stuff
+    reward_tokens: 25
+    type: issue_count
+    enabled: true
+    repeatable: false
+    cooldown_hours: 0
+    criteria:
+      target_count: 3
+    notification_message: "Done! {tokens} tokens"
+settings:
+  some_setting: true
+"""
+        )
+        with patch.object(qs, "QUEST_CONFIG_PATH", config_path):
+            defs, settings = load_quest_config()
+
+        assert "first_quest" in defs
+        assert defs["first_quest"].name == "First Quest"
+        assert defs["first_quest"].reward_tokens == 25
+        assert settings == {"some_setting": True}
+
+    def test_invalid_yaml_returns_empty(self, tmp_path):
+        config_path = tmp_path / "quests.yaml"
+        config_path.write_text(":: not valid yaml ::")
+        with patch.object(qs, "QUEST_CONFIG_PATH", config_path):
+            defs, settings = load_quest_config()
+        assert defs == {}
+        assert settings == {}
+
+    def test_non_dict_yaml_returns_empty(self, tmp_path):
+        config_path = tmp_path / "quests.yaml"
+        config_path.write_text("- item1\n- item2\n")
+        with patch.object(qs, "QUEST_CONFIG_PATH", config_path):
+            defs, settings = load_quest_config()
+        assert defs == {}
+        assert settings == {}
+
+    def test_bad_quest_entry_is_skipped(self, tmp_path):
+        config_path = tmp_path / "quests.yaml"
+        config_path.write_text(
+            """
+quests:
+  good_quest:
+    name: Good
+    type: issue_count
+    reward_tokens: 10
+    enabled: true
+    repeatable: false
+    cooldown_hours: 0
+    criteria: {}
+    notification_message: "{tokens}"
+  bad_quest:
+    type: invalid_type_that_does_not_exist
+"""
+        )
+        with patch.object(qs, "QUEST_CONFIG_PATH", config_path):
+            defs, _ = load_quest_config()
+        assert "good_quest" in defs
+        assert "bad_quest" not in defs
+
+
+# ---------------------------------------------------------------------------
+# get_quest_definitions / get_quest_definition / get_active_quests
+# ---------------------------------------------------------------------------
+
+class TestQuestLookup:
+    def setup_method(self):
+        q1 = _make_quest("q1", enabled=True)
+        q2 = _make_quest("q2", enabled=False)
+        qs._quest_definitions.update({"q1": q1, "q2": q2})
+
+    def test_get_quest_definitions_returns_all(self):
+        defs = get_quest_definitions()
+        assert "q1" in defs
+        assert "q2" in defs
+
+    def test_get_quest_definition_found(self):
+        defn = get_quest_definition("q1")
+        assert defn is not None
+        assert defn.id == "q1"
+
+    def test_get_quest_definition_not_found(self):
+        assert get_quest_definition("missing") is None
+
+    def test_get_active_quests_only_enabled(self):
+        active = get_active_quests()
+        ids = [q.id for q in active]
+        assert "q1" in ids
+        assert "q2" not in ids
+
+
+# ---------------------------------------------------------------------------
+# _get_target_value
+# ---------------------------------------------------------------------------
+
+class TestGetTargetValue:
+    def test_issue_count(self):
+        q = _make_quest(quest_type=QuestType.ISSUE_COUNT, criteria={"target_count": 7})
+        assert _get_target_value(q) == 7
+
+    def test_issue_reduce(self):
+        q = _make_quest(quest_type=QuestType.ISSUE_REDUCE, criteria={"target_reduction": 5})
+        assert _get_target_value(q) == 5
+
+    def test_daily_run(self):
+        q = _make_quest(quest_type=QuestType.DAILY_RUN, criteria={"min_sessions": 3})
+        assert _get_target_value(q) == 3
+
+    def test_docs_update(self):
+        q = _make_quest(quest_type=QuestType.DOCS_UPDATE, criteria={"min_files_changed": 2})
+        assert _get_target_value(q) == 2
+
+    def test_test_improve(self):
+        q = _make_quest(quest_type=QuestType.TEST_IMPROVE, criteria={"min_new_tests": 4})
+        assert _get_target_value(q) == 4
+
+    def test_custom_defaults_to_one(self):
+        q = _make_quest(quest_type=QuestType.CUSTOM, criteria={})
+        assert _get_target_value(q) == 1
+
+    def test_missing_criteria_key_defaults_to_one(self):
+        q = _make_quest(quest_type=QuestType.ISSUE_COUNT, criteria={})
+        assert _get_target_value(q) == 1
+
+
+# ---------------------------------------------------------------------------
+# get_or_create_progress / get_quest_progress
+# ---------------------------------------------------------------------------
+
+class TestProgressCreation:
+    def setup_method(self):
+        qs._quest_definitions["q1"] = _make_quest("q1", criteria={"target_count": 5})
+
+    def test_creates_new_progress(self):
+        progress = get_or_create_progress("q1", "agent_a")
+        assert progress.quest_id == "q1"
+        assert progress.agent_id == "agent_a"
+        assert progress.status == QuestStatus.NOT_STARTED
+        assert progress.target_value == 5
+        assert progress.current_value == 0
+
+    def test_returns_existing_progress(self):
+        p1 = get_or_create_progress("q1", "agent_a")
+        p1.current_value = 3
+        p2 = get_or_create_progress("q1", "agent_a")
+        assert p2.current_value == 3
+        assert p1 is p2
+
+    def test_raises_for_unknown_quest(self):
+        with pytest.raises(ValueError, match="Quest unknown not found"):
+            get_or_create_progress("unknown", "agent_a")
+
+    def test_get_quest_progress_none_before_creation(self):
+        assert get_quest_progress("q1", "agent_a") is None
+
+    def test_get_quest_progress_after_creation(self):
+        get_or_create_progress("q1", "agent_a")
+        progress = get_quest_progress("q1", "agent_a")
+        assert progress is not None
+
+
+# ---------------------------------------------------------------------------
+# update_quest_progress
+# ---------------------------------------------------------------------------
+
+class TestUpdateQuestProgress:
+    def setup_method(self):
+        qs._quest_definitions["q1"] = _make_quest("q1", criteria={"target_count": 3})
+
+    def test_updates_current_value(self):
+        progress = update_quest_progress("q1", "agent_a", 2)
+        assert progress.current_value == 2
+        assert progress.status == QuestStatus.NOT_STARTED
+
+    def test_marks_completed_when_target_reached(self):
+        progress = update_quest_progress("q1", "agent_a", 3)
+        assert progress.status == QuestStatus.COMPLETED
+        assert progress.completed_at != ""
+
+    def test_marks_completed_when_value_exceeds_target(self):
+        progress = update_quest_progress("q1", "agent_a", 10)
+        assert progress.status == QuestStatus.COMPLETED
+
+    def test_does_not_re_complete_already_completed(self):
+        p = update_quest_progress("q1", "agent_a", 3)
+        first_completed_at = p.completed_at
+        p2 = update_quest_progress("q1", "agent_a", 5)
+        # should not change completed_at again
+        assert p2.completed_at == first_completed_at
+
+    def test_does_not_re_complete_claimed_quest(self):
+        p = update_quest_progress("q1", "agent_a", 3)
+        p.status = QuestStatus.CLAIMED
+        p2 = update_quest_progress("q1", "agent_a", 5)
+        assert p2.status == QuestStatus.CLAIMED
+
+    def test_updates_metadata(self):
+        progress = update_quest_progress("q1", "agent_a", 1, metadata={"info": "value"})
+        assert progress.metadata["info"] == "value"
+
+    def test_merges_metadata(self):
+        update_quest_progress("q1", "agent_a", 1, metadata={"a": 1})
+        progress = update_quest_progress("q1", "agent_a", 2, metadata={"b": 2})
+        assert progress.metadata["a"] == 1
+        assert progress.metadata["b"] == 2
+
+
+# ---------------------------------------------------------------------------
+# _is_on_cooldown
+# ---------------------------------------------------------------------------
+
+class TestIsOnCooldown:
+    def test_non_repeatable_never_on_cooldown(self):
+        quest = _make_quest(repeatable=False, cooldown_hours=24)
+        progress = QuestProgress(
+            quest_id="q1",
+            agent_id="agent_a",
+            status=QuestStatus.CLAIMED,
+            last_completed_at=datetime.now(UTC).isoformat(),
+        )
+        assert _is_on_cooldown(progress, quest) is False
+
+    def test_no_last_completed_not_on_cooldown(self):
+        quest = _make_quest(repeatable=True, cooldown_hours=24)
+        progress = QuestProgress(
+            quest_id="q1",
+            agent_id="agent_a",
+            status=QuestStatus.NOT_STARTED,
+            last_completed_at="",
+        )
+        assert _is_on_cooldown(progress, quest) is False
+
+    def test_zero_cooldown_not_on_cooldown(self):
+        quest = _make_quest(repeatable=True, cooldown_hours=0)
+        progress = QuestProgress(
+            quest_id="q1",
+            agent_id="agent_a",
+            status=QuestStatus.CLAIMED,
+            last_completed_at=datetime.now(UTC).isoformat(),
+        )
+        assert _is_on_cooldown(progress, quest) is False
+
+    def test_recent_completion_is_on_cooldown(self):
+        quest = _make_quest(repeatable=True, cooldown_hours=24)
+        recent = datetime.now(UTC) - timedelta(hours=1)
+        progress = QuestProgress(
+            quest_id="q1",
+            agent_id="agent_a",
+            status=QuestStatus.NOT_STARTED,
+            last_completed_at=recent.isoformat(),
+        )
+        assert _is_on_cooldown(progress, quest) is True
+
+    def test_expired_cooldown_not_on_cooldown(self):
+        quest = _make_quest(repeatable=True, cooldown_hours=24)
+        old = datetime.now(UTC) - timedelta(hours=25)
+        progress = QuestProgress(
+            quest_id="q1",
+            agent_id="agent_a",
+            status=QuestStatus.NOT_STARTED,
+            last_completed_at=old.isoformat(),
+        )
+        assert _is_on_cooldown(progress, quest) is False
+
+    def test_invalid_last_completed_returns_false(self):
+        quest = _make_quest(repeatable=True, cooldown_hours=24)
+        progress = QuestProgress(
+            quest_id="q1",
+            agent_id="agent_a",
+            status=QuestStatus.NOT_STARTED,
+            last_completed_at="not-a-date",
+        )
+        assert _is_on_cooldown(progress, quest) is False
+
+
+# ---------------------------------------------------------------------------
+# claim_quest_reward
+# ---------------------------------------------------------------------------
+
+class TestClaimQuestReward:
+    def setup_method(self):
+        qs._quest_definitions["q1"] = _make_quest("q1", reward_tokens=25)
+
+    def test_returns_none_if_no_progress(self):
+        assert claim_quest_reward("q1", "agent_a") is None
+
+    def test_returns_none_if_not_completed(self):
+        get_or_create_progress("q1", "agent_a")
+        assert claim_quest_reward("q1", "agent_a") is None
+
+    def test_returns_none_if_quest_not_found(self):
+        assert claim_quest_reward("nonexistent", "agent_a") is None
+
+    def test_successful_claim(self):
+        progress = get_or_create_progress("q1", "agent_a")
+        progress.status = QuestStatus.COMPLETED
+        progress.completed_at = datetime.now(UTC).isoformat()
+
+        mock_invoice = MagicMock()
+        mock_invoice.payment_hash = "quest_q1_agent_a_123"
+
+        with (
+            patch("timmy.quest_system.create_invoice_entry", return_value=mock_invoice),
+            patch("timmy.quest_system.mark_settled"),
+        ):
+            result = claim_quest_reward("q1", "agent_a")
+
+        assert result is not None
+        assert result["tokens_awarded"] == 25
+        assert result["quest_id"] == "q1"
+        assert result["agent_id"] == "agent_a"
+        assert result["completion_count"] == 1
+
+    def test_successful_claim_marks_claimed(self):
+        progress = get_or_create_progress("q1", "agent_a")
+        progress.status = QuestStatus.COMPLETED
+        progress.completed_at = datetime.now(UTC).isoformat()
+
+        mock_invoice = MagicMock()
+        mock_invoice.payment_hash = "phash"
+
+        with (
+            patch("timmy.quest_system.create_invoice_entry", return_value=mock_invoice),
+            patch("timmy.quest_system.mark_settled"),
+        ):
+            claim_quest_reward("q1", "agent_a")
+
+        assert progress.status == QuestStatus.CLAIMED
+
+    def test_repeatable_quest_resets_after_claim(self):
+        qs._quest_definitions["rep"] = _make_quest(
+            "rep", repeatable=True, cooldown_hours=0, reward_tokens=10
+        )
+        progress = get_or_create_progress("rep", "agent_a")
+        progress.status = QuestStatus.COMPLETED
+        progress.completed_at = datetime.now(UTC).isoformat()
+        progress.current_value = 5
+
+        mock_invoice = MagicMock()
+        mock_invoice.payment_hash = "phash"
+
+        with (
+            patch("timmy.quest_system.create_invoice_entry", return_value=mock_invoice),
+            patch("timmy.quest_system.mark_settled"),
+        ):
+            result = claim_quest_reward("rep", "agent_a")
+
+        assert result is not None
+        assert progress.status == QuestStatus.NOT_STARTED
+        assert progress.current_value == 0
+        assert progress.completed_at == ""
+
+    def test_on_cooldown_returns_none(self):
+        qs._quest_definitions["rep"] = _make_quest("rep", repeatable=True, cooldown_hours=24)
+        progress = get_or_create_progress("rep", "agent_a")
+        progress.status = QuestStatus.COMPLETED
+        recent = datetime.now(UTC) - timedelta(hours=1)
+        progress.last_completed_at = recent.isoformat()
+
+        assert claim_quest_reward("rep", "agent_a") is None
+
+    def test_ledger_error_returns_none(self):
+        progress = get_or_create_progress("q1", "agent_a")
+        progress.status = QuestStatus.COMPLETED
+        progress.completed_at = datetime.now(UTC).isoformat()
+
+        with patch("timmy.quest_system.create_invoice_entry", side_effect=Exception("ledger error")):
+            result = claim_quest_reward("q1", "agent_a")
+
+        assert result is None
+
+
+# ---------------------------------------------------------------------------
+# check_issue_count_quest
+# ---------------------------------------------------------------------------
+
+class TestCheckIssueCountQuest:
+    def setup_method(self):
+        qs._quest_definitions["iq"] = _make_quest(
+            "iq", quest_type=QuestType.ISSUE_COUNT, criteria={"target_count": 2, "issue_labels": ["bug"]}
+        )
+
+    def test_counts_matching_issues(self):
+        issues = [
+            {"labels": [{"name": "bug"}]},
+            {"labels": [{"name": "bug"}, {"name": "priority"}]},
+            {"labels": [{"name": "feature"}]},  # doesn't match
+        ]
+        progress = check_issue_count_quest(
+            qs._quest_definitions["iq"], "agent_a", issues
+        )
+        assert progress.current_value == 2
+        assert progress.status == QuestStatus.COMPLETED
+
+    def test_empty_issues_returns_zero(self):
+        progress = check_issue_count_quest(qs._quest_definitions["iq"], "agent_a", [])
+        assert progress.current_value == 0
+
+    def test_no_labels_filter_counts_all_labeled(self):
+        q = _make_quest(
+            "nolabel",
+            quest_type=QuestType.ISSUE_COUNT,
+            criteria={"target_count": 1, "issue_labels": []},
+        )
+        qs._quest_definitions["nolabel"] = q
+        issues = [
+            {"labels": [{"name": "bug"}]},
+            {"labels": [{"name": "feature"}]},
+        ]
+        progress = check_issue_count_quest(q, "agent_a", issues)
+        assert progress.current_value == 2
+
+
+# ---------------------------------------------------------------------------
+# check_issue_reduce_quest
+# ---------------------------------------------------------------------------
+
+class TestCheckIssueReduceQuest:
+    def setup_method(self):
+        qs._quest_definitions["ir"] = _make_quest(
+            "ir", quest_type=QuestType.ISSUE_REDUCE, criteria={"target_reduction": 5}
+        )
+
+    def test_computes_reduction(self):
+        progress = check_issue_reduce_quest(qs._quest_definitions["ir"], "agent_a", 20, 15)
+        assert progress.current_value == 5
+        assert progress.status == QuestStatus.COMPLETED
+
+    def test_negative_reduction_treated_as_zero(self):
+        progress = check_issue_reduce_quest(qs._quest_definitions["ir"], "agent_a", 10, 15)
+        assert progress.current_value == 0
+
+    def test_no_change_yields_zero(self):
+        progress = check_issue_reduce_quest(qs._quest_definitions["ir"], "agent_a", 10, 10)
+        assert progress.current_value == 0
+
+
+# ---------------------------------------------------------------------------
+# check_daily_run_quest
+# ---------------------------------------------------------------------------
+
+class TestCheckDailyRunQuest:
+    def setup_method(self):
+        qs._quest_definitions["dr"] = _make_quest(
+            "dr", quest_type=QuestType.DAILY_RUN, criteria={"min_sessions": 2}
+        )
+
+    def test_tracks_sessions(self):
+        progress = check_daily_run_quest(qs._quest_definitions["dr"], "agent_a", 2)
+        assert progress.current_value == 2
+        assert progress.status == QuestStatus.COMPLETED
+
+    def test_incomplete_sessions(self):
+        progress = check_daily_run_quest(qs._quest_definitions["dr"], "agent_a", 1)
+        assert progress.current_value == 1
+        assert progress.status != QuestStatus.COMPLETED
+
+
+# ---------------------------------------------------------------------------
+# evaluate_quest_progress
+# ---------------------------------------------------------------------------
+
+class TestEvaluateQuestProgress:
+    def setup_method(self):
+        qs._quest_definitions["iq"] = _make_quest(
+            "iq", quest_type=QuestType.ISSUE_COUNT, criteria={"target_count": 1}
+        )
+        qs._quest_definitions["dis"] = _make_quest("dis", enabled=False)
+
+    def test_disabled_quest_returns_none(self):
+        result = evaluate_quest_progress("dis", "agent_a", {})
+        assert result is None
+
+    def test_missing_quest_returns_none(self):
+        result = evaluate_quest_progress("nonexistent", "agent_a", {})
+        assert result is None
+
+    def test_issue_count_quest_evaluated(self):
+        context = {"closed_issues": [{"labels": [{"name": "bug"}]}]}
+        result = evaluate_quest_progress("iq", "agent_a", context)
+        assert result is not None
+        assert result.current_value == 1
+
+    def test_issue_reduce_quest_evaluated(self):
+        qs._quest_definitions["ir"] = _make_quest(
+            "ir", quest_type=QuestType.ISSUE_REDUCE, criteria={"target_reduction": 3}
+        )
+        context = {"previous_issue_count": 10, "current_issue_count": 7}
+        result = evaluate_quest_progress("ir", "agent_a", context)
+        assert result is not None
+        assert result.current_value == 3
+
+    def test_daily_run_quest_evaluated(self):
+        qs._quest_definitions["dr"] = _make_quest(
+            "dr", quest_type=QuestType.DAILY_RUN, criteria={"min_sessions": 1}
+        )
+        context = {"sessions_completed": 2}
+        result = evaluate_quest_progress("dr", "agent_a", context)
+        assert result is not None
+        assert result.current_value == 2
+
+    def test_custom_quest_returns_existing_progress(self):
+        qs._quest_definitions["cust"] = _make_quest("cust", quest_type=QuestType.CUSTOM)
+        # No progress yet => None (custom quests don't auto-create progress here)
+        result = evaluate_quest_progress("cust", "agent_a", {})
+        assert result is None
+
+    def test_cooldown_prevents_evaluation(self):
+        q = _make_quest("rep_iq", quest_type=QuestType.ISSUE_COUNT, repeatable=True, cooldown_hours=24, criteria={"target_count": 1})
+        qs._quest_definitions["rep_iq"] = q
+        progress = get_or_create_progress("rep_iq", "agent_a")
+        recent = datetime.now(UTC) - timedelta(hours=1)
+        progress.last_completed_at = recent.isoformat()
+
+        context = {"closed_issues": [{"labels": [{"name": "bug"}]}]}
+        result = evaluate_quest_progress("rep_iq", "agent_a", context)
+        # Should return existing progress without updating
+        assert result is progress
+
+
+# ---------------------------------------------------------------------------
+# reset_quest_progress
+# ---------------------------------------------------------------------------
+
+class TestResetQuestProgress:
+    def setup_method(self):
+        qs._quest_definitions["q1"] = _make_quest("q1")
+        qs._quest_definitions["q2"] = _make_quest("q2")
+
+    def test_reset_all(self):
+        get_or_create_progress("q1", "agent_a")
+        get_or_create_progress("q2", "agent_a")
+        count = reset_quest_progress()
+        assert count == 2
+        assert get_quest_progress("q1", "agent_a") is None
+        assert get_quest_progress("q2", "agent_a") is None
+
+    def test_reset_specific_quest(self):
+        get_or_create_progress("q1", "agent_a")
+        get_or_create_progress("q2", "agent_a")
+        count = reset_quest_progress(quest_id="q1")
+        assert count == 1
+        assert get_quest_progress("q1", "agent_a") is None
+        assert get_quest_progress("q2", "agent_a") is not None
+
+    def test_reset_specific_agent(self):
+        get_or_create_progress("q1", "agent_a")
+        get_or_create_progress("q1", "agent_b")
+        count = reset_quest_progress(agent_id="agent_a")
+        assert count == 1
+        assert get_quest_progress("q1", "agent_a") is None
+        assert get_quest_progress("q1", "agent_b") is not None
+
+    def test_reset_specific_quest_and_agent(self):
+        get_or_create_progress("q1", "agent_a")
+        get_or_create_progress("q1", "agent_b")
+        count = reset_quest_progress(quest_id="q1", agent_id="agent_a")
+        assert count == 1
+
+    def test_reset_empty_returns_zero(self):
+        count = reset_quest_progress()
+        assert count == 0
+
+
+# ---------------------------------------------------------------------------
+# get_quest_leaderboard
+# ---------------------------------------------------------------------------
+
+class TestGetQuestLeaderboard:
+    def setup_method(self):
+        qs._quest_definitions["q1"] = _make_quest("q1", reward_tokens=10)
+        qs._quest_definitions["q2"] = _make_quest("q2", reward_tokens=20)
+
+    def test_empty_progress_returns_empty(self):
+        assert get_quest_leaderboard() == []
+
+    def test_leaderboard_sorted_by_tokens(self):
+        p_a = get_or_create_progress("q1", "agent_a")
+        p_a.completion_count = 1
+        p_b = get_or_create_progress("q2", "agent_b")
+        p_b.completion_count = 2
+
+        board = get_quest_leaderboard()
+        assert board[0]["agent_id"] == "agent_b"  # 40 tokens
+        assert board[1]["agent_id"] == "agent_a"  # 10 tokens
+
+    def test_leaderboard_aggregates_multiple_quests(self):
+        p1 = get_or_create_progress("q1", "agent_a")
+        p1.completion_count = 2  # 20 tokens
+        p2 = get_or_create_progress("q2", "agent_a")
+        p2.completion_count = 1  # 20 tokens
+
+        board = get_quest_leaderboard()
+        assert len(board) == 1
+        assert board[0]["total_tokens"] == 40
+        assert board[0]["total_completions"] == 3
+
+    def test_leaderboard_counts_unique_quests(self):
+        p1 = get_or_create_progress("q1", "agent_a")
+        p1.completion_count = 2
+        p2 = get_or_create_progress("q2", "agent_a")
+        p2.completion_count = 1
+
+        board = get_quest_leaderboard()
+        assert board[0]["unique_quests_completed"] == 2
+
+
+# ---------------------------------------------------------------------------
+# get_agent_quests_status
+# ---------------------------------------------------------------------------
+
+class TestGetAgentQuestsStatus:
+    def setup_method(self):
+        qs._quest_definitions["q1"] = _make_quest("q1", reward_tokens=10)
+
+    def test_returns_status_structure(self):
+        result = get_agent_quests_status("agent_a")
+        assert result["agent_id"] == "agent_a"
+        assert isinstance(result["quests"], list)
+        assert "total_tokens_earned" in result
+        assert "total_quests_completed" in result
+        assert "active_quests_count" in result
+
+    def test_includes_quest_info(self):
+        result = get_agent_quests_status("agent_a")
+        quest_info = result["quests"][0]
+        assert quest_info["quest_id"] == "q1"
+        assert quest_info["reward_tokens"] == 10
+        assert quest_info["status"] == QuestStatus.NOT_STARTED.value
+
+    def test_accumulates_tokens_from_completions(self):
+        p = get_or_create_progress("q1", "agent_a")
+        p.completion_count = 3
+        result = get_agent_quests_status("agent_a")
+        assert result["total_tokens_earned"] == 30
+        assert result["total_quests_completed"] == 3
+
+    def test_cooldown_hours_remaining_calculated(self):
+        q = _make_quest("qcool", repeatable=True, cooldown_hours=24, reward_tokens=5)
+        qs._quest_definitions["qcool"] = q
+        p = get_or_create_progress("qcool", "agent_a")
+        recent = datetime.now(UTC) - timedelta(hours=2)
+        p.last_completed_at = recent.isoformat()
+        p.completion_count = 1
+
+        result = get_agent_quests_status("agent_a")
+        qcool_info = next(qi for qi in result["quests"] if qi["quest_id"] == "qcool")
+        assert qcool_info["on_cooldown"] is True
+        assert qcool_info["cooldown_hours_remaining"] > 0
--- a/tests/timmy/test_research.py
+++ b/tests/timmy/test_research.py
@@ -0,0 +1,403 @@
+"""Unit tests for src/timmy/research.py — ResearchOrchestrator pipeline.
+
+Refs #972 (governing spec), #975 (ResearchOrchestrator).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+pytestmark = pytest.mark.unit
+
+
+# ---------------------------------------------------------------------------
+# list_templates
+# ---------------------------------------------------------------------------
+
+
+class TestListTemplates:
+    def test_returns_list(self, tmp_path, monkeypatch):
+        (tmp_path / "tool_evaluation.md").write_text("---\n---\n# T")
+        (tmp_path / "game_analysis.md").write_text("---\n---\n# G")
+        monkeypatch.setattr("timmy.research._SKILLS_ROOT", tmp_path)
+
+        from timmy.research import list_templates
+
+        result = list_templates()
+        assert isinstance(result, list)
+        assert "tool_evaluation" in result
+        assert "game_analysis" in result
+
+    def test_returns_empty_when_dir_missing(self, tmp_path, monkeypatch):
+        monkeypatch.setattr("timmy.research._SKILLS_ROOT", tmp_path / "nonexistent")
+
+        from timmy.research import list_templates
+
+        assert list_templates() == []
+
+
+# ---------------------------------------------------------------------------
+# load_template
+# ---------------------------------------------------------------------------
+
+
+class TestLoadTemplate:
+    def _write_template(self, path: Path, name: str, body: str) -> None:
+        (path / f"{name}.md").write_text(body, encoding="utf-8")
+
+    def test_loads_and_strips_frontmatter(self, tmp_path, monkeypatch):
+        self._write_template(
+            tmp_path,
+            "tool_evaluation",
+            "---\nname: Tool Evaluation\ntype: research\n---\n# Tool Eval: {domain}",
+        )
+        monkeypatch.setattr("timmy.research._SKILLS_ROOT", tmp_path)
+
+        from timmy.research import load_template
+
+        result = load_template("tool_evaluation", {"domain": "PDF parsing"})
+        assert "# Tool Eval: PDF parsing" in result
+        assert "name: Tool Evaluation" not in result
+
+    def test_fills_slots(self, tmp_path, monkeypatch):
+        self._write_template(tmp_path, "arch", "Connect {system_a} to {system_b}")
+        monkeypatch.setattr("timmy.research._SKILLS_ROOT", tmp_path)
+
+        from timmy.research import load_template
+
+        result = load_template("arch", {"system_a": "Kafka", "system_b": "Postgres"})
+        assert "Kafka" in result
+        assert "Postgres" in result
+
+    def test_unfilled_slots_preserved(self, tmp_path, monkeypatch):
+        self._write_template(tmp_path, "t", "Hello {name} and {other}")
+        monkeypatch.setattr("timmy.research._SKILLS_ROOT", tmp_path)
+
+        from timmy.research import load_template
+
+        result = load_template("t", {"name": "World"})
+        assert "{other}" in result
+
+    def test_raises_file_not_found_for_missing_template(self, tmp_path, monkeypatch):
+        monkeypatch.setattr("timmy.research._SKILLS_ROOT", tmp_path)
+
+        from timmy.research import load_template
+
+        with pytest.raises(FileNotFoundError, match="nonexistent"):
+            load_template("nonexistent")
+
+    def test_no_slots_returns_raw_body(self, tmp_path, monkeypatch):
+        self._write_template(tmp_path, "plain", "---\n---\nJust text here")
+        monkeypatch.setattr("timmy.research._SKILLS_ROOT", tmp_path)
+
+        from timmy.research import load_template
+
+        result = load_template("plain")
+        assert result == "Just text here"
+
+
+# ---------------------------------------------------------------------------
+# _check_cache
+# ---------------------------------------------------------------------------
+
+
+class TestCheckCache:
+    def test_returns_none_when_no_hits(self):
+        mock_mem = MagicMock()
+        mock_mem.search.return_value = []
+
+        with patch("timmy.research.SemanticMemory", return_value=mock_mem):
+            from timmy.research import _check_cache
+
+            content, score = _check_cache("some topic")
+
+        assert content is None
+        assert score == 0.0
+
+    def test_returns_content_above_threshold(self):
+        mock_mem = MagicMock()
+        mock_mem.search.return_value = [("cached report text", 0.91)]
+
+        with patch("timmy.research.SemanticMemory", return_value=mock_mem):
+            from timmy.research import _check_cache
+
+            content, score = _check_cache("same topic")
+
+        assert content == "cached report text"
+        assert score == pytest.approx(0.91)
+
+    def test_returns_none_below_threshold(self):
+        mock_mem = MagicMock()
+        mock_mem.search.return_value = [("old report", 0.60)]
+
+        with patch("timmy.research.SemanticMemory", return_value=mock_mem):
+            from timmy.research import _check_cache
+
+            content, score = _check_cache("slightly different topic")
+
+        assert content is None
+        assert score == 0.0
+
+    def test_degrades_gracefully_on_import_error(self):
+        with patch("timmy.research.SemanticMemory", None):
+            from timmy.research import _check_cache
+
+            content, score = _check_cache("topic")
+
+        assert content is None
+        assert score == 0.0
+
+
+# ---------------------------------------------------------------------------
+# _store_result
+# ---------------------------------------------------------------------------
+
+
+class TestStoreResult:
+    def test_calls_store_memory(self):
+        mock_store = MagicMock()
+
+        with patch("timmy.research.store_memory", mock_store):
+            from timmy.research import _store_result
+
+            _store_result("test topic", "# Report\n\nContent here.")
+
+        mock_store.assert_called_once()
+        call_kwargs = mock_store.call_args
+        assert "test topic" in str(call_kwargs)
+
+    def test_degrades_gracefully_on_error(self):
+        mock_store = MagicMock(side_effect=RuntimeError("db error"))
+        with patch("timmy.research.store_memory", mock_store):
+            from timmy.research import _store_result
+
+            # Should not raise
+            _store_result("topic", "report")
+
+
+# ---------------------------------------------------------------------------
+# _save_to_disk
+# ---------------------------------------------------------------------------
+
+
+class TestSaveToDisk:
+    def test_writes_file(self, tmp_path, monkeypatch):
+        monkeypatch.setattr("timmy.research._DOCS_ROOT", tmp_path / "research")
+
+        from timmy.research import _save_to_disk
+
+        path = _save_to_disk("Test Topic: PDF Parsing", "# Test Report")
+        assert path is not None
+        assert path.exists()
+        assert path.read_text() == "# Test Report"
+
+    def test_slugifies_topic_name(self, tmp_path, monkeypatch):
+        monkeypatch.setattr("timmy.research._DOCS_ROOT", tmp_path / "research")
+
+        from timmy.research import _save_to_disk
+
+        path = _save_to_disk("My Complex Topic! v2.0", "content")
+        assert path is not None
+        # Should be slugified: no special chars
+        assert " " not in path.name
+        assert "!" not in path.name
+
+    def test_returns_none_on_error(self, monkeypatch):
+        monkeypatch.setattr(
+            "timmy.research._DOCS_ROOT",
+            Path("/nonexistent_root/deeply/nested"),
+        )
+
+        with patch("pathlib.Path.mkdir", side_effect=PermissionError("denied")):
+            from timmy.research import _save_to_disk
+
+            result = _save_to_disk("topic", "report")
+
+        assert result is None
+
+
+# ---------------------------------------------------------------------------
+# run_research — end-to-end with mocks
+# ---------------------------------------------------------------------------
+
+
+class TestRunResearch:
+    @pytest.mark.asyncio
+    async def test_returns_cached_result_when_cache_hit(self):
+        cached_report = "# Cached Report\n\nPreviously computed."
+        with (
+            patch("timmy.research._check_cache", return_value=(cached_report, 0.93)),
+        ):
+            from timmy.research import run_research
+
+            result = await run_research("some topic")
+
+        assert result.cached is True
+        assert result.cache_similarity == pytest.approx(0.93)
+        assert result.report == cached_report
+        assert result.synthesis_backend == "cache"
+
+    @pytest.mark.asyncio
+    async def test_skips_cache_when_requested(self, tmp_path, monkeypatch):
+        monkeypatch.setattr("timmy.research._SKILLS_ROOT", tmp_path)
+
+        with (
+            patch("timmy.research._check_cache", return_value=("cached", 0.99)) as mock_cache,
+            patch(
+                "timmy.research._formulate_queries",
+                new=AsyncMock(return_value=["q1"]),
+            ),
+            patch("timmy.research._execute_search", new=AsyncMock(return_value=[])),
+            patch("timmy.research._fetch_pages", new=AsyncMock(return_value=[])),
+            patch(
+                "timmy.research._synthesize",
+                new=AsyncMock(return_value=("# Fresh report", "ollama")),
+            ),
+            patch("timmy.research._store_result"),
+        ):
+            from timmy.research import run_research
+
+            result = await run_research("topic", skip_cache=True)
+
+        mock_cache.assert_not_called()
+        assert result.cached is False
+        assert result.report == "# Fresh report"
+
+    @pytest.mark.asyncio
+    async def test_full_pipeline_no_search_results(self, tmp_path, monkeypatch):
+        monkeypatch.setattr("timmy.research._SKILLS_ROOT", tmp_path)
+
+        with (
+            patch("timmy.research._check_cache", return_value=(None, 0.0)),
+            patch(
+                "timmy.research._formulate_queries",
+                new=AsyncMock(return_value=["query 1", "query 2"]),
+            ),
+            patch("timmy.research._execute_search", new=AsyncMock(return_value=[])),
+            patch("timmy.research._fetch_pages", new=AsyncMock(return_value=[])),
+            patch(
+                "timmy.research._synthesize",
+                new=AsyncMock(return_value=("# Report", "ollama")),
+            ),
+            patch("timmy.research._store_result"),
+        ):
+            from timmy.research import run_research
+
+            result = await run_research("a new topic")
+
+        assert not result.cached
+        assert result.query_count == 2
+        assert result.sources_fetched == 0
+        assert result.report == "# Report"
+        assert result.synthesis_backend == "ollama"
+
+    @pytest.mark.asyncio
+    async def test_returns_result_with_error_on_bad_template(self, tmp_path, monkeypatch):
+        monkeypatch.setattr("timmy.research._SKILLS_ROOT", tmp_path)
+
+        with (
+            patch("timmy.research._check_cache", return_value=(None, 0.0)),
+            patch(
+                "timmy.research._formulate_queries",
+                new=AsyncMock(return_value=["q1"]),
+            ),
+            patch("timmy.research._execute_search", new=AsyncMock(return_value=[])),
+            patch("timmy.research._fetch_pages", new=AsyncMock(return_value=[])),
+            patch(
+                "timmy.research._synthesize",
+                new=AsyncMock(return_value=("# Report", "ollama")),
+            ),
+            patch("timmy.research._store_result"),
+        ):
+            from timmy.research import run_research
+
+            result = await run_research("topic", template="nonexistent_template")
+
+        assert len(result.errors) == 1
+        assert "nonexistent_template" in result.errors[0]
+
+    @pytest.mark.asyncio
+    async def test_saves_to_disk_when_requested(self, tmp_path, monkeypatch):
+        monkeypatch.setattr("timmy.research._SKILLS_ROOT", tmp_path)
+        monkeypatch.setattr("timmy.research._DOCS_ROOT", tmp_path / "research")
+
+        with (
+            patch("timmy.research._check_cache", return_value=(None, 0.0)),
+            patch(
+                "timmy.research._formulate_queries",
+                new=AsyncMock(return_value=["q1"]),
+            ),
+            patch("timmy.research._execute_search", new=AsyncMock(return_value=[])),
+            patch("timmy.research._fetch_pages", new=AsyncMock(return_value=[])),
+            patch(
+                "timmy.research._synthesize",
+                new=AsyncMock(return_value=("# Saved Report", "ollama")),
+            ),
+            patch("timmy.research._store_result"),
+        ):
+            from timmy.research import run_research
+
+            result = await run_research("disk topic", save_to_disk=True)
+
+        assert result.report == "# Saved Report"
+        saved_files = list((tmp_path / "research").glob("*.md"))
+        assert len(saved_files) == 1
+        assert saved_files[0].read_text() == "# Saved Report"
+
+    @pytest.mark.asyncio
+    async def test_result_is_not_empty_after_synthesis(self, tmp_path, monkeypatch):
+        monkeypatch.setattr("timmy.research._SKILLS_ROOT", tmp_path)
+
+        with (
+            patch("timmy.research._check_cache", return_value=(None, 0.0)),
+            patch(
+                "timmy.research._formulate_queries",
+                new=AsyncMock(return_value=["q"]),
+            ),
+            patch("timmy.research._execute_search", new=AsyncMock(return_value=[])),
+            patch("timmy.research._fetch_pages", new=AsyncMock(return_value=[])),
+            patch(
+                "timmy.research._synthesize",
+                new=AsyncMock(return_value=("# Non-empty", "ollama")),
+            ),
+            patch("timmy.research._store_result"),
+        ):
+            from timmy.research import run_research
+
+            result = await run_research("topic")
+
+        assert not result.is_empty()
+
+
+# ---------------------------------------------------------------------------
+# ResearchResult
+# ---------------------------------------------------------------------------
+
+
+class TestResearchResult:
+    def test_is_empty_when_no_report(self):
+        from timmy.research import ResearchResult
+
+        r = ResearchResult(topic="t", query_count=0, sources_fetched=0, report="")
+        assert r.is_empty()
+
+    def test_is_not_empty_with_content(self):
+        from timmy.research import ResearchResult
+
+        r = ResearchResult(topic="t", query_count=1, sources_fetched=1, report="# Report")
+        assert not r.is_empty()
+
+    def test_default_cached_false(self):
+        from timmy.research import ResearchResult
+
+        r = ResearchResult(topic="t", query_count=0, sources_fetched=0, report="x")
+        assert r.cached is False
+
+    def test_errors_defaults_to_empty_list(self):
+        from timmy.research import ResearchResult
+
+        r = ResearchResult(topic="t", query_count=0, sources_fetched=0, report="x")
+        assert r.errors == []
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Alexander Whitestone	d7abb7db36	chore: checkpoint local wip for issue 892	2026-04-05 13:31:06 -04:00
Alexander Whitestone	f8f5d08678	feat: Implement NIP-89 and NIP-90 for Nostr agent partnerships This commit introduces a new NostrClient for interacting with the Nostr network. The client implements the basic functionality for NIP-89 (discovery of agent capabilities) and NIP-90 (job delegation). The following changes are included: - A new class in that can connect to relays, subscribe to events, and publish events. - Implementation of (NIP-89) to discover agent capability cards. - Implementation of (NIP-90) to create and publish job requests. - Added and usage: websockets [--version \| <uri>] as dependencies. - Added tests for the . Refs #892	2026-03-23 22:07:43 -04:00
Claude (Opus 4.6)	0b4ed1b756	[claude] feat: enforce 3-issue cap on Kimi delegation (#1304 ) (#1310 ) Some checks failed Tests / lint (push) Has been cancelled Details Tests / test (push) Has been cancelled Details	2026-03-24 02:00:34 +00:00
Claude (Opus 4.6)	8304cf50da	[claude] Add unit tests for backlog_triage.py (#1293 ) (#1307 ) Some checks failed Tests / lint (push) Has been cancelled Details Tests / test (push) Has been cancelled Details	2026-03-24 01:57:44 +00:00
Claude (Opus 4.6)	16c4cc0f9f	[claude] Add unit tests for research_tools.py (#1294 ) (#1308 ) Some checks failed Tests / lint (push) Has been cancelled Details Tests / test (push) Has been cancelled Details	2026-03-24 01:57:39 +00:00
Claude (Opus 4.6)	a48f30fee4	[claude] Add unit tests for quest_system.py (#1292 ) (#1309 ) Some checks failed Tests / lint (push) Has been cancelled Details Tests / test (push) Has been cancelled Details	2026-03-24 01:57:29 +00:00
Claude (Opus 4.6)	e44db42c1a	[claude] Split thinking.py into focused sub-modules (#1279 ) (#1306 ) Some checks failed Tests / lint (push) Has been cancelled Details Tests / test (push) Has been cancelled Details	2026-03-24 01:57:04 +00:00
Claude (Opus 4.6)	de7744916c	[claude] DeerFlow evaluation research note (#1283 ) (#1305 ) Some checks failed Tests / lint (push) Has been cancelled Details Tests / test (push) Has been cancelled Details	2026-03-24 01:56:37 +00:00
Claude (Opus 4.6)	bde7232ece	[claude] Add unit tests for kimi_delegation.py (#1295 ) (#1303 ) Some checks failed Tests / lint (push) Has been cancelled Details Tests / test (push) Has been cancelled Details	2026-03-24 01:54:44 +00:00
Claude (Opus 4.6)	fc4426954e	[claude] Add module docstrings to 9 undocumented files (#1296 ) (#1302 ) Some checks failed Tests / lint (push) Has been cancelled Details Tests / test (push) Has been cancelled Details Co-authored-by: Claude (Opus 4.6) <claude@hermes.local> Co-committed-by: Claude (Opus 4.6) <claude@hermes.local>	2026-03-24 01:54:18 +00:00
Kimi Agent	5be4ecb9ef	[kimi] Add unit tests for sovereignty/perception_cache.py (#1261 ) (#1301 ) Some checks failed Tests / lint (push) Has been cancelled Details Tests / test (push) Has been cancelled Details Co-authored-by: Kimi Agent <kimi@timmy.local> Co-committed-by: Kimi Agent <kimi@timmy.local>	2026-03-24 01:53:44 +00:00
Claude (Opus 4.6)	4f80cfcd58	[claude] Three-tier model router: Local 8B / Hermes 70B / Cloud API cascade (#882 ) (#1297 ) Some checks failed Tests / lint (push) Has been cancelled Details Tests / test (push) Has been cancelled Details Co-authored-by: Claude (Opus 4.6) <claude@hermes.local> Co-committed-by: Claude (Opus 4.6) <claude@hermes.local>	2026-03-24 01:53:25 +00:00
Claude (Opus 4.6)	a7ccfbddc9	[claude] feat: SearXNG + Crawl4AI self-hosted search backend (#1282 ) (#1299 ) Some checks failed Tests / lint (push) Has been cancelled Details Tests / test (push) Has been cancelled Details	2026-03-24 01:52:51 +00:00
Claude (Opus 4.6)	f1f67e62a7	[claude] Document and validate AirLLM Apple Silicon requirements (#1284 ) (#1298 ) Some checks failed Tests / lint (push) Has been cancelled Details Tests / test (push) Has been cancelled Details	2026-03-24 01:52:17 +00:00
Claude (Opus 4.6)	00ef4fbd22	[claude] Document and validate AirLLM Apple Silicon requirements (#1284 ) (#1298 ) Some checks failed Tests / lint (push) Has been cancelled Details Tests / test (push) Has been cancelled Details	2026-03-24 01:52:16 +00:00
Claude (Opus 4.6)	fc0a94202f	[claude] Implement graceful degradation test scenarios (#919 ) (#1291 ) Some checks failed Tests / lint (push) Has been cancelled Details Tests / test (push) Has been cancelled Details	2026-03-24 01:49:58 +00:00
Timmy Time	bd3e207c0d	[loop-cycle-1] docs: add docstrings to VoiceTTS public methods (#774 ) (#1290 ) Some checks failed Tests / lint (push) Has been cancelled Details Tests / test (push) Has been cancelled Details	2026-03-24 01:48:46 +00:00
Claude (Opus 4.6)	cc8ed5b57d	[claude] Fix empty commits: require git add before commit in Kimi workflow (#1268 ) (#1288 ) Some checks failed Tests / lint (push) Has been cancelled Details Tests / test (push) Has been cancelled Details	2026-03-24 01:48:34 +00:00
Claude (Opus 4.6)	823216db60	[claude] Add unit tests for events system backbone (#917 ) (#1289 ) Some checks failed Tests / lint (push) Has been cancelled Details Tests / test (push) Has been cancelled Details	2026-03-24 01:48:16 +00:00
Claude (Opus 4.6)	75ecfaba64	[claude] Wire delegate_task to DistributedWorker for actual execution (#985 ) (#1273 ) Some checks failed Tests / lint (push) Has been cancelled Details Tests / test (push) Has been cancelled Details Co-authored-by: Claude (Opus 4.6) <claude@hermes.local> Co-committed-by: Claude (Opus 4.6) <claude@hermes.local>	2026-03-24 01:47:09 +00:00
Claude (Opus 4.6)	55beaf241f	[claude] Research summary: Kimi creative blueprint (#891 ) (#1286 ) Some checks failed Tests / lint (push) Has been cancelled Details Tests / test (push) Has been cancelled Details	2026-03-24 01:46:28 +00:00
Claude (Opus 4.6)	69498c9add	[claude] Screenshot dump triage — 5 issues created (#1275 ) (#1287 ) Some checks failed Tests / lint (push) Has been cancelled Details Tests / test (push) Has been cancelled Details	2026-03-24 01:46:22 +00:00
Claude (Opus 4.6)	6c76bf2f66	[claude] Integrate health snapshot into Daily Run pre-flight (#923 ) (#1280 ) Some checks failed Tests / lint (push) Has been cancelled Details Tests / test (push) Has been cancelled Details	2026-03-24 01:43:49 +00:00
Claude (Opus 4.6)	0436dfd4c4	[claude] Dashboard: Agent Scorecards panel in Mission Control (#929 ) (#1276 ) Some checks failed Tests / lint (push) Has been cancelled Details Tests / test (push) Has been cancelled Details	2026-03-24 01:43:21 +00:00
Claude (Opus 4.6)	9eeb49a6f1	[claude] Autonomous research pipeline — orchestrator + SOVEREIGNTY.md (#972 ) (#1274 ) Some checks failed Tests / lint (push) Has been cancelled Details Tests / test (push) Has been cancelled Details	2026-03-24 01:40:53 +00:00
Claude (Opus 4.6)	2d6bfe6ba1	[claude] Agent Self-Correction Dashboard (#1007 ) (#1269 ) Some checks failed Tests / lint (push) Has been cancelled Details Tests / test (push) Has been cancelled Details Co-authored-by: Claude (Opus 4.6) <claude@hermes.local> Co-committed-by: Claude (Opus 4.6) <claude@hermes.local>	2026-03-24 01:40:40 +00:00
Claude (Opus 4.6)	ebb2cad552	[claude] feat: Session Sovereignty Report Generator (#957 ) v3 (#1263 ) Some checks failed Tests / lint (push) Has been cancelled Details Tests / test (push) Has been cancelled Details Co-authored-by: Claude (Opus 4.6) <claude@hermes.local> Co-committed-by: Claude (Opus 4.6) <claude@hermes.local>	2026-03-24 01:40:24 +00:00
Claude (Opus 4.6)	003e3883fb	[claude] Restore self-modification loop (#983 ) (#1270 ) Some checks failed Tests / lint (push) Has been cancelled Details Tests / test (push) Has been cancelled Details Co-authored-by: Claude (Opus 4.6) <claude@hermes.local> Co-committed-by: Claude (Opus 4.6) <claude@hermes.local>	2026-03-24 01:40:16 +00:00
Claude (Opus 4.6)	7dfbf05867	[claude] Run 5-test benchmark suite against local model candidates (#1066 ) (#1271 ) Some checks failed Tests / lint (push) Has been cancelled Details Tests / test (push) Has been cancelled Details	2026-03-24 01:38:59 +00:00
				`@@ -0,0 +1 @@`
				`"""Timmy Time Dashboard — source root package."""`
				`@@ -0,0 +1 @@`
				`"""Brain — identity system and task coordination."""`
				`@@ -0,0 +1 @@`
				`"""Vendor-specific chat platform adapters (e.g. Discord) for the chat bridge."""`