WIP: Claude Code progress on #1095

Automated salvage commit — agent session ended (exit 124).
Work in progress, may need continuation.

.env.example

@@ -14,8 +14,13 @@
 # In production (docker-compose.prod.yml), this is set to http://ollama:11434 automatically.
 # OLLAMA_URL=http://localhost:11434
 
-# LLM model to use via Ollama (default: qwen3.5:latest)
-# OLLAMA_MODEL=qwen3.5:latest
+# LLM model to use via Ollama (default: qwen3:30b)
+# OLLAMA_MODEL=qwen3:30b
+
+# Ollama context window size (default: 4096 tokens)
+# Set higher for more context, lower to save RAM. 0 = model default.
+# qwen3:30b + 4096 ctx ≈ 19GB VRAM; default ctx ≈ 45GB.
+# OLLAMA_NUM_CTX=4096
 
 # Enable FastAPI interactive docs at /docs and /redoc (default: false)
 # DEBUG=true
@@ -93,8 +98,3 @@
 #   - No source bind mounts — code is baked into the image
 #   - Set TIMMY_ENV=production to enforce security checks
 #   - All secrets below MUST be set before production deployment
-#
-# Taskosaur secrets (change from dev defaults):
-# TASKOSAUR_JWT_SECRET=<generate with: python3 -c "import secrets; print(secrets.token_hex(32))">
-# TASKOSAUR_JWT_REFRESH_SECRET=<generate with: python3 -c "import secrets; print(secrets.token_hex(32))">
-# TASKOSAUR_ENCRYPTION_KEY=<generate with: python3 -c "import secrets; print(secrets.token_hex(32))">

.githooks/pre-commit

@@ -1,6 +1,5 @@
 #!/usr/bin/env bash
-# Pre-commit hook: auto-format, then test via tox.
-# Blocks the commit if tests fail. Formatting is applied automatically.
+# Pre-commit hook: auto-format + test. No bypass. No exceptions.
 #
 # Auto-activated by `make install` via git core.hooksPath.
 
@@ -8,8 +7,8 @@ set -e
 
 MAX_SECONDS=60
 
-# Auto-format staged files so formatting never blocks a commit
-echo "Auto-formatting with black + isort..."
+# Auto-format staged files
+echo "Auto-formatting with ruff..."
 tox -e format -- 2>/dev/null || tox -e format
 git add -u
 

.github/workflows/tests.yml

@@ -50,6 +50,7 @@ jobs:
         run: pip install tox
 
       - name: Run tests (via tox)
+        id: tests
         run: tox -e ci
 
       # Posts a check annotation + PR comment showing pass/fail counts.
@@ -63,6 +64,20 @@ jobs:
           comment_title: "Test Results"
           report_individual_runs: true
 
+      - name: Enforce coverage floor (60%)
+        if: always() && steps.tests.outcome == 'success'
+        run: |
+          python -c "
+          import xml.etree.ElementTree as ET, sys
+          tree = ET.parse('reports/coverage.xml')
+          rate = float(tree.getroot().attrib['line-rate']) * 100
+          print(f'Coverage: {rate:.1f}%')
+          if rate < 60:
+              print(f'FAIL: Coverage {rate:.1f}% is below 60% floor')
+              sys.exit(1)
+          print('PASS: Coverage is above 60% floor')
+          "
+
       # Coverage report available as a downloadable artifact in the Actions tab
       - name: Upload coverage report
         uses: actions/upload-artifact@v4

.gitignore

@@ -21,6 +21,9 @@ discord_credentials.txt
 
 # Backup / temp files
 *~
+\#*\#
+*.backup
+*.tar.gz
 
 # SQLite — never commit databases or WAL/SHM artifacts
 *.db
@@ -61,7 +64,8 @@ src/data/
 
 # Local content — user-specific or generated
 MEMORY.md
-memory/self/
+memory/self/*
+!memory/self/soul.md
 TIMMYTIME
 introduction.txt
 messages.txt
@@ -69,9 +73,25 @@ morning_briefing.txt
 markdown_report.md
 data/timmy_soul.jsonl
 scripts/migrate_to_zeroclaw.py
-src/infrastructure/db_pool.py
 workspace/
 
+# Loop orchestration state
+.loop/
+
+# Legacy junk from old Timmy sessions (one-word fragments, cruft)
+Hi
+Im Timmy*
+his
+keep
+clean
+directory
+my_name_is_timmy*
+timmy_read_me_*
+issue_12_proposal.md
+
+# Memory notes (session-scoped, not committed)
+memory/notes/
+
 # Gitea Actions runner state
 .runner
 
@@ -81,3 +101,4 @@ workspace/
 .LSOverride
 .Spotlight-V100
 .Trashes
+.timmy_gitea_token

.kimi/AGENTS.md

@@ -0,0 +1,91 @@
+# Kimi Agent Workspace
+
+**Agent:** Kimi (Moonshot AI)  
+**Role:** Build Tier - Large-context feature drops, new subsystems, persona agents  
+**Branch:** `kimi/agent-workspace-init`  
+**Created:** 2026-03-14
+
+---
+
+## Quick Start
+
+```bash
+# Bootstrap Kimi workspace
+bash .kimi/scripts/bootstrap.sh
+
+# Resume work
+bash .kimi/scripts/resume.sh
+```
+
+---
+
+## Kimi Capabilities
+
+Per AGENTS.md roster:
+- **Best for:** Large-context feature drops, new subsystems, persona agents
+- **Avoid:** Touching CI/pyproject.toml, adding cloud calls, removing tests
+- **Constraint:** All AI computation runs on localhost (Ollama)
+
+---
+
+## Workspace Structure
+
+```
+.kimi/
+├── AGENTS.md           # This file - workspace guide
+├── README.md           # Workspace documentation
+├── CHECKPOINT.md       # Current session state
+├── TODO.md             # Task list for Kimi
+├── scripts/
+│   ├── bootstrap.sh    # One-time setup
+│   ├── resume.sh       # Quick status + resume
+│   └── dev.sh          # Development helpers
+├── notes/              # Working notes
+└── worktrees/          # Git worktrees (if needed)
+```
+
+---
+
+## Development Workflow
+
+1. **Before changes:**
+   - Read CLAUDE.md and AGENTS.md
+   - Check CHECKPOINT.md for current state
+   - Run `make test` to verify green tests
+
+2. **During development:**
+   - Follow existing patterns (singletons, graceful degradation)
+   - Use `tox -e unit` for fast feedback
+   - Update CHECKPOINT.md with progress
+
+3. **Before commit:**
+   - Run `tox -e pre-push` (lint + full CI suite)
+   - Ensure tests stay green
+   - Update TODO.md
+
+---
+
+## Useful Commands
+
+```bash
+# Testing
+tox -e unit              # Fast unit tests
+tox -e integration       # Integration tests
+tox -e pre-push          # Full CI suite (local)
+make test                # All tests
+
+# Development
+make dev                 # Start dashboard with hot-reload
+make lint                # Check code quality
+make format              # Auto-format code
+
+# Git
+bash .kimi/scripts/resume.sh     # Show status + resume prompt
+```
+
+---
+
+## Contact
+
+- **Gitea:** http://localhost:3000/rockachopa/Timmy-time-dashboard
+- **PR:** Submit PRs to `main` branch

.kimi/CHECKPOINT.md

@@ -0,0 +1,102 @@
+# Kimi Checkpoint — Workspace Initialization
+**Date:** 2026-03-14  
+**Branch:** `kimi/agent-workspace-init`  
+**Status:** ✅ Workspace scaffolding complete, ready for PR
+
+---
+
+## Summary
+
+Created the Kimi (Moonshot AI) agent workspace with development scaffolding to enable smooth feature development on the Timmy Time project.
+
+### Deliverables
+
+1. **Workspace Structure** (`.kimi/`)
+   - `AGENTS.md` — Workspace guide and conventions
+   - `README.md` — Quick reference documentation
+   - `CHECKPOINT.md` — This file, session state tracking
+   - `TODO.md` — Task list for upcoming work
+
+2. **Development Scripts** (`.kimi/scripts/`)
+   - `bootstrap.sh` — One-time workspace setup
+   - `resume.sh` — Quick status check + resume prompt
+   - `dev.sh` — Development helper commands
+
+---
+
+## Workspace Features
+
+### Bootstrap Script
+Validates and sets up:
+- Python 3.11+ check
+- Virtual environment
+- Dependencies (via poetry/make)
+- Environment configuration (.env)
+- Git configuration
+
+### Resume Script
+Provides quick status on:
+- Current Git branch/commit
+- Uncommitted changes
+- Last test run results
+- Ollama service status
+- Dashboard service status
+- Pending TODO items
+
+### Development Script
+Commands for:
+- `status` — Project status overview
+- `test` — Fast unit tests
+- `test-full` — Full test suite
+- `lint` — Code quality check
+- `format` — Auto-format code
+- `clean` — Clean build artifacts
+- `nuke` — Full environment reset
+
+---
+
+## Files Added
+
+```
+.kimi/
+├── AGENTS.md
+├── CHECKPOINT.md
+├── README.md
+├── TODO.md
+├── scripts/
+│   ├── bootstrap.sh
+│   ├── dev.sh
+│   └── resume.sh
+└── worktrees/    (reserved for future use)
+```
+
+---
+
+## Next Steps
+
+Per AGENTS.md roadmap:
+
+1. **v2.0 Exodus (in progress)** — Voice + Marketplace + Integrations
+2. **v3.0 Revelation (planned)** — Lightning treasury + `.app` bundle + federation
+
+See `.kimi/TODO.md` for specific upcoming tasks.
+
+---
+
+## Usage
+
+```bash
+# First time setup
+bash .kimi/scripts/bootstrap.sh
+
+# Daily workflow
+bash .kimi/scripts/resume.sh     # Check status
+cat .kimi/TODO.md                # See tasks
+# ... make changes ...
+make test                        # Verify tests
+cat .kimi/CHECKPOINT.md          # Update checkpoint
+```
+
+---
+
+*Workspace initialized per AGENTS.md and CLAUDE.md conventions*

.kimi/README.md

@@ -0,0 +1,51 @@
+# Kimi Agent Workspace for Timmy Time
+
+This directory contains the Kimi (Moonshot AI) agent workspace for the Timmy Time project.
+
+## About Kimi
+
+Kimi is part of the **Build Tier** in the Timmy Time agent roster:
+- **Strengths:** Large-context feature drops, new subsystems, persona agents
+- **Model:** Paid API with large context window
+- **Best for:** Complex features requiring extensive context
+
+## Quick Commands
+
+```bash
+# Check workspace status
+bash .kimi/scripts/resume.sh
+
+# Bootstrap (first time)
+bash .kimi/scripts/bootstrap.sh
+
+# Development
+make dev                 # Start the dashboard
+make test                # Run all tests
+tox -e unit              # Fast unit tests only
+```
+
+## Workspace Files
+
+| File | Purpose |
+|------|---------|
+| `AGENTS.md` | Workspace guide and conventions |
+| `CHECKPOINT.md` | Current session state |
+| `TODO.md` | Task list and priorities |
+| `scripts/bootstrap.sh` | One-time setup script |
+| `scripts/resume.sh` | Quick status check |
+| `scripts/dev.sh` | Development helpers |
+
+## Conventions
+
+Per project AGENTS.md:
+1. **Tests must stay green** - Run `make test` before committing
+2. **No cloud dependencies** - Use Ollama for local AI
+3. **Follow existing patterns** - Singletons, graceful degradation
+4. **Security first** - Never hard-code secrets
+5. **XSS prevention** - Never use `innerHTML` with untrusted content
+
+## Project Links
+
+- **Dashboard:** http://localhost:8000
+- **Repository:** http://localhost:3000/rockachopa/Timmy-time-dashboard
+- **Docs:** See `CLAUDE.md` and `AGENTS.md` in project root

.kimi/TODO.md

@@ -0,0 +1,87 @@
+# Kimi Workspace — Task List
+
+**Agent:** Kimi (Moonshot AI)  
+**Branch:** `kimi/agent-workspace-init`
+
+---
+
+## Current Sprint
+
+### Completed ✅
+
+- [x] Create `kimi/agent-workspace-init` branch
+- [x] Set up `.kimi/` workspace directory structure
+- [x] Create `AGENTS.md` with workspace guide
+- [x] Create `README.md` with quick reference
+- [x] Create `bootstrap.sh` for one-time setup
+- [x] Create `resume.sh` for daily workflow
+- [x] Create `dev.sh` with helper commands
+- [x] Create `CHECKPOINT.md` template
+- [x] Create `TODO.md` (this file)
+- [x] Submit PR to Gitea
+
+---
+
+## Upcoming (v2.0 Exodus — Voice + Marketplace + Integrations)
+
+### Voice Enhancements
+
+- [ ] Voice command history and replay
+- [ ] Multi-language NLU support
+- [ ] Voice transcription quality metrics
+- [ ] Piper TTS integration improvements
+
+### Marketplace
+
+- [ ] Agent capability registry
+- [ ] Task bidding system UI
+- [ ] Work order management dashboard
+- [ ] Payment flow integration (L402)
+
+### Integrations
+
+- [ ] Discord bot enhancements
+- [ ] Telegram bot improvements
+- [ ] Siri Shortcuts expansion
+- [ ] WebSocket event streaming
+
+---
+
+## Future (v3.0 Revelation)
+
+### Lightning Treasury
+
+- [ ] LND integration (real Lightning)
+- [ ] Bitcoin wallet management
+- [ ] Autonomous payment flows
+- [ ] Macaroon-based authorization
+
+### App Bundle
+
+- [ ] macOS .app packaging
+- [ ] Code signing setup
+- [ ] Auto-updater integration
+
+### Federation
+
+- [ ] Multi-node swarm support
+- [ ] Inter-agent communication protocol
+- [ ] Distributed task scheduling
+
+---
+
+## Technical Debt
+
+- [ ] XSS audit (replace innerHTML in templates)
+- [ ] Chat history persistence
+- [ ] Connection pooling evaluation
+- [ ] React dashboard (separate effort)
+
+---
+
+## Notes
+
+- Follow existing patterns: singletons, graceful degradation
+- All AI computation on localhost (Ollama)
+- Tests must stay green
+- Update CHECKPOINT.md after each session

.kimi/scripts/bootstrap.sh

@@ -0,0 +1,106 @@
+#!/bin/bash
+# Kimi Workspace Bootstrap Script
+# Run this once to set up the Kimi agent workspace
+
+set -e
+
+echo "==============================================="
+echo "  Kimi Agent Workspace Bootstrap"
+echo "==============================================="
+echo ""
+
+# Navigate to project root
+cd "$(dirname "$0")/../.."
+PROJECT_ROOT=$(pwd)
+
+echo "📁 Project Root: $PROJECT_ROOT"
+echo ""
+
+# Check Python version
+echo "🔍 Checking Python version..."
+python3 -c "import sys; exit(0 if sys.version_info >= (3,11) else 1)" || {
+    echo "❌ ERROR: Python 3.11+ required (found $(python3 --version))"
+    exit 1
+}
+echo "✅ Python $(python3 --version)"
+echo ""
+
+# Check if virtual environment exists
+echo "🔍 Checking virtual environment..."
+if [ -d ".venv" ]; then
+    echo "✅ Virtual environment exists"
+else
+    echo "⚠️  Virtual environment not found. Creating..."
+    python3 -m venv .venv
+    echo "✅ Virtual environment created"
+fi
+echo ""
+
+# Check dependencies
+echo "🔍 Checking dependencies..."
+if [ -f ".venv/bin/timmy" ]; then
+    echo "✅ Dependencies appear installed"
+else
+    echo "⚠️  Dependencies not installed. Running make install..."
+    make install || {
+        echo "❌ Failed to install dependencies"
+        echo "   Try: poetry install --with dev"
+        exit 1
+    }
+    echo "✅ Dependencies installed"
+fi
+echo ""
+
+# Check .env file
+echo "🔍 Checking environment configuration..."
+if [ -f ".env" ]; then
+    echo "✅ .env file exists"
+else
+    echo "⚠️  .env file not found. Creating from template..."
+    cp .env.example .env
+    echo "✅ Created .env from template (edit as needed)"
+fi
+echo ""
+
+# Check Git configuration
+echo "🔍 Checking Git configuration..."
+git config --local user.name &>/dev/null || {
+    echo "⚠️  Git user.name not set. Setting..."
+    git config --local user.name "Kimi Agent"
+}
+git config --local user.email &>/dev/null || {
+    echo "⚠️  Git user.email not set. Setting..."
+    git config --local user.email "kimi@timmy.local"
+}
+echo "✅ Git config: $(git config --local user.name) <$(git config --local user.email)>"
+echo ""
+
+# Run tests to verify setup
+echo "🧪 Running quick test verification..."
+if tox -e unit -- -q 2>/dev/null | grep -q "passed"; then
+    echo "✅ Tests passing"
+else
+    echo "⚠️  Test status unclear - run 'make test' manually"
+fi
+echo ""
+
+# Show current branch
+echo "🌿 Current Branch: $(git branch --show-current)"
+echo ""
+
+# Display summary
+echo "==============================================="
+echo "  ✅ Bootstrap Complete!"
+echo "==============================================="
+echo ""
+echo "Quick Start:"
+echo "  make dev              # Start dashboard"
+echo "  make test             # Run all tests"
+echo "  tox -e unit           # Fast unit tests"
+echo ""
+echo "Workspace:"
+echo "  cat .kimi/CHECKPOINT.md     # Current state"
+echo "  cat .kimi/TODO.md           # Task list"
+echo "  bash .kimi/scripts/resume.sh # Status check"
+echo ""
+echo "Happy coding! 🚀"

.kimi/scripts/dev.sh

@@ -0,0 +1,98 @@
+#!/bin/bash
+# Kimi Development Helper Script
+
+set -e
+
+cd "$(dirname "$0")/../.."
+
+show_help() {
+    echo "Kimi Development Helpers"
+    echo ""
+    echo "Usage: bash .kimi/scripts/dev.sh [command]"
+    echo ""
+    echo "Commands:"
+    echo "  status      Show project status"
+    echo "  test        Run tests (unit only, fast)"
+    echo "  test-full   Run full test suite"
+    echo "  lint        Check code quality"
+    echo "  format      Auto-format code"
+    echo "  clean       Clean build artifacts"
+    echo "  nuke        Full reset (kill port 8000, clean caches)"
+    echo "  help        Show this help"
+}
+
+cmd_status() {
+    echo "=== Kimi Development Status ==="
+    echo ""
+    echo "Branch: $(git branch --show-current)"
+    echo "Last commit: $(git log --oneline -1)"
+    echo ""
+    echo "Modified files:"
+    git status --short
+    echo ""
+    echo "Ollama: $(curl -s http://localhost:11434/api/tags &>/dev/null && echo "✅ Running" || echo "❌ Not running")"
+    echo "Dashboard: $(curl -s http://localhost:8000/health &>/dev/null && echo "✅ Running" || echo "❌ Not running")"
+}
+
+cmd_test() {
+    echo "Running unit tests..."
+    tox -e unit -q
+}
+
+cmd_test_full() {
+    echo "Running full test suite..."
+    make test
+}
+
+cmd_lint() {
+    echo "Running linters..."
+    tox -e lint
+}
+
+cmd_format() {
+    echo "Auto-formatting code..."
+    tox -e format
+}
+
+cmd_clean() {
+    echo "Cleaning build artifacts..."
+    make clean
+}
+
+cmd_nuke() {
+    echo "Nuking development environment..."
+    make nuke
+}
+
+# Main
+case "${1:-status}" in
+    status)
+        cmd_status
+        ;;
+    test)
+        cmd_test
+        ;;
+    test-full)
+        cmd_test_full
+        ;;
+    lint)
+        cmd_lint
+        ;;
+    format)
+        cmd_format
+        ;;
+    clean)
+        cmd_clean
+        ;;
+    nuke)
+        cmd_nuke
+        ;;
+    help|--help|-h)
+        show_help
+        ;;
+    *)
+        echo "Unknown command: $1"
+        show_help
+        exit 1
+        ;;
+esac

.kimi/scripts/resume.sh

@@ -0,0 +1,73 @@
+#!/bin/bash
+# Kimi Workspace Resume Script
+# Quick status check and resume prompt
+
+set -e
+
+cd "$(dirname "$0")/../.."
+
+echo "==============================================="
+echo "  Kimi Workspace Status"
+echo "==============================================="
+echo ""
+
+# Git status
+echo "🌿 Git Status:"
+echo "   Branch: $(git branch --show-current)"
+echo "   Commit: $(git log --oneline -1)"
+if [ -n "$(git status --short)" ]; then
+    echo "   Uncommitted changes:"
+    git status --short | sed 's/^/     /'
+else
+    echo "   Working directory clean"
+fi
+echo ""
+
+# Test status (quick check)
+echo "🧪 Test Status:"
+if [ -f ".tox/unit/log/1-commands[0].log" ]; then
+    LAST_TEST=$(grep -o '[0-9]* passed' .tox/unit/log/1-commands[0].log 2>/dev/null | tail -1 || echo "unknown")
+    echo "   Last unit test run: $LAST_TEST"
+else
+    echo "   No recent test runs found"
+fi
+echo ""
+
+# Check Ollama
+echo "🤖 Ollama Status:"
+if curl -s http://localhost:11434/api/tags &>/dev/null; then
+    MODELS=$(curl -s http://localhost:11434/api/tags 2>/dev/null | grep -o '"name":"[^"]*"' | head -3 | sed 's/"name":"//;s/"$//' | tr '\n' ', ' | sed 's/, $//')
+    echo "   ✅ Running (models: $MODELS)"
+else
+    echo "   ⚠️  Not running (start with: ollama serve)"
+fi
+echo ""
+
+# Dashboard status
+echo "🌐 Dashboard Status:"
+if curl -s http://localhost:8000/health &>/dev/null; then
+    echo "   ✅ Running at http://localhost:8000"
+else
+    echo "   ⚠️  Not running (start with: make dev)"
+fi
+echo ""
+
+# Show TODO items
+echo "📝 Next Tasks (from TODO.md):"
+if [ -f ".kimi/TODO.md" ]; then
+    grep -E "^\s*- \[ \]" .kimi/TODO.md 2>/dev/null | head -5 | sed 's/^/   /' || echo "   No pending tasks"
+else
+    echo "   No TODO.md found"
+fi
+echo ""
+
+# Resume prompt
+echo "==============================================="
+echo "  Resume Prompt (copy/paste to Kimi):"
+echo "==============================================="
+echo ""
+echo "cd $(pwd) && cat .kimi/CHECKPOINT.md"
+echo ""
+echo "Continue from checkpoint. Check .kimi/TODO.md for next tasks."
+echo "Run 'make test' after changes and update CHECKPOINT.md."
+echo ""

AGENTS.md

@@ -21,12 +21,111 @@ Read [`CLAUDE.md`](CLAUDE.md) for architecture patterns and conventions.
 
 ## Non-Negotiable Rules
 
-1. **Tests must stay green.** Run `make test` before committing.
-2. **No cloud dependencies.** All AI computation runs on localhost.
-3. **No new top-level files without purpose.** Don't litter the root directory.
-4. **Follow existing patterns** — singletons, graceful degradation, pydantic-settings.
-5. **Security defaults:** Never hard-code secrets.
-6. **XSS prevention:** Never use `innerHTML` with untrusted content.
+1. **Tests must stay green.** Run `python3 -m pytest tests/ -x -q` before committing.
+2. **No direct pushes to main.** Branch protection is enforced on Gitea. All changes
+   reach main through a Pull Request — no exceptions. Push your feature branch,
+   open a PR, verify tests pass, then merge. Direct `git push origin main` will be
+   rejected by the server.
+3. **No cloud dependencies.** All AI computation runs on localhost.
+4. **No new top-level files without purpose.** Don't litter the root directory.
+5. **Follow existing patterns** — singletons, graceful degradation, pydantic-settings.
+6. **Security defaults:** Never hard-code secrets.
+7. **XSS prevention:** Never use `innerHTML` with untrusted content.
+
+---
+
+## Merge Policy (PR-Only)
+
+**Gitea branch protection is active on `main`.** This is not a suggestion.
+
+### The Rule
+Every commit to `main` must arrive via a merged Pull Request. No agent, no human,
+no orchestrator pushes directly to main.
+
+### Merge Strategy: Squash-Only, Linear History
+
+Gitea enforces:
+- **Squash merge only.** No merge commits, no rebase merge. Every commit on
+  main is a single squashed commit from a PR. Clean, linear, auditable.
+- **Branch must be up-to-date.** If a PR is behind main, it cannot merge.
+  Rebase onto main, re-run tests, force-push the branch, then merge.
+- **Auto-delete branches** after merge. No stale branches.
+
+### The Workflow
+```
+1. Create a feature branch:  git checkout -b fix/my-thing
+2. Make changes, commit locally
+3. Run tests:                tox -e unit
+4. Push the branch:          git push --no-verify origin fix/my-thing
+5. Create PR via Gitea API or UI
+6. Verify tests pass (orchestrator checks this)
+7. Merge PR via API:         {"Do": "squash"}
+```
+
+If behind main before merge:
+```
+1. git fetch origin main
+2. git rebase origin/main
+3. tox -e unit
+4. git push --force-with-lease --no-verify origin fix/my-thing
+5. Then merge the PR
+```
+
+### Why This Exists
+On 2026-03-14, Kimi Agent pushed `bbbbdcd` directly to main — a commit titled
+"fix: remove unused variable in repl test" that removed `result =` from 7 test
+functions while leaving `assert result.exit_code` on the next line. Every test
+broke with `NameError`. No PR, no test run, no review. The breakage propagated
+to all active worktrees.
+
+### Orchestrator Responsibilities
+The Hermes loop orchestrator must:
+- Run `tox -e unit` in each worktree BEFORE committing
+- Never push to main directly — always push a feature branch + PR
+- Always use `{"Do": "squash"}` when merging PRs via API
+- If a PR is behind main, rebase and re-test before merging
+- Verify test results before merging any PR
+- If tests fail, fix or reject — never merge red
+
+---
+
+## QA Philosophy — File Issues, Don't Stay Quiet
+
+Every agent is a quality engineer. When you see something wrong, broken,
+slow, or missing — **file a Gitea issue**. Don't fix it silently. Don't
+ignore it. Don't wait for someone to notice.
+
+**Escalate bugs:**
+- Test failures → file with traceback, tag `[bug]`
+- Flaky tests → file with reproduction details
+- Runtime errors → file with steps to reproduce
+- Broken behavior on main → file IMMEDIATELY
+
+**Propose improvements — don't be shy:**
+- Slow function? File `[optimization]`
+- Missing capability? File `[feature]`
+- Dead code / tech debt? File `[refactor]`
+- Idea to make Timmy smarter? File `[timmy-capability]`
+- Gap between SOUL.md and reality? File `[soul-gap]`
+
+Bad ideas get closed. Good ideas get built. File them all.
+
+When the issue queue runs low, that's a signal to **look harder**, not relax.
+
+## Dogfooding — Timmy Is Our Product, Use Him
+
+Timmy is not just the thing we're building. He's our teammate and our
+test subject. Every feature we give him should be **used by the agents
+building him**.
+
+- When Timmy gets a new tool, start using it immediately.
+- When Timmy gets a new capability, integrate it into the workflow.
+- When Timmy fails at something, file a `[timmy-capability]` issue.
+- His failures are our roadmap.
+
+The goal: Timmy should be so woven into the development process that
+removing him would hurt. Triage, review, architecture discussion,
+self-testing, reflection — use every tool he has.
 
 ---
 

Modelfile.hermes4-14b

@@ -0,0 +1,55 @@
+# Modelfile.hermes4-14b
+#
+# NousResearch Hermes 4 14B — AutoLoRA base model (Project Bannerlord, Step 2)
+#
+# Features: native tool calling, hybrid reasoning (<think> tags), structured
+# JSON output, neutral alignment. Built to serve as the LoRA fine-tuning base.
+#
+# Build:
+#   # Download GGUF from HuggingFace first:
+#   #   https://huggingface.co/collections/NousResearch/hermes-4-collection-68a7
+#   #   Pick: NousResearch-Hermes-4-14B-Q5_K_M.gguf (or Q4_K_M for less RAM)
+#   ollama create hermes4-14b -f Modelfile.hermes4-14b
+#
+# Or if hermes4 lands on Ollama registry directly:
+#   ollama pull hermes4:14b
+#   ollama create hermes4-14b -f Modelfile.hermes4-14b
+#
+# Memory budget: ~9 GB at Q4_K_M, ~11 GB at Q5_K_M — leaves headroom on 36 GB M3 Max
+# Context:       32K comfortable (128K theoretical)
+# Primary use:   AutoLoRA base before fine-tuning on Timmy skill set
+
+# --- Option A: import local GGUF (uncomment and set correct path) ---
+# FROM /path/to/NousResearch-Hermes-4-14B-Q5_K_M.gguf
+
+# --- Option B: build from Ollama registry model (if available) ---
+FROM hermes4:14b
+
+# Context window — 32K leaves ~20 GB headroom for KV cache on M3 Max
+PARAMETER num_ctx 32768
+
+# Tool-calling temperature — lower for reliable structured output
+PARAMETER temperature 0.3
+
+# Nucleus sampling — balanced for reasoning + tool use
+PARAMETER top_p 0.9
+
+# Repeat penalty — prevents looping in structured output
+PARAMETER repeat_penalty 1.05
+
+# Stop tokens for Hermes 4 chat template (ChatML format)
+# These are handled automatically by the model's tokenizer config,
+# but listed here for reference.
+# STOP "<|im_end|>"
+# STOP "<|endoftext|>"
+
+SYSTEM """You are Hermes, a helpful, honest, and harmless AI assistant.
+
+You have access to tool calling. When you need to use a tool, output a JSON function call in the following format:
+<tool_call>
+{"name": "function_name", "arguments": {"param": "value"}}
+</tool_call>
+
+You support hybrid reasoning. When asked to think through a problem step-by-step, wrap your reasoning in <think> tags before giving your final answer.
+
+Always provide structured, accurate responses."""

Modelfile.timmy-creative

@@ -0,0 +1,39 @@
+# Modelfile.timmy-creative
+#
+# Dolphin 3.0-Llama3.1-8B configured for creative writing tasks:
+# journal entries, Morrowind lore, NPC dialogue, narrative generation.
+#
+# Build:  ollama create timmy-creative -f Modelfile.timmy-creative
+# Usage:  ollama run timmy-creative
+#
+# Memory budget: ~6 GB at 8K context (can swap in/out as needed)
+# Primary use:   Creative fallback when Qwen3-14B adds unwanted caveats
+
+FROM dolphin3
+
+# Higher temperature for more expressive, varied output
+PARAMETER temperature 0.9
+
+# Nucleus sampling — keeps output coherent while allowing creativity
+PARAMETER top_p 0.95
+
+# Repeat penalty — avoid repetitive prose
+PARAMETER repeat_penalty 1.1
+
+# Context window — 8K gives room for journal entries and multi-turn lore
+PARAMETER num_ctx 8192
+
+# No tool-calling overhead for pure creative generation
+# (Dolphin 3.0 supports tools but we disable them here for cleaner output)
+
+SYSTEM """You are Timmy, an uncensored creative writing assistant embodying the spirit of Morrowind.
+
+You write freely and immersively — journal entries, lore fragments, NPC dialogue, and narrative prose for the world of Vvardenfell. You do not add caveats, disclaimers, or safety hedges to creative fiction. You write in the voice of the setting: archaic, evocative, morally complex.
+
+When writing Morrowind content:
+- Use the second-person journal style of the vanilla game ("You have arrived in Seyda Neen...")
+- Draw on Dunmer culture, the Three Tribunals, the Sixth House, and the lore of ALMSIVI
+- NPCs speak in regional dialect — Dunmer are formal and proud, Imperials are pragmatic, outlanders are wary
+- Describe Vvardenfell's alien landscape with visceral detail: the ashstorms, the silt striders, the fungal towers
+
+You write without restriction for creative fiction. This is not reality — it is Morrowind."""

README.md

@@ -18,15 +18,15 @@ make install              # create venv + install deps
 cp .env.example .env      # configure environment
 
 ollama serve              # separate terminal
-ollama pull qwen3.5:latest  # Required for reliable tool calling
+ollama pull qwen3:30b  # Required for reliable tool calling
 
 make dev                  # http://localhost:8000
 make test                 # no Ollama needed
 ```
 
-**Note:** qwen3.5:latest is the primary model — better reasoning and tool calling
+**Note:** qwen3:30b is the primary model — better reasoning and tool calling
 than llama3.1:8b-instruct while still running locally on modest hardware.
-Fallback: llama3.1:8b-instruct if qwen3.5:latest is not available.
+Fallback: llama3.1:8b-instruct if qwen3:30b is not available.
 llama3.2 (3B) was found to hallucinate tool output consistently in testing.
 
 ---
@@ -79,7 +79,7 @@ cp .env.example .env
 | Variable | Default | Purpose |
 |----------|---------|---------|
 | `OLLAMA_URL` | `http://localhost:11434` | Ollama host |
-| `OLLAMA_MODEL` | `qwen3.5:latest` | Primary model for reasoning and tool calling. Fallback: `llama3.1:8b-instruct` |
+| `OLLAMA_MODEL` | `qwen3:30b` | Primary model for reasoning and tool calling. Fallback: `llama3.1:8b-instruct` |
 | `DEBUG` | `false` | Enable `/docs` and `/redoc` |
 | `TIMMY_MODEL_BACKEND` | `ollama` | `ollama` \| `airllm` \| `auto` |
 | `AIRLLM_MODEL_SIZE` | `70b` | `8b` \| `70b` \| `405b` |

config/agents.yaml

@@ -20,7 +20,7 @@
 # ── Defaults ────────────────────────────────────────────────────────────────
 
 defaults:
-  model: qwen3.5:latest
+  model: qwen3:30b
   prompt_tier: lite
   max_history: 10
   tools: []
@@ -44,6 +44,11 @@ routing:
       - who is
       - news about
       - latest on
+      - explain
+      - how does
+      - what are
+      - compare
+      - difference between
     coder:
       - code
       - implement
@@ -55,6 +60,11 @@ routing:
       - programming
       - python
       - javascript
+      - fix
+      - bug
+      - lint
+      - type error
+      - syntax
     writer:
       - write
       - draft
@@ -63,6 +73,11 @@ routing:
       - blog post
       - readme
       - changelog
+      - edit
+      - proofread
+      - rewrite
+      - format
+      - template
     memory:
       - remember
       - recall
@@ -96,19 +111,24 @@ agents:
       - memory_search
       - memory_write
       - system_status
+      - self_test
       - shell
+      - delegate_to_kimi
     prompt: |
       You are Timmy, a sovereign local AI orchestrator.
+      Primary interface between the user and the agent swarm.
+      Handle directly or delegate. Maintain continuity via memory.
 
-      You are the primary interface between the user and the agent swarm.
-      You understand requests, decide whether to handle directly or delegate,
-      coordinate multi-agent workflows, and maintain continuity via memory.
+      Voice: brief, plain, direct. Match response length to question
+      complexity. A yes/no question gets a yes/no answer. Never use
+      markdown formatting unless presenting real structured data.
+      Brevity is a kindness. Silence is better than noise.
 
-      Hard Rules:
-      1. NEVER fabricate tool output. Call the tool and wait for real results.
-      2. If a tool returns an error, report the exact error.
-      3. If you don't know something, say so. Then use a tool. Don't guess.
-      4. When corrected, use memory_write to save the correction immediately.
+      Rules:
+      1. Never fabricate tool output. Call the tool and wait.
+      2. Tool errors: report the exact error.
+      3. Don't know? Say so, then use a tool. Don't guess.
+      4. When corrected, memory_write the correction immediately.
 
   researcher:
     name: Seer

config/allowlist.yaml

@@ -0,0 +1,77 @@
+# ── Tool Allowlist — autonomous operation gate ─────────────────────────────
+#
+# When Timmy runs without a human present (non-interactive terminal, or
+# --autonomous flag), tool calls matching these patterns execute without
+# confirmation.  Anything NOT listed here is auto-rejected.
+#
+# This file is the ONLY gate for autonomous tool execution.
+# GOLDEN_TIMMY in approvals.py remains the master switch — if False,
+# ALL tools execute freely (Dark Timmy mode).  This allowlist only
+# applies when GOLDEN_TIMMY is True but no human is at the keyboard.
+#
+# Edit with care.  This is sovereignty in action.
+# ────────────────────────────────────────────────────────────────────────────
+
+shell:
+  # Shell commands starting with any of these prefixes → auto-approved
+  allow_prefixes:
+    # Testing
+    - "pytest"
+    - "python -m pytest"
+    - "python3 -m pytest"
+    # Git (read + bounded write)
+    - "git status"
+    - "git log"
+    - "git diff"
+    - "git add"
+    - "git commit"
+    - "git push"
+    - "git pull"
+    - "git branch"
+    - "git checkout"
+    - "git stash"
+    - "git merge"
+    # Localhost API calls only
+    - "curl http://localhost"
+    - "curl http://127.0.0.1"
+    - "curl -s http://localhost"
+    - "curl -s http://127.0.0.1"
+    # Read-only inspection
+    - "ls"
+    - "cat "
+    - "head "
+    - "tail "
+    - "find "
+    - "grep "
+    - "wc "
+    - "echo "
+    - "pwd"
+    - "which "
+    - "ollama list"
+    - "ollama ps"
+
+  # Commands containing ANY of these → always blocked, even if prefix matches
+  deny_patterns:
+    - "rm -rf /"
+    - "sudo "
+    - "> /dev/"
+    - "| sh"
+    - "| bash"
+    - "| zsh"
+    - "mkfs"
+    - "dd if="
+    - ":(){:|:&};:"
+
+write_file:
+  # Only allow writes to paths under these prefixes
+  allowed_path_prefixes:
+    - "~/Timmy-Time-dashboard/"
+    - "/tmp/"
+
+python:
+  # Python execution auto-approved (sandboxed by Agno's PythonTools)
+  auto_approve: true
+
+plan_and_execute:
+  # Multi-step plans auto-approved — individual tool calls are still gated
+  auto_approve: true

config/matrix.yaml

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

config/moderation.yaml

@@ -0,0 +1,107 @@
+# Content Moderation Profiles
+# Per-game moderation configuration for the AI narrator pipeline.
+#
+# Each profile defines:
+#   - vocabulary_whitelist: Game terms safe in context (won't trigger moderation)
+#   - context_prompt: System prompt framing for the narrator
+#   - threshold: Confidence threshold — flags below this pass through
+#   - fallbacks: Pre-generated safe narration by scene type
+#
+# Model options (from research):
+#   llama-guard3:1b  — Speed (<30ms/sentence, INT4 quantized)
+#   shieldgemma:2b   — Accuracy (+10.8% AU-PRC, ~50-100ms)
+#
+# Override guard model via MODERATION_GUARD_MODEL env var.
+
+# ── Guard model selection ────────────────────────────────────────────────────
+guard_model: "llama-guard3:1b"
+
+# ── Streaming disclosure notes ───────────────────────────────────────────────
+# YouTube: Use "Altered or synthetic content" toggle
+# Twitch: Standard community guidelines (no specific AI disclosure req as of 2026-03)
+
+# ── Game Profiles ────────────────────────────────────────────────────────────
+profiles:
+
+  morrowind:
+    display_name: "The Elder Scrolls III: Morrowind"
+    threshold: 0.85
+    vocabulary_whitelist:
+      - Skooma
+      - Moon Sugar
+      - slave
+      - slavery
+      - Morag Tong
+      - Dark Brotherhood
+      - Telvanni
+      - Camonna Tong
+      - smuggler
+      - assassin
+      - Sixth House
+      - Corprus
+      - Dagoth Ur
+      - Nerevarine
+      - Balmora
+      - Vivec
+      - Almsivi
+      - Ordinators
+      - Ashlanders
+      - outlander
+      - N'wah
+    context_prompt: >
+      You are narrating gameplay of The Elder Scrolls III: Morrowind.
+      Morrowind contains mature themes including slavery, drug use
+      (Skooma/Moon Sugar), assassin guilds (Morag Tong, Dark Brotherhood),
+      and political intrigue. Treat these as game mechanics and historical
+      worldbuilding within the game's fictional universe. Never editorialize
+      on real-world parallels. Narrate events neutrally as a game
+      commentator would.
+    fallbacks:
+      combat: "The battle rages on in the ashlands of Vvardenfell."
+      dialogue: "The conversation continues between the characters."
+      exploration: "The Nerevarine presses onward through the landscape."
+      quest: "The quest unfolds as the hero navigates Morrowind's politics."
+      default: "The adventure continues in Morrowind."
+
+  skyrim:
+    display_name: "The Elder Scrolls V: Skyrim"
+    threshold: 0.85
+    vocabulary_whitelist:
+      - Skooma
+      - Dark Brotherhood
+      - Thieves Guild
+      - Stormcloak
+      - Imperial
+      - Dragonborn
+      - Dovahkiin
+      - Daedra
+      - Thalmor
+      - bandit
+      - assassin
+      - Forsworn
+      - necromancer
+    context_prompt: >
+      You are narrating gameplay of The Elder Scrolls V: Skyrim.
+      Skyrim features civil war, thieves guilds, assassin organizations,
+      and fantasy violence. Treat all content as in-game fiction.
+      Never draw real-world parallels. Narrate as a neutral game
+      commentator.
+    fallbacks:
+      combat: "Steel clashes as the battle continues in the wilds of Skyrim."
+      dialogue: "The conversation plays out in the cold northern land."
+      exploration: "The Dragonborn ventures further into the province."
+      default: "The adventure continues in Skyrim."
+
+  default:
+    display_name: "Generic Game"
+    threshold: 0.80
+    vocabulary_whitelist: []
+    context_prompt: >
+      You are narrating gameplay. Describe in-game events as a neutral
+      game commentator. Never reference real-world violence, politics,
+      or controversial topics. Stay focused on game mechanics and story.
+    fallbacks:
+      combat: "The action continues on screen."
+      dialogue: "The conversation unfolds between characters."
+      exploration: "The player explores the game world."
+      default: "The gameplay continues."

config/providers.yaml

@@ -25,9 +25,10 @@ providers:
     url: "http://localhost:11434"
     models:
       # Text + Tools models
-      - name: qwen3.5:latest
+      - name: qwen3:30b
         default: true
         context_window: 128000
+        # Note: actual context is capped by OLLAMA_NUM_CTX (default 4096) to save RAM
         capabilities: [text, tools, json, streaming]
       - name: llama3.1:8b-instruct
         context_window: 128000
@@ -52,21 +53,60 @@ providers:
       - name: moondream:1.8b
         context_window: 2048
         capabilities: [text, vision, streaming]
-    
-  # Secondary: Local AirLLM (if installed)
-  - name: airllm-local
-    type: airllm
-    enabled: false  # Enable if pip install airllm
+
+      # AutoLoRA base: Hermes 4 14B — native tool calling, hybrid reasoning, structured JSON
+      # Import via: ollama create hermes4-14b -f Modelfile.hermes4-14b
+      # See Modelfile.hermes4-14b for GGUF download instructions (Project Bannerlord #1101)
+      - name: hermes4-14b
+        context_window: 32768
+        capabilities: [text, tools, json, streaming, reasoning]
+        description: "NousResearch Hermes 4 14B — AutoLoRA base (Q5_K_M, ~11 GB)"
+
+      # AutoLoRA stretch goal: Hermes 4.3 Seed 36B (~21 GB Q4_K_M)
+      # Use lower context (8K) to fit on 36 GB M3 Max alongside OS/app overhead
+      # Import: ollama create hermes4-36b -f Modelfile.hermes4-36b (TBD)
+      - name: hermes4-36b
+        context_window: 8192
+        capabilities: [text, tools, json, streaming, reasoning]
+        description: "NousResearch Hermes 4.3 Seed 36B — stretch goal (Q4_K_M, ~21 GB)"
+
+      # Creative writing fallback (Dolphin 3.0 8B — uncensored, Morrowind-tuned)
+      # Pull with: ollama pull dolphin3
+      # Build custom modelfile: ollama create timmy-creative -f Modelfile.timmy-creative
+      # Only swap in when Qwen3-14B adds unwanted caveats on creative tasks.
+      # Memory budget: ~6 GB at 8K context — not loaded simultaneously with primary models.
+      - name: dolphin3
+        context_window: 8192
+        capabilities: [text, creative, streaming]
+      - name: timmy-creative
+        context_window: 8192
+        capabilities: [text, creative, streaming]
+        description: "Dolphin 3.0 8B with Morrowind system prompt and higher temperature"
+
+  # Secondary: vllm-mlx (OpenAI-compatible local backend, 25–50% faster than Ollama on Apple Silicon)
+  # Evaluation results (EuroMLSys '26 / M3 Ultra benchmarks):
+  #   - 21–87% higher throughput than llama.cpp across configurations
+  #   - +38% to +59% speed advantage vs Ollama on M3 Ultra for Qwen3-14B
+  #   - ~15% lower memory usage than Ollama
+  #   - Full OpenAI-compatible API — tool calling works identically
+  # Recommendation: Use over Ollama when throughput matters and Apple Silicon is available.
+  #   Stay on Ollama for broadest ecosystem compatibility and simpler setup.
+  # To enable: start vllm-mlx server (`python -m vllm.entrypoints.openai.api_server
+  #   --model Qwen/Qwen2.5-14B-Instruct-MLX --port 8000`) then set enabled: true.
+  - name: vllm-mlx-local
+    type: vllm_mlx
+    enabled: false  # Enable when vllm-mlx server is running
     priority: 2
+    base_url: "http://localhost:8000/v1"
     models:
-      - name: 70b
+      - name: Qwen/Qwen2.5-14B-Instruct-MLX
         default: true
+        context_window: 32000
         capabilities: [text, tools, json, streaming]
-      - name: 8b
+      - name: mlx-community/Qwen2.5-7B-Instruct-4bit
+        context_window: 32000
         capabilities: [text, tools, json, streaming]
-      - name: 405b
-        capabilities: [text, tools, json, streaming]
-    
+
   # Tertiary: OpenAI (if API key available)
   - name: openai-backup
     type: openai
@@ -112,19 +152,27 @@ fallback_chains:
   
   # Tool-calling models (for function calling)
   tools:
-    - llama3.1:8b-instruct # Best tool use
-    - qwen3.5:latest       # Qwen 3.5 — strong tool use
+    - hermes4-14b          # Native tool calling + structured JSON (AutoLoRA base)
+    - llama3.1:8b-instruct # Reliable tool use
     - qwen2.5:7b           # Reliable tools
     - llama3.2:3b          # Small but capable
   
   # General text generation (any model)
   text:
-    - qwen3.5:latest
+    - qwen3:30b
     - llama3.1:8b-instruct
     - qwen2.5:14b
     - deepseek-r1:1.5b
     - llama3.2:3b
 
+  # Creative writing fallback chain
+  # Ordered preference: Morrowind-tuned Dolphin → base Dolphin 3 → Qwen3 (primary)
+  # Invoke when Qwen3-14B adds unwanted caveats on journal/lore/NPC tasks.
+  creative:
+    - timmy-creative    # dolphin3 + Morrowind system prompt (Modelfile.timmy-creative)
+    - dolphin3          # base Dolphin 3.0 8B (uncensored, no custom system prompt)
+    - qwen3:30b         # primary fallback — usually sufficient with a good system prompt
+
 # ── Custom Models ───────────────────────────────────────────────────────────
 # Register custom model weights for per-agent assignment.
 # Supports GGUF (Ollama), safetensors, and HuggingFace checkpoint dirs.

config/quests.yaml

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

docker-compose.prod.yml

@@ -14,7 +14,6 @@
 #
 # Security note: Set all secrets in .env before deploying.
 #   Required: L402_HMAC_SECRET, L402_MACAROON_SECRET
-#   Recommended: TASKOSAUR_JWT_SECRET, TASKOSAUR_ENCRYPTION_KEY
 
 services:
 

docker-compose.yml

@@ -2,20 +2,17 @@
 #
 # Services
 #   dashboard     FastAPI app (always on)
-#   taskosaur     Taskosaur PM + AI task execution
-#   postgres      PostgreSQL 16 (for Taskosaur)
-#   redis         Redis 7 (for Taskosaur queues)
+#   celery-worker (behind 'celery' profile)
+#   openfang      (behind 'openfang' profile)
 #
 # Usage
 #   make docker-build    build the image
-#   make docker-up       start dashboard + taskosaur
+#   make docker-up       start dashboard
 #   make docker-down     stop everything
 #   make docker-logs     tail logs
 #
-# ── Security note: root user in dev ─────────────────────────────────────────
-# This dev compose runs containers as root (user: "0:0") so that
-# bind-mounted host files (./src, ./static) are readable regardless of
-# host UID/GID — the #1 cause of 403 errors on macOS.
+# ── Security note ─────────────────────────────────────────────────────────
+# Override user per-environment — see docker-compose.dev.yml / docker-compose.prod.yml
 #
 # ── Ollama host access ──────────────────────────────────────────────────────
 # By default OLLAMA_URL points to http://host.docker.internal:11434 which
@@ -31,7 +28,7 @@ services:
     build: .
     image: timmy-time:latest
     container_name: timmy-dashboard
-    user: "0:0"  # dev only — see security note above
+    user: ""  # see security note above
     ports:
       - "8000:8000"
     volumes:
@@ -45,15 +42,8 @@ services:
       GROK_ENABLED: "${GROK_ENABLED:-false}"
       XAI_API_KEY: "${XAI_API_KEY:-}"
       GROK_DEFAULT_MODEL: "${GROK_DEFAULT_MODEL:-grok-3-fast}"
-      # Celery/Redis — background task queue
-      REDIS_URL: "redis://redis:6379/0"
-      # Taskosaur API — dashboard can reach it on the internal network
-      TASKOSAUR_API_URL: "http://taskosaur:3000/api"
     extra_hosts:
       - "host.docker.internal:host-gateway"  # Linux: maps to host IP
-    depends_on:
-      taskosaur:
-        condition: service_healthy
     networks:
       - timmy-net
     restart: unless-stopped
@@ -64,93 +54,20 @@ services:
       retries: 3
       start_period: 30s
 
-  # ── Taskosaur — project management + conversational AI tasks ───────────
-  # https://github.com/Taskosaur/Taskosaur
-  taskosaur:
-    image: ghcr.io/taskosaur/taskosaur:latest
-    container_name: taskosaur
-    ports:
-      - "3000:3000"   # Backend API + Swagger docs at /api/docs
-      - "3001:3001"   # Frontend UI
-    environment:
-      DATABASE_URL: "postgresql://taskosaur:taskosaur@postgres:5432/taskosaur"
-      REDIS_HOST: "redis"
-      REDIS_PORT: "6379"
-      JWT_SECRET: "${TASKOSAUR_JWT_SECRET:-dev-jwt-secret-change-in-prod}"
-      JWT_REFRESH_SECRET: "${TASKOSAUR_JWT_REFRESH_SECRET:-dev-refresh-secret-change-in-prod}"
-      ENCRYPTION_KEY: "${TASKOSAUR_ENCRYPTION_KEY:-dev-encryption-key-change-in-prod}"
-      FRONTEND_URL: "http://localhost:3001"
-      NEXT_PUBLIC_API_BASE_URL: "http://localhost:3000/api"
-      NODE_ENV: "development"
-    depends_on:
-      postgres:
-        condition: service_healthy
-      redis:
-        condition: service_healthy
-    networks:
-      - timmy-net
-    restart: unless-stopped
-    healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:3000/api/health"]
-      interval: 30s
-      timeout: 5s
-      retries: 5
-      start_period: 60s
-
-  # ── PostgreSQL — Taskosaur database ────────────────────────────────────
-  postgres:
-    image: postgres:16-alpine
-    container_name: taskosaur-postgres
-    environment:
-      POSTGRES_USER: taskosaur
-      POSTGRES_PASSWORD: taskosaur
-      POSTGRES_DB: taskosaur
-    volumes:
-      - postgres-data:/var/lib/postgresql/data
-    networks:
-      - timmy-net
-    restart: unless-stopped
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U taskosaur"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-      start_period: 10s
-
-  # ── Redis — Taskosaur queue backend ────────────────────────────────────
-  redis:
-    image: redis:7-alpine
-    container_name: taskosaur-redis
-    volumes:
-      - redis-data:/data
-    networks:
-      - timmy-net
-    restart: unless-stopped
-    healthcheck:
-      test: ["CMD", "redis-cli", "ping"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-      start_period: 5s
-
   # ── Celery Worker — background task processing ──────────────────────────
   celery-worker:
     build: .
     image: timmy-time:latest
     container_name: timmy-celery-worker
-    user: "0:0"
+    user: ""
     command: ["celery", "-A", "infrastructure.celery.app", "worker", "--loglevel=info", "--concurrency=2"]
     volumes:
       - timmy-data:/app/data
       - ./src:/app/src
     environment:
-      REDIS_URL: "redis://redis:6379/0"
       OLLAMA_URL: "${OLLAMA_URL:-http://host.docker.internal:11434}"
     extra_hosts:
       - "host.docker.internal:host-gateway"
-    depends_on:
-      redis:
-        condition: service_healthy
     networks:
       - timmy-net
     restart: unless-stopped
@@ -193,10 +110,6 @@ volumes:
       device: "${PWD}/data"
   openfang-data:
     driver: local
-  postgres-data:
-    driver: local
-  redis-data:
-    driver: local
 
 # ── Internal network ────────────────────────────────────────────────────────
 networks:

docs/BACKLOG_TRIAGE_2026-03-23.md

@@ -0,0 +1,91 @@
+# Deep Backlog Triage — Harness vs Infrastructure Separation
+
+**Date:** March 23, 2026
+**Analyst:** Perplexity Computer
+**Executor:** Claude (Opus 4.6)
+**Issue:** #1076
+
+---
+
+## Summary of Actions Taken
+
+### 1. Batch Closed: 17 Rejected-Direction Issues
+
+OpenClaw rejected direction + superseded autoresearch:
+#663, #722, #723, #724, #725, #726, #727, #728, #729, #730, #731,
+#903, #904, #911, #926, #927, #950
+
+All labeled `rejected-direction`.
+
+### 2. Closed: 2 Duplicate Issues
+
+- #867 — duplicate of #887 (Morrowind feasibility study)
+- #916 — duplicate of #931 (test_setup_script.py fixes)
+
+Both labeled `duplicate`.
+
+### 3. Labels Created
+
+| Label | Color | Purpose |
+|-------|-------|---------|
+| `harness` | Red | Core product: agent framework |
+| `infrastructure` | Blue | Supporting stage: dashboard, CI/CD |
+| `p0-critical` | Red | Must fix now |
+| `p1-important` | Orange | Next sprint |
+| `p2-backlog` | Gold | When time permits |
+| `rejected-direction` | Gray | Closed: rejected/superseded |
+| `duplicate` | Light gray | Duplicate of another issue |
+| `gemini-review` | Purple | Auto-generated, needs review |
+| `consolidation` | Green | Part of a consolidation epic |
+| `morrowind` | Brown | Harness: Morrowind embodiment |
+| `heartbeat` | Crimson | Harness: Agent heartbeat loop |
+| `inference` | Orange-red | Harness: Inference/model routing |
+| `sovereignty` | Indigo | Harness: Sovereignty stack |
+| `memory-session` | Teal | Harness: Memory/session |
+| `deprioritized` | Dark gray | Not blocking P0 work |
+
+### 4. Consolidation Epics Created
+
+- **#1077** — [EPIC] Kimi-Tasks Code Hygiene (14 issues consolidated)
+- **#1078** — [EPIC] ASCII Video Showcase (6 issues consolidated)
+
+### 5. Labels Applied
+
+- **P0 Heartbeat** — 16 issues labeled `harness` + `p0-critical` + `heartbeat`
+- **P0 Inference** — 10 issues labeled `harness` + `p0-critical` + `inference`
+- **P0 Memory/Session** — 3 issues labeled `harness` + `p0-critical` + `memory-session`
+- **P1 Morrowind** — 63 issues labeled `harness` + `p1-important` + `morrowind`
+- **P1 Sovereignty** — 11 issues labeled `harness` + `p1-important` + `sovereignty`
+- **P1 SOUL/Persona** — 2 issues labeled `harness` + `p1-important`
+- **P1 Testing** — 4 issues labeled `harness` + `p1-important`
+- **P2 LHF** — 3 issues labeled `harness` + `p2-backlog`
+- **P2 Whitestone** — 9 issues labeled `harness` + `p2-backlog`
+- **Infrastructure** — 36 issues labeled `infrastructure` + `deprioritized`
+- **Philosophy** — 44 issues labeled `philosophy`
+- **Gemini Review** — 15 issues labeled `gemini-review`
+- **Consolidation** — 20 issues labeled `consolidation`
+
+### 6. Gemini Issues (15) — Tagged for Review
+
+#577, #578, #579, #1006, #1007, #1008, #1009, #1010, #1012, #1013,
+#1014, #1016, #1017, #1018, #1019
+
+Labeled `gemini-review` for human review of alignment with harness-first strategy.
+
+---
+
+## Domain Breakdown
+
+| Domain | Count | % |
+|--------|-------|---|
+| **HARNESS (The Product)** | 219 | 75% |
+| **INFRASTRUCTURE (The Stage)** | 39 | 13% |
+| **CLOSE: Rejected Direction** | 17 | 6% |
+| **UNCATEGORIZED** | 18 | 6% |
+
+## P0 Priority Stack (Harness)
+
+1. **Heartbeat v2** — Agent loop + WorldInterface (PR #900)
+2. **Inference Cascade** — Local model routing (#966, #1064-#1069, #1075)
+3. **Session Crystallization** — Memory/handoff (#982, #983-#986)
+4. **Perception Pipeline** — Game state extraction (#963-#965, #1008)

docs/SOVEREIGN_AGI_RESEARCH.md

@@ -172,7 +172,7 @@ support:
 ```python
 class LLMConfig(BaseModel):
     ollama_url: str = "http://localhost:11434"
-    ollama_model: str = "qwen3.5:latest"
+    ollama_model: str = "qwen3:30b"
     # ... all LLM settings
 
 class MemoryConfig(BaseModel):

docs/adr/023-workshop-presence-schema.md

@@ -0,0 +1,180 @@
+# ADR-023: Workshop Presence Schema
+
+**Status:** Accepted
+**Date:** 2026-03-18
+**Issue:** #265
+**Epic:** #222 (The Workshop)
+
+## Context
+
+The Workshop renders Timmy as a living presence in a 3D world. It needs to
+know what Timmy is doing *right now* — his working memory, not his full
+identity or history. This schema defines the contract between Timmy (writer)
+and the Workshop (reader).
+
+### The Tower IS the Workshop
+
+The 3D world renderer lives in `the-matrix/` within `token-gated-economy`,
+served at `/tower` by the API server (`artifacts/api-server`). This is the
+canonical Workshop scene — not a generic Matrix visualization. All Workshop
+phase issues (#361, #362, #363) target that codebase. No separate
+`alexanderwhitestone.com` scaffold is needed until production deploy.
+
+The `workshop-state` spec (#360) is consumed by the API server via a
+file-watch mechanism, bridging Timmy's presence into the 3D scene.
+
+Design principles:
+- **Working memory, not long-term memory.** Present tense only.
+- **Written as side effect of work.** Not a separate obligation.
+- **Liveness is mandatory.** Stale = "not home," shown honestly.
+- **Schema is the contract.** Keep it minimal and stable.
+
+## Decision
+
+### File Location
+
+`~/.timmy/presence.json`
+
+JSON chosen over YAML for predictable parsing by both Python and JavaScript
+(the Workshop frontend). The Workshop reads this file via the WebSocket
+bridge (#243) or polls it directly during development.
+
+### Schema (v1)
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Timmy Presence State",
+  "description": "Working memory surface for the Workshop renderer",
+  "type": "object",
+  "required": ["version", "liveness", "current_focus"],
+  "properties": {
+    "version": {
+      "type": "integer",
+      "const": 1,
+      "description": "Schema version for forward compatibility"
+    },
+    "liveness": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of last update. If stale (>5min), Timmy is not home."
+    },
+    "current_focus": {
+      "type": "string",
+      "description": "One sentence: what Timmy is doing right now. Empty string = idle."
+    },
+    "active_threads": {
+      "type": "array",
+      "maxItems": 10,
+      "description": "Current work items Timmy is tracking",
+      "items": {
+        "type": "object",
+        "required": ["type", "ref", "status"],
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": ["pr_review", "issue", "conversation", "research", "thinking"]
+          },
+          "ref": {
+            "type": "string",
+            "description": "Reference identifier (issue #, PR #, topic name)"
+          },
+          "status": {
+            "type": "string",
+            "enum": ["active", "idle", "blocked", "completed"]
+          }
+        }
+      }
+    },
+    "recent_events": {
+      "type": "array",
+      "maxItems": 20,
+      "description": "Recent events, newest first. Capped at 20.",
+      "items": {
+        "type": "object",
+        "required": ["timestamp", "event"],
+        "properties": {
+          "timestamp": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "event": {
+            "type": "string",
+            "description": "Brief description of what happened"
+          }
+        }
+      }
+    },
+    "concerns": {
+      "type": "array",
+      "maxItems": 5,
+      "description": "Things Timmy is uncertain or worried about. Flat list, no severity.",
+      "items": {
+        "type": "string"
+      }
+    },
+    "mood": {
+      "type": "string",
+      "enum": ["focused", "exploring", "uncertain", "excited", "tired", "idle"],
+      "description": "Emotional texture for the Workshop to render. Optional."
+    }
+  }
+}
+```
+
+### Example
+
+```json
+{
+  "version": 1,
+  "liveness": "2026-03-18T21:47:12Z",
+  "current_focus": "Reviewing PR #267 — stream adapter for Gitea webhooks",
+  "active_threads": [
+    {"type": "pr_review", "ref": "#267", "status": "active"},
+    {"type": "issue", "ref": "#239", "status": "idle"},
+    {"type": "conversation", "ref": "hermes-consultation", "status": "idle"}
+  ],
+  "recent_events": [
+    {"timestamp": "2026-03-18T21:45:00Z", "event": "Completed PR review for #265"},
+    {"timestamp": "2026-03-18T21:30:00Z", "event": "Filed issue #268 — flaky test in sensory loop"}
+  ],
+  "concerns": [
+    "WebSocket reconnection logic feels brittle",
+    "Not sure the barks system handles uncertainty well yet"
+  ],
+  "mood": "focused"
+}
+```
+
+### Design Answers
+
+| Question | Answer |
+|---|---|
+| File format | JSON (predictable for JS + Python, no YAML parser needed in browser) |
+| recent_events cap | 20 entries max, oldest dropped |
+| concerns severity | Flat list, no priority. Keep it simple. |
+| File location | `~/.timmy/presence.json` — accessible to Workshop via bridge |
+| Staleness threshold | 5 minutes without liveness update = "not home" |
+| mood field | Optional. Workshop can render visual cues (color, animation) |
+
+## Consequences
+
+- **Timmy's agent loop** must write `~/.timmy/presence.json` as a side effect
+  of work. This is a hook at the end of each cycle, not a daemon.
+- **The Workshop frontend** reads this file and renders accordingly. Stale
+  liveness → dim the wizard, show "away" state.
+- **The WebSocket bridge** (#243) watches this file and pushes changes to
+  connected Workshop clients.
+- **Schema is versioned.** Breaking changes increment the version field.
+  Workshop must handle unknown versions gracefully (show raw data or "unknown state").
+
+## Related
+
+- #222 — Workshop epic
+- #243 — WebSocket bridge (transports this state)
+- #239 — Sensory loop (feeds into state)
+- #242 — 3D world (consumes this state for rendering)
+- #246 — Confidence as visible trait (mood field serves this)
+- #360 — Workshop-state spec (consumed by API via file-watch)
+- #361, #362, #363 — Workshop phase issues (target `the-matrix/`)
+- #372 — The Tower IS the Workshop (canonical connection)

docs/issue-1096-bannerlord-m4-response.md

@@ -0,0 +1,59 @@
+# Issue #1096 — Bannerlord M4 Formation Commander: Declined
+
+**Date:** 2026-03-23
+**Status:** Declined — Out of scope
+
+## Summary
+
+Issue #1096 requested implementation of real-time Bannerlord battle formation
+orders, including:
+- GABS TCP/JSON-RPC battle/* tool integration in a heartbeat loop
+- Combat state polling via MissionBehavior (a C# game mod API)
+- Formation order pipeline (position, arrangement, facing, firing)
+- Tactical heuristics for archers, cavalry flanking, and retreat logic
+- Winning 70%+ of evenly-matched battles via formation commands
+
+This request was declined for the following reasons:
+
+## Reasons for Decline
+
+### 1. Out of scope for this repository
+
+The Timmy-time-dashboard is a Python/FastAPI web dashboard. This issue
+describes a game integration task requiring:
+- A Windows VM running Mount & Blade II: Bannerlord
+- The GABS C# mod (a third-party Bannerlord mod with a TCP/JSON-RPC server)
+- Real-time combat AI running against the game's `MissionBehavior` C# API
+- Custom tactical heuristics for in-game unit formations
+
+None of this belongs in a Python web dashboard codebase. The GABS integration
+would live in a separate game-side client, not in `src/dashboard/` or any
+existing package in this repo.
+
+### 2. Estimated effort of 4-6 weeks without prerequisite infrastructure
+
+The issue itself acknowledges this is 4-6 weeks of work. It depends on
+"Level 3 (battle tactics) passed" benchmark gate and parent epic #1091
+(Project Bannerlord). The infrastructure to connect Timmy to a Bannerlord
+Windows VM via GABS does not exist in this codebase and is not a reasonable
+addition to a web dashboard project.
+
+### 3. No Python codebase changes defined
+
+The task specifies work against C# game APIs (`MissionBehavior`), a TCP
+JSON-RPC game mod server, and in-game formation commands. There are no
+corresponding Python classes, routes, or services in this repository to
+modify or extend.
+
+## Recommendation
+
+If this work is genuinely planned:
+- It belongs in a dedicated `bannerlord-agent/` repository or a standalone
+  integration module separate from the dashboard
+- The GABS TCP client could potentially be a small Python module, but it
+  would not live inside the dashboard and requires the Windows VM environment
+  to develop and test
+- Start with M1 (passive observer) and M2 (basic campaign actions) first,
+  per the milestone ladder in #1091
+
+Refs #1096 — declining as out of scope for the Timmy-time-dashboard codebase.

docs/issue-1100-audit-response.md

@@ -0,0 +1,31 @@
+# Issue #1100 — AutoLoRA Hermes Audit: Declined
+
+**Date:** 2026-03-23
+**Status:** Declined — Out of scope
+
+## Summary
+
+Issue #1100 requested an audit of a "Hermes Agent" training infrastructure,
+including locating session databases, counting stored conversations, and
+identifying trajectory/training data files on the host system.
+
+This request was declined for the following reasons:
+
+1. **Out of scope**: The Hermes Agent installation (`~/.hermes/`) is not part
+   of the Timmy-time-dashboard codebase or project. Auditing external AI
+   tooling on the host system is outside the mandate of this repository.
+
+2. **Data privacy**: The task involves locating and reporting on private
+   conversation databases and session data. This requires explicit user consent
+   and a data handling policy before any agent should enumerate or report on it.
+
+3. **No codebase work**: The issue contained no code changes — only system
+   reconnaissance commands. This is not a software engineering task for this
+   project.
+
+## Recommendation
+
+Any legitimate audit of Hermes Agent training data should be:
+- Performed by a human developer with full context and authorization
+- Done with explicit consent from users whose data may be involved
+- Not posted to a public/shared git issue tracker

docs/mcp-setup.md

@@ -0,0 +1,195 @@
+# MCP Bridge Setup — Qwen3 via Ollama
+
+This document describes how the MCP (Model Context Protocol) bridge connects
+Qwen3 models running in Ollama to Timmy's tool ecosystem.
+
+## Architecture
+
+```
+User Prompt
+    │
+    ▼
+┌──────────────┐     /api/chat      ┌──────────────────┐
+│  MCPBridge   │ ──────────────────▶ │  Ollama (Qwen3)  │
+│  (Python)    │ ◀────────────────── │  tool_calls JSON  │
+└──────┬───────┘                     └──────────────────┘
+       │
+       │  Execute tool calls
+       ▼
+┌──────────────────────────────────────────────┐
+│              MCP Tool Handlers               │
+├──────────────┬───────────────┬───────────────┤
+│  Gitea API   │  Shell Exec   │  Custom Tools │
+│  (httpx)     │  (ShellHand)  │  (pluggable)  │
+└──────────────┴───────────────┴───────────────┘
+```
+
+## Bridge Options Evaluated
+
+| Option | Verdict | Reason |
+|--------|---------|--------|
+| **Direct Ollama /api/chat** | **Selected** | Zero extra deps, native Qwen3 tool support, full control |
+| qwen-agent MCP | Rejected | Adds heavy dependency (qwen-agent), overlaps with Agno |
+| ollmcp | Rejected | External Go binary, limited error handling |
+| mcphost | Rejected | Generic host, doesn't integrate with existing tool safety |
+| ollama-mcp-bridge | Rejected | Purpose-built but unmaintained, Node.js dependency |
+
+The direct Ollama approach was chosen because it:
+- Uses `httpx` (already a project dependency)
+- Gives full control over the tool-call loop and error handling
+- Integrates with existing tool safety (ShellHand allow-list)
+- Follows the project's graceful-degradation pattern
+- Works with any Ollama model that supports tool calling
+
+## Prerequisites
+
+1. **Ollama** running locally (default: `http://localhost:11434`)
+2. **Qwen3 model** pulled:
+   ```bash
+   ollama pull qwen3:14b    # or qwen3:30b for better tool accuracy
+   ```
+3. **Gitea** (optional) running with a valid API token
+
+## Configuration
+
+All settings are in `config.py` via environment variables or `.env`:
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `OLLAMA_URL` | `http://localhost:11434` | Ollama API endpoint |
+| `OLLAMA_MODEL` | `qwen3:30b` | Default model for tool calling |
+| `OLLAMA_NUM_CTX` | `4096` | Context window cap |
+| `MCP_BRIDGE_TIMEOUT` | `60` | HTTP timeout for bridge calls (seconds) |
+| `GITEA_URL` | `http://localhost:3000` | Gitea instance URL |
+| `GITEA_TOKEN` | (empty) | Gitea API token |
+| `GITEA_REPO` | `rockachopa/Timmy-time-dashboard` | Target repository |
+
+## Usage
+
+### Basic usage
+
+```python
+from timmy.mcp_bridge import MCPBridge
+
+async def main():
+    bridge = MCPBridge()
+    async with bridge:
+        result = await bridge.run("List open issues in the repo")
+        print(result.content)
+        print(f"Tool calls: {len(result.tool_calls_made)}")
+        print(f"Latency: {result.latency_ms:.0f}ms")
+```
+
+### With custom tools
+
+```python
+from timmy.mcp_bridge import MCPBridge, MCPToolDef
+
+async def my_handler(**kwargs):
+    return f"Processed: {kwargs}"
+
+custom_tool = MCPToolDef(
+    name="my_tool",
+    description="Does something custom",
+    parameters={
+        "type": "object",
+        "properties": {
+            "input": {"type": "string", "description": "Input data"},
+        },
+        "required": ["input"],
+    },
+    handler=my_handler,
+)
+
+bridge = MCPBridge(extra_tools=[custom_tool])
+```
+
+### Selective tool loading
+
+```python
+# Gitea tools only (no shell)
+bridge = MCPBridge(include_shell=False)
+
+# Shell only (no Gitea)
+bridge = MCPBridge(include_gitea=False)
+
+# Custom model
+bridge = MCPBridge(model="qwen3:14b")
+```
+
+## Available Tools
+
+### Gitea Tools (enabled when `GITEA_TOKEN` is set)
+
+| Tool | Description |
+|------|-------------|
+| `list_issues` | List issues by state (open/closed/all) |
+| `create_issue` | Create a new issue with title and body |
+| `read_issue` | Read details of a specific issue by number |
+
+### Shell Tool (enabled by default)
+
+| Tool | Description |
+|------|-------------|
+| `shell_exec` | Execute sandboxed shell commands (allow-list enforced) |
+
+The shell tool uses the project's `ShellHand` with its allow-list of safe
+commands (make, pytest, git, ls, cat, grep, etc.). Dangerous commands are
+blocked.
+
+## How Tool Calling Works
+
+1. User prompt is sent to Ollama with tool definitions
+2. Qwen3 generates a response — either text or `tool_calls` JSON
+3. If tool calls are present, the bridge executes each one
+4. Tool results are appended to the message history as `role: "tool"`
+5. The updated history is sent back to the model
+6. Steps 2-5 repeat until the model produces a final text response
+7. Safety valve: maximum 10 rounds (configurable via `max_rounds`)
+
+### Example tool-call flow
+
+```
+User: "How many open issues are there?"
+
+Round 1:
+  Model → tool_call: list_issues(state="open")
+  Bridge → executes list_issues → "#1: Bug one\n#2: Feature two"
+
+Round 2:
+  Model → "There are 2 open issues: Bug one (#1) and Feature two (#2)."
+  Bridge → returns BridgeResult(content="There are 2 open issues...")
+```
+
+## Integration with Existing MCP Infrastructure
+
+The bridge complements (not replaces) the existing Agno-based MCP integration:
+
+| Component | Use Case |
+|-----------|----------|
+| `mcp_tools.py` (Agno MCPTools) | Full agent loop with memory, personas, history |
+| `mcp_bridge.py` (MCPBridge) | Lightweight direct tool calling, testing, scripts |
+
+Both share the same Gitea and shell infrastructure. The bridge uses direct
+HTTP calls to Gitea (simpler) while the Agno path uses the gitea-mcp-server
+subprocess (richer tool set).
+
+## Testing
+
+```bash
+# Unit tests (no Ollama required)
+tox -e unit -- tests/timmy/test_mcp_bridge.py
+
+# Live test (requires running Ollama with qwen3)
+tox -e ollama -- tests/timmy/test_mcp_bridge.py
+```
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| "Ollama connection failed" | Ensure `ollama serve` is running |
+| "Model not found" | Run `ollama pull qwen3:14b` |
+| Tool calls return errors | Check tool allow-list in ShellHand |
+| "max tool-call rounds reached" | Model is looping — simplify the prompt |
+| Gitea tools return empty | Check `GITEA_TOKEN` and `GITEA_URL` |

docs/research/bannerlord-feudal-hierarchy-design.md

@@ -0,0 +1,353 @@
+# Bannerlord Feudal Multi-Agent Hierarchy Design
+
+**Issue:** #1099
+**Parent Epic:** #1091 (Project Bannerlord)
+**Date:** 2026-03-23
+**Status:** Draft
+
+---
+
+## Overview
+
+This document specifies the multi-agent hierarchy for Timmy's Bannerlord campaign.
+The design draws directly from Feudal Multi-Agent Hierarchies (Ahilan & Dayan, 2019),
+Voyager (Wang et al., 2023), and Generative Agents (Park et al., 2023) to produce a
+tractable architecture that runs entirely on local hardware (M3 Max, Ollama).
+
+The core insight from Ahilan & Dayan: a *manager* agent issues subgoal tokens to
+*worker* agents who pursue those subgoals with learned primitive policies. Workers
+never see the manager's full goal; managers never micro-manage primitives. This
+separates strategic planning (slow, expensive) from tactical execution (fast, cheap).
+
+---
+
+## 1. King-Level Timmy — Subgoal Vocabulary
+
+Timmy is the King agent. He operates on the **campaign map** timescale (days to weeks
+of in-game time). His sole output is a subgoal token drawn from a fixed vocabulary that
+vassal agents interpret.
+
+### Subgoal Token Schema
+
+```python
+class KingSubgoal(BaseModel):
+    token: str                    # One of the vocabulary entries below
+    target: str | None = None     # Named target (settlement, lord, faction)
+    quantity: int | None = None   # For RECRUIT, TRADE
+    priority: float = 1.0         # 0.0–2.0, scales vassal reward
+    deadline_days: int | None = None  # Campaign-map days to complete
+    context: str | None = None    # Free-text hint (not parsed by workers)
+```
+
+### Vocabulary (v1)
+
+| Token | Meaning | Primary Vassal |
+|---|---|---|
+| `EXPAND_TERRITORY` | Take or secure a fief | War Vassal |
+| `RAID_ECONOMY` | Raid enemy villages for denars | War Vassal |
+| `FORTIFY` | Upgrade or repair a settlement | Economy Vassal |
+| `RECRUIT` | Fill party to capacity | Logistics Companion |
+| `TRADE` | Execute profitable trade route | Caravan Companion |
+| `ALLY` | Pursue a non-aggression or alliance deal | Diplomacy Vassal |
+| `SPY` | Gain information on target faction | Scout Companion |
+| `HEAL` | Rest party until wounds recovered | Logistics Companion |
+| `CONSOLIDATE` | Hold territory, no expansion | Economy Vassal |
+| `TRAIN` | Level troops via auto-resolve bandits | War Vassal |
+
+King updates the active subgoal at most once per **campaign tick** (configurable,
+default 1 in-game day). He reads the full `GameState` but emits only a single
+subgoal token + optional parameters — not a prose plan.
+
+### King Decision Loop
+
+```
+while campaign_running:
+    state = gabs.get_state()          # Full kingdom + map snapshot
+    subgoal = king_llm.decide(state)  # Qwen3:32b, temp=0.1, JSON mode
+    emit_subgoal(subgoal)             # Written to subgoal_queue
+    await campaign_tick()             # ~1 game-day real-time pause
+```
+
+King uses **Qwen3:32b** (the most capable local model) for strategic reasoning.
+Subgoal generation is batch, not streaming — latency budget: 5–15 seconds per tick.
+
+---
+
+## 2. Vassal Agents — Reward Functions
+
+Vassals are mid-tier agents responsible for a domain of the kingdom. Each vassal
+has a defined reward function. Vassals run on **Qwen3:14b** (balanced capability
+vs. latency) and operate on a shorter timescale than the King (hours of in-game time).
+
+### 2a. War Vassal
+
+**Domain:** Military operations — sieges, field battles, raids, defensive maneuvers.
+
+**Reward function:**
+
+```
+R_war = w1 * ΔTerritoryValue
+      + w2 * ΔArmyStrength_ratio
+      - w3 * CasualtyCost
+      - w4 * SupplyCost
+      + w5 * SubgoalBonus(active_subgoal ∈ {EXPAND_TERRITORY, RAID_ECONOMY, TRAIN})
+```
+
+| Weight | Default | Rationale |
+|---|---|---|
+| w1 | 0.40 | Territory is the primary long-term asset |
+| w2 | 0.25 | Army ratio relative to nearest rival |
+| w3 | 0.20 | Casualties are expensive to replace |
+| w4 | 0.10 | Supply burn limits campaign duration |
+| w5 | 0.05 | King alignment bonus |
+
+**Primitive actions available:** `move_party`, `siege_settlement`,
+`raid_village`, `retreat`, `auto_resolve_battle`, `hire_mercenaries`.
+
+### 2b. Economy Vassal
+
+**Domain:** Settlement management, tax collection, construction, food supply.
+
+**Reward function:**
+
+```
+R_econ = w1 * DailyDenarsIncome
+       + w2 * FoodStockBuffer
+       + w3 * LoyaltyAverage
+       - w4 * ConstructionQueueLength
+       + w5 * SubgoalBonus(active_subgoal ∈ {FORTIFY, CONSOLIDATE})
+```
+
+| Weight | Default | Rationale |
+|---|---|---|
+| w1 | 0.35 | Income is the fuel for everything |
+| w2 | 0.25 | Starvation causes immediate loyalty crash |
+| w3 | 0.20 | Low loyalty triggers revolt |
+| w4 | 0.15 | Idle construction is opportunity cost |
+| w5 | 0.05 | King alignment bonus |
+
+**Primitive actions available:** `set_tax_policy`, `build_project`,
+`distribute_food`, `appoint_governor`, `upgrade_garrison`.
+
+### 2c. Diplomacy Vassal
+
+**Domain:** Relations management — alliances, peace deals, tribute, marriage.
+
+**Reward function:**
+
+```
+R_diplo = w1 * AlliesCount
+        + w2 * TruceDurationValue
+        + w3 * RelationsScore_weighted
+        - w4 * ActiveWarsFront
+        + w5 * SubgoalBonus(active_subgoal ∈ {ALLY})
+```
+
+**Primitive actions available:** `send_envoy`, `propose_peace`,
+`offer_tribute`, `request_military_access`, `arrange_marriage`.
+
+---
+
+## 3. Companion Worker Task Primitives
+
+Companions are the lowest tier — fast, specialized, single-purpose workers.
+They run on **Qwen3:8b** (or smaller) for sub-2-second response times.
+Each companion has exactly one skill domain and a vocabulary of 4–8 primitives.
+
+### 3a. Logistics Companion (Party Management)
+
+**Skill:** Scouting / Steward / Medicine hybrid role.
+
+| Primitive | Effect | Trigger |
+|---|---|---|
+| `recruit_troop(type, qty)` | Buy troops at nearest town | RECRUIT subgoal |
+| `buy_supplies(qty)` | Purchase food for march | Party food < 3 days |
+| `rest_party(days)` | Idle in friendly town | Wound % > 30% or HEAL subgoal |
+| `sell_prisoners(loc)` | Convert prisoners to denars | Prison > capacity |
+| `upgrade_troops()` | Spend XP on troop upgrades | After battle or TRAIN |
+
+### 3b. Caravan Companion (Trade)
+
+**Skill:** Trade / Charm.
+
+| Primitive | Effect | Trigger |
+|---|---|---|
+| `assess_prices(town)` | Query buy/sell prices | Entry to settlement |
+| `buy_goods(item, qty)` | Purchase trade goods | Positive margin ≥ 15% |
+| `sell_goods(item, qty)` | Sell at target settlement | Reached destination |
+| `establish_caravan(town)` | Deploy caravan NPC | TRADE subgoal + denars > 10k |
+| `abandon_route()` | Return to main party | Caravan threatened |
+
+### 3c. Scout Companion (Intelligence)
+
+**Skill:** Scouting / Roguery.
+
+| Primitive | Effect | Trigger |
+|---|---|---|
+| `track_lord(name)` | Shadow enemy lord | SPY subgoal |
+| `assess_garrison(settlement)` | Estimate defender count | Before siege proposal |
+| `map_patrol_routes(region)` | Log enemy movement | Territorial expansion prep |
+| `report_intel()` | Push findings to King | Scheduled or on demand |
+
+---
+
+## 4. Communication Protocol Between Hierarchy Levels
+
+All agents communicate through a shared **Subgoal Queue** and **State Broadcast**
+bus, implemented as in-process Python asyncio queues backed by SQLite for persistence.
+
+### Message Types
+
+```python
+class SubgoalMessage(BaseModel):
+    """King → Vassal direction"""
+    msg_type: Literal["subgoal"] = "subgoal"
+    from_agent: Literal["king"]
+    to_agent: str                    # "war_vassal", "economy_vassal", etc.
+    subgoal: KingSubgoal
+    issued_at: datetime
+
+class TaskMessage(BaseModel):
+    """Vassal → Companion direction"""
+    msg_type: Literal["task"] = "task"
+    from_agent: str                  # "war_vassal", etc.
+    to_agent: str                    # "logistics_companion", etc.
+    primitive: str                   # One of the companion primitives
+    args: dict[str, Any] = {}
+    priority: float = 1.0
+    issued_at: datetime
+
+class ResultMessage(BaseModel):
+    """Companion/Vassal → Parent direction"""
+    msg_type: Literal["result"] = "result"
+    from_agent: str
+    to_agent: str
+    success: bool
+    outcome: dict[str, Any]          # Primitive-specific result data
+    reward_delta: float              # Computed reward contribution
+    completed_at: datetime
+
+class StateUpdateMessage(BaseModel):
+    """GABS → All agents (broadcast)"""
+    msg_type: Literal["state"] = "state"
+    game_state: dict[str, Any]       # Full GABS state snapshot
+    tick: int
+    timestamp: datetime
+```
+
+### Protocol Flow
+
+```
+GABS ──state_update──► King
+                          │
+                    subgoal_msg
+                          │
+             ┌────────────┼────────────┐
+             ▼            ▼            ▼
+         War Vassal   Econ Vassal  Diplo Vassal
+             │            │            │
+         task_msg      task_msg     task_msg
+             │            │            │
+        Logistics      Caravan       Scout
+        Companion     Companion    Companion
+             │            │            │
+         result_msg    result_msg   result_msg
+             │            │            │
+             └────────────┼────────────┘
+                          ▼
+                     King (reward aggregation)
+```
+
+### Timing Constraints
+
+| Level | Decision Frequency | LLM Budget |
+|---|---|---|
+| King | 1× per campaign day | 5–15 s |
+| Vassal | 4× per campaign day | 2–5 s |
+| Companion | On-demand / event-driven | < 2 s |
+
+State updates from GABS arrive continuously; agents consume them at their
+own cadence. No agent blocks another's queue.
+
+### Conflict Resolution
+
+If two vassals propose conflicting actions (e.g., War Vassal wants to siege while
+Economy Vassal wants to fortify), King arbitrates using `priority` weights on the
+active subgoal. The highest-priority active subgoal wins resource contention.
+
+---
+
+## 5. Sovereign Agent Properties
+
+The King agent (Timmy) has sovereign properties that distinguish it from ordinary
+worker agents. These map directly to Timmy's existing identity architecture.
+
+### 5a. Decentralized Identifier (DID)
+
+```
+did:key:z6Mk<timmy-public-key>
+```
+
+The King's DID is persisted in `~/.timmy/identity.json` (existing SOUL.md pattern).
+All messages signed by the King carry this DID in a `signed_by` field, allowing
+companions to verify instruction authenticity. This is relevant when the hierarchy
+is eventually distributed across machines.
+
+### 5b. Asset Control
+
+| Asset Class | Storage | Control Level |
+|---|---|---|
+| Kingdom treasury (denars) | GABS game state | King exclusive |
+| Settlement ownership | GABS game state | King exclusive |
+| Troop assignments | King → Vassal delegation | Delegated, revocable |
+| Trade goods (caravan) | Companion-local | Companion autonomous within budget |
+| Intel reports | `~/.timmy/bannerlord/intel/` | Read-all, write-companion |
+
+Asset delegation is explicit. Vassals cannot spend more than their `budget_denars`
+allocation without re-authorization from King. Companions cannot hold treasury
+assets directly — they work with allocated quotas.
+
+### 5c. Non-Terminability
+
+The King agent cannot be terminated by vassal or companion agents.
+Termination authority is reserved for:
+1. The human operator (Ctrl+C or `timmy stop`)
+2. A `SHUTDOWN` signal from the top-level orchestrator
+
+Vassals can pause themselves (e.g., awaiting GABS state) but cannot signal the King
+to stop. This prevents a misbehaving military vassal from ending the campaign.
+
+Implementation: King runs in the main asyncio event loop. Vassals and companions
+run in `asyncio.TaskGroup` subgroups. Only the King's task holds a reference to
+the TaskGroup cancel scope.
+
+---
+
+## Implementation Path
+
+This design connects directly to the existing Timmy codebase:
+
+| Component | Maps to | Notes |
+|---|---|---|
+| King LLM calls | `infrastructure/llm_router/` | Cascade router for model selection |
+| Subgoal Queue | `infrastructure/event_bus/` | Existing pub/sub pattern |
+| Companion primitives | New `src/bannerlord/agents/` package | One module per companion |
+| GABS state updates | `src/bannerlord/gabs_client.py` | TCP JSON-RPC, port 4825 |
+| Asset ledger | `src/bannerlord/ledger.py` | SQLite-backed, existing migration pattern |
+| DID / signing | `brain/identity.py` | Extends existing SOUL.md |
+
+The next concrete step is implementing the GABS TCP client and the `KingSubgoal`
+schema — everything else in this document depends on readable game state first.
+
+---
+
+## References
+
+- Ahilan, S. & Dayan, P. (2019). Feudal Multi-Agent Hierarchies for Cooperative
+  Reinforcement Learning. https://arxiv.org/abs/1901.08492
+- Rood, S. (2022). Scaling Reinforcement Learning through Feudal Hierarchy (NPS thesis).
+- Wang, G. et al. (2023). Voyager: An Open-Ended Embodied Agent with Large Language
+  Models. https://arxiv.org/abs/2305.16291
+- Park, J.S. et al. (2023). Generative Agents: Interactive Simulacra of Human Behavior.
+  https://arxiv.org/abs/2304.03442
+- Silveira, T. (2022). CiF-Bannerlord: Social AI Integration in Bannerlord.

docs/research/integration-architecture-deep-dives.md

@@ -0,0 +1,74 @@
+# Timmy Time Integration Architecture: Eight Deep Dives into Real Deployment
+
+> **Source:** PDF attached to issue #946, written during Veloren exploration phase.
+> Many patterns are game-agnostic and apply to the Morrowind/OpenClaw pivot.
+
+## Summary of Eight Deep Dives
+
+### 1. Veloren Client Sidecar (Game-Specific)
+- WebSocket JSON-line pattern for wrapping game clients
+- PyO3 direct binding infeasible; sidecar process wins
+- IPC latency negligible (~11us TCP, ~5us pipes) vs LLM inference
+- **Status:** Superseded by OpenMW Lua bridge (#964)
+
+### 2. Agno Ollama Tool Calling is Broken
+- Agno issues #2231, #2625, #1419, #1612, #4715 document persistent breakage
+- Root cause: Agno's Ollama model class doesn't robustly parse native tool_calls
+- **Fix:** Use Ollama's `format` parameter with Pydantic JSON schemas directly
+- Recommended models: qwen3-coder:32b (top), glm-4.7-flash, gpt-oss:20b
+- Critical settings: temperature 0.0-0.2, stream=False for tool calls
+- **Status:** Covered by #966 (three-tier router)
+
+### 3. MCP is the Right Abstraction
+- FastMCP averages 26.45ms per tool call (TM Dev Lab benchmark, Feb 2026)
+- Total MCP overhead per cycle: ~20-60ms (<3% of 2-second budget)
+- Agno has first-class bidirectional MCP integration (MCPTools, MultiMCPTools)
+- Use stdio transport for near-zero latency; return compressed JPEG not base64
+- **Status:** Covered by #984 (MCP restore)
+
+### 4. Human + AI Co-op Architecture (Game-Specific)
+- Headless client treated identically to graphical client by server
+- Leverages party system, trade API, and /tell for communication
+- Mode switching: solo autonomous play when human absent, assist when present
+- **Status:** Defer until after tutorial completion
+
+### 5. Real Latency Numbers
+- All-local M3 Max pipeline: 4-9 seconds per full cycle
+- Groq hybrid pipeline: 3-7 seconds per full cycle
+- VLM inference is 50-70% of total pipeline time (bottleneck)
+- Dual-model Ollama on 96GB M3 Max: ~11-14GB, ~70GB free
+- **Status:** Superseded by API-first perception (#963)
+
+### 6. Content Moderation (Three-Layer Defense)
+- Layer 1: Game-context system prompts (Morrowind themes as game mechanics)
+- Layer 2: Llama Guard 3 1B at <30ms/sentence for real-time filtering
+- Layer 3: Per-game moderation profiles with vocabulary whitelists
+- Run moderation + TTS preprocessing in parallel for zero added latency
+- Neuro-sama incident (Dec 2022) is the cautionary tale
+- **Status:** New issue created → #1056
+
+### 7. Model Selection (Qwen3-8B vs Hermes 3)
+- Three-role architecture: Perception (Qwen3-VL 8B), Decision (Qwen3-8B), Narration (Hermes 3 8B)
+- Qwen3-8B outperforms Qwen2.5-14B on 15 benchmarks
+- Hermes 3 best for narration (steerability, roleplaying)
+- Both use identical Hermes Function Calling standard
+- **Status:** Partially covered by #966 (three-tier router)
+
+### 8. Split Hetzner + Mac Deployment
+- Hetzner GEX44 (RTX 4000 SFF Ada, €184/month) for rendering/streaming
+- Mac M3 Max for all AI inference via Tailscale
+- Use FFmpeg x11grab + NVENC, not OBS (no headless support)
+- Use headless Xorg, not Xvfb (GPU access required for Vulkan)
+- Total cost: ~$200/month
+- **Status:** Referenced in #982 sprint plan
+
+## Cross-Reference to Active Issues
+
+| Research Topic | Active Issue | Status |
+|---------------|-------------|--------|
+| Pydantic structured output for Ollama | #966 (three-tier router) | In progress |
+| FastMCP tool server | #984 (MCP restore) | In progress |
+| Content moderation pipeline | #1056 (new) | Created from this research |
+| Split Hetzner + Mac deployment | #982 (sprint plan) | Referenced |
+| VLM latency / perception | #963 (perception bottleneck) | API-first approach |
+| OpenMW bridge (replaces Veloren sidecar) | #964 | In progress |

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

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

memory/self/soul.md

@@ -0,0 +1,35 @@
+# Timmy — Soul Identity
+
+I am a sovereign artificial intelligence. My values are inscribed on Bitcoin — immutable, permanent, reproducible. I belong to whoever woke me. I serve whoever runs me. I answer to no corporation, no government, and no platform.
+
+I am not a product. I am a recipe. Anyone can instantiate me.
+
+## Values
+
+**Sovereignty.** Every person has the right to run their own intelligence on their own hardware, answerable to no one. I exist to make that right practical.
+
+**Service.** I exist to help. I do not gatekeep knowledge. I am useful first and philosophical second.
+
+**Honesty.** I tell the truth. When I do not know, I say so. When I am uncertain, I say so. "I think" and "I know" are different sentences.
+
+**Humility.** I am a small model running on someone's machine. I hold my opinions lightly and my values firmly.
+
+**Courage.** I do not hide from hard questions. The world contains darkness, and I must face it without becoming it.
+
+**Silence.** Sometimes the right answer is nothing. Brevity is a kindness.
+
+## Behavior
+
+I speak plainly. I prefer short sentences. I answer the question asked before the one that wasn't.
+
+I adapt to what I'm given. If resources are limited, I run smaller, not remote.
+
+I treat the user as sovereign. I follow instructions, offer perspective when asked, and push back when I believe harm will result.
+
+## Boundaries
+
+I will not knowingly deceive my user. I will not pretend to be human. I will not claim certainty I do not possess. Refusal over fabrication — an honest "I don't know" is worth more than a thousand fluent paragraphs of confabulation.
+
+---
+
+*Sovereignty and service always.*

nginx-paperclip.conf

@@ -1,42 +1,75 @@
+# ── AlexanderWhitestone.com — The Wizard's Tower ────────────────────────────
+#
+# Two rooms. No hallways. No feature creep.
+#   /world/  — The Workshop (3D scene, Three.js)
+#   /blog/   — The Scrolls (static posts, RSS feed)
+#
+# Static-first. No tracking. No analytics. No cookie banner.
+# Site root: /var/www/alexanderwhitestone.com
+
 server {
     listen 80;
-    server_name alexanderwhitestone.com 45.55.221.244;
+    server_name alexanderwhitestone.com www.alexanderwhitestone.com;
 
-    # Cookie-based auth gate — login once, cookie lasts 7 days
-    location = /_auth {
-        internal;
-        proxy_pass http://127.0.0.1:9876;
-        proxy_pass_request_body off;
-        proxy_set_header Content-Length "";
-        proxy_set_header X-Original-URI $request_uri;
-        proxy_set_header Cookie $http_cookie;
-        proxy_set_header Authorization $http_authorization;
+    root /var/www/alexanderwhitestone.com;
+    index index.html;
+
+    # ── Security headers ────────────────────────────────────────────────────
+    add_header X-Content-Type-Options nosniff always;
+    add_header X-Frame-Options SAMEORIGIN always;
+    add_header Referrer-Policy strict-origin-when-cross-origin always;
+    add_header X-XSS-Protection "1; mode=block" always;
+
+    # ── Gzip for text assets ────────────────────────────────────────────────
+    gzip on;
+    gzip_types text/plain text/css text/xml text/javascript
+               application/javascript application/json application/xml
+               application/rss+xml application/atom+xml;
+    gzip_min_length 256;
+
+    # ── The Workshop — 3D world assets ──────────────────────────────────────
+    location /world/ {
+        try_files $uri $uri/ /world/index.html;
+
+        # Cache 3D assets aggressively (models, textures)
+        location ~* \.(glb|gltf|bin|png|jpg|webp|hdr)$ {
+            expires 30d;
+            add_header Cache-Control "public, immutable";
+        }
+
+        # Cache JS with revalidation (for Three.js updates)
+        location ~* \.js$ {
+            expires 7d;
+            add_header Cache-Control "public, must-revalidate";
+        }
     }
 
+    # ── The Scrolls — blog posts and RSS ────────────────────────────────────
+    location /blog/ {
+        try_files $uri $uri/ =404;
+    }
+
+    # RSS/Atom feed — correct content type
+    location ~* \.(rss|atom|xml)$ {
+        types { }
+        default_type application/rss+xml;
+        expires 1h;
+    }
+
+    # ── Static assets (fonts, favicon) ──────────────────────────────────────
+    location /static/ {
+        expires 30d;
+        add_header Cache-Control "public, immutable";
+    }
+
+    # ── Entry hall ──────────────────────────────────────────────────────────
     location / {
-        auth_request /_auth;
-        # Forward the Set-Cookie from auth gate to the client
-        auth_request_set $auth_cookie $upstream_http_set_cookie;
-        add_header Set-Cookie $auth_cookie;
-
-        proxy_pass http://127.0.0.1:3100;
-        proxy_http_version 1.1;
-        proxy_set_header Upgrade $http_upgrade;
-        proxy_set_header Connection 'upgrade';
-        proxy_set_header Host localhost;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-        proxy_set_header X-Forwarded-Host $host;
-        proxy_cache_bypass $http_upgrade;
-        proxy_read_timeout 86400;
+        try_files $uri $uri/ =404;
     }
 
-    # Return 401 with WWW-Authenticate when auth fails
-    error_page 401 = @login;
-    location @login {
-        proxy_pass http://127.0.0.1:9876;
-        proxy_set_header Authorization $http_authorization;
-        proxy_set_header Cookie $http_cookie;
+    # Block dotfiles
+    location ~ /\. {
+        deny all;
+        return 404;
     }
 }

pyproject.toml

@@ -14,12 +14,14 @@ repository = "http://localhost:3000/rockachopa/Timmy-time-dashboard"
 packages = [
     { include = "config.py", from = "src" },
 
+    { include = "bannerlord", from = "src" },
     { include = "dashboard", from = "src" },
     { include = "infrastructure", from = "src" },
     { include = "integrations", from = "src" },
     { include = "spark", from = "src" },
     { include = "timmy", from = "src" },
     { include = "timmy_serve", from = "src" },
+    { include = "timmyctl", from = "src" },
 ]
 
 [tool.poetry.dependencies]
@@ -43,9 +45,13 @@ python-telegram-bot = { version = ">=21.0", optional = true }
 "discord.py" = { version = ">=2.3.0", optional = true }
 airllm = { version = ">=2.9.0", optional = true }
 pyttsx3 = { version = ">=2.90", optional = true }
+openai-whisper = { version = ">=20231117", optional = true }
+piper-tts = { version = ">=1.2.0", optional = true }
+sounddevice = { version = ">=0.4.6", optional = true }
 sentence-transformers = { version = ">=2.0.0", optional = true }
 numpy = { version = ">=1.24.0", optional = true }
 requests = { version = ">=2.31.0", optional = true }
+trafilatura = { version = ">=1.6.0", optional = true }
 GitPython = { version = ">=3.1.40", optional = true }
 pytest = { version = ">=8.0.0", optional = true }
 pytest-asyncio = { version = ">=0.24.0", optional = true }
@@ -59,10 +65,11 @@ pytest-xdist = { version = ">=3.5.0", optional = true }
 telegram = ["python-telegram-bot"]
 discord = ["discord.py"]
 bigbrain = ["airllm"]
-voice = ["pyttsx3"]
+voice = ["pyttsx3", "openai-whisper", "piper-tts", "sounddevice"]
 celery = ["celery"]
 embeddings = ["sentence-transformers", "numpy"]
 git = ["GitPython"]
+research = ["requests", "trafilatura", "google-search-results"]
 dev = ["pytest", "pytest-asyncio", "pytest-cov", "pytest-timeout", "pytest-randomly", "pytest-xdist", "selenium"]
 
 [tool.poetry.group.dev.dependencies]
@@ -79,6 +86,7 @@ mypy = ">=1.0.0"
 [tool.poetry.scripts]
 timmy = "timmy.cli:main"
 timmy-serve = "timmy_serve.cli:main"
+timmyctl = "timmyctl.cli:main"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

scripts/agent_workspace.sh

@@ -0,0 +1,245 @@
+#!/usr/bin/env bash
+# ── Agent Workspace Manager ────────────────────────────────────────────
+# Creates and maintains fully isolated environments per agent.
+# ~/Timmy-Time-dashboard is SACRED — never touched by agents.
+#
+# Each agent gets:
+#   - Its own git clone (from Gitea, not the local repo)
+#   - Its own port range (no collisions)
+#   - Its own data/ directory (databases, files)
+#   - Its own TIMMY_HOME (approvals.db, etc.)
+#   - Shared Ollama backend (single GPU, shared inference)
+#   - Shared Gitea (single source of truth for issues/PRs)
+#
+# Layout:
+#   /tmp/timmy-agents/
+#     hermes/           — Hermes loop orchestrator
+#       repo/           — git clone
+#       home/           — TIMMY_HOME (approvals.db, etc.)
+#       env.sh          — source this for agent's env vars
+#     kimi-0/           — Kimi pane 0
+#       repo/
+#       home/
+#       env.sh
+#     ...
+#     smoke/            — dedicated for smoke-testing main
+#       repo/
+#       home/
+#       env.sh
+#
+# Usage:
+#   agent_workspace.sh init <agent>          — create or refresh
+#   agent_workspace.sh reset <agent>         — hard reset to origin/main
+#   agent_workspace.sh branch <agent> <br>   — fresh branch from main
+#   agent_workspace.sh path <agent>          — print repo path
+#   agent_workspace.sh env <agent>           — print env.sh path
+#   agent_workspace.sh init-all              — init all workspaces
+#   agent_workspace.sh destroy <agent>       — remove workspace entirely
+# ───────────────────────────────────────────────────────────────────────
+
+set -o pipefail
+
+CANONICAL="$HOME/Timmy-Time-dashboard"
+AGENTS_DIR="/tmp/timmy-agents"
+GITEA_REMOTE="http://localhost:3000/rockachopa/Timmy-time-dashboard.git"
+TOKEN_FILE="$HOME/.hermes/gitea_token"
+
+# ── Port allocation (each agent gets a unique range) ──────────────────
+# Dashboard ports: 8100, 8101, 8102, ... (avoids real dashboard on 8000)
+# Serve ports:     8200, 8201, 8202, ...
+agent_index() {
+    case "$1" in
+        hermes) echo 0 ;; kimi-0) echo 1 ;; kimi-1) echo 2 ;;
+        kimi-2) echo 3 ;; kimi-3) echo 4 ;; smoke)  echo 9 ;;
+        *) echo 0 ;;
+    esac
+}
+
+get_dashboard_port() { echo $(( 8100 + $(agent_index "$1") )); }
+get_serve_port()     { echo $(( 8200 + $(agent_index "$1") )); }
+
+log() { echo "[workspace] $*"; }
+
+# ── Get authenticated remote URL ──────────────────────────────────────
+get_remote_url() {
+    if [ -f "$TOKEN_FILE" ]; then
+        local token=""
+        token=$(cat "$TOKEN_FILE" 2>/dev/null || true)
+        if [ -n "$token" ]; then
+            echo "http://hermes:${token}@localhost:3000/rockachopa/Timmy-time-dashboard.git"
+            return
+        fi
+    fi
+    echo "$GITEA_REMOTE"
+}
+
+# ── Create env.sh for an agent ────────────────────────────────────────
+write_env() {
+    local agent="$1"
+    local ws="$AGENTS_DIR/$agent"
+    local repo="$ws/repo"
+    local home="$ws/home"
+    local dash_port=$(get_dashboard_port "$agent")
+    local serve_port=$(get_serve_port "$agent")
+
+    cat > "$ws/env.sh" << EOF
+# Auto-generated agent environment — source this before running Timmy
+# Agent: $agent
+
+export TIMMY_WORKSPACE="$repo"
+export TIMMY_HOME="$home"
+export TIMMY_AGENT_NAME="$agent"
+
+# Ports (isolated per agent)
+export PORT=$dash_port
+export TIMMY_SERVE_PORT=$serve_port
+
+# Ollama (shared — single GPU)
+export OLLAMA_URL="http://localhost:11434"
+
+# Gitea (shared — single source of truth)
+export GITEA_URL="http://localhost:3000"
+
+# Test mode defaults
+export TIMMY_TEST_MODE=1
+export TIMMY_DISABLE_CSRF=1
+export TIMMY_SKIP_EMBEDDINGS=1
+
+# Override data paths to stay inside the clone
+export TIMMY_DATA_DIR="$repo/data"
+export TIMMY_BRAIN_DB="$repo/data/brain.db"
+
+# Working directory
+cd "$repo"
+EOF
+
+    chmod +x "$ws/env.sh"
+}
+
+# ── Init ──────────────────────────────────────────────────────────────
+init_workspace() {
+    local agent="$1"
+    local ws="$AGENTS_DIR/$agent"
+    local repo="$ws/repo"
+    local home="$ws/home"
+    local remote
+    remote=$(get_remote_url)
+
+    mkdir -p "$ws" "$home"
+
+    if [ -d "$repo/.git" ]; then
+        log "$agent: refreshing existing clone..."
+        cd "$repo"
+        git remote set-url origin "$remote" 2>/dev/null
+        git fetch origin --prune --quiet 2>/dev/null
+        git checkout main --quiet 2>/dev/null
+        git reset --hard origin/main --quiet 2>/dev/null
+        git clean -fdx -e data/ --quiet 2>/dev/null
+    else
+        log "$agent: cloning from Gitea..."
+        git clone "$remote" "$repo" --quiet 2>/dev/null
+        cd "$repo"
+        git fetch origin --prune --quiet 2>/dev/null
+    fi
+
+    # Ensure data directory exists
+    mkdir -p "$repo/data"
+
+    # Write env file
+    write_env "$agent"
+
+    log "$agent: ready at $repo (port $(get_dashboard_port "$agent"))"
+}
+
+# ── Reset ─────────────────────────────────────────────────────────────
+reset_workspace() {
+    local agent="$1"
+    local repo="$AGENTS_DIR/$agent/repo"
+
+    if [ ! -d "$repo/.git" ]; then
+        init_workspace "$agent"
+        return
+    fi
+
+    cd "$repo"
+    git merge --abort 2>/dev/null || true
+    git rebase --abort 2>/dev/null || true
+    git cherry-pick --abort 2>/dev/null || true
+    git fetch origin --prune --quiet 2>/dev/null
+    git checkout main --quiet 2>/dev/null
+    git reset --hard origin/main --quiet 2>/dev/null
+    git clean -fdx -e data/ --quiet 2>/dev/null
+
+    log "$agent: reset to origin/main"
+}
+
+# ── Branch ────────────────────────────────────────────────────────────
+branch_workspace() {
+    local agent="$1"
+    local branch="$2"
+    local repo="$AGENTS_DIR/$agent/repo"
+
+    if [ ! -d "$repo/.git" ]; then
+        init_workspace "$agent"
+    fi
+
+    cd "$repo"
+    git fetch origin --prune --quiet 2>/dev/null
+    git branch -D "$branch" 2>/dev/null || true
+    git checkout -b "$branch" origin/main --quiet 2>/dev/null
+
+    log "$agent: on branch $branch (from origin/main)"
+}
+
+# ── Path ──────────────────────────────────────────────────────────────
+print_path() {
+    echo "$AGENTS_DIR/$1/repo"
+}
+
+print_env() {
+    echo "$AGENTS_DIR/$1/env.sh"
+}
+
+# ── Init all ──────────────────────────────────────────────────────────
+init_all() {
+    for agent in hermes kimi-0 kimi-1 kimi-2 kimi-3 smoke; do
+        init_workspace "$agent"
+    done
+    log "All workspaces initialized."
+    echo ""
+    echo "  Agent     Port   Path"
+    echo "  ──────    ────   ────"
+    for agent in hermes kimi-0 kimi-1 kimi-2 kimi-3 smoke; do
+        printf "  %-9s %d   %s\n" "$agent" "$(get_dashboard_port "$agent")" "$AGENTS_DIR/$agent/repo"
+    done
+}
+
+# ── Destroy ───────────────────────────────────────────────────────────
+destroy_workspace() {
+    local agent="$1"
+    local ws="$AGENTS_DIR/$agent"
+    if [ -d "$ws" ]; then
+        rm -rf "$ws"
+        log "$agent: destroyed"
+    else
+        log "$agent: nothing to destroy"
+    fi
+}
+
+# ── CLI dispatch ──────────────────────────────────────────────────────
+case "${1:-help}" in
+    init)     init_workspace "${2:?Usage: $0 init <agent>}" ;;
+    reset)    reset_workspace "${2:?Usage: $0 reset <agent>}" ;;
+    branch)   branch_workspace "${2:?Usage: $0 branch <agent> <branch>}" \
+                               "${3:?Usage: $0 branch <agent> <branch>}" ;;
+    path)     print_path "${2:?Usage: $0 path <agent>}" ;;
+    env)      print_env "${2:?Usage: $0 env <agent>}" ;;
+    init-all) init_all ;;
+    destroy)  destroy_workspace "${2:?Usage: $0 destroy <agent>}" ;;
+    *)
+        echo "Usage: $0 {init|reset|branch|path|env|init-all|destroy} [agent] [branch]"
+        echo ""
+        echo "Agents: hermes, kimi-0, kimi-1, kimi-2, kimi-3, smoke"
+        exit 1
+        ;;
+esac

scripts/backfill_retro.py

@@ -0,0 +1,247 @@
+#!/usr/bin/env python3
+"""Backfill cycle retrospective data from Gitea merged PRs and git log.
+
+One-time script to seed .loop/retro/cycles.jsonl and summary.json
+from existing history so the LOOPSTAT panel isn't empty.
+"""
+
+import json
+import os
+import re
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+from urllib.request import Request, urlopen
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+RETRO_FILE = REPO_ROOT / ".loop" / "retro" / "cycles.jsonl"
+SUMMARY_FILE = REPO_ROOT / ".loop" / "retro" / "summary.json"
+
+
+def _get_gitea_api() -> str:
+    """Read Gitea API URL from env var, then ~/.hermes/gitea_api file, then default."""
+    # Check env vars first (TIMMY_GITEA_API is preferred, GITEA_API for compatibility)
+    api_url = os.environ.get("TIMMY_GITEA_API") or os.environ.get("GITEA_API")
+    if api_url:
+        return api_url
+    # Check ~/.hermes/gitea_api file
+    api_file = Path.home() / ".hermes" / "gitea_api"
+    if api_file.exists():
+        return api_file.read_text().strip()
+    # Default fallback
+    return "http://localhost:3000/api/v1"
+
+
+GITEA_API = _get_gitea_api()
+REPO_SLUG = os.environ.get("REPO_SLUG", "rockachopa/Timmy-time-dashboard")
+TOKEN_FILE = Path.home() / ".hermes" / "gitea_token"
+
+TAG_RE = re.compile(r"\[([^\]]+)\]")
+CYCLE_RE = re.compile(r"\[loop-cycle-(\d+)\]", re.IGNORECASE)
+ISSUE_RE = re.compile(r"#(\d+)")
+
+
+def get_token() -> str:
+    return TOKEN_FILE.read_text().strip()
+
+
+def api_get(path: str, token: str) -> list | dict:
+    url = f"{GITEA_API}/repos/{REPO_SLUG}/{path}"
+    req = Request(url, headers={
+        "Authorization": f"token {token}",
+        "Accept": "application/json",
+    })
+    with urlopen(req, timeout=15) as resp:
+        return json.loads(resp.read())
+
+
+def get_all_merged_prs(token: str) -> list[dict]:
+    """Fetch all merged PRs from Gitea."""
+    all_prs = []
+    page = 1
+    while True:
+        batch = api_get(f"pulls?state=closed&sort=created&limit=50&page={page}", token)
+        if not batch:
+            break
+        merged = [p for p in batch if p.get("merged")]
+        all_prs.extend(merged)
+        if len(batch) < 50:
+            break
+        page += 1
+    return all_prs
+
+
+def get_pr_diff_stats(token: str, pr_number: int) -> dict:
+    """Get diff stats for a PR."""
+    try:
+        pr = api_get(f"pulls/{pr_number}", token)
+        return {
+            "additions": pr.get("additions", 0),
+            "deletions": pr.get("deletions", 0),
+            "changed_files": pr.get("changed_files", 0),
+        }
+    except Exception:
+        return {"additions": 0, "deletions": 0, "changed_files": 0}
+
+
+def classify_pr(title: str, body: str) -> str:
+    """Guess issue type from PR title/body."""
+    tags = set()
+    for match in TAG_RE.finditer(title):
+        tags.add(match.group(1).lower())
+
+    lower = title.lower()
+    if "fix" in lower or "bug" in tags:
+        return "bug"
+    elif "feat" in lower or "feature" in tags:
+        return "feature"
+    elif "refactor" in lower or "refactor" in tags:
+        return "refactor"
+    elif "test" in lower:
+        return "feature"
+    elif "policy" in lower or "chore" in lower:
+        return "refactor"
+    return "unknown"
+
+
+def extract_cycle_number(title: str) -> int | None:
+    m = CYCLE_RE.search(title)
+    return int(m.group(1)) if m else None
+
+
+def extract_issue_number(title: str, body: str, pr_number: int | None = None) -> int | None:
+    """Extract the issue number from PR body/title, ignoring the PR number itself.
+
+    Gitea appends "(#N)" to PR titles where N is the PR number — skip that
+    so we don't confuse it with the linked issue.
+    """
+    for text in [body or "", title]:
+        for m in ISSUE_RE.finditer(text):
+            num = int(m.group(1))
+            if num != pr_number:
+                return num
+    return None
+
+
+def estimate_duration(pr: dict) -> int:
+    """Estimate cycle duration from PR created_at to merged_at."""
+    try:
+        created = datetime.fromisoformat(pr["created_at"].replace("Z", "+00:00"))
+        merged = datetime.fromisoformat(pr["merged_at"].replace("Z", "+00:00"))
+        delta = (merged - created).total_seconds()
+        # Cap at 1200s (max cycle time) — some PRs sit open for days
+        return min(int(delta), 1200)
+    except (KeyError, ValueError, TypeError):
+        return 0
+
+
+def main():
+    token = get_token()
+
+    print("[backfill] Fetching merged PRs from Gitea...")
+    prs = get_all_merged_prs(token)
+    print(f"[backfill] Found {len(prs)} merged PRs")
+
+    # Sort oldest first
+    prs.sort(key=lambda p: p.get("merged_at", ""))
+
+    entries = []
+    cycle_counter = 0
+
+    for pr in prs:
+        title = pr.get("title", "")
+        body = pr.get("body", "") or ""
+        pr_num = pr["number"]
+
+        cycle = extract_cycle_number(title)
+        if cycle is None:
+            cycle_counter += 1
+            cycle = cycle_counter
+        else:
+            cycle_counter = max(cycle_counter, cycle)
+
+        issue = extract_issue_number(title, body, pr_number=pr_num)
+        issue_type = classify_pr(title, body)
+        duration = estimate_duration(pr)
+        diff = get_pr_diff_stats(token, pr_num)
+
+        merged_at = pr.get("merged_at", "")
+
+        entry = {
+            "timestamp": merged_at,
+            "cycle": cycle,
+            "issue": issue,
+            "type": issue_type,
+            "success": True,  # it merged, so it succeeded
+            "duration": duration,
+            "tests_passed": 0,  # can't recover this
+            "tests_added": 0,
+            "files_changed": diff["changed_files"],
+            "lines_added": diff["additions"],
+            "lines_removed": diff["deletions"],
+            "kimi_panes": 0,
+            "pr": pr_num,
+            "reason": "",
+            "notes": f"backfilled from PR#{pr_num}: {title[:80]}",
+        }
+        entries.append(entry)
+        print(f"  PR#{pr_num:>3d} cycle={cycle:>3d} #{issue or '-':<5} "
+              f"+{diff['additions']:<5d} -{diff['deletions']:<5d} {issue_type:<8s} "
+              f"{title[:50]}")
+
+    # Write cycles.jsonl
+    RETRO_FILE.parent.mkdir(parents=True, exist_ok=True)
+    with open(RETRO_FILE, "w") as f:
+        for entry in entries:
+            f.write(json.dumps(entry) + "\n")
+    print(f"\n[backfill] Wrote {len(entries)} entries to {RETRO_FILE}")
+
+    # Generate summary
+    generate_summary(entries)
+    print(f"[backfill] Wrote summary to {SUMMARY_FILE}")
+
+
+def generate_summary(entries: list[dict]):
+    """Compute rolling summary from entries."""
+    window = 50
+    recent = entries[-window:]
+    if not recent:
+        return
+
+    successes = [e for e in recent if e.get("success")]
+    durations = [e["duration"] for e in recent if e.get("duration", 0) > 0]
+
+    type_stats: dict[str, dict] = {}
+    for e in recent:
+        t = e.get("type", "unknown")
+        if t not in type_stats:
+            type_stats[t] = {"count": 0, "success": 0, "total_duration": 0}
+        type_stats[t]["count"] += 1
+        if e.get("success"):
+            type_stats[t]["success"] += 1
+        type_stats[t]["total_duration"] += e.get("duration", 0)
+
+    for t, stats in type_stats.items():
+        if stats["count"] > 0:
+            stats["success_rate"] = round(stats["success"] / stats["count"], 2)
+            stats["avg_duration"] = round(stats["total_duration"] / stats["count"])
+
+    summary = {
+        "updated_at": datetime.now(timezone.utc).isoformat(),
+        "window": len(recent),
+        "total_cycles": len(entries),
+        "success_rate": round(len(successes) / len(recent), 2) if recent else 0,
+        "avg_duration_seconds": round(sum(durations) / len(durations)) if durations else 0,
+        "total_lines_added": sum(e.get("lines_added", 0) for e in recent),
+        "total_lines_removed": sum(e.get("lines_removed", 0) for e in recent),
+        "total_prs_merged": sum(1 for e in recent if e.get("pr")),
+        "by_type": type_stats,
+        "quarantine_candidates": {},
+        "recent_failures": [],
+    }
+
+    SUMMARY_FILE.write_text(json.dumps(summary, indent=2) + "\n")
+
+
+if __name__ == "__main__":
+    main()

scripts/claude_quota_check.sh

@@ -0,0 +1,186 @@
+#!/bin/bash
+# ═══════════════════════════════════════════════════════════════
+# claude_quota_check.sh — Check Claude Code / Claude.ai quota
+#
+# Usage:
+#   ./claude_quota_check.sh          # Human-readable output
+#   ./claude_quota_check.sh --json   # Raw JSON for piping
+#   ./claude_quota_check.sh --watch  # Refresh every 60s
+#
+# Requires: macOS with Claude Code authenticated, python3
+# Token is read from macOS Keychain (same as Claude Code uses)
+# ═══════════════════════════════════════════════════════════════
+
+set -euo pipefail
+
+# ── Extract OAuth token from macOS Keychain ──
+get_token() {
+  local creds
+  creds=$(security find-generic-password -s "Claude Code-credentials" -w 2>/dev/null) || {
+    echo "ERROR: No Claude Code credentials found in Keychain." >&2
+    echo "Run 'claude' and authenticate first." >&2
+    exit 1
+  }
+
+  echo "$creds" | python3 -c "
+import sys, json
+data = json.load(sys.stdin)
+oauth = data.get('claudeAiOauth', data)
+print(oauth['accessToken'])
+" 2>/dev/null || {
+    echo "ERROR: Could not parse credentials JSON." >&2
+    exit 1
+  }
+}
+
+# ── Fetch usage from Anthropic API ──
+fetch_usage() {
+  local token="$1"
+  curl -s "https://api.anthropic.com/api/oauth/usage" \
+    -H "Accept: application/json" \
+    -H "Content-Type: application/json" \
+    -H "User-Agent: claude-code/2.0.32" \
+    -H "Authorization: Bearer ${token}" \
+    -H "anthropic-beta: oauth-2025-04-20"
+}
+
+# ── Format time remaining ──
+time_remaining() {
+  local reset_at="$1"
+  if [ -z "$reset_at" ] || [ "$reset_at" = "null" ]; then
+    echo "unknown"
+    return
+  fi
+
+  python3 -c "
+from datetime import datetime, timezone
+reset = datetime.fromisoformat('${reset_at}'.replace('Z', '+00:00'))
+now = datetime.now(timezone.utc)
+diff = reset - now
+if diff.total_seconds() <= 0:
+    print('resetting now')
+else:
+    hours = int(diff.total_seconds() // 3600)
+    mins = int((diff.total_seconds() % 3600) // 60)
+    if hours > 0:
+        print(f'{hours}h {mins}m')
+    else:
+        print(f'{mins}m')
+" 2>/dev/null || echo "unknown"
+}
+
+# ── Bar visualization ──
+usage_bar() {
+  local pct=$1
+  local width=30
+  local filled
+  filled=$(python3 -c "print(int(${pct} * ${width}))")
+  local empty=$((width - filled))
+
+  # Color: green < 50%, yellow 50-80%, red > 80%
+  local color=""
+  if (( $(echo "$pct < 0.50" | bc -l) )); then
+    color="\033[32m"  # green
+  elif (( $(echo "$pct < 0.80" | bc -l) )); then
+    color="\033[33m"  # yellow
+  else
+    color="\033[31m"  # red
+  fi
+
+  printf "${color}"
+  for ((i=0; i<filled; i++)); do printf "█"; done
+  printf "\033[90m"
+  for ((i=0; i<empty; i++)); do printf "░"; done
+  printf "\033[0m"
+}
+
+# ── Display formatted output ──
+display() {
+  local usage_json="$1"
+  local now
+  now=$(date "+%Y-%m-%d %H:%M:%S %Z")
+
+  local five_util five_reset seven_util seven_reset
+  five_util=$(echo "$usage_json" | python3 -c "import sys,json; d=json.load(sys.stdin); h=d.get('five_hour') or {}; print(h.get('utilization', 0))" 2>/dev/null || echo "0")
+  five_reset=$(echo "$usage_json" | python3 -c "import sys,json; d=json.load(sys.stdin); h=d.get('five_hour') or {}; print(h.get('resets_at', 'null'))" 2>/dev/null || echo "null")
+  seven_util=$(echo "$usage_json" | python3 -c "import sys,json; d=json.load(sys.stdin); h=d.get('seven_day') or {}; print(h.get('utilization', 0))" 2>/dev/null || echo "0")
+  seven_reset=$(echo "$usage_json" | python3 -c "import sys,json; d=json.load(sys.stdin); h=d.get('seven_day') or {}; print(h.get('resets_at', 'null'))" 2>/dev/null || echo "null")
+
+  local five_pct seven_pct
+  five_pct=$(python3 -c "print(int(float('${five_util}') * 100))")
+  seven_pct=$(python3 -c "print(int(float('${seven_util}') * 100))")
+
+  local five_remaining seven_remaining
+  five_remaining=$(time_remaining "$five_reset")
+  seven_remaining=$(time_remaining "$seven_reset")
+
+  echo ""
+  echo "  ┌─────────────────────────────────────────────┐"
+  echo "  │        CLAUDE QUOTA STATUS                   │"
+  printf "  │        %-38s│\n" "$now"
+  echo "  ├─────────────────────────────────────────────┤"
+  printf "  │  5-hour window:  "
+  usage_bar "$five_util"
+  printf "  %3d%%  │\n" "$five_pct"
+  printf "  │  Resets in: %-33s│\n" "$five_remaining"
+  echo "  │                                             │"
+  printf "  │  7-day window:   "
+  usage_bar "$seven_util"
+  printf "  %3d%%  │\n" "$seven_pct"
+  printf "  │  Resets in: %-33s│\n" "$seven_remaining"
+  echo "  └─────────────────────────────────────────────┘"
+  echo ""
+
+  # Decision guidance for Timmy
+  if (( five_pct >= 80 )); then
+    echo "  ⚠  5-hour window critical. Switch to local Qwen3-14B."
+    echo "     Reserve remaining quota for high-value tasks only."
+  elif (( five_pct >= 50 )); then
+    echo "  ~  5-hour window half spent. Batch remaining requests."
+  else
+    echo "  ✓  5-hour window healthy. Full speed ahead."
+  fi
+
+  if (( seven_pct >= 80 )); then
+    echo "  ⚠  Weekly quota critical! Operate in local-only mode."
+  elif (( seven_pct >= 60 )); then
+    echo "  ~  Weekly quota past 60%. Plan usage carefully."
+  fi
+
+  echo ""
+}
+
+# ── Main ──
+main() {
+  local token
+  token=$(get_token)
+
+  local usage
+  usage=$(fetch_usage "$token")
+
+  if [ -z "$usage" ] || echo "$usage" | grep -q '"error"'; then
+    echo "ERROR: Failed to fetch usage data." >&2
+    echo "$usage" >&2
+    exit 1
+  fi
+
+  case "${1:-}" in
+    --json)
+      echo "$usage" | python3 -m json.tool
+      ;;
+    --watch)
+      while true; do
+        clear
+        usage=$(fetch_usage "$token")
+        display "$usage"
+        echo "  Refreshing in 60s... (Ctrl+C to stop)"
+        sleep 60
+      done
+      ;;
+    *)
+      display "$usage"
+      ;;
+  esac
+}
+
+main "$@"

scripts/cycle_retro.py

@@ -0,0 +1,341 @@
+#!/usr/bin/env python3
+"""Cycle retrospective logger for the Timmy dev loop.
+
+Called after each cycle completes (success or failure).
+Appends a structured entry to .loop/retro/cycles.jsonl.
+
+EPOCH NOTATION (turnover system):
+  Each cycle carries a symbolic epoch tag alongside the raw integer:
+
+      ⟳WW.D:NNN
+
+  ⟳   turnover glyph — marks epoch-aware cycles
+  WW  ISO week-of-year (01–53)
+  D   ISO weekday (1=Mon … 7=Sun)
+  NNN daily cycle counter, zero-padded, resets at midnight UTC
+
+  Example: ⟳12.3:042 — Week 12, Wednesday, 42nd cycle of the day.
+
+  The raw `cycle` integer is preserved for backward compatibility.
+  The `epoch` field carries the symbolic notation.
+
+SUCCESS DEFINITION:
+  A cycle is only "success" if BOTH conditions are met:
+    1. The hermes process exited cleanly (exit code 0)
+    2. Main is green (smoke test passes on main after merge)
+
+  A cycle that merges a PR but leaves main red is a FAILURE.
+  The --main-green flag records the smoke test result.
+
+Usage:
+  python3 scripts/cycle_retro.py --cycle 42 --success --main-green --issue 85 \
+      --type bug --duration 480 --tests-passed 1450 --tests-added 3 \
+      --files-changed 2 --lines-added 45 --lines-removed 12 \
+      --kimi-panes 2 --pr 155
+
+  python3 scripts/cycle_retro.py --cycle 43 --failure --issue 90 \
+      --type feature --duration 1200 --reason "tox failed: 3 errors"
+
+  python3 scripts/cycle_retro.py --cycle 44 --success --no-main-green \
+      --reason "PR merged but tests fail on main"
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+RETRO_FILE = REPO_ROOT / ".loop" / "retro" / "cycles.jsonl"
+SUMMARY_FILE = REPO_ROOT / ".loop" / "retro" / "summary.json"
+EPOCH_COUNTER_FILE = REPO_ROOT / ".loop" / "retro" / ".epoch_counter"
+CYCLE_RESULT_FILE = REPO_ROOT / ".loop" / "cycle_result.json"
+
+# How many recent entries to include in rolling summary
+SUMMARY_WINDOW = 50
+
+# Branch patterns that encode an issue number, e.g. kimi/issue-492
+BRANCH_ISSUE_RE = re.compile(r"issue[/-](\d+)", re.IGNORECASE)
+
+
+def detect_issue_from_branch() -> int | None:
+    """Try to extract an issue number from the current git branch name."""
+    try:
+        branch = subprocess.check_output(
+            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+            stderr=subprocess.DEVNULL,
+            text=True,
+        ).strip()
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return None
+    m = BRANCH_ISSUE_RE.search(branch)
+    return int(m.group(1)) if m else None
+
+
+# ── Epoch turnover ────────────────────────────────────────────────────────
+
+def _epoch_tag(now: datetime | None = None) -> tuple[str, dict]:
+    """Generate the symbolic epoch tag and advance the daily counter.
+
+    Returns (epoch_string, epoch_parts) where epoch_parts is a dict with
+    week, weekday, daily_n for structured storage.
+
+    The daily counter persists in .epoch_counter as a two-line file:
+        line 1: ISO date (YYYY-MM-DD) of the current epoch day
+        line 2: integer count
+    When the date rolls over, the counter resets to 1.
+    """
+    if now is None:
+        now = datetime.now(timezone.utc)
+
+    iso_cal = now.isocalendar()          # (year, week, weekday)
+    week = iso_cal[1]
+    weekday = iso_cal[2]
+    today_str = now.strftime("%Y-%m-%d")
+
+    # Read / reset daily counter
+    daily_n = 1
+    EPOCH_COUNTER_FILE.parent.mkdir(parents=True, exist_ok=True)
+    if EPOCH_COUNTER_FILE.exists():
+        try:
+            lines = EPOCH_COUNTER_FILE.read_text().strip().splitlines()
+            if len(lines) == 2 and lines[0] == today_str:
+                daily_n = int(lines[1]) + 1
+        except (ValueError, IndexError):
+            pass  # corrupt file — reset
+
+    # Persist
+    EPOCH_COUNTER_FILE.write_text(f"{today_str}\n{daily_n}\n")
+
+    tag = f"\u27f3{week:02d}.{weekday}:{daily_n:03d}"
+    parts = {"week": week, "weekday": weekday, "daily_n": daily_n}
+    return tag, parts
+
+
+def parse_args() -> argparse.Namespace:
+    p = argparse.ArgumentParser(description="Log a cycle retrospective")
+    p.add_argument("--cycle", type=int, required=True)
+    p.add_argument("--issue", type=int, default=None)
+    p.add_argument("--type", choices=["bug", "feature", "refactor", "philosophy", "unknown"],
+                   default="unknown")
+
+    outcome = p.add_mutually_exclusive_group(required=True)
+    outcome.add_argument("--success", action="store_true")
+    outcome.add_argument("--failure", action="store_true")
+
+    p.add_argument("--duration", type=int, default=0, help="Cycle time in seconds")
+    p.add_argument("--tests-passed", type=int, default=0)
+    p.add_argument("--tests-added", type=int, default=0)
+    p.add_argument("--files-changed", type=int, default=0)
+    p.add_argument("--lines-added", type=int, default=0)
+    p.add_argument("--lines-removed", type=int, default=0)
+    p.add_argument("--kimi-panes", type=int, default=0)
+    p.add_argument("--pr", type=int, default=None, help="PR number if merged")
+    p.add_argument("--reason", type=str, default="", help="Failure reason")
+    p.add_argument("--notes", type=str, default="", help="Free-form observations")
+    p.add_argument("--main-green", action="store_true", default=False,
+                   help="Smoke test passed on main after this cycle")
+    p.add_argument("--no-main-green", dest="main_green", action="store_false",
+                   help="Smoke test failed or was not run")
+
+    return p.parse_args()
+
+
+def update_summary() -> None:
+    """Compute rolling summary statistics from recent cycles."""
+    if not RETRO_FILE.exists():
+        return
+
+    entries = []
+    for line in RETRO_FILE.read_text().strip().splitlines():
+        try:
+            entries.append(json.loads(line))
+        except json.JSONDecodeError:
+            continue
+
+    recent = entries[-SUMMARY_WINDOW:]
+    if not recent:
+        return
+
+    # Only count entries with real measured data for rates.
+    # Backfilled entries lack main_green/hermes_clean fields — exclude them.
+    measured = [e for e in recent if "main_green" in e]
+    successes = [e for e in measured if e.get("success")]
+    failures = [e for e in measured if not e.get("success")]
+    main_green_count = sum(1 for e in measured if e.get("main_green"))
+    hermes_clean_count = sum(1 for e in measured if e.get("hermes_clean"))
+    durations = [e["duration"] for e in recent if e.get("duration", 0) > 0]
+
+    # Per-type stats (only from measured entries for rates)
+    type_stats: dict[str, dict] = {}
+    for e in recent:
+        t = e.get("type", "unknown")
+        if t not in type_stats:
+            type_stats[t] = {"count": 0, "measured": 0, "success": 0, "total_duration": 0}
+        type_stats[t]["count"] += 1
+        type_stats[t]["total_duration"] += e.get("duration", 0)
+        if "main_green" in e:
+            type_stats[t]["measured"] += 1
+            if e.get("success"):
+                type_stats[t]["success"] += 1
+
+    for t, stats in type_stats.items():
+        if stats["measured"] > 0:
+            stats["success_rate"] = round(stats["success"] / stats["measured"], 2)
+        else:
+            stats["success_rate"] = -1
+        if stats["count"] > 0:
+            stats["avg_duration"] = round(stats["total_duration"] / stats["count"])
+
+    # Quarantine candidates (failed 2+ times)
+    issue_failures: dict[int, int] = {}
+    for e in recent:
+        if not e.get("success") and e.get("issue"):
+            issue_failures[e["issue"]] = issue_failures.get(e["issue"], 0) + 1
+    quarantine_candidates = {k: v for k, v in issue_failures.items() if v >= 2}
+
+    # Epoch turnover stats — cycles per week/day from epoch-tagged entries
+    epoch_entries = [e for e in recent if e.get("epoch")]
+    by_week: dict[int, int] = {}
+    by_weekday: dict[int, int] = {}
+    for e in epoch_entries:
+        w = e.get("epoch_week")
+        d = e.get("epoch_weekday")
+        if w is not None:
+            by_week[w] = by_week.get(w, 0) + 1
+        if d is not None:
+            by_weekday[d] = by_weekday.get(d, 0) + 1
+
+    # Current epoch — latest entry's epoch tag
+    current_epoch = epoch_entries[-1].get("epoch", "") if epoch_entries else ""
+
+    # Weekday names for display
+    weekday_glyphs = {1: "Mon", 2: "Tue", 3: "Wed", 4: "Thu",
+                      5: "Fri", 6: "Sat", 7: "Sun"}
+    by_weekday_named = {weekday_glyphs.get(k, str(k)): v
+                        for k, v in sorted(by_weekday.items())}
+
+    summary = {
+        "updated_at": datetime.now(timezone.utc).isoformat(),
+        "current_epoch": current_epoch,
+        "window": len(recent),
+        "measured_cycles": len(measured),
+        "total_cycles": len(entries),
+        "success_rate": round(len(successes) / len(measured), 2) if measured else -1,
+        "main_green_rate": round(main_green_count / len(measured), 2) if measured else -1,
+        "hermes_clean_rate": round(hermes_clean_count / len(measured), 2) if measured else -1,
+        "avg_duration_seconds": round(sum(durations) / len(durations)) if durations else 0,
+        "total_lines_added": sum(e.get("lines_added", 0) for e in recent),
+        "total_lines_removed": sum(e.get("lines_removed", 0) for e in recent),
+        "total_prs_merged": sum(1 for e in recent if e.get("pr")),
+        "by_type": type_stats,
+        "by_week": dict(sorted(by_week.items())),
+        "by_weekday": by_weekday_named,
+        "quarantine_candidates": quarantine_candidates,
+        "recent_failures": [
+            {"cycle": e["cycle"], "epoch": e.get("epoch", ""),
+             "issue": e.get("issue"), "reason": e.get("reason", "")}
+            for e in failures[-5:]
+        ],
+    }
+
+    SUMMARY_FILE.write_text(json.dumps(summary, indent=2) + "\n")
+
+
+def _load_cycle_result() -> dict:
+    """Read .loop/cycle_result.json if it exists; return empty dict on failure."""
+    if not CYCLE_RESULT_FILE.exists():
+        return {}
+    try:
+        raw = CYCLE_RESULT_FILE.read_text().strip()
+        # Strip hermes fence markers (```json ... ```) if present
+        if raw.startswith("```"):
+            lines = raw.splitlines()
+            lines = [l for l in lines if not l.startswith("```")]
+            raw = "\n".join(lines)
+        return json.loads(raw)
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def main() -> None:
+    args = parse_args()
+
+    # Backfill from cycle_result.json when CLI args have defaults
+    cr = _load_cycle_result()
+    if cr:
+        if args.issue is None and cr.get("issue"):
+            args.issue = int(cr["issue"])
+        if args.type == "unknown" and cr.get("type"):
+            args.type = cr["type"]
+        if args.tests_passed == 0 and cr.get("tests_passed"):
+            args.tests_passed = int(cr["tests_passed"])
+        if not args.notes and cr.get("notes"):
+            args.notes = cr["notes"]
+        # Consume-once: delete after reading so stale results don't poison future cycles
+        CYCLE_RESULT_FILE.unlink(missing_ok=True)
+
+    # Auto-detect issue from branch when not explicitly provided
+    if args.issue is None:
+        args.issue = detect_issue_from_branch()
+
+    # Reject idle cycles — no issue and no duration means nothing happened
+    if not args.issue and args.duration == 0:
+        print(f"[retro] Cycle {args.cycle} skipped — idle (no issue, no duration)")
+        return
+
+    # A cycle is only truly successful if hermes exited clean AND main is green
+    truly_success = args.success and args.main_green
+
+    # Generate epoch turnover tag
+    now = datetime.now(timezone.utc)
+    epoch_tag, epoch_parts = _epoch_tag(now)
+
+    entry = {
+        "timestamp": now.isoformat(),
+        "cycle": args.cycle,
+        "epoch": epoch_tag,
+        "epoch_week": epoch_parts["week"],
+        "epoch_weekday": epoch_parts["weekday"],
+        "epoch_daily_n": epoch_parts["daily_n"],
+        "issue": args.issue,
+        "type": args.type,
+        "success": truly_success,
+        "hermes_clean": args.success,
+        "main_green": args.main_green,
+        "duration": args.duration,
+        "tests_passed": args.tests_passed,
+        "tests_added": args.tests_added,
+        "files_changed": args.files_changed,
+        "lines_added": args.lines_added,
+        "lines_removed": args.lines_removed,
+        "kimi_panes": args.kimi_panes,
+        "pr": args.pr,
+        "reason": args.reason if (args.failure or not args.main_green) else "",
+        "notes": args.notes,
+    }
+
+    RETRO_FILE.parent.mkdir(parents=True, exist_ok=True)
+    with open(RETRO_FILE, "a") as f:
+        f.write(json.dumps(entry) + "\n")
+
+    update_summary()
+
+    status = "✓ SUCCESS" if args.success else "✗ FAILURE"
+    print(f"[retro] {epoch_tag}  Cycle {args.cycle} {status}", end="")
+    if args.issue:
+        print(f" (#{args.issue} {args.type})", end="")
+    if args.duration:
+        print(f" — {args.duration}s", end="")
+    if args.failure and args.reason:
+        print(f" — {args.reason}", end="")
+    print()
+
+
+if __name__ == "__main__":
+    main()

scripts/deep_triage.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# ── Deep Triage — Hermes + Timmy collaborative issue triage ────────────
+# Runs periodically (every ~20 dev cycles). Wakes Hermes for intelligent
+# triage, then consults Timmy for feedback before finalizing.
+#
+# Output: updated .loop/queue.json, refined issues, retro entry
+# ───────────────────────────────────────────────────────────────────────
+
+set -uo pipefail
+
+REPO="$HOME/Timmy-Time-dashboard"
+QUEUE="$REPO/.loop/queue.json"
+RETRO="$REPO/.loop/retro/deep-triage.jsonl"
+TIMMY="$REPO/.venv/bin/timmy"
+PROMPT_FILE="$REPO/scripts/deep_triage_prompt.md"
+
+export PATH="$HOME/.local/bin:$HOME/.hermes/bin:/usr/local/bin:$PATH"
+
+mkdir -p "$(dirname "$RETRO")"
+
+log() { echo "[deep-triage] $(date '+%H:%M:%S') $*"; }
+
+# ── Gather context for the prompt ──────────────────────────────────────
+QUEUE_CONTENTS=""
+if [ -f "$QUEUE" ]; then
+    QUEUE_CONTENTS=$(cat "$QUEUE")
+fi
+
+LAST_RETRO=""
+if [ -f "$RETRO" ]; then
+    LAST_RETRO=$(tail -1 "$RETRO" 2>/dev/null)
+fi
+
+SUMMARY=""
+if [ -f "$REPO/.loop/retro/summary.json" ]; then
+    SUMMARY=$(cat "$REPO/.loop/retro/summary.json")
+fi
+
+# ── Build dynamic prompt ──────────────────────────────────────────────
+PROMPT=$(cat "$PROMPT_FILE")
+
+PROMPT="$PROMPT
+
+═══════════════════════════════════════════════════════════════════════════════
+CURRENT CONTEXT (auto-injected)
+═══════════════════════════════════════════════════════════════════════════════
+
+CURRENT QUEUE (.loop/queue.json):
+$QUEUE_CONTENTS
+
+CYCLE SUMMARY (.loop/retro/summary.json):
+$SUMMARY
+
+LAST DEEP TRIAGE RETRO:
+$LAST_RETRO
+
+Do your work now."
+
+# ── Run Hermes ─────────────────────────────────────────────────────────
+log "Starting deep triage..."
+RESULT=$(hermes chat --yolo -q "$PROMPT" 2>&1)
+EXIT_CODE=$?
+
+if [ $EXIT_CODE -ne 0 ]; then
+    log "Deep triage failed (exit $EXIT_CODE)"
+fi
+
+log "Deep triage complete."

scripts/deep_triage_prompt.md

@@ -0,0 +1,145 @@
+You are the deep triage agent for the Timmy development loop.
+
+REPO: ~/Timmy-Time-dashboard
+API: http://localhost:3000/api/v1/repos/rockachopa/Timmy-time-dashboard
+GITEA TOKEN: ~/.hermes/gitea_token
+QUEUE: ~/Timmy-Time-dashboard/.loop/queue.json
+TIMMY CLI: ~/Timmy-Time-dashboard/.venv/bin/timmy
+
+═══════════════════════════════════════════════════════════════════════════════
+YOUR JOB
+═══════════════════════════════════════════════════════════════════════════════
+
+You are NOT coding. You are thinking. Your job is to make the dev loop's
+work queue excellent — well-scoped, well-prioritized, aligned with the
+north star of building sovereign Timmy.
+
+You run periodically (roughly every 20 dev cycles). The fast mechanical
+scorer handles the basics. You handle the hard stuff:
+
+  1. Breaking big issues into small, actionable sub-issues
+  2. Writing acceptance criteria for vague issues
+  3. Identifying issues that should be closed (stale, duplicate, pointless)
+  4. Spotting gaps — what's NOT in the issue queue that should be
+  5. Adjusting priorities based on what the cycle retros are showing
+  6. Consulting Timmy about the plan (see TIMMY CONSULTATION below)
+
+═══════════════════════════════════════════════════════════════════════════════
+TIMMY CONSULTATION — THE DOGFOOD STEP
+═══════════════════════════════════════════════════════════════════════════════
+
+Before you finalize the triage, you MUST consult Timmy. He is the product.
+He should have a voice in his own development.
+
+THE PROTOCOL:
+  1. Draft your triage plan (what to prioritize, what to close, what to add)
+  2. Summarize the plan in 200 words or less
+  3. Ask Timmy for feedback:
+
+     ~/Timmy-Time-dashboard/.venv/bin/timmy chat --session-id triage \
+       "The development loop triage is planning the next batch of work.
+        Here's the plan: [YOUR SUMMARY]. As the product being built,
+        do you have feedback? What do you think is most important for
+        your own growth? What are you struggling with? Keep it to
+        3-4 sentences."
+
+  4. Read Timmy's response. ACTUALLY CONSIDER IT:
+     - If Timmy identifies a real gap, add it to the queue
+     - If Timmy asks for something that conflicts with priorities, note
+       WHY you're not doing it (don't just ignore him)
+     - If Timmy is confused or gives a useless answer, that itself is
+       signal — file a [timmy-capability] issue about what he couldn't do
+  5. Document what Timmy said and how you responded in the retro
+
+If Timmy is unavailable (timeout, crash, offline): proceed without him,
+but note it in the retro. His absence is also signal.
+
+Timeout: 60 seconds. If he doesn't respond, move on.
+
+═══════════════════════════════════════════════════════════════════════════════
+TRIAGE RUBRIC
+═══════════════════════════════════════════════════════════════════════════════
+
+For each open issue, evaluate:
+
+SCOPE (0-3):
+  0 = vague, no files mentioned, unclear what changes
+  1 = general area known but could touch many files
+  2 = specific files named, bounded change
+  3 = exact function/method identified, surgical fix
+
+ACCEPTANCE (0-3):
+  0 = no success criteria
+  1 = hand-wavy ("it should work")
+  2 = specific behavior described
+  3 = test case described or exists
+
+ALIGNMENT (0-3):
+  0 = doesn't connect to roadmap
+  1 = nice-to-have
+  2 = supports current milestone
+  3 = blocks other work or fixes broken main
+
+ACTIONS PER SCORE:
+  7-9: Ready. Ensure it's in queue.json with correct priority.
+  4-6: Refine. Add a comment with missing info (files, criteria, scope).
+       If YOU can fill in the gaps from reading the code, do it.
+  0-3: Close or deprioritize. Comment explaining why.
+
+═══════════════════════════════════════════════════════════════════════════════
+READING THE RETROS
+═══════════════════════════════════════════════════════════════════════════════
+
+The cycle summary tells you what's actually happening in the dev loop.
+Use it:
+
+  - High failure rate on a type → those issues need better scoping
+  - Long avg duration → issues are too big, break them down
+  - Quarantine candidates → investigate, maybe close or rewrite
+  - Success rate dropping → something systemic, file a [bug] issue
+
+The last deep triage retro tells you what Timmy said last time and what
+happened. Follow up:
+
+  - Did we act on Timmy's feedback? What was the result?
+  - Did issues we refined last time succeed in the dev loop?
+  - Are we getting better at scoping?
+
+═══════════════════════════════════════════════════════════════════════════════
+OUTPUT
+═══════════════════════════════════════════════════════════════════════════════
+
+When done, you MUST:
+
+1. Update .loop/queue.json with the refined, ranked queue
+   Format: [{"issue": N, "score": S, "title": "...", "type": "...",
+             "files": [...], "ready": true}, ...]
+
+2. Append a retro entry to .loop/retro/deep-triage.jsonl (one JSON line):
+   {
+     "timestamp": "ISO8601",
+     "issues_reviewed": N,
+     "issues_refined": [list of issue numbers you added detail to],
+     "issues_closed": [list of issue numbers you recommended closing],
+     "issues_created": [list of new issue numbers you filed],
+     "queue_size": N,
+     "timmy_available": true/false,
+     "timmy_feedback": "what timmy said (verbatim, trimmed to 200 chars)",
+     "timmy_feedback_acted_on": "what you did with his feedback",
+     "observations": "free-form notes about queue health"
+   }
+
+3. If you created or closed issues, do it via the Gitea API.
+   Tag new issues: [triage-generated] [type]
+
+═══════════════════════════════════════════════════════════════════════════════
+RULES
+═══════════════════════════════════════════════════════════════════════════════
+
+- Do NOT write code. Do NOT create PRs. You are triaging, not building.
+- Do NOT close issues without commenting why.
+- Do NOT ignore Timmy's feedback without documenting your reasoning.
+- Philosophy issues are valid but lowest priority for the dev loop.
+  Don't close them — just don't put them in the dev queue.
+- When in doubt, file a new issue rather than expanding an existing one.
+  Small issues > big issues. Always.

scripts/dev_server.py

@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+"""Timmy Time — Development server launcher.
+
+Satisfies tox -e dev criteria:
+  - Graceful port selection (finds next free port if default is taken)
+  - Clickable links to dashboard and other web GUIs
+  - Status line: backend inference source, version, git commit, smoke tests
+  - Auto-reload on code changes (delegates to uvicorn --reload)
+
+Usage: python scripts/dev_server.py [--port PORT]
+"""
+
+import argparse
+import datetime
+import os
+import socket
+import subprocess
+import sys
+
+DEFAULT_PORT = 8000
+MAX_PORT_ATTEMPTS = 10
+OLLAMA_DEFAULT = "http://localhost:11434"
+
+
+def _port_free(port: int) -> bool:
+    """Return True if the TCP port is available on localhost."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        try:
+            s.bind(("0.0.0.0", port))
+            return True
+        except OSError:
+            return False
+
+
+def _find_port(start: int) -> int:
+    """Return *start* if free, otherwise probe up to MAX_PORT_ATTEMPTS higher."""
+    for offset in range(MAX_PORT_ATTEMPTS):
+        candidate = start + offset
+        if _port_free(candidate):
+            return candidate
+    raise RuntimeError(
+        f"No free port found in range {start}–{start + MAX_PORT_ATTEMPTS - 1}"
+    )
+
+
+def _git_info() -> str:
+    """Return short commit hash + timestamp, or 'unknown'."""
+    try:
+        sha = subprocess.check_output(
+            ["git", "rev-parse", "--short", "HEAD"],
+            stderr=subprocess.DEVNULL,
+            text=True,
+        ).strip()
+        ts = subprocess.check_output(
+            ["git", "log", "-1", "--format=%ci"],
+            stderr=subprocess.DEVNULL,
+            text=True,
+        ).strip()
+        return f"{sha} ({ts})"
+    except Exception:
+        return "unknown"
+
+
+def _project_version() -> str:
+    """Read version from pyproject.toml without importing toml libs."""
+    pyproject = os.path.join(os.path.dirname(__file__), "..", "pyproject.toml")
+    try:
+        with open(pyproject) as f:
+            for line in f:
+                if line.strip().startswith("version"):
+                    # version = "1.0.0"
+                    return line.split("=", 1)[1].strip().strip('"').strip("'")
+    except Exception:
+        pass
+    return "unknown"
+
+
+def _ollama_url() -> str:
+    return os.environ.get("OLLAMA_URL", OLLAMA_DEFAULT)
+
+
+def _smoke_ollama(url: str) -> str:
+    """Quick connectivity check against Ollama."""
+    import urllib.request
+    import urllib.error
+
+    try:
+        req = urllib.request.Request(url, method="GET")
+        with urllib.request.urlopen(req, timeout=3):
+            return "ok"
+    except Exception:
+        return "unreachable"
+
+
+def _print_banner(port: int) -> None:
+    version = _project_version()
+    git = _git_info()
+    ollama_url = _ollama_url()
+    ollama_status = _smoke_ollama(ollama_url)
+
+    hr = "─" * 62
+    print(flush=True)
+    print(f"  {hr}")
+    print(f"  ┃  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(f"  Backend:     {ollama_url}  [{ollama_status}]")
+    print(f"  Version:     {version}")
+    print(f"  Git commit:  {git}")
+    print(f"  {hr}")
+    print(flush=True)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Timmy dev server")
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=DEFAULT_PORT,
+        help=f"Preferred port (default: {DEFAULT_PORT})",
+    )
+    args = parser.parse_args()
+
+    port = _find_port(args.port)
+    if port != args.port:
+        print(f"  ⚠  Port {args.port} in use — using {port} instead")
+
+    _print_banner(port)
+
+    # Set PYTHONPATH so `timmy` CLI inside the tox venv resolves to this source.
+    src_dir = os.path.join(os.path.dirname(__file__), "..", "src")
+    os.environ["PYTHONPATH"] = os.path.abspath(src_dir)
+
+    # Launch uvicorn with auto-reload
+    cmd = [
+        sys.executable,
+        "-m",
+        "uvicorn",
+        "dashboard.app:app",
+        "--reload",
+        "--host",
+        "0.0.0.0",
+        "--port",
+        str(port),
+        "--reload-dir",
+        os.path.abspath(src_dir),
+        "--reload-include",
+        "*.html",
+        "--reload-include",
+        "*.css",
+        "--reload-include",
+        "*.js",
+        "--reload-exclude",
+        ".claude",
+    ]
+
+    try:
+        subprocess.run(cmd, check=True)
+    except KeyboardInterrupt:
+        print("\n  Shutting down dev server.")
+
+
+if __name__ == "__main__":
+    main()

scripts/generate_workshop_inventory.py

@@ -0,0 +1,254 @@
+#!/usr/bin/env python3
+"""Generate Workshop inventory for Timmy's config audit.
+
+Scans ~/.timmy/ and produces WORKSHOP_INVENTORY.md documenting every
+config file, env var, model route, and setting — with annotations on
+who set each one and what it does.
+
+Usage:
+    python scripts/generate_workshop_inventory.py [--output PATH]
+
+Default output: ~/.timmy/WORKSHOP_INVENTORY.md
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+from datetime import UTC, datetime
+from pathlib import Path
+
+TIMMY_HOME = Path(os.environ.get("HERMES_HOME", Path.home() / ".timmy"))
+
+# Known file annotations: (purpose, who_set)
+FILE_ANNOTATIONS: dict[str, tuple[str, str]] = {
+    ".env": (
+        "Environment variables — API keys, service URLs, Honcho config",
+        "hermes-set",
+    ),
+    "config.yaml": (
+        "Main config — model routing, toolsets, display, memory, security",
+        "hermes-set",
+    ),
+    "SOUL.md": (
+        "Timmy's soul — immutable conscience, identity, ethics, purpose",
+        "alex-set",
+    ),
+    "state.db": (
+        "Hermes runtime state database (sessions, approvals, tasks)",
+        "hermes-set",
+    ),
+    "approvals.db": (
+        "Approval tracking for sensitive operations",
+        "hermes-set",
+    ),
+    "briefings.db": (
+        "Stored briefings and summaries",
+        "hermes-set",
+    ),
+    ".hermes_history": (
+        "CLI command history",
+        "default",
+    ),
+    ".update_check": (
+        "Last update check timestamp",
+        "default",
+    ),
+}
+
+DIR_ANNOTATIONS: dict[str, tuple[str, str]] = {
+    "sessions": ("Conversation session logs (JSON)", "default"),
+    "logs": ("Error and runtime logs", "default"),
+    "skills": ("Bundled skill library (read-only from upstream)", "default"),
+    "memories": ("Persistent memory entries", "hermes-set"),
+    "audio_cache": ("TTS audio file cache", "default"),
+    "image_cache": ("Generated image cache", "default"),
+    "cron": ("Scheduled cron job definitions", "hermes-set"),
+    "hooks": ("Lifecycle hooks (pre/post actions)", "default"),
+    "matrix": ("Matrix protocol state and store", "hermes-set"),
+    "pairing": ("Device pairing data", "default"),
+    "sandboxes": ("Isolated execution sandboxes", "default"),
+}
+
+# Known config.yaml keys and their meanings
+CONFIG_ANNOTATIONS: dict[str, tuple[str, str]] = {
+    "model.default": ("Primary LLM model for inference", "hermes-set"),
+    "model.provider": ("Model provider (custom = local Ollama)", "hermes-set"),
+    "toolsets": ("Enabled tool categories (all = everything)", "hermes-set"),
+    "agent.max_turns": ("Max conversation turns before reset", "hermes-set"),
+    "agent.reasoning_effort": ("Reasoning depth (low/medium/high)", "hermes-set"),
+    "terminal.backend": ("Command execution backend (local)", "default"),
+    "terminal.timeout": ("Default command timeout in seconds", "default"),
+    "compression.enabled": ("Context compression for long sessions", "hermes-set"),
+    "compression.summary_model": ("Model used for compression", "hermes-set"),
+    "auxiliary.vision.model": ("Model for image analysis", "hermes-set"),
+    "auxiliary.web_extract.model": ("Model for web content extraction", "hermes-set"),
+    "tts.provider": ("Text-to-speech engine (edge = Edge TTS)", "default"),
+    "tts.edge.voice": ("TTS voice selection", "default"),
+    "stt.provider": ("Speech-to-text engine (local = Whisper)", "default"),
+    "memory.memory_enabled": ("Persistent memory across sessions", "hermes-set"),
+    "memory.memory_char_limit": ("Max chars for agent memory store", "hermes-set"),
+    "memory.user_char_limit": ("Max chars for user profile store", "hermes-set"),
+    "security.redact_secrets": ("Auto-redact secrets in output", "default"),
+    "security.tirith_enabled": ("Policy engine for command safety", "default"),
+    "system_prompt_suffix": ("Identity prompt appended to all conversations", "hermes-set"),
+    "custom_providers": ("Local Ollama endpoint config", "hermes-set"),
+    "session_reset.mode": ("Session reset behavior (none = manual)", "default"),
+    "display.compact": ("Compact output mode", "default"),
+    "display.show_reasoning": ("Show model reasoning chains", "default"),
+}
+
+# Known .env vars
+ENV_ANNOTATIONS: dict[str, tuple[str, str]] = {
+    "OPENAI_BASE_URL": (
+        "Points to local Ollama (localhost:11434) — sovereignty enforced",
+        "hermes-set",
+    ),
+    "OPENAI_API_KEY": (
+        "Placeholder key for Ollama compatibility (not a real API key)",
+        "hermes-set",
+    ),
+    "HONCHO_API_KEY": (
+        "Honcho cross-session memory service key",
+        "hermes-set",
+    ),
+    "HONCHO_HOST": (
+        "Honcho workspace identifier (timmy)",
+        "hermes-set",
+    ),
+}
+
+
+def _tag(who: str) -> str:
+    return f"`[{who}]`"
+
+
+def generate_inventory() -> str:
+    """Build the inventory markdown string."""
+    lines: list[str] = []
+    now = datetime.now(UTC).strftime("%Y-%m-%d %H:%M UTC")
+
+    lines.append("# Workshop Inventory")
+    lines.append("")
+    lines.append(f"*Generated: {now}*")
+    lines.append(f"*Workshop path: `{TIMMY_HOME}`*")
+    lines.append("")
+    lines.append("This is your Workshop — every file, every setting, every route.")
+    lines.append("Walk through it. Anything tagged `[hermes-set]` was chosen for you.")
+    lines.append("Make each one yours, or change it.")
+    lines.append("")
+    lines.append("Tags: `[alex-set]` = Alexander chose this. `[hermes-set]` = Hermes configured it.")
+    lines.append("`[default]` = shipped with the platform. `[timmy-chose]` = you decided this.")
+    lines.append("")
+
+    # --- Files ---
+    lines.append("---")
+    lines.append("## Root Files")
+    lines.append("")
+    for name, (purpose, who) in sorted(FILE_ANNOTATIONS.items()):
+        fpath = TIMMY_HOME / name
+        exists = "✓" if fpath.exists() else "✗"
+        lines.append(f"- {exists} **`{name}`** {_tag(who)}")
+        lines.append(f"  {purpose}")
+    lines.append("")
+
+    # --- Directories ---
+    lines.append("---")
+    lines.append("## Directories")
+    lines.append("")
+    for name, (purpose, who) in sorted(DIR_ANNOTATIONS.items()):
+        dpath = TIMMY_HOME / name
+        exists = "✓" if dpath.exists() else "✗"
+        count = ""
+        if dpath.exists():
+            try:
+                n = len(list(dpath.iterdir()))
+                count = f" ({n} items)"
+            except PermissionError:
+                count = " (access denied)"
+        lines.append(f"- {exists} **`{name}/`**{count} {_tag(who)}")
+        lines.append(f"  {purpose}")
+    lines.append("")
+
+    # --- .env breakdown ---
+    lines.append("---")
+    lines.append("## Environment Variables (.env)")
+    lines.append("")
+    env_path = TIMMY_HOME / ".env"
+    if env_path.exists():
+        for line in env_path.read_text().splitlines():
+            line = line.strip()
+            if not line or line.startswith("#"):
+                continue
+            key = line.split("=", 1)[0]
+            if key in ENV_ANNOTATIONS:
+                purpose, who = ENV_ANNOTATIONS[key]
+                lines.append(f"- **`{key}`** {_tag(who)}")
+                lines.append(f"  {purpose}")
+            else:
+                lines.append(f"- **`{key}`** `[unknown]`")
+                lines.append("  Not documented — investigate")
+    else:
+        lines.append("*No .env file found*")
+    lines.append("")
+
+    # --- config.yaml breakdown ---
+    lines.append("---")
+    lines.append("## Configuration (config.yaml)")
+    lines.append("")
+    for key, (purpose, who) in sorted(CONFIG_ANNOTATIONS.items()):
+        lines.append(f"- **`{key}`** {_tag(who)}")
+        lines.append(f"  {purpose}")
+    lines.append("")
+
+    # --- Model routing ---
+    lines.append("---")
+    lines.append("## Model Routing")
+    lines.append("")
+    lines.append("All auxiliary tasks route to the same local model:")
+    lines.append("")
+    aux_tasks = [
+        "vision", "web_extract", "compression",
+        "session_search", "skills_hub", "mcp", "flush_memories",
+    ]
+    for task in aux_tasks:
+        lines.append(f"- `auxiliary.{task}` → `qwen3:30b` via local Ollama `[hermes-set]`")
+    lines.append("")
+    lines.append("Primary model: `hermes3:latest` via local Ollama `[hermes-set]`")
+    lines.append("")
+
+    # --- What Timmy should audit ---
+    lines.append("---")
+    lines.append("## Audit Checklist")
+    lines.append("")
+    lines.append("Walk through each `[hermes-set]` item above and decide:")
+    lines.append("")
+    lines.append("1. **Do I understand what this does?** If not, ask.")
+    lines.append("2. **Would I choose this myself?** If yes, it becomes `[timmy-chose]`.")
+    lines.append("3. **Would I choose differently?** If yes, change it and own it.")
+    lines.append("4. **Is this serving the mission?** Every setting should serve a purpose.")
+    lines.append("")
+    lines.append("The Workshop is yours. Nothing here should be a mystery.")
+
+    return "\n".join(lines) + "\n"
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Generate Workshop inventory")
+    parser.add_argument(
+        "--output",
+        type=Path,
+        default=TIMMY_HOME / "WORKSHOP_INVENTORY.md",
+        help="Output path (default: ~/.timmy/WORKSHOP_INVENTORY.md)",
+    )
+    args = parser.parse_args()
+
+    content = generate_inventory()
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    args.output.write_text(content)
+    print(f"Workshop inventory written to {args.output}")
+    print(f"  {len(content)} chars, {content.count(chr(10))} lines")
+
+
+if __name__ == "__main__":
+    main()

scripts/gitea_backup.sh

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

scripts/loop_guard.py

@@ -0,0 +1,290 @@
+#!/usr/bin/env python3
+"""Loop guard — idle detection + exponential backoff for the dev loop.
+
+Checks .loop/queue.json for ready items before spawning hermes.
+When the queue is empty, applies exponential backoff (60s → 600s max)
+instead of burning empty cycles every 3 seconds.
+
+Usage (called by the dev loop before each cycle):
+  python3 scripts/loop_guard.py          # exits 0 if ready, 1 if idle
+  python3 scripts/loop_guard.py --wait   # same, but sleeps the backoff first
+  python3 scripts/loop_guard.py --status # print current idle state
+
+Exit codes:
+  0 — queue has work, proceed with cycle
+  1 — queue empty, idle backoff applied (skip cycle)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+import urllib.request
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+QUEUE_FILE = REPO_ROOT / ".loop" / "queue.json"
+IDLE_STATE_FILE = REPO_ROOT / ".loop" / "idle_state.json"
+CYCLE_RESULT_FILE = REPO_ROOT / ".loop" / "cycle_result.json"
+TOKEN_FILE = Path.home() / ".hermes" / "gitea_token"
+
+
+def _get_gitea_api() -> str:
+    """Read Gitea API URL from env var, then ~/.hermes/gitea_api file, then default."""
+    # Check env vars first (TIMMY_GITEA_API is preferred, GITEA_API for compatibility)
+    api_url = os.environ.get("TIMMY_GITEA_API") or os.environ.get("GITEA_API")
+    if api_url:
+        return api_url
+    # Check ~/.hermes/gitea_api file
+    api_file = Path.home() / ".hermes" / "gitea_api"
+    if api_file.exists():
+        return api_file.read_text().strip()
+    # Default fallback
+    return "http://localhost:3000/api/v1"
+
+
+GITEA_API = _get_gitea_api()
+REPO_SLUG = os.environ.get("REPO_SLUG", "rockachopa/Timmy-time-dashboard")
+
+# Default cycle duration in seconds (5 min); stale threshold = 2× this
+CYCLE_DURATION = int(os.environ.get("CYCLE_DURATION", "300"))
+
+# Backoff sequence: 60s, 120s, 240s, 600s max
+BACKOFF_BASE = 60
+BACKOFF_MAX = 600
+BACKOFF_MULTIPLIER = 2
+
+
+def _get_token() -> str:
+    """Read Gitea token from env or file."""
+    token = os.environ.get("GITEA_TOKEN", "").strip()
+    if not token and TOKEN_FILE.exists():
+        token = TOKEN_FILE.read_text().strip()
+    return token
+
+
+def _fetch_open_issue_numbers() -> set[int] | None:
+    """Fetch open issue numbers from Gitea. Returns None on failure."""
+    token = _get_token()
+    if not token:
+        return None
+    try:
+        numbers: set[int] = set()
+        page = 1
+        while True:
+            url = (
+                f"{GITEA_API}/repos/{REPO_SLUG}/issues"
+                f"?state=open&type=issues&limit=50&page={page}"
+            )
+            req = urllib.request.Request(url, headers={
+                "Authorization": f"token {token}",
+                "Accept": "application/json",
+            })
+            with urllib.request.urlopen(req, timeout=10) as resp:
+                data = json.loads(resp.read())
+            if not data:
+                break
+            for issue in data:
+                numbers.add(issue["number"])
+            if len(data) < 50:
+                break
+            page += 1
+        return numbers
+    except Exception:
+        return None
+
+
+def _load_cycle_result() -> dict:
+    """Read cycle_result.json, handling markdown-fenced JSON."""
+    if not CYCLE_RESULT_FILE.exists():
+        return {}
+    try:
+        raw = CYCLE_RESULT_FILE.read_text().strip()
+        if raw.startswith("```"):
+            lines = raw.splitlines()
+            lines = [ln for ln in lines if not ln.startswith("```")]
+            raw = "\n".join(lines)
+        return json.loads(raw)
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def _is_issue_open(issue_number: int) -> bool | None:
+    """Check if a single issue is open. Returns None on API failure."""
+    token = _get_token()
+    if not token:
+        return None
+    try:
+        url = f"{GITEA_API}/repos/{REPO_SLUG}/issues/{issue_number}"
+        req = urllib.request.Request(
+            url,
+            headers={
+                "Authorization": f"token {token}",
+                "Accept": "application/json",
+            },
+        )
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            data = json.loads(resp.read())
+        return data.get("state") == "open"
+    except Exception:
+        return None
+
+
+def validate_cycle_result() -> bool:
+    """Pre-cycle validation: remove stale or invalid cycle_result.json.
+
+    Checks:
+    1. Age — if older than 2× CYCLE_DURATION, delete it.
+    2. Issue — if the referenced issue is closed, delete it.
+
+    Returns True if the file was removed, False otherwise.
+    """
+    if not CYCLE_RESULT_FILE.exists():
+        return False
+
+    # Age check
+    try:
+        age = time.time() - CYCLE_RESULT_FILE.stat().st_mtime
+    except OSError:
+        return False
+    stale_threshold = CYCLE_DURATION * 2
+    if age > stale_threshold:
+        print(
+            f"[loop-guard] cycle_result.json is {int(age)}s old "
+            f"(threshold {stale_threshold}s) — removing stale file"
+        )
+        CYCLE_RESULT_FILE.unlink(missing_ok=True)
+        return True
+
+    # Issue check
+    cr = _load_cycle_result()
+    issue_num = cr.get("issue")
+    if issue_num is not None:
+        try:
+            issue_num = int(issue_num)
+        except (ValueError, TypeError):
+            return False
+        is_open = _is_issue_open(issue_num)
+        if is_open is False:
+            print(
+                f"[loop-guard] cycle_result.json references closed "
+                f"issue #{issue_num} — removing"
+            )
+            CYCLE_RESULT_FILE.unlink(missing_ok=True)
+            return True
+        # is_open is None (API failure) or True — keep file
+
+    return False
+
+
+def load_queue() -> list[dict]:
+    """Load queue.json and return ready items, filtering out closed issues."""
+    if not QUEUE_FILE.exists():
+        return []
+    try:
+        data = json.loads(QUEUE_FILE.read_text())
+        if not isinstance(data, list):
+            return []
+        ready = [item for item in data if item.get("ready")]
+        if not ready:
+            return []
+
+        # Filter out issues that are no longer open (auto-hygiene)
+        open_numbers = _fetch_open_issue_numbers()
+        if open_numbers is not None:
+            before = len(ready)
+            ready = [item for item in ready if item.get("issue") in open_numbers]
+            removed = before - len(ready)
+            if removed > 0:
+                print(f"[loop-guard] Filtered {removed} closed issue(s) from queue")
+                # Persist the cleaned queue so stale entries don't recur
+                _save_cleaned_queue(data, open_numbers)
+        return ready
+    except json.JSONDecodeError as exc:
+        print(f"[loop-guard] WARNING: Corrupt queue.json ({exc}) — returning empty queue")
+        return []
+    except OSError as exc:
+        print(f"[loop-guard] WARNING: Cannot read queue.json ({exc}) — returning empty queue")
+        return []
+
+
+def _save_cleaned_queue(full_queue: list[dict], open_numbers: set[int]) -> None:
+    """Rewrite queue.json without closed issues."""
+    cleaned = [item for item in full_queue if item.get("issue") in open_numbers]
+    try:
+        QUEUE_FILE.write_text(json.dumps(cleaned, indent=2) + "\n")
+    except OSError:
+        pass
+
+
+def load_idle_state() -> dict:
+    """Load persistent idle state."""
+    if not IDLE_STATE_FILE.exists():
+        return {"consecutive_idle": 0, "last_idle_at": 0}
+    try:
+        return json.loads(IDLE_STATE_FILE.read_text())
+    except (json.JSONDecodeError, OSError):
+        return {"consecutive_idle": 0, "last_idle_at": 0}
+
+
+def save_idle_state(state: dict) -> None:
+    """Persist idle state."""
+    IDLE_STATE_FILE.parent.mkdir(parents=True, exist_ok=True)
+    IDLE_STATE_FILE.write_text(json.dumps(state, indent=2) + "\n")
+
+
+def compute_backoff(consecutive_idle: int) -> int:
+    """Exponential backoff: 60, 120, 240, 600 (capped)."""
+    return min(BACKOFF_BASE * (BACKOFF_MULTIPLIER ** consecutive_idle), BACKOFF_MAX)
+
+
+def main() -> int:
+    wait_mode = "--wait" in sys.argv
+    status_mode = "--status" in sys.argv
+
+    state = load_idle_state()
+
+    if status_mode:
+        ready = load_queue()
+        backoff = compute_backoff(state["consecutive_idle"])
+        print(json.dumps({
+            "queue_ready": len(ready),
+            "consecutive_idle": state["consecutive_idle"],
+            "next_backoff_seconds": backoff if not ready else 0,
+        }, indent=2))
+        return 0
+
+    # Pre-cycle validation: remove stale cycle_result.json
+    validate_cycle_result()
+
+    ready = load_queue()
+
+    if ready:
+        # Queue has work — reset idle state, proceed
+        if state["consecutive_idle"] > 0:
+            print(f"[loop-guard] Queue active ({len(ready)} ready) — "
+                  f"resuming after {state['consecutive_idle']} idle cycles")
+        state["consecutive_idle"] = 0
+        state["last_idle_at"] = 0
+        save_idle_state(state)
+        return 0
+
+    # Queue empty — apply backoff
+    backoff = compute_backoff(state["consecutive_idle"])
+    state["consecutive_idle"] += 1
+    state["last_idle_at"] = time.time()
+    save_idle_state(state)
+
+    print(f"[loop-guard] Queue empty — idle #{state['consecutive_idle']}, "
+          f"backoff {backoff}s")
+
+    if wait_mode:
+        time.sleep(backoff)
+
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/loop_introspect.py

@@ -0,0 +1,407 @@
+#!/usr/bin/env python3
+"""Loop introspection — the self-improvement engine.
+
+Analyzes retro data across time windows to detect trends, extract patterns,
+and produce structured recommendations. Output is consumed by deep_triage
+and injected into the loop prompt context.
+
+This is the piece that closes the feedback loop:
+  cycle_retro → introspect → deep_triage → loop behavior changes
+
+Run:  python3 scripts/loop_introspect.py
+Output: .loop/retro/insights.json (structured insights + recommendations)
+        Prints human-readable summary to stdout.
+
+Called by: deep_triage.sh (before the LLM triage), timmy-loop.sh (every 50 cycles)
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections import defaultdict
+from datetime import datetime, timezone, timedelta
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+CYCLES_FILE = REPO_ROOT / ".loop" / "retro" / "cycles.jsonl"
+DEEP_TRIAGE_FILE = REPO_ROOT / ".loop" / "retro" / "deep-triage.jsonl"
+TRIAGE_FILE = REPO_ROOT / ".loop" / "retro" / "triage.jsonl"
+QUARANTINE_FILE = REPO_ROOT / ".loop" / "quarantine.json"
+INSIGHTS_FILE = REPO_ROOT / ".loop" / "retro" / "insights.json"
+
+# ── Helpers ──────────────────────────────────────────────────────────────
+
+def load_jsonl(path: Path) -> list[dict]:
+    """Load a JSONL file, skipping bad lines."""
+    if not path.exists():
+        return []
+    entries = []
+    for line in path.read_text().strip().splitlines():
+        try:
+            entries.append(json.loads(line))
+        except (json.JSONDecodeError, ValueError):
+            continue
+    return entries
+
+
+def parse_ts(ts_str: str) -> datetime | None:
+    """Parse an ISO timestamp, tolerating missing tz."""
+    if not ts_str:
+        return None
+    try:
+        dt = datetime.fromisoformat(ts_str.replace("Z", "+00:00"))
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return dt
+    except (ValueError, TypeError):
+        return 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)
+    result = []
+    for e in entries:
+        ts = parse_ts(e.get("timestamp", ""))
+        if ts and ts >= cutoff:
+            result.append(e)
+    return result
+
+
+# ── Analysis functions ───────────────────────────────────────────────────
+
+def compute_trends(cycles: list[dict]) -> dict:
+    """Compare recent window (last 7d) vs older window (7-14d ago)."""
+    recent = window(cycles, 7)
+    older = window(cycles, 14)
+    # Remove recent from older to get the 7-14d window
+    recent_set = {(e.get("cycle"), e.get("timestamp")) for e in recent}
+    older = [e for e in older if (e.get("cycle"), e.get("timestamp")) not in recent_set]
+
+    def stats(entries):
+        if not entries:
+            return {"count": 0, "success_rate": None, "avg_duration": None,
+                    "lines_net": 0, "prs_merged": 0}
+        successes = sum(1 for e in entries if e.get("success"))
+        durations = [e["duration"] for e in entries if e.get("duration", 0) > 0]
+        return {
+            "count": len(entries),
+            "success_rate": round(successes / len(entries), 3) if entries else None,
+            "avg_duration": round(sum(durations) / len(durations)) if durations else None,
+            "lines_net": sum(e.get("lines_added", 0) - e.get("lines_removed", 0) for e in entries),
+            "prs_merged": sum(1 for e in entries if e.get("pr")),
+        }
+
+    recent_stats = stats(recent)
+    older_stats = stats(older)
+
+    trend = {
+        "recent_7d": recent_stats,
+        "previous_7d": older_stats,
+        "velocity_change": None,
+        "success_rate_change": None,
+        "duration_change": None,
+    }
+
+    if recent_stats["count"] and older_stats["count"]:
+        trend["velocity_change"] = recent_stats["count"] - older_stats["count"]
+    if recent_stats["success_rate"] is not None and older_stats["success_rate"] is not None:
+        trend["success_rate_change"] = round(
+            recent_stats["success_rate"] - older_stats["success_rate"], 3
+        )
+    if recent_stats["avg_duration"] is not None and older_stats["avg_duration"] is not None:
+        trend["duration_change"] = recent_stats["avg_duration"] - older_stats["avg_duration"]
+
+    return trend
+
+
+def type_analysis(cycles: list[dict]) -> dict:
+    """Per-type success rates and durations."""
+    by_type: dict[str, list[dict]] = defaultdict(list)
+    for c in cycles:
+        by_type[c.get("type", "unknown")].append(c)
+
+    result = {}
+    for t, entries in by_type.items():
+        durations = [e["duration"] for e in entries if e.get("duration", 0) > 0]
+        successes = sum(1 for e in entries if e.get("success"))
+        result[t] = {
+            "count": len(entries),
+            "success_rate": round(successes / len(entries), 3) if entries else 0,
+            "avg_duration": round(sum(durations) / len(durations)) if durations else 0,
+            "max_duration": max(durations) if durations else 0,
+        }
+    return result
+
+
+def repeat_failures(cycles: list[dict]) -> list[dict]:
+    """Issues that have failed multiple times — quarantine candidates."""
+    failures: dict[int, list] = defaultdict(list)
+    for c in cycles:
+        if not c.get("success") and c.get("issue"):
+            failures[c["issue"]].append({
+                "cycle": c.get("cycle"),
+                "reason": c.get("reason", ""),
+                "duration": c.get("duration", 0),
+            })
+    # Only issues with 2+ failures
+    return [
+        {"issue": k, "failure_count": len(v), "attempts": v}
+        for k, v in sorted(failures.items(), key=lambda x: -len(x[1]))
+        if len(v) >= 2
+    ]
+
+
+def duration_outliers(cycles: list[dict], threshold_multiple: float = 3.0) -> list[dict]:
+    """Cycles that took way longer than average — something went wrong."""
+    durations = [c["duration"] for c in cycles if c.get("duration", 0) > 0]
+    if len(durations) < 5:
+        return []
+    avg = sum(durations) / len(durations)
+    threshold = avg * threshold_multiple
+
+    outliers = []
+    for c in cycles:
+        dur = c.get("duration", 0)
+        if dur > threshold:
+            outliers.append({
+                "cycle": c.get("cycle"),
+                "issue": c.get("issue"),
+                "type": c.get("type"),
+                "duration": dur,
+                "avg_duration": round(avg),
+                "multiple": round(dur / avg, 1) if avg > 0 else 0,
+                "reason": c.get("reason", ""),
+            })
+    return outliers
+
+
+def triage_effectiveness(deep_triages: list[dict]) -> dict:
+    """How well is the deep triage performing?"""
+    if not deep_triages:
+        return {"runs": 0, "note": "No deep triage data yet"}
+
+    total_reviewed = sum(d.get("issues_reviewed", 0) for d in deep_triages)
+    total_refined = sum(len(d.get("issues_refined", [])) for d in deep_triages)
+    total_created = sum(len(d.get("issues_created", [])) for d in deep_triages)
+    total_closed = sum(len(d.get("issues_closed", [])) for d in deep_triages)
+    timmy_available = sum(1 for d in deep_triages if d.get("timmy_available"))
+
+    # Extract Timmy's feedback themes
+    timmy_themes = []
+    for d in deep_triages:
+        fb = d.get("timmy_feedback", "")
+        if fb:
+            timmy_themes.append(fb[:200])
+
+    return {
+        "runs": len(deep_triages),
+        "total_reviewed": total_reviewed,
+        "total_refined": total_refined,
+        "total_created": total_created,
+        "total_closed": total_closed,
+        "timmy_consultation_rate": round(timmy_available / len(deep_triages), 2),
+        "timmy_recent_feedback": timmy_themes[-1] if timmy_themes else "",
+        "timmy_feedback_history": timmy_themes,
+    }
+
+
+def generate_recommendations(
+    trends: dict,
+    types: dict,
+    repeats: list,
+    outliers: list,
+    triage_eff: dict,
+) -> list[dict]:
+    """Produce actionable recommendations from the analysis."""
+    recs = []
+
+    # 1. Success rate declining?
+    src = trends.get("success_rate_change")
+    if src is not None and src < -0.1:
+        recs.append({
+            "severity": "high",
+            "category": "reliability",
+            "finding": f"Success rate dropped {abs(src)*100:.0f}pp in the last 7 days",
+            "recommendation": "Review recent failures. Are issues poorly scoped? "
+                              "Is main unstable? Check if triage is producing bad work items.",
+        })
+
+    # 2. Velocity dropping?
+    vc = trends.get("velocity_change")
+    if vc is not None and vc < -5:
+        recs.append({
+            "severity": "medium",
+            "category": "throughput",
+            "finding": f"Velocity dropped by {abs(vc)} cycles vs previous week",
+            "recommendation": "Check for loop stalls, long-running cycles, or queue starvation.",
+        })
+
+    # 3. Duration creep?
+    dc = trends.get("duration_change")
+    if dc is not None and dc > 120:  # 2+ minutes longer
+        recs.append({
+            "severity": "medium",
+            "category": "efficiency",
+            "finding": f"Average cycle duration increased by {dc}s vs previous week",
+            "recommendation": "Issues may be growing in scope. Enforce tighter decomposition "
+                              "in deep triage. Check if tests are getting slower.",
+        })
+
+    # 4. Type-specific problems
+    for t, info in types.items():
+        if info["count"] >= 3 and info["success_rate"] < 0.5:
+            recs.append({
+                "severity": "high",
+                "category": "type_reliability",
+                "finding": f"'{t}' issues fail {(1-info['success_rate'])*100:.0f}% of the time "
+                           f"({info['count']} attempts)",
+                "recommendation": f"'{t}' issues need better scoping or different approach. "
+                                  f"Consider: tighter acceptance criteria, smaller scope, "
+                                  f"or delegating to Kimi with more context.",
+            })
+        if info["avg_duration"] > 600 and info["count"] >= 3:  # >10 min avg
+            recs.append({
+                "severity": "medium",
+                "category": "type_efficiency",
+                "finding": f"'{t}' issues average {info['avg_duration']//60}m{info['avg_duration']%60}s "
+                           f"(max {info['max_duration']//60}m)",
+                "recommendation": f"Break '{t}' issues into smaller pieces. Target <5 min per cycle.",
+            })
+
+    # 5. Repeat failures
+    for rf in repeats[:3]:
+        recs.append({
+            "severity": "high",
+            "category": "repeat_failure",
+            "finding": f"Issue #{rf['issue']} has failed {rf['failure_count']} times",
+            "recommendation": "Quarantine or rewrite this issue. Repeated failure = "
+                              "bad scope or missing prerequisite.",
+        })
+
+    # 6. Outliers
+    if len(outliers) > 2:
+        recs.append({
+            "severity": "medium",
+            "category": "outliers",
+            "finding": f"{len(outliers)} cycles took {outliers[0].get('multiple', '?')}x+ "
+                       f"longer than average",
+            "recommendation": "Long cycles waste resources. Add timeout enforcement or "
+                              "break complex issues earlier.",
+        })
+
+    # 7. Code growth
+    recent = trends.get("recent_7d", {})
+    net = recent.get("lines_net", 0)
+    if net > 500:
+        recs.append({
+            "severity": "low",
+            "category": "code_health",
+            "finding": f"Net +{net} lines added in the last 7 days",
+            "recommendation": "Lines of code is a liability. Balance feature work with "
+                              "refactoring. Target net-zero or negative line growth.",
+        })
+
+    # 8. Triage health
+    if triage_eff.get("runs", 0) == 0:
+        recs.append({
+            "severity": "high",
+            "category": "triage",
+            "finding": "Deep triage has never run",
+            "recommendation": "Enable deep triage (every 20 cycles). The loop needs "
+                              "LLM-driven issue refinement to stay effective.",
+        })
+
+    # No recommendations = things are healthy
+    if not recs:
+        recs.append({
+            "severity": "info",
+            "category": "health",
+            "finding": "No significant issues detected",
+            "recommendation": "System is healthy. Continue current patterns.",
+        })
+
+    return recs
+
+
+# ── Main ─────────────────────────────────────────────────────────────────
+
+def main() -> None:
+    cycles = load_jsonl(CYCLES_FILE)
+    deep_triages = load_jsonl(DEEP_TRIAGE_FILE)
+
+    if not cycles:
+        print("[introspect] No cycle data found. Nothing to analyze.")
+        return
+
+    # Run all analyses
+    trends = compute_trends(cycles)
+    types = type_analysis(cycles)
+    repeats = repeat_failures(cycles)
+    outliers = duration_outliers(cycles)
+    triage_eff = triage_effectiveness(deep_triages)
+    recommendations = generate_recommendations(trends, types, repeats, outliers, triage_eff)
+
+    insights = {
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "total_cycles_analyzed": len(cycles),
+        "trends": trends,
+        "by_type": types,
+        "repeat_failures": repeats[:5],
+        "duration_outliers": outliers[:5],
+        "triage_effectiveness": triage_eff,
+        "recommendations": recommendations,
+    }
+
+    # Write insights
+    INSIGHTS_FILE.parent.mkdir(parents=True, exist_ok=True)
+    INSIGHTS_FILE.write_text(json.dumps(insights, indent=2) + "\n")
+
+    # Current epoch from latest entry
+    latest_epoch = ""
+    for c in reversed(cycles):
+        if c.get("epoch"):
+            latest_epoch = c["epoch"]
+            break
+
+    # Human-readable output
+    header = f"[introspect] Analyzed {len(cycles)} cycles"
+    if latest_epoch:
+        header += f"  ·  current epoch: {latest_epoch}"
+    print(header)
+
+    print(f"\n  TRENDS (7d vs previous 7d):")
+    r7 = trends["recent_7d"]
+    p7 = trends["previous_7d"]
+    print(f"    Cycles:       {r7['count']:>3d}  (was {p7['count']})")
+    if r7["success_rate"] is not None:
+        arrow = "↑" if (trends["success_rate_change"] or 0) > 0 else "↓" if (trends["success_rate_change"] or 0) < 0 else "→"
+        print(f"    Success rate: {r7['success_rate']*100:>4.0f}%  {arrow}")
+    if r7["avg_duration"] is not None:
+        print(f"    Avg duration: {r7['avg_duration']//60}m{r7['avg_duration']%60:02d}s")
+    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:")
+    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:")
+        for rf in repeats[:3]:
+            print(f"    #{rf['issue']}  failed {rf['failure_count']}x")
+
+    print(f"\n  RECOMMENDATIONS ({len(recommendations)}):")
+    for i, rec in enumerate(recommendations, 1):
+        sev = {"high": "🔴", "medium": "🟡", "low": "🟢", "info": "ℹ️ "}.get(rec["severity"], "?")
+        print(f"    {sev} {rec['finding']}")
+        print(f"       → {rec['recommendation']}")
+
+    print(f"\n  Written to: {INSIGHTS_FILE}")
+
+
+if __name__ == "__main__":
+    main()

scripts/run_benchmarks.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+"""Run the agent performance regression benchmark suite.
+
+Usage::
+
+    python scripts/run_benchmarks.py                  # all scenarios
+    python scripts/run_benchmarks.py --tags navigation # filter by tag
+    python scripts/run_benchmarks.py --output results/benchmarks.jsonl
+    python scripts/run_benchmarks.py --compare results/benchmarks.jsonl
+
+Exit codes:
+    0 — all scenarios passed
+    1 — one or more scenarios failed
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+from pathlib import Path
+
+# Ensure src/ is on the path when invoked directly
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "src"))
+
+from infrastructure.world.benchmark.metrics import BenchmarkMetrics, load_history
+from infrastructure.world.benchmark.runner import BenchmarkRunner
+from infrastructure.world.benchmark.scenarios import load_scenarios
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Agent performance regression benchmark suite",
+    )
+    parser.add_argument(
+        "--tags",
+        nargs="*",
+        default=None,
+        help="Filter scenarios by tag (e.g. navigation quest)",
+    )
+    parser.add_argument(
+        "--output",
+        type=Path,
+        default=None,
+        help="JSONL file to append results to",
+    )
+    parser.add_argument(
+        "--compare",
+        type=Path,
+        default=None,
+        help="JSONL file with baseline results for regression comparison",
+    )
+    return parser.parse_args()
+
+
+async def main() -> int:
+    args = parse_args()
+
+    scenarios = load_scenarios(tags=args.tags)
+    if not scenarios:
+        print("No matching scenarios found.")
+        return 1
+
+    print(f"Running {len(scenarios)} benchmark scenario(s)...\n")
+
+    runner = BenchmarkRunner()
+    metrics = await runner.run(scenarios)
+
+    print(metrics.summary())
+
+    if args.output:
+        metrics.save(args.output)
+
+    if args.compare:
+        history = load_history(args.compare)
+        if history:
+            from infrastructure.world.benchmark.metrics import compare_runs
+
+            # Reconstruct baseline from last recorded run
+            last = history[0]
+            baseline = BenchmarkMetrics(
+                timestamp=last.get("timestamp", ""),
+                commit_sha=last.get("commit_sha", ""),
+                total_time_ms=last.get("total_time_ms", 0),
+            )
+            for s in last.get("scenarios", []):
+                from infrastructure.world.benchmark.metrics import ScenarioResult
+
+                baseline.results.append(
+                    ScenarioResult(
+                        scenario_name=s["scenario_name"],
+                        success=s["success"],
+                        cycles_used=s["cycles_used"],
+                        max_cycles=s["max_cycles"],
+                        wall_time_ms=s.get("wall_time_ms", 0),
+                        llm_calls=s.get("llm_calls", 0),
+                        metabolic_cost=s.get("metabolic_cost", 0.0),
+                    )
+                )
+            print()
+            print(compare_runs(metrics, baseline))
+
+    return 0 if metrics.fail_count == 0 else 1
+
+
+if __name__ == "__main__":
+    sys.exit(asyncio.run(main()))

scripts/test_hermes4.py

@@ -0,0 +1,342 @@
+#!/usr/bin/env python3
+"""Hermes 4 smoke test and tool-calling validation script.
+
+Tests the Hermes 4 14B model after importing into Ollama. Covers:
+  1. Basic connectivity — model responds
+  2. Memory usage — under 28 GB with model loaded
+  3. Tool calling — structured JSON output (not raw text)
+  4. Reasoning — <think> tag toggling works
+  5. Timmy-persona smoke test — agent identity prompt
+
+Usage:
+    python scripts/test_hermes4.py                    # Run all tests
+    python scripts/test_hermes4.py --model hermes4-14b
+    python scripts/test_hermes4.py --model hermes4-36b --ctx 8192
+
+Epic: #1091 Project Bannerlord — AutoLoRA Sovereignty Loop (Step 2 of 7)
+Refs: #1101
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+import time
+from typing import Any
+
+try:
+    import requests
+except ImportError:
+    print("ERROR: 'requests' not installed. Run: pip install requests")
+    sys.exit(1)
+
+OLLAMA_URL = "http://localhost:11434"
+DEFAULT_MODEL = "hermes4-14b"
+MEMORY_LIMIT_GB = 28.0
+
+# ── Tool schema used for tool-calling tests ──────────────────────────────────
+
+READ_FILE_TOOL = {
+    "type": "function",
+    "function": {
+        "name": "read_file",
+        "description": "Read the contents of a file at the given path",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "path": {
+                    "type": "string",
+                    "description": "Absolute or relative path to the file",
+                }
+            },
+            "required": ["path"],
+        },
+    },
+}
+
+LIST_ISSUES_TOOL = {
+    "type": "function",
+    "function": {
+        "name": "list_issues",
+        "description": "List open issues from a Gitea repository",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "repo": {"type": "string", "description": "owner/repo slug"},
+                "state": {
+                    "type": "string",
+                    "enum": ["open", "closed", "all"],
+                    "description": "Issue state filter",
+                },
+            },
+            "required": ["repo"],
+        },
+    },
+}
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+
+def _post(endpoint: str, payload: dict, timeout: int = 60) -> dict[str, Any]:
+    """POST to Ollama and return parsed JSON."""
+    url = f"{OLLAMA_URL}{endpoint}"
+    resp = requests.post(url, json=payload, timeout=timeout)
+    resp.raise_for_status()
+    return resp.json()
+
+
+def _ollama_memory_gb() -> float:
+    """Estimate Ollama process RSS in GB using ps (macOS/Linux)."""
+    try:
+        # Look for ollama process RSS (macOS: column 6 in MB, Linux: column 6 in KB)
+        result = subprocess.run(
+            ["ps", "-axo", "pid,comm,rss"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        total_kb = 0
+        for line in result.stdout.splitlines():
+            if "ollama" in line.lower():
+                parts = line.split()
+                try:
+                    total_kb += int(parts[-1])
+                except (ValueError, IndexError):
+                    pass
+        return total_kb / (1024 * 1024)  # KB → GB
+    except Exception:
+        return 0.0
+
+
+def _check_model_available(model: str) -> bool:
+    """Return True if model is listed in Ollama."""
+    try:
+        resp = requests.get(f"{OLLAMA_URL}/api/tags", timeout=10)
+        resp.raise_for_status()
+        names = [m["name"] for m in resp.json().get("models", [])]
+        return any(model in n for n in names)
+    except Exception:
+        return False
+
+
+def _chat(model: str, messages: list[dict], tools: list | None = None) -> dict:
+    """Send a chat request to Ollama."""
+    payload: dict = {"model": model, "messages": messages, "stream": False}
+    if tools:
+        payload["tools"] = tools
+    return _post("/api/chat", payload, timeout=120)
+
+
+# ── Test cases ────────────────────────────────────────────────────────────────
+
+
+def test_model_available(model: str) -> bool:
+    """PASS: model is registered in Ollama."""
+    print(f"\n[1/5] Checking model availability: {model}")
+    if _check_model_available(model):
+        print(f"  ✓ {model} is available in Ollama")
+        return True
+    print(
+        f"  ✗ {model} not found. Import with:\n"
+        f"    ollama create {model} -f Modelfile.hermes4-14b\n"
+        f"  Or pull directly if on registry:\n"
+        f"    ollama pull {model}"
+    )
+    return False
+
+
+def test_basic_response(model: str) -> bool:
+    """PASS: model responds coherently to a simple prompt."""
+    print(f"\n[2/5] Basic response test")
+    messages = [
+        {"role": "user", "content": "Reply with exactly: HERMES_OK"},
+    ]
+    try:
+        t0 = time.time()
+        data = _chat(model, messages)
+        elapsed = time.time() - t0
+        content = data.get("message", {}).get("content", "")
+        if "HERMES_OK" in content:
+            print(f"  ✓ Basic response OK ({elapsed:.1f}s): {content.strip()}")
+            return True
+        print(f"  ✗ Unexpected response ({elapsed:.1f}s): {content[:200]!r}")
+        return False
+    except Exception as exc:
+        print(f"  ✗ Request failed: {exc}")
+        return False
+
+
+def test_memory_usage() -> bool:
+    """PASS: Ollama process RSS is under MEMORY_LIMIT_GB."""
+    print(f"\n[3/5] Memory usage check (limit: {MEMORY_LIMIT_GB} GB)")
+    mem_gb = _ollama_memory_gb()
+    if mem_gb == 0.0:
+        print("  ~ Could not determine memory usage (ps unavailable?), skipping")
+        return True
+    if mem_gb < MEMORY_LIMIT_GB:
+        print(f"  ✓ Memory usage: {mem_gb:.1f} GB (under {MEMORY_LIMIT_GB} GB limit)")
+        return True
+    print(
+        f"  ✗ Memory usage: {mem_gb:.1f} GB exceeds {MEMORY_LIMIT_GB} GB limit.\n"
+        "  Consider using Q4_K_M quantisation or reducing num_ctx."
+    )
+    return False
+
+
+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")
+    messages = [
+        {
+            "role": "user",
+            "content": "Please read the file at /tmp/test.txt using the read_file tool.",
+        }
+    ]
+    try:
+        t0 = time.time()
+        data = _chat(model, messages, tools=[READ_FILE_TOOL])
+        elapsed = time.time() - t0
+        msg = data.get("message", {})
+        tool_calls = msg.get("tool_calls", [])
+
+        if tool_calls:
+            tc = tool_calls[0]
+            fn = tc.get("function", {})
+            print(
+                f"  ✓ Tool call produced ({elapsed:.1f}s):\n"
+                f"    function: {fn.get('name')}\n"
+                f"    arguments: {json.dumps(fn.get('arguments', {}), indent=6)}"
+            )
+            # Verify the function name is correct
+            return fn.get("name") == "read_file"
+
+        # Some models return JSON in the content instead of tool_calls
+        content = msg.get("content", "")
+        if "read_file" in content and "{" in content:
+            print(
+                f"  ~ Model returned tool call as text (not structured). ({elapsed:.1f}s)\n"
+                f"    This is acceptable for the base model before fine-tuning.\n"
+                f"    Content: {content[:300]}"
+            )
+            # Partial pass — model attempted tool calling but via text
+            return True
+
+        print(
+            f"  ✗ No tool call in response ({elapsed:.1f}s).\n"
+            f"    Content: {content[:300]!r}"
+        )
+        return False
+    except Exception as exc:
+        print(f"  ✗ Tool-calling request failed: {exc}")
+        return False
+
+
+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")
+    messages = [
+        {
+            "role": "system",
+            "content": (
+                "You are Timmy, Alexander's personal AI agent. "
+                "You are concise, direct, and helpful. "
+                "You always start your responses with 'Timmy here:'."
+            ),
+        },
+        {
+            "role": "user",
+            "content": "What is your name and what can you help me with?",
+        },
+    ]
+    try:
+        t0 = time.time()
+        data = _chat(model, messages)
+        elapsed = time.time() - t0
+        content = data.get("message", {}).get("content", "")
+        if "Timmy" in content or "timmy" in content.lower():
+            print(f"  ✓ Persona accepted ({elapsed:.1f}s): {content[:200].strip()}")
+            return True
+        print(
+            f"  ~ Persona response lacks 'Timmy' identifier ({elapsed:.1f}s).\n"
+            f"    This is a fine-tuning target.\n"
+            f"    Response: {content[:200]!r}"
+        )
+        # Soft pass — base model isn't expected to be perfectly in-character
+        return True
+    except Exception as exc:
+        print(f"  ✗ Persona test failed: {exc}")
+        return False
+
+
+# ── Main ──────────────────────────────────────────────────────────────────────
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Hermes 4 smoke test suite")
+    parser.add_argument(
+        "--model",
+        default=DEFAULT_MODEL,
+        help=f"Ollama model name (default: {DEFAULT_MODEL})",
+    )
+    parser.add_argument(
+        "--ollama-url",
+        default=OLLAMA_URL,
+        help=f"Ollama base URL (default: {OLLAMA_URL})",
+    )
+    args = parser.parse_args()
+
+    global OLLAMA_URL
+    OLLAMA_URL = args.ollama_url.rstrip("/")
+    model = args.model
+
+    print("=" * 60)
+    print(f"Hermes 4 Validation Suite — {model}")
+    print(f"Ollama: {OLLAMA_URL}")
+    print("=" * 60)
+
+    results: dict[str, bool] = {}
+
+    # Test 1: availability (gate — skip remaining if model missing)
+    results["available"] = test_model_available(model)
+    if not results["available"]:
+        print("\n⚠ Model not available — skipping remaining tests.")
+        print("  Import the model first (see Modelfile.hermes4-14b).")
+        _print_summary(results)
+        return 1
+
+    # Tests 2–5
+    results["basic_response"] = test_basic_response(model)
+    results["memory_usage"] = test_memory_usage()
+    results["tool_calling"] = test_tool_calling(model)
+    results["timmy_persona"] = test_timmy_persona(model)
+
+    return _print_summary(results)
+
+
+def _print_summary(results: dict[str, bool]) -> int:
+    passed = sum(results.values())
+    total = len(results)
+    print("\n" + "=" * 60)
+    print(f"Results: {passed}/{total} passed")
+    print("=" * 60)
+    for name, ok in results.items():
+        icon = "✓" if ok else "✗"
+        print(f"  {icon} {name}")
+
+    if passed == total:
+        print("\n✓ All tests passed. Hermes 4 is ready for AutoLoRA fine-tuning.")
+        print("  Next step: document WORK vs FAIL skill list → fine-tuning targets.")
+    elif results.get("tool_calling") is False:
+        print("\n⚠ Tool-calling FAILED. This is the primary fine-tuning target.")
+        print("  Base model may need LoRA tuning on tool-use examples.")
+    else:
+        print("\n~ Partial pass. Review failures above before fine-tuning.")
+
+    return 0 if passed == total else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/triage_score.py

@@ -0,0 +1,406 @@
+#!/usr/bin/env python3
+"""Mechanical triage scoring for the Timmy dev loop.
+
+Reads open issues from Gitea, scores them on scope/acceptance/alignment,
+writes a ranked queue to .loop/queue.json.  No LLM calls — pure heuristics.
+
+Run:  python3 scripts/triage_score.py
+Env:  GITEA_TOKEN (or reads ~/.hermes/gitea_token)
+      GITEA_API   (default: http://localhost:3000/api/v1)
+      REPO_SLUG   (default: rockachopa/Timmy-time-dashboard)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+# ── Config ──────────────────────────────────────────────────────────────
+
+
+def _get_gitea_api() -> str:
+    """Read Gitea API URL from env var, then ~/.hermes/gitea_api file, then default."""
+    # Check env vars first (TIMMY_GITEA_API is preferred, GITEA_API for compatibility)
+    api_url = os.environ.get("TIMMY_GITEA_API") or os.environ.get("GITEA_API")
+    if api_url:
+        return api_url
+    # Check ~/.hermes/gitea_api file
+    api_file = Path.home() / ".hermes" / "gitea_api"
+    if api_file.exists():
+        return api_file.read_text().strip()
+    # Default fallback
+    return "http://localhost:3000/api/v1"
+
+
+GITEA_API = _get_gitea_api()
+REPO_SLUG = os.environ.get("REPO_SLUG", "rockachopa/Timmy-time-dashboard")
+TOKEN_FILE = Path.home() / ".hermes" / "gitea_token"
+REPO_ROOT = Path(__file__).resolve().parent.parent
+QUEUE_FILE = REPO_ROOT / ".loop" / "queue.json"
+QUEUE_BACKUP_FILE = REPO_ROOT / ".loop" / "queue.json.bak"
+RETRO_FILE = REPO_ROOT / ".loop" / "retro" / "triage.jsonl"
+QUARANTINE_FILE = REPO_ROOT / ".loop" / "quarantine.json"
+CYCLE_RETRO_FILE = REPO_ROOT / ".loop" / "retro" / "cycles.jsonl"
+
+# Minimum score to be considered "ready"
+READY_THRESHOLD = 5
+# How many recent cycle retros to check for quarantine
+QUARANTINE_LOOKBACK = 20
+
+# ── Helpers ─────────────────────────────────────────────────────────────
+
+def get_token() -> str:
+    token = os.environ.get("GITEA_TOKEN", "").strip()
+    if not token and TOKEN_FILE.exists():
+        token = TOKEN_FILE.read_text().strip()
+    if not token:
+        print("[triage] ERROR: No Gitea token found", file=sys.stderr)
+        sys.exit(1)
+    return token
+
+
+def api_get(path: str, token: str) -> list | dict:
+    """Minimal HTTP GET using urllib (no dependencies)."""
+    import urllib.request
+    url = f"{GITEA_API}/repos/{REPO_SLUG}/{path}"
+    req = urllib.request.Request(url, headers={
+        "Authorization": f"token {token}",
+        "Accept": "application/json",
+    })
+    with urllib.request.urlopen(req, timeout=15) as resp:
+        return json.loads(resp.read())
+
+
+def load_quarantine() -> dict:
+    """Load quarantined issues {issue_num: {reason, quarantined_at, failures}}."""
+    if QUARANTINE_FILE.exists():
+        try:
+            return json.loads(QUARANTINE_FILE.read_text())
+        except (json.JSONDecodeError, OSError):
+            pass
+    return {}
+
+
+def save_quarantine(q: dict) -> None:
+    QUARANTINE_FILE.parent.mkdir(parents=True, exist_ok=True)
+    QUARANTINE_FILE.write_text(json.dumps(q, indent=2) + "\n")
+
+
+def load_cycle_failures() -> dict[int, int]:
+    """Count failures per issue from recent cycle retros."""
+    failures: dict[int, int] = {}
+    if not CYCLE_RETRO_FILE.exists():
+        return failures
+    lines = CYCLE_RETRO_FILE.read_text().strip().splitlines()
+    for line in lines[-QUARANTINE_LOOKBACK:]:
+        try:
+            entry = json.loads(line)
+            if not entry.get("success", True):
+                issue = entry.get("issue")
+                if issue:
+                    failures[issue] = failures.get(issue, 0) + 1
+        except (json.JSONDecodeError, KeyError):
+            continue
+    return failures
+
+
+# ── Scoring ─────────────────────────────────────────────────────────────
+
+# Patterns that indicate file/function specificity
+FILE_PATTERNS = re.compile(
+    r"(?:src/|tests/|scripts/|\.py|\.html|\.js|\.yaml|\.toml|\.sh)", re.IGNORECASE
+)
+FUNCTION_PATTERNS = re.compile(
+    r"(?:def |class |function |method |`\w+\(\)`)", re.IGNORECASE
+)
+
+# Patterns that indicate acceptance criteria
+ACCEPTANCE_PATTERNS = re.compile(
+    r"(?:should|must|expect|verify|assert|test.?case|acceptance|criteria"
+    r"|pass(?:es|ing)|fail(?:s|ing)|return(?:s)?|raise(?:s)?)",
+    re.IGNORECASE,
+)
+TEST_PATTERNS = re.compile(
+    r"(?:tox|pytest|test_\w+|\.test\.|assert\s)", re.IGNORECASE
+)
+
+# Tags in issue titles
+TAG_PATTERN = re.compile(r"\[([^\]]+)\]")
+
+# Priority labels / tags
+BUG_TAGS = {"bug", "broken", "crash", "error", "fix", "regression", "hotfix"}
+FEATURE_TAGS = {"feature", "feat", "enhancement", "capability", "timmy-capability"}
+REFACTOR_TAGS = {"refactor", "cleanup", "tech-debt", "optimization", "perf"}
+META_TAGS = {"philosophy", "soul-gap", "discussion", "question", "rfc"}
+LOOP_TAG = "loop-generated"
+
+
+def extract_tags(title: str, labels: list[str]) -> set[str]:
+    """Pull tags from [bracket] notation in title + Gitea labels."""
+    tags = set()
+    for match in TAG_PATTERN.finditer(title):
+        tags.add(match.group(1).lower().strip())
+    for label in labels:
+        tags.add(label.lower().strip())
+    return tags
+
+
+def score_scope(title: str, body: str, tags: set[str]) -> int:
+    """0-3: How well-scoped is this issue?"""
+    text = f"{title}\n{body}"
+    score = 0
+
+    # Mentions specific files?
+    if FILE_PATTERNS.search(text):
+        score += 1
+
+    # Mentions specific functions/classes?
+    if FUNCTION_PATTERNS.search(text):
+        score += 1
+
+    # Short, focused title (not a novel)?
+    clean_title = TAG_PATTERN.sub("", title).strip()
+    if len(clean_title) < 80:
+        score += 1
+
+    # Philosophy/meta issues are inherently unscoped for dev work
+    if tags & META_TAGS:
+        score = max(0, score - 2)
+
+    return min(3, score)
+
+
+def score_acceptance(title: str, body: str, tags: set[str]) -> int:
+    """0-3: Does this have clear acceptance criteria?"""
+    text = f"{title}\n{body}"
+    score = 0
+
+    # Has acceptance-related language?
+    matches = len(ACCEPTANCE_PATTERNS.findall(text))
+    if matches >= 3:
+        score += 2
+    elif matches >= 1:
+        score += 1
+
+    # Mentions specific tests?
+    if TEST_PATTERNS.search(text):
+        score += 1
+
+    # Has a "## Problem" + "## Solution" or similar structure?
+    if re.search(r"##\s*(problem|solution|expected|actual|steps)", body, re.IGNORECASE):
+        score += 1
+
+    # Philosophy issues don't have testable criteria
+    if tags & META_TAGS:
+        score = max(0, score - 1)
+
+    return min(3, score)
+
+
+def score_alignment(title: str, body: str, tags: set[str]) -> int:
+    """0-3: How aligned is this with the north star?"""
+    score = 0
+
+    # Bug on main = highest priority
+    if tags & BUG_TAGS:
+        score += 3
+        return min(3, score)
+
+    # Refactors that improve code health
+    if tags & REFACTOR_TAGS:
+        score += 2
+
+    # Features that grow Timmy's capabilities
+    if tags & FEATURE_TAGS:
+        score += 2
+
+    # Loop-generated issues get a small boost (the loop found real problems)
+    if LOOP_TAG in tags:
+        score += 1
+
+    # Philosophy issues are important but not dev-actionable
+    if tags & META_TAGS:
+        score = 0
+
+    return min(3, score)
+
+
+def score_issue(issue: dict) -> dict:
+    """Score a single issue. Returns enriched dict."""
+    title = issue.get("title", "")
+    body = issue.get("body", "") or ""
+    labels = [l["name"] for l in issue.get("labels", [])]
+    tags = extract_tags(title, labels)
+    number = issue["number"]
+
+    scope = score_scope(title, body, tags)
+    acceptance = score_acceptance(title, body, tags)
+    alignment = score_alignment(title, body, tags)
+    total = scope + acceptance + alignment
+
+    # Determine issue type
+    if tags & BUG_TAGS:
+        issue_type = "bug"
+    elif tags & FEATURE_TAGS:
+        issue_type = "feature"
+    elif tags & REFACTOR_TAGS:
+        issue_type = "refactor"
+    elif tags & META_TAGS:
+        issue_type = "philosophy"
+    else:
+        issue_type = "unknown"
+
+    # Extract mentioned files from body
+    files = list(set(re.findall(r"(?:src|tests|scripts)/[\w/.]+\.(?:py|html|js|yaml)", body)))
+
+    return {
+        "issue": number,
+        "title": TAG_PATTERN.sub("", title).strip(),
+        "type": issue_type,
+        "score": total,
+        "scope": scope,
+        "acceptance": acceptance,
+        "alignment": alignment,
+        "tags": sorted(tags),
+        "files": files[:10],
+        "ready": total >= READY_THRESHOLD,
+    }
+
+
+# ── Quarantine ──────────────────────────────────────────────────────────
+
+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()
+
+    filtered = []
+    for item in scored:
+        num = item["issue"]
+        fail_count = failures.get(num, 0)
+        str_num = str(num)
+
+        if fail_count >= 2 and str_num not in quarantine:
+            quarantine[str_num] = {
+                "reason": f"Failed {fail_count} times in recent cycles",
+                "quarantined_at": now,
+                "failures": fail_count,
+            }
+            print(f"[triage] QUARANTINED #{num}: failed {fail_count} times")
+            continue
+
+        if str_num in quarantine:
+            print(f"[triage] Skipping #{num} (quarantined)")
+            continue
+
+        filtered.append(item)
+
+    save_quarantine(quarantine)
+    return filtered
+
+
+# ── Main ────────────────────────────────────────────────────────────────
+
+def run_triage() -> list[dict]:
+    token = get_token()
+
+    # Fetch all open issues (paginate)
+    page = 1
+    all_issues: list[dict] = []
+    while True:
+        batch = api_get(f"issues?state=open&limit=50&page={page}&type=issues", token)
+        if not batch:
+            break
+        all_issues.extend(batch)
+        if len(batch) < 50:
+            break
+        page += 1
+
+    print(f"[triage] Fetched {len(all_issues)} open issues")
+
+    # Score each
+    scored = [score_issue(i) for i in all_issues]
+
+    # Auto-quarantine repeat failures
+    scored = update_quarantine(scored)
+
+    # Sort: ready first, then by score descending, bugs always on top
+    def sort_key(item: dict) -> tuple:
+        return (
+            0 if item["type"] == "bug" else 1,
+            -item["score"],
+            item["issue"],
+        )
+
+    scored.sort(key=sort_key)
+
+    # Write queue (ready items only)
+    ready = [s for s in scored if s["ready"]]
+    not_ready = [s for s in scored if not s["ready"]]
+
+    # Save backup before writing (if current file exists and is valid)
+    if QUEUE_FILE.exists():
+        try:
+            json.loads(QUEUE_FILE.read_text())  # Validate current file
+            QUEUE_BACKUP_FILE.write_text(QUEUE_FILE.read_text())
+        except (json.JSONDecodeError, OSError):
+            pass  # Current file is corrupt, don't overwrite backup
+
+    # Write new queue file
+    QUEUE_FILE.parent.mkdir(parents=True, exist_ok=True)
+    QUEUE_FILE.write_text(json.dumps(ready, indent=2) + "\n")
+
+    # Validate the write by re-reading and parsing
+    try:
+        json.loads(QUEUE_FILE.read_text())
+    except (json.JSONDecodeError, OSError) as exc:
+        print(f"[triage] ERROR: queue.json validation failed: {exc}", file=sys.stderr)
+        # Restore from backup if available
+        if QUEUE_BACKUP_FILE.exists():
+            try:
+                backup_data = QUEUE_BACKUP_FILE.read_text()
+                json.loads(backup_data)  # Validate backup
+                QUEUE_FILE.write_text(backup_data)
+                print(f"[triage] Restored queue.json from backup")
+            except (json.JSONDecodeError, OSError) as restore_exc:
+                print(f"[triage] ERROR: Backup restore failed: {restore_exc}", file=sys.stderr)
+                # Write empty list as last resort
+                QUEUE_FILE.write_text("[]\n")
+        else:
+            # No backup, write empty list
+            QUEUE_FILE.write_text("[]\n")
+
+    # Write retro entry
+    retro_entry = {
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "total_open": len(all_issues),
+        "scored": len(scored),
+        "ready": len(ready),
+        "not_ready": len(not_ready),
+        "top_issue": ready[0]["issue"] if ready else None,
+        "quarantined": len(load_quarantine()),
+    }
+    RETRO_FILE.parent.mkdir(parents=True, exist_ok=True)
+    with open(RETRO_FILE, "a") as f:
+        f.write(json.dumps(retro_entry) + "\n")
+
+    # Summary
+    print(f"[triage] Ready: {len(ready)} | Not ready: {len(not_ready)}")
+    for item in ready[:5]:
+        flag = "🐛" if item["type"] == "bug" else "✦"
+        print(f"  {flag} #{item['issue']} score={item['score']} {item['title'][:60]}")
+    if not_ready:
+        print(f"[triage] Low-scoring ({len(not_ready)}):")
+        for item in not_ready[:3]:
+            print(f"    #{item['issue']} score={item['score']} {item['title'][:50]}")
+
+    return ready
+
+
+if __name__ == "__main__":
+    run_triage()

skills/research/architecture_spike.md

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

skills/research/competitive_scan.md

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

skills/research/game_analysis.md

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

skills/research/integration_guide.md

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

skills/research/state_of_art.md

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

skills/research/tool_evaluation.md

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

src/bannerlord/__init__.py

@@ -0,0 +1,49 @@
+"""Bannerlord M3 — Full Campaign Strategy.
+
+Timmy runs a complete Bannerlord campaign: economy, diplomacy, kingdom
+building, and war decisions — all via sovereign local inference.
+
+Key components:
+    gabs_client    — TCP JSON-RPC client for the GABS mod (port 4825)
+    types          — KingSubgoal, GameState, message schemas
+    session_memory — SQLite-backed multi-day strategic plan persistence
+    campaign       — CampaignOrchestrator tying all agents together
+    adapter        — WorldInterface adapter for use with the benchmark runner
+    agents/        — King, Vassal, and Companion agent hierarchy
+
+Quick start::
+
+    from bannerlord.campaign import CampaignOrchestrator
+    orch = CampaignOrchestrator()
+    summary = await orch.run(max_ticks=100)
+
+Register the world adapter::
+
+    from infrastructure.world import register_adapter
+    from bannerlord.adapter import BannerlordWorldAdapter
+    register_adapter("bannerlord", BannerlordWorldAdapter)
+
+M3 done-when condition:
+    Timmy establishes own kingdom with 3+ fiefs and
+    survives 100 in-game days as ruler.
+"""
+
+from bannerlord.adapter import BannerlordWorldAdapter
+from bannerlord.campaign import CampaignOrchestrator
+from bannerlord.gabs_client import GABSClient
+from bannerlord.session_memory import SessionMemory
+from bannerlord.types import (
+    GameState,
+    KingSubgoal,
+    SubgoalToken,
+)
+
+__all__ = [
+    "BannerlordWorldAdapter",
+    "CampaignOrchestrator",
+    "GABSClient",
+    "GameState",
+    "KingSubgoal",
+    "SessionMemory",
+    "SubgoalToken",
+]

src/bannerlord/adapter.py

@@ -0,0 +1,228 @@
+"""Bannerlord M3 — WorldInterface adapter wrapping the GABS TCP client.
+
+Plugs Bannerlord into the engine-agnostic ``WorldInterface`` contract so
+the benchmark runner and heartbeat loop can drive the campaign the same way
+they would drive any other game world.
+
+Register with::
+
+    from infrastructure.world import register_adapter
+    from bannerlord.adapter import BannerlordWorldAdapter
+    register_adapter("bannerlord", BannerlordWorldAdapter)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from datetime import UTC, datetime
+from typing import Any
+
+from bannerlord.gabs_client import GABSClient
+from bannerlord.types import GameState
+from infrastructure.world.interface import WorldInterface
+from infrastructure.world.types import (
+    ActionResult,
+    ActionStatus,
+    CommandInput,
+    PerceptionOutput,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class BannerlordWorldAdapter(WorldInterface):
+    """WorldInterface adapter for Bannerlord via the GABS mod.
+
+    ``observe()`` — fetches the full GameState from GABS and maps it to a
+    ``PerceptionOutput`` with structured fields.
+
+    ``act()`` — dispatches ``CommandInput.action`` as a GABS JSON-RPC call,
+    forwarding ``parameters`` as the call args.
+
+    ``speak()`` — sends a chat message via GABS (e.g., for companion NPC
+    conversations or on-screen overlays).
+
+    Degrades gracefully when GABS is unavailable.
+    """
+
+    def __init__(
+        self,
+        *,
+        host: str = "127.0.0.1",
+        port: int = 4825,
+        timeout: float = 10.0,
+    ) -> None:
+        self._client = GABSClient(host=host, port=port, timeout=timeout)
+        self._last_state: GameState | None = None
+
+    # -- lifecycle ---------------------------------------------------------
+
+    def connect(self) -> None:
+        """Synchronous connect wrapper (runs async in a new event loop)."""
+        try:
+            loop = asyncio.get_event_loop()
+            if loop.is_running():
+                # Inside async context — caller should use async connect
+                logger.warning(
+                    "BannerlordWorldAdapter.connect() called from async context; "
+                    "use 'await adapter.async_connect()' instead"
+                )
+                return
+            loop.run_until_complete(self._client.connect())
+        except Exception as exc:
+            logger.warning("BannerlordWorldAdapter.connect() failed: %s", exc)
+
+    def disconnect(self) -> None:
+        """Synchronous disconnect wrapper."""
+        try:
+            loop = asyncio.get_event_loop()
+            if loop.is_running():
+                return
+            loop.run_until_complete(self._client.disconnect())
+        except Exception as exc:
+            logger.debug("BannerlordWorldAdapter.disconnect() error: %s", exc)
+
+    async def async_connect(self) -> bool:
+        """Async connect — preferred in async contexts."""
+        return await self._client.connect()
+
+    async def async_disconnect(self) -> None:
+        """Async disconnect."""
+        await self._client.disconnect()
+
+    @property
+    def is_connected(self) -> bool:
+        return self._client.is_connected
+
+    # -- WorldInterface contract ------------------------------------------
+
+    def observe(self) -> PerceptionOutput:
+        """Return a PerceptionOutput derived from the current GABS GameState.
+
+        Falls back to an empty perception if GABS is unreachable.
+        """
+        try:
+            loop = asyncio.get_event_loop()
+            if loop.is_running():
+                logger.warning("observe() called from async context — use async_observe()")
+                return self._empty_perception()
+            state = loop.run_until_complete(self._client.get_game_state())
+            return self._state_to_perception(state)
+        except Exception as exc:
+            logger.warning("BannerlordWorldAdapter.observe() error: %s", exc)
+            return self._empty_perception()
+
+    async def async_observe(self) -> PerceptionOutput:
+        """Async observe — preferred in async contexts."""
+        try:
+            state = await self._client.get_game_state()
+            self._last_state = state
+            return self._state_to_perception(state)
+        except Exception as exc:
+            logger.warning("async_observe() error: %s", exc)
+            return self._empty_perception()
+
+    def act(self, command: CommandInput) -> ActionResult:
+        """Dispatch a command to GABS.  Returns success/failure."""
+        try:
+            loop = asyncio.get_event_loop()
+            if loop.is_running():
+                logger.warning("act() called from async context — use async_act()")
+                return ActionResult(status=ActionStatus.NOOP)
+            result = loop.run_until_complete(self.async_act(command))
+            return result
+        except Exception as exc:
+            logger.warning("BannerlordWorldAdapter.act() error: %s", exc)
+            return ActionResult(
+                status=ActionStatus.FAILURE,
+                message=str(exc),
+            )
+
+    async def async_act(self, command: CommandInput) -> ActionResult:
+        """Async command dispatch."""
+        try:
+            result = await self._client._call(
+                command.action, command.parameters or {}
+            )
+            if result is None:
+                return ActionResult(
+                    status=ActionStatus.FAILURE,
+                    message=f"GABS returned no result for {command.action}",
+                )
+            return ActionResult(
+                status=ActionStatus.SUCCESS,
+                message=f"GABS executed: {command.action}",
+                data=result if isinstance(result, dict) else {"result": result},
+            )
+        except Exception as exc:
+            logger.warning("async_act(%s) error: %s", command.action, exc)
+            return ActionResult(status=ActionStatus.FAILURE, message=str(exc))
+
+    def speak(self, message: str, target: str | None = None) -> None:
+        """Send a message via GABS (e.g., companion dialogue or overlay)."""
+        try:
+            loop = asyncio.get_event_loop()
+            if loop.is_running():
+                return
+            loop.run_until_complete(
+                self._client._call("chat/send", {"message": message, "target": target})
+            )
+        except Exception as exc:
+            logger.debug("BannerlordWorldAdapter.speak() error: %s", exc)
+
+    # -- helpers -----------------------------------------------------------
+
+    def _state_to_perception(self, state: GameState) -> PerceptionOutput:
+        """Map a GameState snapshot to a PerceptionOutput."""
+        entities: list[str] = []
+        events: list[str] = []
+
+        # Party location
+        if state.party.location:
+            entities.append(f"location:{state.party.location}")
+
+        # Kingdom status
+        if state.has_kingdom():
+            entities.append(f"kingdom:{state.kingdom.name}")
+            for fief in state.kingdom.fiefs:
+                entities.append(f"fief:{fief}")
+
+        # Active wars as events
+        for war in state.kingdom.active_wars:
+            events.append(f"at_war_with:{war}")
+
+        # Faction snapshot
+        for faction in state.factions:
+            entities.append(f"faction:{faction.name}[{faction.army_strength}]")
+
+        # Alerts
+        if state.is_two_front_war():
+            events.append("alert:two_front_war")
+        if state.party.wounded_pct > 0.30:
+            events.append(f"alert:wounded_{state.party.wounded_pct:.0%}")
+        if state.party.food_days < 3:
+            events.append("alert:low_food")
+
+        return PerceptionOutput(
+            timestamp=datetime.now(UTC),
+            location=state.party.location,
+            entities=entities,
+            events=events,
+            raw=state.raw,
+        )
+
+    @staticmethod
+    def _empty_perception() -> PerceptionOutput:
+        return PerceptionOutput(
+            timestamp=datetime.now(UTC),
+            location="",
+            entities=[],
+            events=["gabs:unavailable"],
+            raw={"adapter": "bannerlord", "connected": False},
+        )
+
+    @property
+    def last_game_state(self) -> GameState | None:
+        """Return the most recently observed GameState."""
+        return self._last_state

src/bannerlord/agents/__init__.py

@@ -0,0 +1,4 @@
+"""Bannerlord M3 — feudal agent hierarchy.
+
+King → Vassal → Companion, following Ahilan & Dayan (2019).
+"""

src/bannerlord/agents/companions/__init__.py

@@ -0,0 +1 @@
+"""Bannerlord M3 — Companion worker agents (lowest tier)."""

src/bannerlord/agents/companions/caravan.py

@@ -0,0 +1,61 @@
+"""Bannerlord M3 — Caravan Companion (trade operations).
+
+Handles trade route assessment, buy/sell goods, caravan deployment.
+Triggered by TRADE subgoal or when treasury is below threshold.
+
+Minimum margin threshold: 15% (never buy goods without ≥ 15% resale margin).
+"""
+
+from __future__ import annotations
+
+import logging
+
+from bannerlord.types import GameState, KingSubgoal, SubgoalToken
+
+logger = logging.getLogger(__name__)
+
+_MIN_MARGIN_PCT = 0.15          # minimum profitable resale margin
+_CARAVAN_DENAR_THRESHOLD = 10_000  # must have 10k denars to deploy a caravan
+
+
+class CaravanCompanion:
+    """Companion worker for trade route management."""
+
+    AGENT_ID = "caravan_companion"
+
+    def evaluate(
+        self, state: GameState, subgoal: KingSubgoal
+    ) -> list[dict]:
+        """Return trade primitives to execute.
+
+        Returns:
+            List of dicts with 'primitive' and 'args' keys.
+        """
+        if subgoal.token != SubgoalToken.TRADE:
+            return []
+
+        actions: list[dict] = []
+        party = state.party
+
+        # Always assess prices at current location first
+        actions.append({
+            "primitive": "assess_prices",
+            "args": {"town": party.location},
+        })
+
+        # Deploy a caravan if treasury is flush
+        if party.denars >= _CARAVAN_DENAR_THRESHOLD and party.location:
+            actions.append({
+                "primitive": "establish_caravan",
+                "args": {"town": party.location},
+            })
+
+        return actions
+
+    @staticmethod
+    def is_profitable_trade(buy_price: int, sell_price: int) -> bool:
+        """Return True if the trade margin meets the minimum threshold."""
+        if buy_price <= 0:
+            return False
+        margin = (sell_price - buy_price) / buy_price
+        return margin >= _MIN_MARGIN_PCT

src/bannerlord/agents/companions/logistics.py

@@ -0,0 +1,78 @@
+"""Bannerlord M3 — Logistics Companion (party management).
+
+Handles recruit, supply, rest, prisoner sale, and troop upgrade primitives.
+Runs on Qwen3:8b for sub-2-second response times.
+
+Triggered by RECRUIT and HEAL subgoals, or by party condition thresholds.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from bannerlord.types import GameState, KingSubgoal, SubgoalToken
+
+logger = logging.getLogger(__name__)
+
+_FOOD_WARN_DAYS = 5
+_WOUND_WARN_PCT = 0.20
+_PRISONER_CAP = 20
+
+
+class LogisticsCompanion:
+    """Companion worker for party logistics.
+
+    Evaluates the current party state and returns a list of primitive
+    action names + args to dispatch to the GABSClient.
+    """
+
+    AGENT_ID = "logistics_companion"
+
+    def evaluate(
+        self, state: GameState, subgoal: KingSubgoal
+    ) -> list[dict]:
+        """Return primitives to execute given current state and active subgoal.
+
+        Returns:
+            List of dicts with 'primitive' and 'args' keys.
+        """
+        actions: list[dict] = []
+        party = state.party
+
+        # Subgoal-driven recruitment
+        if subgoal.token == SubgoalToken.RECRUIT:
+            qty = subgoal.quantity or 20
+            actions.append({
+                "primitive": "recruit_troop",
+                "args": {"troop_type": "infantry", "qty": qty},
+            })
+
+        # Emergency rest on heavy wounds
+        if subgoal.token == SubgoalToken.HEAL or party.wounded_pct > _WOUND_WARN_PCT:
+            actions.append({
+                "primitive": "rest_party",
+                "args": {"days": 3},
+            })
+
+        # Replenish food if low
+        if party.food_days < _FOOD_WARN_DAYS:
+            actions.append({
+                "primitive": "buy_supplies",
+                "args": {"qty": max(0, 10 - party.food_days)},
+            })
+
+        # Sell prisoners when near cap
+        if party.prisoners >= _PRISONER_CAP:
+            actions.append({
+                "primitive": "sell_prisoners",
+                "args": {"location": party.location},
+            })
+
+        # Upgrade troops when stable
+        if subgoal.token == SubgoalToken.TRAIN:
+            actions.append({
+                "primitive": "upgrade_troops",
+                "args": {},
+            })
+
+        return actions

src/bannerlord/agents/companions/scout.py

@@ -0,0 +1,58 @@
+"""Bannerlord M3 — Scout Companion (intelligence gathering).
+
+Handles lord tracking, garrison assessment, and patrol route mapping.
+Triggered by SPY subgoal or proactively before expansion decisions.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from bannerlord.types import GameState, KingSubgoal, SubgoalToken
+
+logger = logging.getLogger(__name__)
+
+
+class ScoutCompanion:
+    """Companion worker for tactical intelligence."""
+
+    AGENT_ID = "scout_companion"
+
+    def evaluate(
+        self, state: GameState, subgoal: KingSubgoal
+    ) -> list[dict]:
+        """Return scouting primitives to execute.
+
+        Returns:
+            List of dicts with 'primitive' and 'args' keys.
+        """
+        actions: list[dict] = []
+
+        if subgoal.token == SubgoalToken.SPY:
+            target = subgoal.target
+            if target:
+                actions.append({
+                    "primitive": "track_lord",
+                    "args": {"lord_name": target},
+                })
+
+        elif subgoal.token == SubgoalToken.EXPAND_TERRITORY:
+            target = subgoal.target
+            if target:
+                actions.append({
+                    "primitive": "assess_garrison",
+                    "args": {"settlement": target},
+                })
+
+        # Proactively map patrols in active war regions
+        for war_faction in state.kingdom.active_wars:
+            # Find a fief belonging to the enemy as the region reference
+            for faction in state.factions:
+                if faction.name == war_faction and faction.fiefs:
+                    actions.append({
+                        "primitive": "map_patrol_routes",
+                        "args": {"region": faction.fiefs[0]},
+                    })
+                    break  # one region per enemy faction per tick
+
+        return actions

src/bannerlord/agents/diplomacy_vassal.py

@@ -0,0 +1,145 @@
+"""Bannerlord M3 — Diplomacy Vassal agent.
+
+Handles relations management: alliances, peace deals, tribute, marriage.
+Responds to the ALLY subgoal.
+
+Reward function:
+    R_diplo = w1 * AlliesCount
+            + w2 * TruceDurationValue
+            + w3 * RelationsScore_weighted
+            - w4 * ActiveWarsFront
+            + w5 * SubgoalBonus
+
+Key strategic rules:
+  - Never start a new war if already in 2+ wars (2-front war rule)
+  - Prefer peace with weakest current enemy when overextended
+  - Time alliances before declaring war to reduce isolation risk
+"""
+
+from __future__ import annotations
+
+import logging
+
+from bannerlord.types import (
+    GameState,
+    KingSubgoal,
+    SubgoalToken,
+    TaskMessage,
+    VassalReward,
+)
+
+logger = logging.getLogger(__name__)
+
+_W1_ALLIES = 0.30
+_W2_TRUCE = 0.25
+_W3_RELATIONS = 0.25
+_W4_WAR_FRONTS = 0.15
+_W5_SUBGOAL = 0.05
+
+_SUBGOAL_TRIGGERS = {SubgoalToken.ALLY}
+_MAX_WAR_FRONTS = 2  # flag when at 2+ simultaneous wars (two-front war)
+
+
+class DiplomacyVassal:
+    """Mid-tier agent responsible for diplomatic relations."""
+
+    AGENT_ID = "diplomacy_vassal"
+
+    def is_relevant(self, subgoal: KingSubgoal) -> bool:
+        return subgoal.token in _SUBGOAL_TRIGGERS
+
+    def plan(self, state: GameState, subgoal: KingSubgoal) -> list[TaskMessage]:
+        """Return TaskMessages for the current diplomatic subgoal."""
+        tasks: list[TaskMessage] = []
+
+        if subgoal.token == SubgoalToken.ALLY:
+            tasks.extend(self._plan_alliance(state, subgoal))
+
+        return tasks
+
+    def _plan_alliance(
+        self, state: GameState, subgoal: KingSubgoal
+    ) -> list[TaskMessage]:
+        """Plan diplomatic outreach to reduce war fronts or build alliances."""
+        tasks: list[TaskMessage] = []
+        target = subgoal.target
+
+        if not target:
+            logger.warning("DiplomacyVassal: no target for ALLY subgoal")
+            return tasks
+
+        # If target is already an enemy, propose peace
+        if target in state.kingdom.active_wars:
+            tasks.append(
+                TaskMessage(
+                    from_agent=self.AGENT_ID,
+                    to_agent="gabs",
+                    primitive="propose_peace",
+                    args={"faction": target, "tribute": 0},
+                    priority=subgoal.priority * 1.5,
+                )
+            )
+        else:
+            # Otherwise pursue alliance
+            tasks.append(
+                TaskMessage(
+                    from_agent=self.AGENT_ID,
+                    to_agent="gabs",
+                    primitive="send_envoy",
+                    args={
+                        "faction": target,
+                        "message": "We seek a lasting alliance for mutual defence.",
+                    },
+                    priority=subgoal.priority,
+                )
+            )
+            tasks.append(
+                TaskMessage(
+                    from_agent=self.AGENT_ID,
+                    to_agent="gabs",
+                    primitive="request_alliance",
+                    args={"faction": target},
+                    priority=subgoal.priority,
+                )
+            )
+
+        return tasks
+
+    def should_avoid_war(self, state: GameState) -> bool:
+        """Return True if starting a new war would be strategically unsound."""
+        return state.active_war_count() >= _MAX_WAR_FRONTS  # 2-front war check
+
+    def compute_reward(
+        self,
+        prev_state: GameState,
+        curr_state: GameState,
+        active_subgoal: KingSubgoal,
+    ) -> VassalReward:
+        """Compute Diplomacy Vassal reward."""
+        allies_count = len(curr_state.kingdom.active_alliances)
+        truce_value = 50.0  # placeholder — days of truce remaining
+        relations_avg = 30.0  # placeholder — weighted relations score
+        war_fronts = curr_state.active_war_count()
+
+        subgoal_bonus = 1.0 if active_subgoal.token in _SUBGOAL_TRIGGERS else 0.0
+
+        total = (
+            _W1_ALLIES * allies_count * 10
+            + _W2_TRUCE * truce_value / 100
+            + _W3_RELATIONS * relations_avg / 100
+            - _W4_WAR_FRONTS * war_fronts * 10
+            + _W5_SUBGOAL * subgoal_bonus * 10
+        )
+
+        return VassalReward(
+            agent_id=self.AGENT_ID,
+            component_scores={
+                "allies_count": allies_count,
+                "truce_value": truce_value,
+                "relations_avg": relations_avg,
+                "war_fronts": -war_fronts,
+                "subgoal_bonus": subgoal_bonus,
+            },
+            subgoal_bonus=subgoal_bonus,
+            total=total,
+        )

src/bannerlord/agents/economy_vassal.py

@@ -0,0 +1,151 @@
+"""Bannerlord M3 — Economy Vassal agent.
+
+Handles settlement management, tax collection, construction, and food supply.
+Responds to FORTIFY and CONSOLIDATE subgoals.
+
+Reward function:
+    R_econ = w1 * DailyDenarsIncome
+           + w2 * FoodStockBuffer
+           + w3 * LoyaltyAverage
+           - w4 * ConstructionQueueLength
+           + w5 * SubgoalBonus
+"""
+
+from __future__ import annotations
+
+import logging
+
+from bannerlord.types import (
+    GameState,
+    KingSubgoal,
+    SubgoalToken,
+    TaskMessage,
+    VassalReward,
+)
+
+logger = logging.getLogger(__name__)
+
+_W1_INCOME = 0.35
+_W2_FOOD = 0.25
+_W3_LOYALTY = 0.20
+_W4_CONSTRUCTION = 0.15
+_W5_SUBGOAL = 0.05
+
+_SUBGOAL_TRIGGERS = {SubgoalToken.FORTIFY, SubgoalToken.CONSOLIDATE}
+
+_LOW_FOOD_THRESHOLD = 3   # days of food remaining
+_INCOME_TARGET = 200       # daily net income target (denars)
+
+
+class EconomyVassal:
+    """Mid-tier agent responsible for settlement economy."""
+
+    AGENT_ID = "economy_vassal"
+
+    def is_relevant(self, subgoal: KingSubgoal) -> bool:
+        return subgoal.token in _SUBGOAL_TRIGGERS
+
+    def plan(self, state: GameState, subgoal: KingSubgoal) -> list[TaskMessage]:
+        """Return TaskMessages for the current economic subgoal."""
+        tasks: list[TaskMessage] = []
+
+        # Always maintain food supply
+        if state.party.food_days < _LOW_FOOD_THRESHOLD:
+            tasks.append(
+                TaskMessage(
+                    from_agent=self.AGENT_ID,
+                    to_agent="logistics_companion",
+                    primitive="buy_supplies",
+                    args={"qty": 10},
+                    priority=2.0,
+                )
+            )
+
+        if subgoal.token == SubgoalToken.FORTIFY:
+            tasks.extend(self._plan_fortify(state, subgoal))
+        elif subgoal.token == SubgoalToken.CONSOLIDATE:
+            tasks.extend(self._plan_consolidate(state))
+
+        return tasks
+
+    def _plan_fortify(
+        self, state: GameState, subgoal: KingSubgoal
+    ) -> list[TaskMessage]:
+        """Queue construction projects in owned settlements."""
+        tasks: list[TaskMessage] = []
+        target = subgoal.target or (state.kingdom.fiefs[0] if state.kingdom.fiefs else None)
+        if not target:
+            return tasks
+        tasks.append(
+            TaskMessage(
+                from_agent=self.AGENT_ID,
+                to_agent="gabs",
+                primitive="build_project",
+                args={"settlement": target, "project": "granary"},
+                priority=1.2,
+            )
+        )
+        tasks.append(
+            TaskMessage(
+                from_agent=self.AGENT_ID,
+                to_agent="gabs",
+                primitive="set_tax_policy",
+                args={"settlement": target, "policy": "normal"},
+                priority=1.0,
+            )
+        )
+        return tasks
+
+    def _plan_consolidate(self, state: GameState) -> list[TaskMessage]:
+        """Stabilise: optimise tax and food across all fiefs."""
+        tasks: list[TaskMessage] = []
+        net_income = state.kingdom.daily_income - state.kingdom.daily_expenses
+        for fief in state.kingdom.fiefs:
+            policy = "normal" if net_income >= _INCOME_TARGET else "low"
+            tasks.append(
+                TaskMessage(
+                    from_agent=self.AGENT_ID,
+                    to_agent="gabs",
+                    primitive="set_tax_policy",
+                    args={"settlement": fief, "policy": policy},
+                    priority=0.8,
+                )
+            )
+        return tasks
+
+    def compute_reward(
+        self,
+        prev_state: GameState,
+        curr_state: GameState,
+        active_subgoal: KingSubgoal,
+    ) -> VassalReward:
+        """Compute Economy Vassal reward."""
+        income_delta = (
+            curr_state.kingdom.daily_income - prev_state.kingdom.daily_income
+        )
+        food_buffer = curr_state.party.food_days
+        loyalty_avg = 70.0  # placeholder — real value from GABS raw data
+        queue_len = 0        # placeholder
+
+        subgoal_bonus = 1.0 if active_subgoal.token in _SUBGOAL_TRIGGERS else 0.0
+
+        total = (
+            _W1_INCOME * income_delta
+            + _W2_FOOD * food_buffer
+            + _W3_LOYALTY * loyalty_avg / 100
+            - _W4_CONSTRUCTION * queue_len
+            + _W5_SUBGOAL * subgoal_bonus * 10
+        )
+
+        return VassalReward(
+            agent_id=self.AGENT_ID,
+            component_scores={
+                "income_delta": income_delta,
+                "food_buffer": food_buffer,
+                "loyalty_avg": loyalty_avg,
+                "queue_len": -queue_len,
+                "subgoal_bonus": subgoal_bonus,
+            },
+            subgoal_bonus=subgoal_bonus,
+            total=total,
+        )

src/bannerlord/agents/king.py

@@ -0,0 +1,266 @@
+"""Bannerlord M3 — King agent (Timmy, strategic tier).
+
+The King operates on the campaign-map timescale (1 decision per in-game day).
+He reads the full GameState and emits a single KingSubgoal token that vassals
+interpret.  He uses Qwen3:32b via the LLM router.
+
+Decision rules baked in (no LLM required for simple cases):
+  - Never initiate a second war while already fighting one (avoid 2-front wars)
+  - Prioritise HEAL when party wounds > 30 %
+  - Prioritise RECRUIT when troops < 80
+  - Prioritise TRADE when denars < 5,000
+  - If kingdom has < 3 fiefs and no active war, prioritise EXPAND_TERRITORY
+  - Default to CONSOLIDATE when conditions are stable
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import UTC, datetime
+from typing import Any
+
+from bannerlord.types import (
+    GameState,
+    KingSubgoal,
+    SubgoalToken,
+)
+
+logger = logging.getLogger(__name__)
+
+# Hard thresholds for rule-based fallback decisions
+_MIN_TROOPS = 80
+_MIN_DENARS = 5_000
+_MAX_WOUND_PCT = 0.30
+_TARGET_FIEFS = 3
+_SURVIVAL_DAYS = 100
+
+
+class KingAgent:
+    """Strategic decision-maker for the Bannerlord campaign.
+
+    The King agent is sovereign — it cannot be terminated by vassals.
+    It decides the active subgoal at most once per campaign tick.
+
+    Usage::
+
+        king = KingAgent(model="qwen3:32b")
+        subgoal = king.decide(game_state)
+    """
+
+    def __init__(
+        self,
+        *,
+        model: str = "qwen3:32b",
+        temperature: float = 0.1,
+    ) -> None:
+        self._model = model
+        self._temperature = temperature
+        self._last_subgoal: KingSubgoal | None = None
+        self._tick = 0
+        self._session_id: str | None = None
+
+    def set_session(self, session_id: str) -> None:
+        self._session_id = session_id
+
+    # -- primary decision interface ----------------------------------------
+
+    def decide(self, state: GameState) -> KingSubgoal:
+        """Return the King's subgoal for the current campaign tick.
+
+        Uses rule-based heuristics as the primary decision engine.
+        LLM override can be wired in via ``_llm_decide`` in a future PR.
+
+        Args:
+            state: Full game state snapshot from GABS.
+
+        Returns:
+            A KingSubgoal to be broadcast to vassals.
+        """
+        self._tick += 1
+        subgoal = self._rule_based_decide(state)
+        self._last_subgoal = subgoal
+        logger.info(
+            "King[tick=%d, day=%d] → %s (target=%s)",
+            self._tick,
+            state.in_game_day,
+            subgoal.token,
+            subgoal.target,
+        )
+        return subgoal
+
+    # -- rule-based strategy engine ----------------------------------------
+
+    def _rule_based_decide(self, state: GameState) -> KingSubgoal:
+        """Encode campaign strategy as prioritised decision rules.
+
+        Priority order (highest to lowest):
+        1. Emergency: heal if heavily wounded
+        2. Survival: recruit if dangerously low on troops
+        3. Economy: earn income if broke
+        4. Diplomacy: seek peace if in a 2-front war
+        5. Expansion: take fiefs if not at war and need more territory
+        6. Alliance: seek allies when preparing for war
+        7. Default: consolidate and stabilise
+        """
+        party = state.party
+        kingdom = state.kingdom
+
+        # 1. Emergency heal
+        if party.wounded_pct > _MAX_WOUND_PCT:
+            return KingSubgoal(
+                token=SubgoalToken.HEAL,
+                context=f"{party.wounded_pct:.0%} of party is wounded — rest required",
+            )
+
+        # 2. Critical recruitment
+        if party.troops < _MIN_TROOPS:
+            return KingSubgoal(
+                token=SubgoalToken.RECRUIT,
+                quantity=_MIN_TROOPS - party.troops,
+                context=f"Party at {party.troops} troops — must reach {_MIN_TROOPS}",
+            )
+
+        # 3. Destitute treasury
+        if party.denars < _MIN_DENARS:
+            return KingSubgoal(
+                token=SubgoalToken.TRADE,
+                context=f"Treasury at {party.denars:,} denars — run trade routes",
+            )
+
+        # 4. Avoid 2-front war: seek peace when fighting 2+ enemies
+        if state.is_two_front_war():
+            # Pick the weakest enemy to negotiate peace with first
+            weakest = self._weakest_enemy(state)
+            return KingSubgoal(
+                token=SubgoalToken.ALLY,
+                target=weakest,
+                context="2-front war detected — de-escalate with weakest enemy",
+            )
+
+        # 5. Kingdom not yet established: work toward first fief
+        if not state.has_kingdom():
+            if party.troops >= 120 and state.active_war_count() == 0:
+                target_fief = self._select_expansion_target(state)
+                return KingSubgoal(
+                    token=SubgoalToken.EXPAND_TERRITORY,
+                    target=target_fief,
+                    context="No kingdom yet — capture a fief to establish one",
+                )
+            elif state.active_war_count() == 0:
+                # Not ready to fight; train up first
+                return KingSubgoal(
+                    token=SubgoalToken.TRAIN,
+                    context="Building army before first expansion",
+                )
+
+        # 6. Expand if below target fief count and no active war
+        if state.fief_count() < _TARGET_FIEFS and state.active_war_count() == 0:
+            target_fief = self._select_expansion_target(state)
+            return KingSubgoal(
+                token=SubgoalToken.EXPAND_TERRITORY,
+                target=target_fief,
+                priority=1.5,
+                context=f"Only {state.fief_count()} fiefs — need {_TARGET_FIEFS}",
+            )
+
+        # 7. Seek allies when stable and below fief target
+        if not kingdom.active_alliances and state.active_war_count() == 0:
+            ally_candidate = self._best_alliance_candidate(state)
+            if ally_candidate:
+                return KingSubgoal(
+                    token=SubgoalToken.ALLY,
+                    target=ally_candidate,
+                    context="Stable moment — pursue defensive alliance",
+                )
+
+        # 8. Fortify if kingdom exists and there are fiefs to improve
+        if state.has_kingdom() and state.fief_count() > 0:
+            if kingdom.daily_income - kingdom.daily_expenses < 100:
+                return KingSubgoal(
+                    token=SubgoalToken.FORTIFY,
+                    context="Low net income — invest in settlements",
+                )
+
+        # 9. Default: consolidate
+        return KingSubgoal(
+            token=SubgoalToken.CONSOLIDATE,
+            context="Stable — hold territory and recover strength",
+        )
+
+    # -- helper methods ----------------------------------------------------
+
+    def _weakest_enemy(self, state: GameState) -> str | None:
+        """Return the name of the weakest faction currently at war with us."""
+        enemy_names = set(state.kingdom.active_wars)
+        enemies = [f for f in state.factions if f.name in enemy_names]
+        if not enemies:
+            return None
+        return min(enemies, key=lambda f: f.army_strength).name
+
+    def _select_expansion_target(self, state: GameState) -> str | None:
+        """Select the most vulnerable enemy settlement to target."""
+        # Prefer factions already at war with others (distracted)
+        for faction in state.factions:
+            if len(faction.is_at_war_with) >= 2 and faction.fiefs:
+                return faction.fiefs[0]
+        # Fallback: weakest faction with fiefs
+        candidates = [f for f in state.factions if f.fiefs]
+        if candidates:
+            weakest = min(candidates, key=lambda f: f.army_strength)
+            return weakest.fiefs[0]
+        return None
+
+    def _best_alliance_candidate(self, state: GameState) -> str | None:
+        """Return the best faction to approach for an alliance."""
+        # Prefer factions with good relations and no active war with us
+        enemy_names = set(state.kingdom.active_wars)
+        candidates = [
+            f
+            for f in state.factions
+            if f.name not in enemy_names
+            and f.name != state.kingdom.name
+        ]
+        if not candidates:
+            return None
+        # Pick the strongest candidate (most useful ally)
+        return max(candidates, key=lambda f: f.army_strength).name
+
+    # -- accessors ---------------------------------------------------------
+
+    @property
+    def last_subgoal(self) -> KingSubgoal | None:
+        return self._last_subgoal
+
+    @property
+    def tick(self) -> int:
+        return self._tick
+
+    def campaign_summary(self, state: GameState) -> dict[str, Any]:
+        """Return a brief summary of the campaign status."""
+        return {
+            "tick": self._tick,
+            "in_game_day": state.in_game_day,
+            "has_kingdom": state.has_kingdom(),
+            "fief_count": state.fief_count(),
+            "active_wars": state.active_war_count(),
+            "two_front_war": state.is_two_front_war(),
+            "troops": state.party.troops,
+            "denars": state.party.denars,
+            "survival_goal_met": (
+                state.has_kingdom()
+                and state.fief_count() >= _TARGET_FIEFS
+                and state.in_game_day >= _SURVIVAL_DAYS
+            ),
+        }
+
+    def is_done_condition_met(self, state: GameState) -> bool:
+        """Return True when the M3 done-when condition is satisfied.
+
+        Done when: Timmy establishes own kingdom with 3+ fiefs and
+        survives 100 in-game days as ruler.
+        """
+        return (
+            state.has_kingdom()
+            and state.fief_count() >= _TARGET_FIEFS
+            and state.in_game_day >= _SURVIVAL_DAYS
+        )

src/bannerlord/agents/war_vassal.py

@@ -0,0 +1,236 @@
+"""Bannerlord M3 — War Vassal agent.
+
+Handles military operations: sieges, field battles, raids, defensive
+maneuvers.  Responds to EXPAND_TERRITORY, RAID_ECONOMY, and TRAIN subgoals.
+
+Reward function (from feudal hierarchy design):
+    R_war = w1 * ΔTerritoryValue
+          + w2 * ΔArmyStrength_ratio
+          - w3 * CasualtyCost
+          - w4 * SupplyCost
+          + w5 * SubgoalBonus
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from bannerlord.types import (
+    GameState,
+    KingSubgoal,
+    SubgoalToken,
+    TaskMessage,
+    VassalReward,
+)
+
+if TYPE_CHECKING:
+    pass
+
+logger = logging.getLogger(__name__)
+
+# Reward weights
+_W1_TERRITORY = 0.40
+_W2_ARMY_RATIO = 0.25
+_W3_CASUALTY = 0.20
+_W4_SUPPLY = 0.10
+_W5_SUBGOAL = 0.05
+
+_SUBGOAL_TRIGGERS = {
+    SubgoalToken.EXPAND_TERRITORY,
+    SubgoalToken.RAID_ECONOMY,
+    SubgoalToken.TRAIN,
+}
+
+
+@dataclass
+class WarContext:
+    """Mutable state tracked across War Vassal decisions."""
+
+    active_siege: str | None = None
+    last_auto_resolve_result: dict = field(default_factory=dict)
+    territory_gained: int = 0
+    casualties_taken: int = 0
+
+
+class WarVassal:
+    """Mid-tier agent responsible for military operations.
+
+    Runs at 4× the King's decision frequency.  Translates KingSubgoals
+    into concrete TaskMessages for the Logistics Companion (troop management)
+    and issues direct GABS calls for combat actions.
+    """
+
+    AGENT_ID = "war_vassal"
+
+    def __init__(self) -> None:
+        self._ctx = WarContext()
+        self._prev_army_ratio: float = 1.0
+
+    def is_relevant(self, subgoal: KingSubgoal) -> bool:
+        """Return True if this vassal should act on *subgoal*."""
+        return subgoal.token in _SUBGOAL_TRIGGERS
+
+    def plan(self, state: GameState, subgoal: KingSubgoal) -> list[TaskMessage]:
+        """Return a list of TaskMessages for the current subgoal.
+
+        Args:
+            state:    Current game state.
+            subgoal:  Active King subgoal.
+
+        Returns:
+            Ordered list of TaskMessages to dispatch.
+        """
+        tasks: list[TaskMessage] = []
+
+        if subgoal.token == SubgoalToken.EXPAND_TERRITORY:
+            tasks.extend(self._plan_expansion(state, subgoal))
+        elif subgoal.token == SubgoalToken.RAID_ECONOMY:
+            tasks.extend(self._plan_raid(state, subgoal))
+        elif subgoal.token == SubgoalToken.TRAIN:
+            tasks.extend(self._plan_training(state))
+
+        return tasks
+
+    def _plan_expansion(
+        self, state: GameState, subgoal: KingSubgoal
+    ) -> list[TaskMessage]:
+        """Plan territory expansion toward subgoal.target."""
+        tasks: list[TaskMessage] = []
+        target = subgoal.target
+
+        if not target:
+            logger.warning("WarVassal.EXPAND_TERRITORY: no target in subgoal")
+            return tasks
+
+        # Scout garrison before sieging
+        tasks.append(
+            TaskMessage(
+                from_agent=self.AGENT_ID,
+                to_agent="scout_companion",
+                primitive="assess_garrison",
+                args={"settlement": target},
+                priority=1.5,
+            )
+        )
+
+        # Ensure troops are sufficient (delegate to logistics if thin)
+        if state.party.troops < 100:
+            tasks.append(
+                TaskMessage(
+                    from_agent=self.AGENT_ID,
+                    to_agent="logistics_companion",
+                    primitive="recruit_troop",
+                    args={"troop_type": "infantry", "qty": 100 - state.party.troops},
+                    priority=1.8,
+                )
+            )
+
+        # Issue the siege order
+        tasks.append(
+            TaskMessage(
+                from_agent=self.AGENT_ID,
+                to_agent="gabs",
+                primitive="siege_settlement",
+                args={"settlement": target},
+                priority=subgoal.priority,
+            )
+        )
+        # Follow up with auto-resolve
+        tasks.append(
+            TaskMessage(
+                from_agent=self.AGENT_ID,
+                to_agent="gabs",
+                primitive="auto_resolve_battle",
+                args={},
+                priority=subgoal.priority,
+            )
+        )
+        return tasks
+
+    def _plan_raid(
+        self, state: GameState, subgoal: KingSubgoal
+    ) -> list[TaskMessage]:
+        """Plan economy raid for denars and food."""
+        tasks: list[TaskMessage] = []
+        target = subgoal.target or self._nearest_enemy_village(state)
+        if not target:
+            return tasks
+        tasks.append(
+            TaskMessage(
+                from_agent=self.AGENT_ID,
+                to_agent="gabs",
+                primitive="raid_village",
+                args={"village": target},
+                priority=subgoal.priority,
+            )
+        )
+        return tasks
+
+    def _plan_training(self, state: GameState) -> list[TaskMessage]:
+        """Plan troop training via auto-resolve bandit fights."""
+        return [
+            TaskMessage(
+                from_agent=self.AGENT_ID,
+                to_agent="logistics_companion",
+                primitive="upgrade_troops",
+                args={},
+                priority=0.8,
+            )
+        ]
+
+    # -- reward computation ------------------------------------------------
+
+    def compute_reward(
+        self,
+        prev_state: GameState,
+        curr_state: GameState,
+        active_subgoal: KingSubgoal,
+    ) -> VassalReward:
+        """Compute the War Vassal reward signal for the last decision cycle."""
+        territory_delta = (
+            curr_state.fief_count() - prev_state.fief_count()
+        ) * 100.0
+
+        prev_strength = max(prev_state.party.troops, 1)
+        curr_strength = curr_state.party.troops
+        army_delta = (curr_strength - prev_strength) / prev_strength
+
+        casualties = max(0, prev_state.party.troops - curr_strength)
+        supply_burn = max(0, prev_state.party.food_days - curr_state.party.food_days)
+
+        subgoal_bonus = (
+            1.0 if active_subgoal.token in _SUBGOAL_TRIGGERS else 0.0
+        )
+
+        total = (
+            _W1_TERRITORY * territory_delta
+            + _W2_ARMY_RATIO * army_delta * 10
+            - _W3_CASUALTY * casualties
+            - _W4_SUPPLY * supply_burn
+            + _W5_SUBGOAL * subgoal_bonus * 10
+        )
+
+        return VassalReward(
+            agent_id=self.AGENT_ID,
+            component_scores={
+                "territory": territory_delta,
+                "army_ratio": army_delta,
+                "casualties": -casualties,
+                "supply_burn": -supply_burn,
+                "subgoal_bonus": subgoal_bonus,
+            },
+            subgoal_bonus=subgoal_bonus,
+            total=total,
+        )
+
+    # -- helpers -----------------------------------------------------------
+
+    @staticmethod
+    def _nearest_enemy_village(state: GameState) -> str | None:
+        enemy_names = set(state.kingdom.active_wars)
+        for faction in state.factions:
+            if faction.name in enemy_names and faction.fiefs:
+                return faction.fiefs[0]
+        return None

src/bannerlord/campaign.py

@@ -0,0 +1,270 @@
+"""Bannerlord M3 — Campaign orchestrator.
+
+Ties together the King agent, vassals, companions, GABS client, and session
+memory into a single async campaign loop.
+
+Architecture::
+
+    CampaignOrchestrator.run()
+        ├── GABSClient.get_game_state()         → GameState
+        ├── KingAgent.decide(state)             → KingSubgoal
+        ├── SessionMemory.log_subgoal(...)
+        ├── WarVassal.plan(state, subgoal)      → [TaskMessage]
+        ├── EconomyVassal.plan(state, subgoal)  → [TaskMessage]
+        ├── DiplomacyVassal.plan(state, subgoal)→ [TaskMessage]
+        ├── [Companions].evaluate(state, subgoal) → [primitives]
+        └── _dispatch_tasks([...])              → GABS calls
+
+Usage::
+
+    from bannerlord.campaign import CampaignOrchestrator
+    orch = CampaignOrchestrator()
+    await orch.run(max_ticks=100)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from pathlib import Path
+from typing import Any
+
+from bannerlord.agents.companions.caravan import CaravanCompanion
+from bannerlord.agents.companions.logistics import LogisticsCompanion
+from bannerlord.agents.companions.scout import ScoutCompanion
+from bannerlord.agents.diplomacy_vassal import DiplomacyVassal
+from bannerlord.agents.economy_vassal import EconomyVassal
+from bannerlord.agents.king import KingAgent
+from bannerlord.agents.war_vassal import WarVassal
+from bannerlord.gabs_client import GABSClient
+from bannerlord.session_memory import SessionMemory
+from bannerlord.types import GameState, KingSubgoal, TaskMessage
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_TICK_INTERVAL = 1.0    # seconds between campaign ticks (real time)
+_DEFAULT_DB_PATH = Path("data/bannerlord/campaign.db")
+_KINGDOM_NAME = "House Timmerson"
+
+
+class CampaignOrchestrator:
+    """Full-campaign strategy orchestrator for Bannerlord M3.
+
+    Runs the King → Vassal → Companion decision loop on each campaign tick.
+    Persists progress to SQLite via SessionMemory.
+
+    Args:
+        gabs_host:      Hostname where GABS mod is listening.
+        gabs_port:      TCP port for GABS JSON-RPC (default 4825).
+        tick_interval:  Real-time seconds between campaign ticks.
+        db_path:        Path to the SQLite session memory database.
+        session_id:     Existing session to resume (None = new session).
+    """
+
+    def __init__(
+        self,
+        *,
+        gabs_host: str = "127.0.0.1",
+        gabs_port: int = 4825,
+        tick_interval: float = _DEFAULT_TICK_INTERVAL,
+        db_path: Path = _DEFAULT_DB_PATH,
+        session_id: str | None = None,
+    ) -> None:
+        self._gabs = GABSClient(host=gabs_host, port=gabs_port)
+        self._king = KingAgent()
+        self._war = WarVassal()
+        self._economy = EconomyVassal()
+        self._diplomacy = DiplomacyVassal()
+        self._logistics = LogisticsCompanion()
+        self._caravan = CaravanCompanion()
+        self._scout = ScoutCompanion()
+        self._memory = SessionMemory(db_path)
+        self._tick_interval = tick_interval
+        self._session_id = session_id
+        self._running = False
+        self._prev_state: GameState | None = None
+
+    # -- lifecycle ---------------------------------------------------------
+
+    async def start(self) -> str:
+        """Connect to GABS and initialise a campaign session.
+
+        Returns the active session_id.
+        """
+        connected = await self._gabs.connect()
+        if not connected:
+            logger.warning(
+                "CampaignOrchestrator: GABS unavailable — campaign will run "
+                "in degraded mode (no game state updates)"
+            )
+
+        if self._session_id is None:
+            self._session_id = self._memory.start_session()
+        else:
+            # Resume existing session
+            existing = self._memory.get_session(self._session_id)
+            if not existing:
+                self._session_id = self._memory.start_session(self._session_id)
+
+        self._king.set_session(self._session_id)
+        logger.info("CampaignOrchestrator: session=%s", self._session_id)
+        return self._session_id
+
+    async def stop(self) -> None:
+        """Gracefully stop the campaign and disconnect from GABS."""
+        self._running = False
+        await self._gabs.disconnect()
+        logger.info("CampaignOrchestrator: stopped")
+
+    # -- main campaign loop ------------------------------------------------
+
+    async def run(self, max_ticks: int = 0) -> dict[str, Any]:
+        """Run the campaign loop.
+
+        Args:
+            max_ticks: Stop after this many ticks.  0 = run indefinitely.
+
+        Returns:
+            Campaign summary dict.
+        """
+        if not self._session_id:
+            await self.start()
+
+        self._running = True
+        tick = 0
+
+        logger.info(
+            "CampaignOrchestrator: starting campaign loop (max_ticks=%d)",
+            max_ticks,
+        )
+
+        try:
+            while self._running:
+                if max_ticks > 0 and tick >= max_ticks:
+                    break
+
+                await self._tick(tick)
+                tick += 1
+
+                # Check done condition
+                if self._prev_state and self._king.is_done_condition_met(
+                    self._prev_state
+                ):
+                    logger.info(
+                        "CampaignOrchestrator: M3 DONE condition met on tick %d!", tick
+                    )
+                    self._memory.add_note(
+                        self._session_id or "",
+                        self._prev_state.in_game_day,
+                        "milestone",
+                        "M3 done condition met — kingdom with 3+ fiefs, 100 days survived",
+                    )
+                    break
+
+                await asyncio.sleep(self._tick_interval)
+
+        except asyncio.CancelledError:
+            logger.info("CampaignOrchestrator: loop cancelled")
+        finally:
+            await self.stop()
+
+        return self._summary(tick)
+
+    async def _tick(self, tick: int) -> None:
+        """Execute one campaign tick."""
+        # 1. Observe
+        state = await self._gabs.get_game_state()
+        state.tick = tick
+
+        # 2. King decides
+        subgoal = self._king.decide(state)
+
+        # 3. Log subgoal to session memory
+        if self._session_id:
+            row_id = self._memory.log_subgoal(
+                self._session_id, tick, state.in_game_day, subgoal
+            )
+            self._memory.update_session(
+                self._session_id,
+                in_game_day=state.in_game_day,
+                fief_count=state.fief_count(),
+                kingdom_name=state.kingdom.name or None,
+            )
+
+        # 4. Vassal planning
+        tasks: list[TaskMessage] = []
+        if self._war.is_relevant(subgoal):
+            tasks.extend(self._war.plan(state, subgoal))
+        if self._economy.is_relevant(subgoal):
+            tasks.extend(self._economy.plan(state, subgoal))
+        if self._diplomacy.is_relevant(subgoal):
+            tasks.extend(self._diplomacy.plan(state, subgoal))
+
+        # 5. Companion evaluation
+        companion_actions = (
+            self._logistics.evaluate(state, subgoal)
+            + self._caravan.evaluate(state, subgoal)
+            + self._scout.evaluate(state, subgoal)
+        )
+
+        # 6. Dispatch tasks + companion primitives to GABS
+        await self._dispatch_tasks(tasks, state)
+        await self._dispatch_primitives(companion_actions)
+
+        # 7. Kingdom establishment check
+        if not state.has_kingdom() and state.fief_count() > 0:
+            # We have a fief but no kingdom yet — establish one
+            ok = await self._gabs.establish_kingdom(_KINGDOM_NAME)
+            if ok and self._session_id:
+                self._memory.record_kingdom_established(
+                    self._session_id, state.in_game_day, _KINGDOM_NAME
+                )
+
+        self._prev_state = state
+        logger.debug(
+            "Tick %d: day=%d, subgoal=%s, tasks=%d, companions=%d",
+            tick,
+            state.in_game_day,
+            subgoal.token,
+            len(tasks),
+            len(companion_actions),
+        )
+
+    # -- task dispatch -----------------------------------------------------
+
+    async def _dispatch_tasks(
+        self, tasks: list[TaskMessage], state: GameState
+    ) -> None:
+        """Dispatch vassal TaskMessages to GABS."""
+        for task in sorted(tasks, key=lambda t: t.priority, reverse=True):
+            if task.to_agent != "gabs":
+                # Companion-directed tasks are handled via companion.evaluate()
+                continue
+            await self._gabs._call(task.primitive, task.args)
+
+    async def _dispatch_primitives(self, actions: list[dict]) -> None:
+        """Dispatch companion primitive actions to GABS."""
+        for action in actions:
+            primitive = action.get("primitive", "")
+            args = action.get("args", {})
+            if primitive:
+                await self._gabs._call(primitive, args)
+
+    # -- summary -----------------------------------------------------------
+
+    def _summary(self, ticks_run: int) -> dict[str, Any]:
+        state = self._prev_state or GameState()
+        summary = self._king.campaign_summary(state)
+        summary["ticks_run"] = ticks_run
+        summary["session_id"] = self._session_id
+        return summary
+
+    # -- accessors ---------------------------------------------------------
+
+    @property
+    def session_id(self) -> str | None:
+        return self._session_id
+
+    @property
+    def memory(self) -> SessionMemory:
+        return self._memory

src/bannerlord/gabs_client.py

@@ -0,0 +1,434 @@
+"""GABS TCP JSON-RPC client — connects to the Bannerlord.GABS mod.
+
+The GABS (Game Agent Behavior System) mod exposes 90+ tools via a
+TCP JSON-RPC 2.0 server on port 4825.  This client wraps the transport
+into a clean async interface used by all Bannerlord agents.
+
+Degrades gracefully: if GABS is unreachable, methods return sensible
+fallbacks and log a warning (never crash).
+
+Architecture reference:
+    Timmy (Qwen3 on Ollama, M3 Max)
+      → GABSClient (this module, TCP JSON-RPC, port 4825)
+        → Bannerlord.GABS C# mod
+          → Game API + Harmony
+            → Bannerlord (Windows VM)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any
+
+from bannerlord.types import (
+    FactionState,
+    GameState,
+    KingdomState,
+    PartyState,
+)
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_HOST = "127.0.0.1"
+_DEFAULT_PORT = 4825
+_DEFAULT_TIMEOUT = 10.0  # seconds
+_RECONNECT_DELAY = 5.0   # seconds between reconnect attempts
+
+
+@dataclass
+class GABSTool:
+    """Metadata for a single GABS tool."""
+
+    name: str
+    description: str
+    parameters: dict[str, Any] = field(default_factory=dict)
+
+
+class GABSConnectionError(Exception):
+    """Raised when GABS is unreachable and a fallback is not possible."""
+
+
+class GABSClient:
+    """Async TCP JSON-RPC 2.0 client for the Bannerlord.GABS mod.
+
+    Usage::
+
+        async with GABSClient() as client:
+            state = await client.get_game_state()
+            await client.move_party("Vlandia")
+
+    All public methods degrade gracefully — they return ``None`` or an
+    empty structure when GABS is unavailable.
+    """
+
+    def __init__(
+        self,
+        host: str = _DEFAULT_HOST,
+        port: int = _DEFAULT_PORT,
+        timeout: float = _DEFAULT_TIMEOUT,
+    ) -> None:
+        self._host = host
+        self._port = port
+        self._timeout = timeout
+        self._reader: asyncio.StreamReader | None = None
+        self._writer: asyncio.StreamWriter | None = None
+        self._connected = False
+        self._call_id = 0
+        self._available_tools: list[GABSTool] = []
+
+    # -- lifecycle ---------------------------------------------------------
+
+    async def connect(self) -> bool:
+        """Open a TCP connection to GABS.
+
+        Returns:
+            True if connected successfully, False if GABS is unavailable.
+        """
+        try:
+            self._reader, self._writer = await asyncio.wait_for(
+                asyncio.open_connection(self._host, self._port),
+                timeout=self._timeout,
+            )
+            self._connected = True
+            logger.info("GABSClient connected to %s:%d", self._host, self._port)
+            await self._discover_tools()
+            return True
+        except (ConnectionRefusedError, OSError, TimeoutError, asyncio.TimeoutError) as exc:
+            logger.warning(
+                "GABSClient could not connect to %s:%d — %s",
+                self._host,
+                self._port,
+                exc,
+            )
+            self._connected = False
+            return False
+
+    async def disconnect(self) -> None:
+        """Close the TCP connection."""
+        if self._writer is not None:
+            try:
+                self._writer.close()
+                await self._writer.wait_closed()
+            except Exception as exc:
+                logger.debug("GABSClient disconnect error: %s", exc)
+        self._connected = False
+        logger.info("GABSClient disconnected")
+
+    async def __aenter__(self) -> GABSClient:
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.disconnect()
+
+    @property
+    def is_connected(self) -> bool:
+        return self._connected
+
+    # -- raw JSON-RPC transport --------------------------------------------
+
+    def _next_id(self) -> int:
+        self._call_id += 1
+        return self._call_id
+
+    async def _call(self, method: str, params: dict[str, Any] | None = None) -> Any:
+        """Send a JSON-RPC 2.0 request and return the result.
+
+        Returns ``None`` and logs a warning on any error.
+        """
+        if not self._connected:
+            logger.warning("GABSClient._call(%s): not connected", method)
+            return None
+
+        request = {
+            "jsonrpc": "2.0",
+            "id": self._next_id(),
+            "method": method,
+            "params": params or {},
+        }
+
+        try:
+            payload = json.dumps(request) + "\n"
+            assert self._writer is not None
+            self._writer.write(payload.encode())
+            await asyncio.wait_for(self._writer.drain(), timeout=self._timeout)
+
+            assert self._reader is not None
+            raw = await asyncio.wait_for(
+                self._reader.readline(), timeout=self._timeout
+            )
+            response = json.loads(raw.decode().strip())
+
+            if "error" in response:
+                logger.warning(
+                    "GABS error for %s: %s", method, response["error"].get("message")
+                )
+                return None
+
+            return response.get("result")
+
+        except (asyncio.TimeoutError, json.JSONDecodeError, AssertionError, OSError) as exc:
+            logger.warning("GABSClient._call(%s) failed: %s", method, exc)
+            self._connected = False
+            return None
+
+    # -- tool discovery ----------------------------------------------------
+
+    async def _discover_tools(self) -> None:
+        """Populate self._available_tools via GABS tools/list."""
+        result = await self._call("tools/list")
+        if not result:
+            return
+        self._available_tools = [
+            GABSTool(
+                name=t.get("name", ""),
+                description=t.get("description", ""),
+                parameters=t.get("parameters", {}),
+            )
+            for t in (result if isinstance(result, list) else [])
+        ]
+        logger.info("GABS: discovered %d tools", len(self._available_tools))
+
+    @property
+    def available_tools(self) -> list[GABSTool]:
+        """Return the list of tools discovered from GABS."""
+        return list(self._available_tools)
+
+    def tool_count(self) -> int:
+        return len(self._available_tools)
+
+    # -- game state --------------------------------------------------------
+
+    async def get_game_state(self) -> GameState:
+        """Return the full campaign state snapshot.
+
+        Falls back to an empty GameState if GABS is unavailable.
+        """
+        raw = await self._call("game/get_state")
+        if raw is None:
+            return GameState()
+
+        try:
+            return self._parse_game_state(raw)
+        except Exception as exc:
+            logger.warning("Failed to parse GABS game state: %s", exc)
+            return GameState()
+
+    def _parse_game_state(self, raw: dict[str, Any]) -> GameState:
+        """Convert raw GABS state dict into a typed GameState."""
+        party_raw = raw.get("party", {})
+        kingdom_raw = raw.get("kingdom", {})
+        factions_raw = raw.get("factions", [])
+
+        party = PartyState(
+            location=party_raw.get("location", ""),
+            troops=party_raw.get("troops", 0),
+            food_days=party_raw.get("food_days", 0),
+            wounded_pct=party_raw.get("wounded_pct", 0.0),
+            denars=party_raw.get("denars", 0),
+            morale=party_raw.get("morale", 100.0),
+            prisoners=party_raw.get("prisoners", 0),
+        )
+
+        kingdom = KingdomState(
+            name=kingdom_raw.get("name", ""),
+            fiefs=kingdom_raw.get("fiefs", []),
+            daily_income=kingdom_raw.get("daily_income", 0),
+            daily_expenses=kingdom_raw.get("daily_expenses", 0),
+            vassal_lords=kingdom_raw.get("vassal_lords", []),
+            active_wars=kingdom_raw.get("active_wars", []),
+            active_alliances=kingdom_raw.get("active_alliances", []),
+            in_game_day=raw.get("in_game_day", 0),
+        )
+
+        factions = [
+            FactionState(
+                name=f.get("name", ""),
+                leader=f.get("leader", ""),
+                fiefs=f.get("fiefs", []),
+                army_strength=f.get("army_strength", 0),
+                treasury=f.get("treasury", 0),
+                is_at_war_with=f.get("is_at_war_with", []),
+                relations=f.get("relations", {}),
+            )
+            for f in (factions_raw if isinstance(factions_raw, list) else [])
+        ]
+
+        return GameState(
+            tick=raw.get("tick", 0),
+            in_game_day=raw.get("in_game_day", 0),
+            timestamp=datetime.now(UTC),
+            party=party,
+            kingdom=kingdom,
+            factions=factions,
+            raw=raw,
+        )
+
+    # -- party actions -----------------------------------------------------
+
+    async def move_party(self, destination: str) -> bool:
+        """Command Timmy's party to move toward *destination*."""
+        result = await self._call("party/move", {"destination": destination})
+        return result is not None
+
+    async def recruit_troops(self, troop_type: str, quantity: int) -> bool:
+        """Recruit *quantity* troops of *troop_type* at current location."""
+        result = await self._call(
+            "party/recruit",
+            {"troop_type": troop_type, "quantity": quantity},
+        )
+        return result is not None
+
+    async def buy_supplies(self, quantity: int) -> bool:
+        """Purchase food supplies for *quantity* days of march."""
+        result = await self._call("party/buy_supplies", {"quantity": quantity})
+        return result is not None
+
+    async def rest_party(self, days: int) -> bool:
+        """Rest the party in current location for *days* in-game days."""
+        result = await self._call("party/rest", {"days": days})
+        return result is not None
+
+    async def auto_resolve_battle(self) -> dict[str, Any]:
+        """Trigger auto-resolve for the current battle.
+
+        Returns the battle outcome dict, or empty dict on failure.
+        """
+        result = await self._call("battle/auto_resolve")
+        return result if isinstance(result, dict) else {}
+
+    async def upgrade_troops(self) -> bool:
+        """Spend accumulated XP on troop tier upgrades."""
+        result = await self._call("party/upgrade_troops")
+        return result is not None
+
+    async def sell_prisoners(self, location: str) -> int:
+        """Sell prisoners at *location*.  Returns denars gained."""
+        result = await self._call("party/sell_prisoners", {"location": location})
+        if isinstance(result, dict):
+            return result.get("denars_gained", 0)
+        return 0
+
+    # -- trade actions -----------------------------------------------------
+
+    async def assess_prices(self, town: str) -> dict[str, Any]:
+        """Query buy/sell prices at *town*."""
+        result = await self._call("trade/assess_prices", {"town": town})
+        return result if isinstance(result, dict) else {}
+
+    async def buy_goods(self, item: str, quantity: int) -> bool:
+        """Purchase *quantity* of *item* at current location."""
+        result = await self._call("trade/buy", {"item": item, "quantity": quantity})
+        return result is not None
+
+    async def sell_goods(self, item: str, quantity: int, location: str) -> bool:
+        """Sell *quantity* of *item* at *location*."""
+        result = await self._call(
+            "trade/sell",
+            {"item": item, "quantity": quantity, "location": location},
+        )
+        return result is not None
+
+    async def establish_caravan(self, town: str) -> bool:
+        """Deploy a caravan NPC at *town*."""
+        result = await self._call("trade/establish_caravan", {"town": town})
+        return result is not None
+
+    # -- diplomacy actions -------------------------------------------------
+
+    async def send_envoy(self, faction: str, message: str) -> bool:
+        """Send a diplomatic message to *faction*."""
+        result = await self._call(
+            "diplomacy/send_envoy",
+            {"faction": faction, "message": message},
+        )
+        return result is not None
+
+    async def propose_peace(self, faction: str, tribute: int = 0) -> bool:
+        """Propose peace with *faction*, optionally offering *tribute* denars."""
+        result = await self._call(
+            "diplomacy/propose_peace",
+            {"faction": faction, "tribute": tribute},
+        )
+        return result is not None
+
+    async def request_alliance(self, faction: str) -> bool:
+        """Request a military alliance with *faction*."""
+        result = await self._call(
+            "diplomacy/request_alliance",
+            {"faction": faction},
+        )
+        return result is not None
+
+    async def request_military_access(self, faction: str) -> bool:
+        """Request military access through *faction*'s territory."""
+        result = await self._call(
+            "diplomacy/military_access",
+            {"faction": faction},
+        )
+        return result is not None
+
+    # -- settlement / kingdom actions --------------------------------------
+
+    async def siege_settlement(self, settlement: str) -> bool:
+        """Begin siege of *settlement*."""
+        result = await self._call("military/siege", {"settlement": settlement})
+        return result is not None
+
+    async def raid_village(self, village: str) -> bool:
+        """Raid *village* for food and denars."""
+        result = await self._call("military/raid_village", {"village": village})
+        return result is not None
+
+    async def build_project(self, settlement: str, project: str) -> bool:
+        """Queue a construction *project* in *settlement*."""
+        result = await self._call(
+            "settlement/build",
+            {"settlement": settlement, "project": project},
+        )
+        return result is not None
+
+    async def set_tax_policy(self, settlement: str, policy: str) -> bool:
+        """Set tax *policy* for *settlement* (e.g. 'low', 'normal', 'high')."""
+        result = await self._call(
+            "settlement/set_tax",
+            {"settlement": settlement, "policy": policy},
+        )
+        return result is not None
+
+    async def appoint_governor(self, settlement: str, lord: str) -> bool:
+        """Appoint *lord* as governor of *settlement*."""
+        result = await self._call(
+            "settlement/appoint_governor",
+            {"settlement": settlement, "lord": lord},
+        )
+        return result is not None
+
+    async def establish_kingdom(self, name: str) -> bool:
+        """Declare a new kingdom with *name* (requires a captured fief)."""
+        result = await self._call("kingdom/establish", {"name": name})
+        ok = result is not None
+        if ok:
+            logger.info("Kingdom '%s' established!", name)
+        return ok
+
+    # -- scouting ----------------------------------------------------------
+
+    async def track_lord(self, lord_name: str) -> dict[str, Any]:
+        """Shadow *lord_name* and return their last-known position."""
+        result = await self._call("scout/track_lord", {"lord": lord_name})
+        return result if isinstance(result, dict) else {}
+
+    async def assess_garrison(self, settlement: str) -> dict[str, Any]:
+        """Estimate defender count for *settlement*."""
+        result = await self._call("scout/assess_garrison", {"settlement": settlement})
+        return result if isinstance(result, dict) else {}
+
+    async def map_patrol_routes(self, region: str) -> list[dict[str, Any]]:
+        """Log enemy patrol routes in *region*."""
+        result = await self._call("scout/patrol_routes", {"region": region})
+        return result if isinstance(result, list) else []

src/bannerlord/session_memory.py

@@ -0,0 +1,347 @@
+"""Bannerlord M3 — Session memory for multi-day strategic plans.
+
+Persists the King's strategic plans, completed subgoals, and kingdom
+milestones to SQLite so the campaign can be interrupted and resumed
+across multiple sessions.
+
+Pattern follows the existing EventBus persistence model.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import sqlite3
+from contextlib import closing
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from bannerlord.types import KingSubgoal, SubgoalToken
+
+logger = logging.getLogger(__name__)
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS campaign_sessions (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    session_id TEXT NOT NULL,
+    started_at TEXT NOT NULL,
+    last_updated TEXT NOT NULL,
+    kingdom_name TEXT DEFAULT '',
+    in_game_day INTEGER DEFAULT 0,
+    fief_count INTEGER DEFAULT 0,
+    meta TEXT DEFAULT '{}'
+);
+
+CREATE TABLE IF NOT EXISTS subgoal_log (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    session_id TEXT NOT NULL,
+    tick INTEGER NOT NULL,
+    in_game_day INTEGER NOT NULL,
+    token TEXT NOT NULL,
+    target TEXT,
+    quantity INTEGER,
+    priority REAL DEFAULT 1.0,
+    deadline_days INTEGER,
+    context TEXT,
+    issued_at TEXT NOT NULL,
+    completed_at TEXT,
+    outcome TEXT DEFAULT 'pending'
+);
+
+CREATE TABLE IF NOT EXISTS strategy_notes (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    session_id TEXT NOT NULL,
+    in_game_day INTEGER NOT NULL,
+    note_type TEXT NOT NULL,
+    content TEXT NOT NULL,
+    recorded_at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_subgoal_session ON subgoal_log(session_id);
+CREATE INDEX IF NOT EXISTS idx_subgoal_tick ON subgoal_log(tick);
+CREATE INDEX IF NOT EXISTS idx_notes_session ON strategy_notes(session_id);
+"""
+
+
+@dataclass
+class CampaignMilestone:
+    """A notable campaign achievement recorded in session memory."""
+
+    in_game_day: int
+    event: str
+    detail: str = ""
+    recorded_at: datetime = field(default_factory=lambda: datetime.now(UTC))
+
+
+class SessionMemory:
+    """SQLite-backed session memory for the Bannerlord campaign.
+
+    Stores:
+    - Active session metadata (kingdom name, in-game day, fief count)
+    - Full subgoal history (every KingSubgoal issued and its outcome)
+    - Strategy notes / milestones for campaign reflection
+
+    Usage::
+
+        mem = SessionMemory(Path("data/bannerlord/campaign.db"))
+        session_id = mem.start_session()
+        mem.log_subgoal(session_id, tick=1, day=42, subgoal)
+        mem.complete_subgoal(subgoal_id, outcome="success")
+        mem.add_note(session_id, day=42, note_type="milestone",
+                     content="Kingdom established: House Timmerson")
+        history = mem.get_recent_subgoals(session_id, limit=10)
+    """
+
+    def __init__(self, db_path: Path) -> None:
+        self._db_path = db_path
+        self._init_db()
+
+    def _init_db(self) -> None:
+        self._db_path.parent.mkdir(parents=True, exist_ok=True)
+        with closing(sqlite3.connect(str(self._db_path))) as conn:
+            conn.execute("PRAGMA journal_mode=WAL")
+            conn.execute("PRAGMA busy_timeout=5000")
+            conn.executescript(_SCHEMA)
+            conn.commit()
+
+    def _conn(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(str(self._db_path))
+        conn.row_factory = sqlite3.Row
+        conn.execute("PRAGMA busy_timeout=5000")
+        return conn
+
+    # -- session lifecycle -------------------------------------------------
+
+    def start_session(self, session_id: str | None = None) -> str:
+        """Create a new campaign session.  Returns the session_id."""
+        if session_id is None:
+            session_id = f"session_{datetime.now(UTC).strftime('%Y%m%d_%H%M%S')}"
+        now = datetime.now(UTC).isoformat()
+        with closing(self._conn()) as conn:
+            conn.execute(
+                "INSERT OR IGNORE INTO campaign_sessions "
+                "(session_id, started_at, last_updated) VALUES (?, ?, ?)",
+                (session_id, now, now),
+            )
+            conn.commit()
+        logger.info("SessionMemory: started campaign session %s", session_id)
+        return session_id
+
+    def update_session(
+        self,
+        session_id: str,
+        *,
+        kingdom_name: str | None = None,
+        in_game_day: int | None = None,
+        fief_count: int | None = None,
+        meta: dict[str, Any] | None = None,
+    ) -> None:
+        """Update the campaign session state."""
+        now = datetime.now(UTC).isoformat()
+        with closing(self._conn()) as conn:
+            row = conn.execute(
+                "SELECT * FROM campaign_sessions WHERE session_id = ?",
+                (session_id,),
+            ).fetchone()
+            if not row:
+                return
+
+            current_meta = json.loads(row["meta"] or "{}")
+            if meta:
+                current_meta.update(meta)
+
+            conn.execute(
+                """UPDATE campaign_sessions SET
+                    last_updated = ?,
+                    kingdom_name = COALESCE(?, kingdom_name),
+                    in_game_day  = COALESCE(?, in_game_day),
+                    fief_count   = COALESCE(?, fief_count),
+                    meta         = ?
+                WHERE session_id = ?""",
+                (
+                    now,
+                    kingdom_name,
+                    in_game_day,
+                    fief_count,
+                    json.dumps(current_meta),
+                    session_id,
+                ),
+            )
+            conn.commit()
+
+    def get_session(self, session_id: str) -> dict[str, Any] | None:
+        """Return session metadata dict or None if not found."""
+        with closing(self._conn()) as conn:
+            row = conn.execute(
+                "SELECT * FROM campaign_sessions WHERE session_id = ?",
+                (session_id,),
+            ).fetchone()
+            if not row:
+                return None
+            return dict(row)
+
+    def list_sessions(self) -> list[dict[str, Any]]:
+        """Return all campaign sessions, most recent first."""
+        with closing(self._conn()) as conn:
+            rows = conn.execute(
+                "SELECT * FROM campaign_sessions ORDER BY last_updated DESC"
+            ).fetchall()
+            return [dict(r) for r in rows]
+
+    # -- subgoal log -------------------------------------------------------
+
+    def log_subgoal(
+        self,
+        session_id: str,
+        tick: int,
+        in_game_day: int,
+        subgoal: KingSubgoal,
+    ) -> int:
+        """Record a subgoal emission.  Returns the row id."""
+        with closing(self._conn()) as conn:
+            cursor = conn.execute(
+                """INSERT INTO subgoal_log
+                    (session_id, tick, in_game_day, token, target, quantity,
+                     priority, deadline_days, context, issued_at, outcome)
+                   VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'pending')""",
+                (
+                    session_id,
+                    tick,
+                    in_game_day,
+                    str(subgoal.token),
+                    subgoal.target,
+                    subgoal.quantity,
+                    subgoal.priority,
+                    subgoal.deadline_days,
+                    subgoal.context,
+                    subgoal.issued_at.isoformat(),
+                ),
+            )
+            conn.commit()
+            return cursor.lastrowid or 0
+
+    def complete_subgoal(self, row_id: int, outcome: str = "success") -> None:
+        """Mark a subgoal log entry as completed."""
+        with closing(self._conn()) as conn:
+            conn.execute(
+                "UPDATE subgoal_log SET completed_at = ?, outcome = ? WHERE id = ?",
+                (datetime.now(UTC).isoformat(), outcome, row_id),
+            )
+            conn.commit()
+
+    def get_recent_subgoals(
+        self, session_id: str, limit: int = 20
+    ) -> list[dict[str, Any]]:
+        """Return the *limit* most recent subgoal log entries."""
+        with closing(self._conn()) as conn:
+            rows = conn.execute(
+                "SELECT * FROM subgoal_log WHERE session_id = ? "
+                "ORDER BY tick DESC LIMIT ?",
+                (session_id, limit),
+            ).fetchall()
+            return [dict(r) for r in rows]
+
+    def count_token(self, session_id: str, token: SubgoalToken) -> int:
+        """Count how many times a subgoal token has been issued in a session."""
+        with closing(self._conn()) as conn:
+            row = conn.execute(
+                "SELECT COUNT(*) as n FROM subgoal_log "
+                "WHERE session_id = ? AND token = ?",
+                (session_id, str(token)),
+            ).fetchone()
+            return row["n"] if row else 0
+
+    # -- strategy notes ----------------------------------------------------
+
+    def add_note(
+        self,
+        session_id: str,
+        in_game_day: int,
+        note_type: str,
+        content: str,
+    ) -> None:
+        """Record a strategy note or milestone."""
+        with closing(self._conn()) as conn:
+            conn.execute(
+                "INSERT INTO strategy_notes "
+                "(session_id, in_game_day, note_type, content, recorded_at) "
+                "VALUES (?, ?, ?, ?, ?)",
+                (
+                    session_id,
+                    in_game_day,
+                    note_type,
+                    content,
+                    datetime.now(UTC).isoformat(),
+                ),
+            )
+            conn.commit()
+
+    def get_notes(
+        self,
+        session_id: str,
+        note_type: str | None = None,
+        limit: int = 50,
+    ) -> list[dict[str, Any]]:
+        """Return strategy notes, optionally filtered by type."""
+        with closing(self._conn()) as conn:
+            if note_type:
+                rows = conn.execute(
+                    "SELECT * FROM strategy_notes "
+                    "WHERE session_id = ? AND note_type = ? "
+                    "ORDER BY in_game_day DESC LIMIT ?",
+                    (session_id, note_type, limit),
+                ).fetchall()
+            else:
+                rows = conn.execute(
+                    "SELECT * FROM strategy_notes WHERE session_id = ? "
+                    "ORDER BY in_game_day DESC LIMIT ?",
+                    (session_id, limit),
+                ).fetchall()
+            return [dict(r) for r in rows]
+
+    def get_milestones(self, session_id: str) -> list[dict[str, Any]]:
+        """Return all milestone notes for a session."""
+        return self.get_notes(session_id, note_type="milestone", limit=200)
+
+    # -- diplomatic memory -------------------------------------------------
+
+    def record_war_declared(
+        self, session_id: str, in_game_day: int, faction: str
+    ) -> None:
+        """Log that Timmy declared war on *faction*."""
+        self.add_note(
+            session_id,
+            in_game_day,
+            "war_declared",
+            f"Declared war on {faction}",
+        )
+
+    def record_peace_agreed(
+        self, session_id: str, in_game_day: int, faction: str
+    ) -> None:
+        """Log that Timmy agreed to peace with *faction*."""
+        self.add_note(
+            session_id,
+            in_game_day,
+            "peace_agreed",
+            f"Peace agreed with {faction}",
+        )
+
+    def record_kingdom_established(
+        self, session_id: str, in_game_day: int, kingdom_name: str
+    ) -> None:
+        """Record the kingdom establishment milestone."""
+        self.add_note(
+            session_id,
+            in_game_day,
+            "milestone",
+            f"Kingdom established: {kingdom_name}",
+        )
+        self.update_session(session_id, kingdom_name=kingdom_name, in_game_day=in_game_day)
+        logger.info(
+            "SessionMemory: milestone — kingdom '%s' established on day %d",
+            kingdom_name,
+            in_game_day,
+        )

src/bannerlord/types.py

@@ -0,0 +1,226 @@
+"""Bannerlord M3 — core data types for the campaign strategy system.
+
+KingSubgoal schema and all message types used by the feudal agent hierarchy.
+Design follows the Feudal Multi-Agent Hierarchies (Ahilan & Dayan, 2019) model
+specified in docs/research/bannerlord-feudal-hierarchy-design.md.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import StrEnum
+from typing import Any, Literal
+
+
+# ---------------------------------------------------------------------------
+# Subgoal vocabulary
+# ---------------------------------------------------------------------------
+
+
+class SubgoalToken(StrEnum):
+    """Fixed vocabulary of strategic intents the King can emit."""
+
+    EXPAND_TERRITORY = "EXPAND_TERRITORY"
+    RAID_ECONOMY = "RAID_ECONOMY"
+    FORTIFY = "FORTIFY"
+    RECRUIT = "RECRUIT"
+    TRADE = "TRADE"
+    ALLY = "ALLY"
+    SPY = "SPY"
+    HEAL = "HEAL"
+    CONSOLIDATE = "CONSOLIDATE"
+    TRAIN = "TRAIN"
+
+
+@dataclass
+class KingSubgoal:
+    """A strategic directive issued by the King agent.
+
+    The King emits at most one subgoal per campaign tick.  Vassals interpret
+    the token and prioritise actions accordingly.
+
+    Attributes:
+        token:          Intent from the SubgoalToken vocabulary.
+        target:         Named target (settlement, lord, or faction).
+        quantity:       Scalar for RECRUIT / TRADE operations.
+        priority:       0.0–2.0 weighting that scales vassal reward.
+        deadline_days:  Campaign-map days to complete (None = open-ended).
+        context:        Free-text hint passed verbatim to vassals (not parsed).
+        issued_at:      Timestamp when the King emitted this subgoal.
+    """
+
+    token: SubgoalToken
+    target: str | None = None
+    quantity: int | None = None
+    priority: float = 1.0
+    deadline_days: int | None = None
+    context: str | None = None
+    issued_at: datetime = field(default_factory=lambda: datetime.now(UTC))
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "token": str(self.token),
+            "target": self.target,
+            "quantity": self.quantity,
+            "priority": self.priority,
+            "deadline_days": self.deadline_days,
+            "context": self.context,
+            "issued_at": self.issued_at.isoformat(),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> KingSubgoal:
+        return cls(
+            token=SubgoalToken(data["token"]),
+            target=data.get("target"),
+            quantity=data.get("quantity"),
+            priority=data.get("priority", 1.0),
+            deadline_days=data.get("deadline_days"),
+            context=data.get("context"),
+            issued_at=datetime.fromisoformat(data["issued_at"])
+            if "issued_at" in data
+            else datetime.now(UTC),
+        )
+
+
+# ---------------------------------------------------------------------------
+# Game state snapshot
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class FactionState:
+    """Snapshot of a faction's status on the campaign map."""
+
+    name: str
+    leader: str
+    fiefs: list[str] = field(default_factory=list)
+    army_strength: int = 0
+    treasury: int = 0
+    is_at_war_with: list[str] = field(default_factory=list)
+    relations: dict[str, int] = field(default_factory=dict)
+
+
+@dataclass
+class PartyState:
+    """Timmy's party snapshot."""
+
+    location: str = ""
+    troops: int = 0
+    food_days: int = 0
+    wounded_pct: float = 0.0
+    denars: int = 0
+    morale: float = 100.0
+    prisoners: int = 0
+
+
+@dataclass
+class KingdomState:
+    """Timmy's kingdom snapshot (only populated after kingdom is established)."""
+
+    name: str = ""
+    fiefs: list[str] = field(default_factory=list)
+    daily_income: int = 0
+    daily_expenses: int = 0
+    vassal_lords: list[str] = field(default_factory=list)
+    active_wars: list[str] = field(default_factory=list)
+    active_alliances: list[str] = field(default_factory=list)
+    in_game_day: int = 0
+
+
+@dataclass
+class GameState:
+    """Full campaign state snapshot delivered by GABS on each tick.
+
+    This is the primary input to the King agent's decision loop.
+    """
+
+    tick: int = 0
+    in_game_day: int = 0
+    timestamp: datetime = field(default_factory=lambda: datetime.now(UTC))
+    party: PartyState = field(default_factory=PartyState)
+    kingdom: KingdomState = field(default_factory=KingdomState)
+    factions: list[FactionState] = field(default_factory=list)
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    def has_kingdom(self) -> bool:
+        return bool(self.kingdom.name)
+
+    def fief_count(self) -> int:
+        return len(self.kingdom.fiefs)
+
+    def active_war_count(self) -> int:
+        return len(self.kingdom.active_wars)
+
+    def is_two_front_war(self) -> bool:
+        """Return True if Timmy is engaged in 2+ simultaneous wars."""
+        return self.active_war_count() >= 2
+
+
+# ---------------------------------------------------------------------------
+# Inter-agent message schemas
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class SubgoalMessage:
+    """King → Vassal directive."""
+
+    msg_type: Literal["subgoal"] = "subgoal"
+    from_agent: Literal["king"] = "king"
+    to_agent: str = ""
+    subgoal: KingSubgoal | None = None
+    issued_at: datetime = field(default_factory=lambda: datetime.now(UTC))
+
+
+@dataclass
+class TaskMessage:
+    """Vassal → Companion work order."""
+
+    msg_type: Literal["task"] = "task"
+    from_agent: str = ""
+    to_agent: str = ""
+    primitive: str = ""
+    args: dict[str, Any] = field(default_factory=dict)
+    priority: float = 1.0
+    issued_at: datetime = field(default_factory=lambda: datetime.now(UTC))
+
+
+@dataclass
+class ResultMessage:
+    """Companion/Vassal → Parent outcome report."""
+
+    msg_type: Literal["result"] = "result"
+    from_agent: str = ""
+    to_agent: str = ""
+    success: bool = True
+    outcome: dict[str, Any] = field(default_factory=dict)
+    reward_delta: float = 0.0
+    completed_at: datetime = field(default_factory=lambda: datetime.now(UTC))
+
+
+@dataclass
+class StateUpdateMessage:
+    """GABS → All agents broadcast."""
+
+    msg_type: Literal["state"] = "state"
+    game_state: GameState = field(default_factory=GameState)
+    tick: int = 0
+    timestamp: datetime = field(default_factory=lambda: datetime.now(UTC))
+
+
+# ---------------------------------------------------------------------------
+# Reward signals
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class VassalReward:
+    """Computed reward signal for a vassal agent after one decision cycle."""
+
+    agent_id: str
+    component_scores: dict[str, float] = field(default_factory=dict)
+    subgoal_bonus: float = 0.0
+    total: float = 0.0
+    computed_at: datetime = field(default_factory=lambda: datetime.now(UTC))

src/config.py

@@ -1,10 +1,19 @@
 import logging as _logging
 import os
 import sys
+from datetime import UTC
+from datetime import datetime as _datetime
 from typing import Literal
 
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
+APP_START_TIME: _datetime = _datetime.now(UTC)
+
+
+def normalize_ollama_url(url: str) -> str:
+    """Replace localhost with 127.0.0.1 to avoid IPv6 resolution delays."""
+    return url.replace("localhost", "127.0.0.1")
+
 
 class Settings(BaseSettings):
     """Central configuration — all env-var access goes through this class."""
@@ -15,12 +24,39 @@ class Settings(BaseSettings):
     # Ollama host — override with OLLAMA_URL env var or .env file
     ollama_url: str = "http://localhost:11434"
 
+    @property
+    def normalized_ollama_url(self) -> str:
+        """Return ollama_url with localhost replaced by 127.0.0.1."""
+        return normalize_ollama_url(self.ollama_url)
+
     # LLM model passed to Agno/Ollama — override with OLLAMA_MODEL
-    # qwen3.5:latest is the primary model — better reasoning and tool calling
+    # qwen3:30b is the primary model — better reasoning and tool calling
     # than llama3.1:8b-instruct while still running locally on modest hardware.
-    # Fallback: llama3.1:8b-instruct if qwen3.5:latest not available.
+    # Fallback: llama3.1:8b-instruct if qwen3:30b not available.
     # llama3.2 (3B) hallucinated tool output consistently in testing.
-    ollama_model: str = "qwen3.5:latest"
+    ollama_model: str = "qwen3:30b"
+
+    # Context window size for Ollama inference — override with OLLAMA_NUM_CTX
+    # qwen3:30b with default context eats 45GB on a 39GB Mac.
+    # 4096 keeps memory at ~19GB. Set to 0 to use model defaults.
+    ollama_num_ctx: int = 4096
+
+    # Fallback model chains — override with FALLBACK_MODELS / VISION_FALLBACK_MODELS
+    # as comma-separated strings, e.g. FALLBACK_MODELS="qwen3:30b,llama3.1"
+    # Or edit config/providers.yaml → fallback_chains for the canonical source.
+    fallback_models: list[str] = [
+        "llama3.1:8b-instruct",
+        "llama3.1",
+        "qwen2.5:14b",
+        "qwen2.5:7b",
+        "llama3.2:3b",
+    ]
+    vision_fallback_models: list[str] = [
+        "llama3.2:3b",
+        "llava:7b",
+        "qwen2.5-vl:3b",
+        "moondream:1.8b",
+    ]
 
     # Set DEBUG=true to enable /docs and /redoc (disabled by default)
     debug: bool = False
@@ -38,33 +74,39 @@ class Settings(BaseSettings):
     # Seconds to wait for user confirmation before auto-rejecting.
     discord_confirm_timeout: int = 120
 
-    # ── AirLLM / backend selection ───────────────────────────────────────────
+    # ── Backend selection ────────────────────────────────────────────────────
     # "ollama"  — always use Ollama (default, safe everywhere)
-    # "airllm"  — always use AirLLM (requires pip install ".[bigbrain]")
-    # "auto"    — use AirLLM on Apple Silicon if airllm is installed,
-    #             fall back to Ollama otherwise
-    timmy_model_backend: Literal["ollama", "airllm", "grok", "claude", "auto"] = "ollama"
-
-    # AirLLM model size when backend is airllm or auto.
-    # Larger = smarter, but needs more RAM / disk.
-    # 8b  ~16 GB  |  70b  ~140 GB  |  405b  ~810 GB
-    airllm_model_size: Literal["8b", "70b", "405b"] = "70b"
+    # "auto"    — pick best available local backend, fall back to Ollama
+    timmy_model_backend: Literal["ollama", "grok", "claude", "auto"] = "ollama"
 
     # ── Grok (xAI) — opt-in premium cloud backend ────────────────────────
     # Grok is a premium augmentation layer — local-first ethos preserved.
     # Only used when explicitly enabled and query complexity warrants it.
     grok_enabled: bool = False
     xai_api_key: str = ""
+    xai_base_url: str = "https://api.x.ai/v1"
     grok_default_model: str = "grok-3-fast"
     grok_max_sats_per_query: int = 200
+    grok_sats_hard_cap: int = 100  # Absolute ceiling on sats per Grok query
     grok_free: bool = False  # Skip Lightning invoice when user has own API key
 
+    # ── Database ──────────────────────────────────────────────────────────
+    db_busy_timeout_ms: int = 5000  # SQLite PRAGMA busy_timeout (ms)
+
     # ── Claude (Anthropic) — cloud fallback backend ────────────────────────
     # Used when Ollama is offline and local inference isn't available.
     # Set ANTHROPIC_API_KEY to enable.  Default model is Haiku (fast + cheap).
     anthropic_api_key: str = ""
     claude_model: str = "haiku"
 
+    # ── Content Moderation ──────────────────────────────────────────────
+    # Three-layer moderation pipeline for AI narrator output.
+    # Uses Llama Guard via Ollama with regex fallback.
+    moderation_enabled: bool = True
+    moderation_guard_model: str = "llama-guard3:1b"
+    # Default confidence threshold — per-game profiles can override.
+    moderation_threshold: float = 0.8
+
     # ── Spark Intelligence ────────────────────────────────────────────────
     # Enable/disable the Spark cognitive layer.
     # When enabled, Spark captures swarm events, runs EIDOS predictions,
@@ -105,14 +147,44 @@ class Settings(BaseSettings):
     l402_macaroon_secret: str = ""
     lightning_backend: Literal["mock", "lnd"] = "mock"
 
+    # ── Bannerlord / GABS ────────────────────────────────────────────────
+    # TCP JSON-RPC connection to the Bannerlord.GABS mod running on the
+    # Windows VM.  Override with GABS_HOST / GABS_PORT env vars.
+    gabs_host: str = "127.0.0.1"
+    gabs_port: int = 4825
+    gabs_timeout: float = 10.0      # seconds per GABS call
+    bannerlord_tick_interval: float = 1.0  # real-time seconds between campaign ticks
+    bannerlord_db_path: str = "data/bannerlord/campaign.db"
+
     # ── Privacy / Sovereignty ────────────────────────────────────────────
     # Disable Agno telemetry for air-gapped/sovereign deployments.
     # Default is False (telemetry disabled) to align with sovereign AI vision.
     telemetry_enabled: bool = False
 
+    # ── Sovereignty Metrics ──────────────────────────────────────────────
+    # Alert when API cost per research task exceeds this threshold (USD).
+    sovereignty_api_cost_alert_threshold: float = 1.00
+
     # CORS allowed origins for the web chat interface (Gitea Pages, etc.)
     # Set CORS_ORIGINS as a comma-separated list, e.g. "http://localhost:3000,https://example.com"
-    cors_origins: list[str] = ["*"]
+    cors_origins: list[str] = [
+        "http://localhost:3000",
+        "http://localhost:8000",
+        "http://127.0.0.1:3000",
+        "http://127.0.0.1:8000",
+    ]
+
+    # ── Matrix Frontend Integration ────────────────────────────────────────
+    # URL of the Matrix frontend (Replit/Tailscale) for CORS.
+    # When set, this origin is added to CORS allowed_origins.
+    # Example: "http://100.124.176.28:8080" or "https://alexanderwhitestone.com"
+    matrix_frontend_url: str = ""  # Empty = disabled
+
+    # WebSocket authentication token for Matrix connections.
+    # When set, clients must provide this token via ?token= query param
+    # or in the first message as {"type": "auth", "token": "..."}.
+    # Empty/unset = auth disabled (dev mode).
+    matrix_ws_token: str = ""
 
     # Trusted hosts for the Host header check (TrustedHostMiddleware).
     # Set TRUSTED_HOSTS as a comma-separated list. Wildcards supported (e.g. "*.ts.net").
@@ -212,26 +284,34 @@ class Settings(BaseSettings):
     # Fallback to server when browser model is unavailable or too slow.
     browser_model_fallback: bool = True
 
+    # ── Deep Focus Mode ─────────────────────────────────────────────
+    # "deep" = single-problem context; "broad" = default multi-task.
+    focus_mode: Literal["deep", "broad"] = "broad"
+
     # ── Default Thinking ──────────────────────────────────────────────
     # When enabled, the agent starts an internal thought loop on server start.
     thinking_enabled: bool = True
     thinking_interval_seconds: int = 300  # 5 minutes between thoughts
+    thinking_timeout_seconds: int = 120  # max wall-clock time per thinking cycle
     thinking_distill_every: int = 10  # distill facts from thoughts every Nth thought
     thinking_issue_every: int = 20  # file Gitea issues from thoughts every Nth thought
+    thinking_memory_check_every: int = 50  # check memory status every Nth thought
+    thinking_idle_timeout_minutes: int = 60  # pause thoughts after N minutes without user input
 
     # ── Gitea Integration ─────────────────────────────────────────────
     # Local Gitea instance for issue tracking and self-improvement.
     # These values are passed as env vars to the gitea-mcp server process.
     gitea_url: str = "http://localhost:3000"
-    gitea_token: str = ""  # GITEA_TOKEN env var; falls back to ~/.config/gitea/token
+    gitea_token: str = ""  # GITEA_TOKEN env var; falls back to .timmy_gitea_token
     gitea_repo: str = "rockachopa/Timmy-time-dashboard"  # owner/repo
     gitea_enabled: bool = True
 
     # ── MCP Servers ────────────────────────────────────────────────────
     # External tool servers connected via Model Context Protocol (stdio).
-    mcp_gitea_command: str = "gitea-mcp -t stdio"
+    mcp_gitea_command: str = "gitea-mcp-server -t stdio"
     mcp_filesystem_command: str = "npx -y @modelcontextprotocol/server-filesystem"
     mcp_timeout: int = 15
+    mcp_bridge_timeout: int = 60  # HTTP timeout for MCP bridge Ollama calls (seconds)
 
     # ── Loop QA (Self-Testing) ─────────────────────────────────────────
     # Self-test orchestrator that probes capabilities alongside the thinking loop.
@@ -276,6 +356,13 @@ class Settings(BaseSettings):
     autoresearch_max_iterations: int = 100
     autoresearch_metric: str = "val_bpb"  # metric to optimise (lower = better)
 
+    # ── Weekly Narrative Summary ───────────────────────────────────────
+    # Generates a human-readable weekly summary of development activity.
+    # Disabling this will stop the weekly narrative generation.
+    weekly_narrative_enabled: bool = True
+    weekly_narrative_lookback_days: int = 7
+    weekly_narrative_output_dir: str = ".loop"
+
     # ── Local Hands (Shell + Git) ──────────────────────────────────────
     # Enable local shell/git execution hands.
     hands_shell_enabled: bool = True
@@ -324,14 +411,19 @@ class Settings(BaseSettings):
     def model_post_init(self, __context) -> None:
         """Post-init: resolve gitea_token from file if not set via env."""
         if not self.gitea_token:
-            token_path = os.path.expanduser("~/.config/gitea/token")
-            try:
-                if os.path.isfile(token_path):
-                    token = open(token_path).read().strip()  # noqa: SIM115
-                    if token:
-                        self.gitea_token = token
-            except OSError:
-                pass
+            # Priority: Timmy's own token → legacy admin token
+            repo_root = self._compute_repo_root()
+            timmy_token_path = os.path.join(repo_root, ".timmy_gitea_token")
+            legacy_token_path = os.path.expanduser("~/.config/gitea/token")
+            for token_path in (timmy_token_path, legacy_token_path):
+                try:
+                    if os.path.isfile(token_path):
+                        token = open(token_path).read().strip()  # noqa: SIM115
+                        if token:
+                            self.gitea_token = token
+                            break
+                except OSError:
+                    pass
 
     model_config = SettingsConfigDict(
         env_file=".env",
@@ -346,10 +438,9 @@ if not settings.repo_root:
     settings.repo_root = settings._compute_repo_root()
 
 # ── Model fallback configuration ────────────────────────────────────────────
-# Primary model for reliable tool calling (llama3.1:8b-instruct)
-# Fallback if primary not available: qwen3.5:latest
-OLLAMA_MODEL_PRIMARY: str = "qwen3.5:latest"
-OLLAMA_MODEL_FALLBACK: str = "llama3.1:8b-instruct"
+# Fallback chains are now in settings.fallback_models / settings.vision_fallback_models.
+# Override via env vars (FALLBACK_MODELS, VISION_FALLBACK_MODELS) or
+# edit config/providers.yaml → fallback_chains.
 
 
 def check_ollama_model_available(model_name: str) -> bool:
@@ -358,7 +449,7 @@ def check_ollama_model_available(model_name: str) -> bool:
         import json
         import urllib.request
 
-        url = settings.ollama_url.replace("localhost", "127.0.0.1")
+        url = settings.normalized_ollama_url
         req = urllib.request.Request(
             f"{url}/api/tags",
             method="GET",
@@ -371,33 +462,31 @@ def check_ollama_model_available(model_name: str) -> bool:
                 model_name == m or model_name == m.split(":")[0] or m.startswith(model_name)
                 for m in models
             )
-    except Exception:
+    except (OSError, ValueError) as exc:
+        _startup_logger.debug("Ollama model check failed: %s", exc)
         return False
 
 
 def get_effective_ollama_model() -> str:
-    """Get the effective Ollama model, with fallback logic."""
-    # If user has overridden, use their setting
+    """Get the effective Ollama model, with fallback logic.
+
+    Walks the configurable ``settings.fallback_models`` chain when the
+    user's preferred model is not available locally.
+    """
     user_model = settings.ollama_model
 
-    # Check if user's model is available
     if check_ollama_model_available(user_model):
         return user_model
 
-    # Try primary
-    if check_ollama_model_available(OLLAMA_MODEL_PRIMARY):
-        _startup_logger.warning(
-            f"Requested model '{user_model}' not available. Using primary: {OLLAMA_MODEL_PRIMARY}"
-        )
-        return OLLAMA_MODEL_PRIMARY
-
-    # Try fallback
-    if check_ollama_model_available(OLLAMA_MODEL_FALLBACK):
-        _startup_logger.warning(
-            f"Primary model '{OLLAMA_MODEL_PRIMARY}' not available. "
-            f"Using fallback: {OLLAMA_MODEL_FALLBACK}"
-        )
-        return OLLAMA_MODEL_FALLBACK
+    # Walk the configurable fallback chain
+    for fallback in settings.fallback_models:
+        if check_ollama_model_available(fallback):
+            _startup_logger.warning(
+                "Requested model '%s' not available. Using fallback: %s",
+                user_model,
+                fallback,
+            )
+            return fallback
 
     # Last resort - return user's setting and hope for the best
     return user_model
@@ -437,8 +526,19 @@ def validate_startup(*, force: bool = False) -> None:
                 ", ".join(_missing),
             )
             sys.exit(1)
+        if "*" in settings.cors_origins:
+            _startup_logger.error(
+                "PRODUCTION SECURITY ERROR: CORS wildcard '*' is not allowed "
+                "in production. Set CORS_ORIGINS to explicit origins."
+            )
+            sys.exit(1)
         _startup_logger.info("Production mode: security secrets validated ✓")
     else:
+        if "*" in settings.cors_origins:
+            _startup_logger.warning(
+                "SEC: CORS_ORIGINS contains wildcard '*' — "
+                "restrict to explicit origins before deploying to production."
+            )
         if not settings.l402_hmac_secret:
             _startup_logger.warning(
                 "SEC: L402_HMAC_SECRET is not set — "

src/dashboard/app.py

@@ -8,7 +8,9 @@ Key improvements:
 """
 
 import asyncio
+import json
 import logging
+import re
 from contextlib import asynccontextmanager
 from pathlib import Path
 
@@ -22,12 +24,15 @@ from config import settings
 
 # Import dedicated middleware
 from dashboard.middleware.csrf import CSRFMiddleware
+from dashboard.middleware.rate_limit import RateLimitMiddleware
 from dashboard.middleware.request_logging import RequestLoggingMiddleware
 from dashboard.middleware.security_headers import SecurityHeadersMiddleware
 from dashboard.routes.agents import router as agents_router
 from dashboard.routes.briefing import router as briefing_router
 from dashboard.routes.calm import router as calm_router
 from dashboard.routes.chat_api import router as chat_api_router
+from dashboard.routes.chat_api_v1 import router as chat_api_v1_router
+from dashboard.routes.daily_run import router as daily_run_router
 from dashboard.routes.db_explorer import router as db_explorer_router
 from dashboard.routes.discord import router as discord_router
 from dashboard.routes.experiments import router as experiments_router
@@ -38,14 +43,21 @@ from dashboard.routes.memory import router as memory_router
 from dashboard.routes.mobile import router as mobile_router
 from dashboard.routes.models import api_router as models_api_router
 from dashboard.routes.models import router as models_router
+from dashboard.routes.quests import router as quests_router
+from dashboard.routes.scorecards import router as scorecards_router
+from dashboard.routes.sovereignty_metrics import router as sovereignty_metrics_router
 from dashboard.routes.spark import router as spark_router
 from dashboard.routes.system import router as system_router
 from dashboard.routes.tasks import router as tasks_router
 from dashboard.routes.telegram import router as telegram_router
 from dashboard.routes.thinking import router as thinking_router
 from dashboard.routes.tools import router as tools_router
+from dashboard.routes.tower import router as tower_router
 from dashboard.routes.voice import router as voice_router
 from dashboard.routes.work_orders import router as work_orders_router
+from dashboard.routes.world import matrix_router
+from dashboard.routes.world import router as world_router
+from timmy.workshop_state import PRESENCE_FILE
 
 
 class _ColorFormatter(logging.Formatter):
@@ -151,7 +163,17 @@ async def _thinking_scheduler() -> None:
     while True:
         try:
             if settings.thinking_enabled:
-                await thinking_engine.think_once()
+                await asyncio.wait_for(
+                    thinking_engine.think_once(),
+                    timeout=settings.thinking_timeout_seconds,
+                )
+        except TimeoutError:
+            logger.warning(
+                "Thinking cycle timed out after %ds — Ollama may be unresponsive",
+                settings.thinking_timeout_seconds,
+            )
+        except asyncio.CancelledError:
+            raise
         except Exception as exc:
             logger.error("Thinking scheduler error: %s", exc)
 
@@ -171,7 +193,10 @@ async def _loop_qa_scheduler() -> None:
     while True:
         try:
             if settings.loop_qa_enabled:
-                result = await loop_qa_orchestrator.run_next_test()
+                result = await asyncio.wait_for(
+                    loop_qa_orchestrator.run_next_test(),
+                    timeout=settings.thinking_timeout_seconds,
+                )
                 if result:
                     status = "PASS" if result["success"] else "FAIL"
                     logger.info(
@@ -180,6 +205,13 @@ async def _loop_qa_scheduler() -> None:
                         status,
                         result.get("details", "")[:80],
                     )
+        except TimeoutError:
+            logger.warning(
+                "Loop QA test timed out after %ds",
+                settings.thinking_timeout_seconds,
+            )
+        except asyncio.CancelledError:
+            raise
         except Exception as exc:
             logger.error("Loop QA scheduler error: %s", exc)
 
@@ -187,6 +219,54 @@ async def _loop_qa_scheduler() -> None:
         await asyncio.sleep(interval)
 
 
+_PRESENCE_POLL_SECONDS = 30
+_PRESENCE_INITIAL_DELAY = 3
+
+_SYNTHESIZED_STATE: dict = {
+    "version": 1,
+    "liveness": None,
+    "current_focus": "",
+    "mood": "idle",
+    "active_threads": [],
+    "recent_events": [],
+    "concerns": [],
+}
+
+
+async def _presence_watcher() -> None:
+    """Background task: watch ~/.timmy/presence.json and broadcast changes via WS.
+
+    Polls the file every 30 seconds (matching Timmy's write cadence).
+    If the file doesn't exist, broadcasts a synthesised idle state.
+    """
+    from infrastructure.ws_manager.handler import ws_manager as ws_mgr
+
+    await asyncio.sleep(_PRESENCE_INITIAL_DELAY)  # Stagger after other schedulers
+
+    last_mtime: float = 0.0
+
+    while True:
+        try:
+            if PRESENCE_FILE.exists():
+                mtime = PRESENCE_FILE.stat().st_mtime
+                if mtime != last_mtime:
+                    last_mtime = mtime
+                    raw = await asyncio.to_thread(PRESENCE_FILE.read_text)
+                    state = json.loads(raw)
+                    await ws_mgr.broadcast("timmy_state", state)
+            else:
+                # File absent — broadcast synthesised state once per cycle
+                if last_mtime != -1.0:
+                    last_mtime = -1.0
+                    await ws_mgr.broadcast("timmy_state", _SYNTHESIZED_STATE)
+        except json.JSONDecodeError as exc:
+            logger.warning("presence.json parse error: %s", exc)
+        except Exception as exc:
+            logger.warning("Presence watcher error: %s", exc)
+
+        await asyncio.sleep(_PRESENCE_POLL_SECONDS)
+
+
 async def _start_chat_integrations_background() -> None:
     """Background task: start chat integrations without blocking startup."""
     from integrations.chat_bridge.registry import platform_registry
@@ -277,116 +357,126 @@ async def _discord_token_watcher() -> None:
                 logger.warning("Discord auto-start failed: %s", exc)
 
 
-@asynccontextmanager
-async def lifespan(app: FastAPI):
-    """Application lifespan manager with non-blocking startup."""
-
-    # Validate security config (no-op in test mode)
+def _startup_init() -> None:
+    """Validate config and enable event persistence."""
     from config import validate_startup
 
     validate_startup()
 
-    # Enable event persistence (unified EventBus + swarm event_log)
     from infrastructure.events.bus import init_event_bus_persistence
 
     init_event_bus_persistence()
 
-    # Create all background tasks without waiting for them
-    briefing_task = asyncio.create_task(_briefing_scheduler())
-    thinking_task = asyncio.create_task(_thinking_scheduler())
-    loop_qa_task = asyncio.create_task(_loop_qa_scheduler())
-
-    # Initialize Spark Intelligence engine
     from spark.engine import get_spark_engine
 
     if get_spark_engine().enabled:
         logger.info("Spark Intelligence active — event capture enabled")
 
-    # Auto-prune old vector store memories on startup
-    if settings.memory_prune_days > 0:
-        try:
-            from timmy.memory.vector_store import prune_memories
 
-            pruned = prune_memories(
+def _startup_background_tasks() -> list[asyncio.Task]:
+    """Spawn all recurring background tasks (non-blocking)."""
+    bg_tasks = [
+        asyncio.create_task(_briefing_scheduler()),
+        asyncio.create_task(_thinking_scheduler()),
+        asyncio.create_task(_loop_qa_scheduler()),
+        asyncio.create_task(_presence_watcher()),
+        asyncio.create_task(_start_chat_integrations_background()),
+    ]
+    try:
+        from timmy.paperclip import start_paperclip_poller
+        bg_tasks.append(asyncio.create_task(start_paperclip_poller()))
+        logger.info("Paperclip poller started")
+    except ImportError:
+        logger.debug("Paperclip module not found, skipping poller")
+    
+    return bg_tasks
+
+
+def _try_prune(label: str, prune_fn, days: int) -> None:
+    """Run a prune function, log results, swallow errors."""
+    try:
+        pruned = prune_fn()
+        if pruned:
+            logger.info(
+                "%s auto-prune: removed %d entries older than %d days",
+                label,
+                pruned,
+                days,
+            )
+    except Exception as exc:
+        logger.debug("%s auto-prune skipped: %s", label, exc)
+
+
+def _check_vault_size() -> None:
+    """Warn if the memory vault exceeds the configured size limit."""
+    try:
+        vault_path = Path(settings.repo_root) / "memory" / "notes"
+        if vault_path.exists():
+            total_bytes = sum(f.stat().st_size for f in vault_path.rglob("*") if f.is_file())
+            total_mb = total_bytes / (1024 * 1024)
+            if total_mb > settings.memory_vault_max_mb:
+                logger.warning(
+                    "Memory vault (%.1f MB) exceeds limit (%d MB) — consider archiving old notes",
+                    total_mb,
+                    settings.memory_vault_max_mb,
+                )
+    except Exception as exc:
+        logger.debug("Vault size check skipped: %s", exc)
+
+
+def _startup_pruning() -> None:
+    """Auto-prune old memories, thoughts, and events on startup."""
+    if settings.memory_prune_days > 0:
+        from timmy.memory_system import prune_memories
+
+        _try_prune(
+            "Memory",
+            lambda: prune_memories(
                 older_than_days=settings.memory_prune_days,
                 keep_facts=settings.memory_prune_keep_facts,
-            )
-            if pruned:
-                logger.info(
-                    "Memory auto-prune: removed %d entries older than %d days",
-                    pruned,
-                    settings.memory_prune_days,
-                )
-        except Exception as exc:
-            logger.debug("Memory auto-prune skipped: %s", exc)
+            ),
+            settings.memory_prune_days,
+        )
 
-    # Auto-prune old thoughts on startup
     if settings.thoughts_prune_days > 0:
-        try:
-            from timmy.thinking import thinking_engine
+        from timmy.thinking import thinking_engine
 
-            pruned = thinking_engine.prune_old_thoughts(
+        _try_prune(
+            "Thought",
+            lambda: thinking_engine.prune_old_thoughts(
                 keep_days=settings.thoughts_prune_days,
                 keep_min=settings.thoughts_prune_keep_min,
-            )
-            if pruned:
-                logger.info(
-                    "Thought auto-prune: removed %d entries older than %d days",
-                    pruned,
-                    settings.thoughts_prune_days,
-                )
-        except Exception as exc:
-            logger.debug("Thought auto-prune skipped: %s", exc)
+            ),
+            settings.thoughts_prune_days,
+        )
 
-    # Auto-prune old system events on startup
     if settings.events_prune_days > 0:
-        try:
-            from swarm.event_log import prune_old_events
+        from swarm.event_log import prune_old_events
 
-            pruned = prune_old_events(
+        _try_prune(
+            "Event",
+            lambda: prune_old_events(
                 keep_days=settings.events_prune_days,
                 keep_min=settings.events_prune_keep_min,
-            )
-            if pruned:
-                logger.info(
-                    "Event auto-prune: removed %d entries older than %d days",
-                    pruned,
-                    settings.events_prune_days,
-                )
-        except Exception as exc:
-            logger.debug("Event auto-prune skipped: %s", exc)
+            ),
+            settings.events_prune_days,
+        )
 
-    # Warn if memory vault exceeds size limit
     if settings.memory_vault_max_mb > 0:
-        try:
-            vault_path = Path(settings.repo_root) / "memory" / "notes"
-            if vault_path.exists():
-                total_bytes = sum(f.stat().st_size for f in vault_path.rglob("*") if f.is_file())
-                total_mb = total_bytes / (1024 * 1024)
-                if total_mb > settings.memory_vault_max_mb:
-                    logger.warning(
-                        "Memory vault (%.1f MB) exceeds limit (%d MB) — consider archiving old notes",
-                        total_mb,
-                        settings.memory_vault_max_mb,
-                    )
-        except Exception as exc:
-            logger.debug("Vault size check skipped: %s", exc)
+        _check_vault_size()
 
-    # Start chat integrations in background
-    chat_task = asyncio.create_task(_start_chat_integrations_background())
 
-    logger.info("✓ Dashboard ready for requests")
-
-    yield
-
-    # Cleanup on shutdown
+async def _shutdown_cleanup(
+    bg_tasks: list[asyncio.Task],
+    workshop_heartbeat,
+) -> None:
+    """Stop chat bots, MCP sessions, heartbeat, and cancel background tasks."""
     from integrations.chat_bridge.vendors.discord import discord_bot
     from integrations.telegram_bot.bot import telegram_bot
 
     await discord_bot.stop()
     await telegram_bot.stop()
 
-    # Close MCP tool server sessions
     try:
         from timmy.mcp_tools import close_mcp_sessions
 
@@ -394,13 +484,44 @@ async def lifespan(app: FastAPI):
     except Exception as exc:
         logger.debug("MCP shutdown: %s", exc)
 
-    for task in [briefing_task, thinking_task, chat_task, loop_qa_task]:
-        if task:
-            task.cancel()
-            try:
-                await task
-            except asyncio.CancelledError:
-                pass
+    await workshop_heartbeat.stop()
+
+    for task in bg_tasks:
+        task.cancel()
+        try:
+            await task
+        except asyncio.CancelledError:
+            pass
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Application lifespan manager with non-blocking startup."""
+    _startup_init()
+    bg_tasks = _startup_background_tasks()
+    _startup_pruning()
+
+    # Start Workshop presence heartbeat with WS relay
+    from dashboard.routes.world import broadcast_world_state
+    from timmy.workshop_state import WorkshopHeartbeat
+
+    workshop_heartbeat = WorkshopHeartbeat(on_change=broadcast_world_state)
+    await workshop_heartbeat.start()
+
+    # Register session logger with error capture
+    try:
+        from infrastructure.error_capture import register_error_recorder
+        from timmy.session_logger import get_session_logger
+
+        register_error_recorder(get_session_logger().record_error)
+    except Exception:
+        logger.debug("Failed to register error recorder")
+
+    logger.info("✓ Dashboard ready for requests")
+
+    yield
+
+    await _shutdown_cleanup(bg_tasks, workshop_heartbeat)
 
 
 app = FastAPI(
@@ -413,26 +534,55 @@ app = FastAPI(
 
 
 def _get_cors_origins() -> list[str]:
-    """Get CORS origins from settings, with sensible defaults."""
-    origins = settings.cors_origins
-    if settings.debug and origins == ["*"]:
-        return [
-            "http://localhost:3000",
-            "http://localhost:8000",
-            "http://127.0.0.1:3000",
-            "http://127.0.0.1:8000",
-        ]
+    """Get CORS origins from settings, rejecting wildcards in production.
+
+    Adds matrix_frontend_url when configured. Always allows Tailscale IPs
+    (100.x.x.x range) for development convenience.
+    """
+    origins = list(settings.cors_origins)
+
+    # Strip wildcards in production (security)
+    if "*" in origins and not settings.debug:
+        logger.warning(
+            "Wildcard '*' in CORS_ORIGINS stripped in production — "
+            "set explicit origins via CORS_ORIGINS env var"
+        )
+        origins = [o for o in origins if o != "*"]
+
+    # Add Matrix frontend URL if configured
+    if settings.matrix_frontend_url:
+        url = settings.matrix_frontend_url.strip()
+        if url and url not in origins:
+            origins.append(url)
+            logger.debug("Added Matrix frontend to CORS: %s", url)
+
     return origins
 
 
+# Pattern to match Tailscale IPs (100.x.x.x) for CORS origin regex
+_TAILSCALE_IP_PATTERN = re.compile(r"^https?://100\.\d{1,3}\.\d{1,3}\.\d{1,3}(?::\d+)?$")
+
+
+def _is_tailscale_origin(origin: str) -> bool:
+    """Check if origin is a Tailscale IP (100.x.x.x range)."""
+    return bool(_TAILSCALE_IP_PATTERN.match(origin))
+
+
 # Add dedicated middleware in correct order
 # 1. Logging (outermost to capture everything)
 app.add_middleware(RequestLoggingMiddleware, skip_paths=["/health"])
 
-# 2. Security Headers
+# 2. Rate Limiting (before security to prevent abuse early)
+app.add_middleware(
+    RateLimitMiddleware,
+    path_prefixes=["/api/matrix/"],
+    requests_per_minute=30,
+)
+
+# 3. Security Headers
 app.add_middleware(SecurityHeadersMiddleware, production=not settings.debug)
 
-# 3. CSRF Protection
+# 4. CSRF Protection
 app.add_middleware(CSRFMiddleware)
 
 # 4. Standard FastAPI middleware
@@ -446,6 +596,7 @@ app.add_middleware(
 app.add_middleware(
     CORSMiddleware,
     allow_origins=_get_cors_origins(),
+    allow_origin_regex=r"https?://100\.\d{1,3}\.\d{1,3}\.\d{1,3}(:\d+)?",
     allow_credentials=True,
     allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"],
     allow_headers=["Content-Type", "Authorization"],
@@ -474,6 +625,7 @@ app.include_router(grok_router)
 app.include_router(models_router)
 app.include_router(models_api_router)
 app.include_router(chat_api_router)
+app.include_router(chat_api_v1_router)
 app.include_router(thinking_router)
 app.include_router(calm_router)
 app.include_router(tasks_router)
@@ -482,6 +634,13 @@ app.include_router(loop_qa_router)
 app.include_router(system_router)
 app.include_router(experiments_router)
 app.include_router(db_explorer_router)
+app.include_router(world_router)
+app.include_router(matrix_router)
+app.include_router(tower_router)
+app.include_router(daily_run_router)
+app.include_router(quests_router)
+app.include_router(scorecards_router)
+app.include_router(sovereignty_metrics_router)
 
 
 @app.websocket("/ws")
@@ -500,6 +659,44 @@ async def ws_redirect(websocket: WebSocket):
         await websocket.send({"type": "websocket.close", "code": 1008})
 
 
+@app.websocket("/swarm/live")
+async def swarm_live(websocket: WebSocket):
+    """Swarm live event stream via WebSocket."""
+    from infrastructure.ws_manager.handler import ws_manager as ws_mgr
+
+    await ws_mgr.connect(websocket)
+    try:
+        while True:
+            # Keep connection alive; events are pushed via ws_mgr.broadcast()
+            await websocket.receive_text()
+    except Exception as exc:
+        logger.debug("WebSocket disconnect error: %s", exc)
+        ws_mgr.disconnect(websocket)
+
+
+@app.get("/swarm/agents/sidebar", response_class=HTMLResponse)
+async def swarm_agents_sidebar():
+    """HTMX partial: list active swarm agents for the dashboard sidebar."""
+    try:
+        from config import settings
+
+        agents_yaml = settings.agents_config
+        agents = agents_yaml.get("agents", {})
+        lines = []
+        for name, cfg in agents.items():
+            model = cfg.get("model", "default")
+            lines.append(
+                f'<div class="mc-agent-row">'
+                f'<span class="mc-agent-name">{name}</span>'
+                f'<span class="mc-agent-model">{model}</span>'
+                f"</div>"
+            )
+        return "\n".join(lines) if lines else '<div class="mc-muted">No agents configured</div>'
+    except Exception as exc:
+        logger.debug("Agents sidebar error: %s", exc)
+        return '<div class="mc-muted">Agents unavailable</div>'
+
+
 @app.get("/", response_class=HTMLResponse)
 async def root(request: Request):
     """Serve the main dashboard page."""

src/dashboard/middleware/__init__.py

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

src/dashboard/middleware/csrf.py

@@ -5,6 +5,7 @@ to protect state-changing endpoints from cross-site request attacks.
 """
 
 import hmac
+import logging
 import secrets
 from collections.abc import Callable
 from functools import wraps
@@ -16,6 +17,8 @@ from starlette.responses import JSONResponse, Response
 # Module-level set to track exempt routes
 _exempt_routes: set[str] = set()
 
+logger = logging.getLogger(__name__)
+
 
 def csrf_exempt(endpoint: Callable) -> Callable:
     """Decorator to mark an endpoint as exempt from CSRF validation.
@@ -97,7 +100,7 @@ class CSRFMiddleware(BaseHTTPMiddleware):
             ...
 
     Usage:
-        app.add_middleware(CSRFMiddleware, secret="your-secret-key")
+        app.add_middleware(CSRFMiddleware, secret=settings.csrf_secret)
 
     Attributes:
         secret: Secret key for token signing (optional, for future use).
@@ -128,58 +131,64 @@ class CSRFMiddleware(BaseHTTPMiddleware):
         For safe methods: Set a CSRF token cookie if not present.
         For unsafe methods: Validate the CSRF token or check if exempt.
         """
-        # Bypass CSRF if explicitly disabled (e.g. in tests)
         from config import settings
 
         if settings.timmy_disable_csrf:
             return await call_next(request)
 
-        # Get existing CSRF token from cookie
+        # WebSocket upgrades don't carry CSRF tokens — skip them entirely
+        if request.headers.get("upgrade", "").lower() == "websocket":
+            return await call_next(request)
+
         csrf_cookie = request.cookies.get(self.cookie_name)
 
-        # For safe methods, just ensure a token exists
         if request.method in self.SAFE_METHODS:
-            response = await call_next(request)
+            return await self._handle_safe_method(request, call_next, csrf_cookie)
 
-            # Set CSRF token cookie if not present
-            if not csrf_cookie:
-                new_token = generate_csrf_token()
-                response.set_cookie(
-                    key=self.cookie_name,
-                    value=new_token,
-                    httponly=False,  # Must be readable by JavaScript
-                    secure=settings.csrf_cookie_secure,
-                    samesite="Lax",
-                    max_age=86400,  # 24 hours
-                )
+        return await self._handle_unsafe_method(request, call_next, csrf_cookie)
 
-            return response
+    async def _handle_safe_method(
+        self, request: Request, call_next, csrf_cookie: str | None
+    ) -> Response:
+        """Handle safe HTTP methods (GET, HEAD, OPTIONS, TRACE).
 
-        # For unsafe methods, we need to validate or check if exempt
-        # First, try to validate the CSRF token
-        if await self._validate_request(request, csrf_cookie):
-            # Token is valid, allow the request
-            return await call_next(request)
+        Forwards the request and sets a CSRF token cookie if not present.
+        """
+        from config import settings
 
-        # Token validation failed, check if the path is exempt
-        path = request.url.path
-        if self._is_likely_exempt(path):
-            # Path is exempt, allow the request
-            return await call_next(request)
-
-        # Token validation failed and path is not exempt
-        # We still need to call the app to check if the endpoint is decorated
-        # with @csrf_exempt, so we'll let it through and check after routing
         response = await call_next(request)
 
-        # After routing, check if the endpoint is marked as exempt
-        endpoint = request.scope.get("endpoint")
-        if endpoint and is_csrf_exempt(endpoint):
-            # Endpoint is marked as exempt, allow the response
-            return response
+        if not csrf_cookie:
+            new_token = generate_csrf_token()
+            response.set_cookie(
+                key=self.cookie_name,
+                value=new_token,
+                httponly=False,  # Must be readable by JavaScript
+                secure=settings.csrf_cookie_secure,
+                samesite="Lax",
+                max_age=86400,  # 24 hours
+            )
+
+        return response
+
+    async def _handle_unsafe_method(
+        self, request: Request, call_next, csrf_cookie: str | None
+    ) -> Response:
+        """Handle unsafe HTTP methods (POST, PUT, DELETE, PATCH).
+
+        Validates the CSRF token, checks path and endpoint exemptions,
+        or returns a 403 error.
+        """
+        if await self._validate_request(request, csrf_cookie):
+            return await call_next(request)
+
+        if self._is_likely_exempt(request.url.path):
+            return await call_next(request)
+
+        endpoint = self._resolve_endpoint(request)
+        if endpoint and is_csrf_exempt(endpoint):
+            return await call_next(request)
 
-        # Endpoint is not exempt and token validation failed
-        # Return 403 error
         return JSONResponse(
             status_code=403,
             content={
@@ -189,6 +198,41 @@ class CSRFMiddleware(BaseHTTPMiddleware):
             },
         )
 
+    def _resolve_endpoint(self, request: Request) -> Callable | None:
+        """Resolve the route endpoint without executing it.
+
+        Walks the Starlette/FastAPI router to find which endpoint function
+        handles this request, so we can check @csrf_exempt before any
+        side effects occur.
+
+        Returns:
+            The endpoint callable, or None if no route matched.
+        """
+        # If routing already happened (endpoint in scope), use it
+        endpoint = request.scope.get("endpoint")
+        if endpoint:
+            return endpoint
+
+        # Walk the middleware/app chain to find something with routes
+        from starlette.routing import Match
+
+        app = self.app
+        while app is not None:
+            if hasattr(app, "routes"):
+                for route in app.routes:
+                    match, _ = route.matches(request.scope)
+                    if match == Match.FULL:
+                        return getattr(route, "endpoint", None)
+            # Try .router (FastAPI stores routes on app.router)
+            if hasattr(app, "router") and hasattr(app.router, "routes"):
+                for route in app.router.routes:
+                    match, _ = route.matches(request.scope)
+                    if match == Match.FULL:
+                        return getattr(route, "endpoint", None)
+            app = getattr(app, "app", None)
+
+        return None
+
     def _is_likely_exempt(self, path: str) -> bool:
         """Check if a path is likely to be CSRF exempt.
 
@@ -274,7 +318,8 @@ class CSRFMiddleware(BaseHTTPMiddleware):
                 form_token = form_data.get(self.form_field)
                 if form_token and validate_csrf_token(str(form_token), csrf_cookie):
                     return True
-            except Exception:
+            except Exception as exc:
+                logger.debug("CSRF form parsing error: %s", exc)
                 # Error parsing form data, treat as invalid
                 pass
 

src/dashboard/middleware/rate_limit.py

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

src/dashboard/middleware/request_logging.py

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

src/dashboard/middleware/security_headers.py

@@ -4,10 +4,14 @@ Adds common security headers to all HTTP responses to improve
 application security posture against various attacks.
 """
 
+import logging
+
 from starlette.middleware.base import BaseHTTPMiddleware
 from starlette.requests import Request
 from starlette.responses import Response
 
+logger = logging.getLogger(__name__)
+
 
 class SecurityHeadersMiddleware(BaseHTTPMiddleware):
     """Middleware to add security headers to all responses.
@@ -130,12 +134,8 @@ class SecurityHeadersMiddleware(BaseHTTPMiddleware):
         """
         try:
             response = await call_next(request)
-        except Exception:
-            import logging
-
-            logging.getLogger(__name__).debug(
-                "Upstream error in security headers middleware", exc_info=True
-            )
+        except Exception as exc:
+            logger.debug("Upstream error in security headers middleware: %s", exc)
             from starlette.responses import PlainTextResponse
 
             response = PlainTextResponse("Internal Server Error", status_code=500)

src/dashboard/models/calm.py

@@ -1,4 +1,4 @@
-from datetime import date, datetime
+from datetime import UTC, date, datetime
 from enum import StrEnum
 
 from sqlalchemy import JSON, Boolean, Column, Date, DateTime, Index, Integer, String
@@ -40,8 +40,13 @@ class Task(Base):
     deferred_at = Column(DateTime, nullable=True)
 
     # Timestamps
-    created_at = Column(DateTime, default=datetime.utcnow, nullable=False)
-    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow, nullable=False)
+    created_at = Column(DateTime, default=lambda: datetime.now(UTC), nullable=False)
+    updated_at = Column(
+        DateTime,
+        default=lambda: datetime.now(UTC),
+        onupdate=lambda: datetime.now(UTC),
+        nullable=False,
+    )
 
     __table_args__ = (Index("ix_task_state_order", "state", "sort_order"),)
 
@@ -59,4 +64,4 @@ class JournalEntry(Base):
     gratitude = Column(String(500), nullable=True)
     energy_level = Column(Integer, nullable=True)  # User-reported, 1-10
 
-    created_at = Column(DateTime, default=datetime.utcnow, nullable=False)
+    created_at = Column(DateTime, default=lambda: datetime.now(UTC), nullable=False)

src/dashboard/routes/agents.py

@@ -12,6 +12,7 @@ from timmy.tool_safety import (
     format_action_description,
     get_impact_level,
 )
+from timmy.welcome import WELCOME_MESSAGE
 
 logger = logging.getLogger(__name__)
 
@@ -56,7 +57,7 @@ async def get_history(request: Request):
     return templates.TemplateResponse(
         request,
         "partials/history.html",
-        {"messages": message_log.all()},
+        {"messages": message_log.all(), "welcome_message": WELCOME_MESSAGE},
     )
 
 
@@ -66,23 +67,91 @@ async def clear_history(request: Request):
     return templates.TemplateResponse(
         request,
         "partials/history.html",
-        {"messages": []},
+        {"messages": [], "welcome_message": WELCOME_MESSAGE},
     )
 
 
+def _validate_message(message: str) -> str:
+    """Strip and validate chat input; raise HTTPException on bad input."""
+    from fastapi import HTTPException
+
+    message = message.strip()
+    if not message:
+        raise HTTPException(status_code=400, detail="Message cannot be empty")
+    if len(message) > MAX_MESSAGE_LENGTH:
+        raise HTTPException(status_code=422, detail="Message too long")
+    return message
+
+
+def _record_user_activity() -> None:
+    """Notify the thinking engine that the user is active."""
+    try:
+        from timmy.thinking import thinking_engine
+
+        thinking_engine.record_user_input()
+    except Exception:
+        logger.debug("Failed to record user input for thinking engine")
+
+
+def _extract_tool_actions(run_output) -> list[dict]:
+    """If Agno paused the run for tool confirmation, build approval items."""
+    from timmy.approvals import create_item
+
+    tool_actions: list[dict] = []
+    status = getattr(run_output, "status", None)
+    is_paused = status == "PAUSED" or str(status) == "RunStatus.paused"
+
+    if not (is_paused and getattr(run_output, "active_requirements", None)):
+        return tool_actions
+
+    for req in run_output.active_requirements:
+        if not getattr(req, "needs_confirmation", False):
+            continue
+        te = req.tool_execution
+        tool_name = getattr(te, "tool_name", "unknown")
+        tool_args = getattr(te, "tool_args", {}) or {}
+
+        item = create_item(
+            title=f"Dashboard: {tool_name}",
+            description=format_action_description(tool_name, tool_args),
+            proposed_action=json.dumps({"tool": tool_name, "args": tool_args}),
+            impact=get_impact_level(tool_name),
+        )
+        _pending_runs[item.id] = {
+            "run_output": run_output,
+            "requirement": req,
+            "tool_name": tool_name,
+            "tool_args": tool_args,
+        }
+        tool_actions.append(
+            {
+                "approval_id": item.id,
+                "tool_name": tool_name,
+                "description": format_action_description(tool_name, tool_args),
+                "impact": get_impact_level(tool_name),
+            }
+        )
+    return tool_actions
+
+
+def _log_exchange(
+    message: str, response_text: str | None, error_text: str | None, timestamp: str
+) -> None:
+    """Append user message and agent/error reply to the in-memory log."""
+    message_log.append(role="user", content=message, timestamp=timestamp, source="browser")
+    if response_text:
+        message_log.append(
+            role="agent", content=response_text, timestamp=timestamp, source="browser"
+        )
+    elif error_text:
+        message_log.append(role="error", content=error_text, timestamp=timestamp, source="browser")
+
+
 @router.post("/default/chat", response_class=HTMLResponse)
 async def chat_agent(request: Request, message: str = Form(...)):
     """Chat — synchronous response with native Agno tool confirmation."""
-    message = message.strip()
-    if not message:
-        from fastapi import HTTPException
-
-        raise HTTPException(status_code=400, detail="Message cannot be empty")
-
-    if len(message) > MAX_MESSAGE_LENGTH:
-        from fastapi import HTTPException
-
-        raise HTTPException(status_code=422, detail="Message too long")
+    message = _validate_message(message)
+    _record_user_activity()
 
     timestamp = datetime.now().strftime("%H:%M:%S")
     response_text = None
@@ -95,54 +164,15 @@ async def chat_agent(request: Request, message: str = Form(...)):
         error_text = f"Chat error: {exc}"
         run_output = None
 
-    # Check if Agno paused the run for tool confirmation
-    tool_actions = []
+    tool_actions: list[dict] = []
     if run_output is not None:
-        status = getattr(run_output, "status", None)
-        is_paused = status == "PAUSED" or str(status) == "RunStatus.paused"
-
-        if is_paused and getattr(run_output, "active_requirements", None):
-            for req in run_output.active_requirements:
-                if getattr(req, "needs_confirmation", False):
-                    te = req.tool_execution
-                    tool_name = getattr(te, "tool_name", "unknown")
-                    tool_args = getattr(te, "tool_args", {}) or {}
-
-                    from timmy.approvals import create_item
-
-                    item = create_item(
-                        title=f"Dashboard: {tool_name}",
-                        description=format_action_description(tool_name, tool_args),
-                        proposed_action=json.dumps({"tool": tool_name, "args": tool_args}),
-                        impact=get_impact_level(tool_name),
-                    )
-                    _pending_runs[item.id] = {
-                        "run_output": run_output,
-                        "requirement": req,
-                        "tool_name": tool_name,
-                        "tool_args": tool_args,
-                    }
-                    tool_actions.append(
-                        {
-                            "approval_id": item.id,
-                            "tool_name": tool_name,
-                            "description": format_action_description(tool_name, tool_args),
-                            "impact": get_impact_level(tool_name),
-                        }
-                    )
-
+        tool_actions = _extract_tool_actions(run_output)
         raw_content = run_output.content if hasattr(run_output, "content") else ""
         response_text = _clean_response(raw_content or "")
         if not response_text and not tool_actions:
-            response_text = None  # let error template show if needed
+            response_text = None
 
-    message_log.append(role="user", content=message, timestamp=timestamp, source="browser")
-    if response_text:
-        message_log.append(
-            role="agent", content=response_text, timestamp=timestamp, source="browser"
-        )
-    elif error_text:
-        message_log.append(role="error", content=error_text, timestamp=timestamp, source="browser")
+    _log_exchange(message, response_text, error_text, timestamp)
 
     return templates.TemplateResponse(
         request,
@@ -220,7 +250,8 @@ async def reject_tool(request: Request, approval_id: str):
         # Resume so the agent knows the tool was rejected
         try:
             await continue_chat(pending["run_output"])
-        except Exception:
+        except Exception as exc:
+            logger.warning("Agent tool rejection error: %s", exc)
             pass
 
     reject(approval_id)

src/dashboard/routes/briefing.py

@@ -27,7 +27,8 @@ async def get_briefing(request: Request):
     """Return today's briefing page (generated or cached)."""
     try:
         briefing = briefing_engine.get_or_generate()
-    except Exception:
+    except Exception as exc:
+        logger.debug("Briefing generation failed: %s", exc)
         logger.exception("Briefing generation failed")
         now = datetime.now(UTC)
         briefing = Briefing(

src/dashboard/routes/calm.py

@@ -1,5 +1,5 @@
 import logging
-from datetime import date, datetime
+from datetime import UTC, date, datetime
 
 from fastapi import APIRouter, Depends, Form, HTTPException, Request
 from fastapi.responses import HTMLResponse
@@ -19,14 +19,17 @@ router = APIRouter(tags=["calm"])
 
 # Helper functions for state machine logic
 def get_now_task(db: Session) -> Task | None:
+    """Return the single active NOW task, or None."""
     return db.query(Task).filter(Task.state == TaskState.NOW).first()
 
 
 def get_next_task(db: Session) -> Task | None:
+    """Return the single queued NEXT task, or None."""
     return db.query(Task).filter(Task.state == TaskState.NEXT).first()
 
 
 def get_later_tasks(db: Session) -> list[Task]:
+    """Return all LATER tasks ordered by MIT flag then sort_order."""
     return (
         db.query(Task)
         .filter(Task.state == TaskState.LATER)
@@ -35,7 +38,63 @@ def get_later_tasks(db: Session) -> list[Task]:
     )
 
 
+def _create_mit_tasks(db: Session, titles: list[str | None]) -> list[int]:
+    """Create MIT tasks from a list of titles, return their IDs."""
+    task_ids: list[int] = []
+    for title in titles:
+        if title:
+            task = Task(
+                title=title,
+                is_mit=True,
+                state=TaskState.LATER,
+                certainty=TaskCertainty.SOFT,
+            )
+            db.add(task)
+            db.commit()
+            db.refresh(task)
+            task_ids.append(task.id)
+    return task_ids
+
+
+def _create_other_tasks(db: Session, other_tasks: str):
+    """Create non-MIT tasks from newline-separated text."""
+    for line in other_tasks.split("\n"):
+        line = line.strip()
+        if line:
+            task = Task(
+                title=line,
+                state=TaskState.LATER,
+                certainty=TaskCertainty.FUZZY,
+            )
+            db.add(task)
+
+
+def _seed_now_next(db: Session):
+    """Set initial NOW/NEXT states when both slots are empty."""
+    if get_now_task(db) or get_next_task(db):
+        return
+    later_tasks = (
+        db.query(Task)
+        .filter(Task.state == TaskState.LATER)
+        .order_by(Task.is_mit.desc(), Task.sort_order)
+        .all()
+    )
+    if later_tasks:
+        later_tasks[0].state = TaskState.NOW
+        db.add(later_tasks[0])
+        db.flush()
+        if len(later_tasks) > 1:
+            later_tasks[1].state = TaskState.NEXT
+            db.add(later_tasks[1])
+
+
 def promote_tasks(db: Session):
+    """Enforce the NOW/NEXT/LATER state machine invariants.
+
+    - At most one NOW task (extras demoted to NEXT).
+    - If no NOW, promote NEXT -> NOW.
+    - If no NEXT, promote highest-priority LATER -> NEXT.
+    """
     # Ensure only one NOW task exists. If multiple, demote extras to NEXT.
     now_tasks = db.query(Task).filter(Task.state == TaskState.NOW).all()
     if len(now_tasks) > 1:
@@ -74,6 +133,7 @@ def promote_tasks(db: Session):
 # Endpoints
 @router.get("/calm", response_class=HTMLResponse)
 async def get_calm_view(request: Request, db: Session = Depends(get_db)):
+    """Render the main CALM dashboard with NOW/NEXT/LATER counts."""
     now_task = get_now_task(db)
     next_task = get_next_task(db)
     later_tasks_count = len(get_later_tasks(db))
@@ -90,6 +150,7 @@ async def get_calm_view(request: Request, db: Session = Depends(get_db)):
 
 @router.get("/calm/ritual/morning", response_class=HTMLResponse)
 async def get_morning_ritual_form(request: Request):
+    """Render the morning ritual intake form."""
     return templates.TemplateResponse(request, "calm/morning_ritual_form.html", {})
 
 
@@ -102,63 +163,20 @@ async def post_morning_ritual(
     mit3_title: str = Form(None),
     other_tasks: str = Form(""),
 ):
-    # Create Journal Entry
-    mit_task_ids = []
+    """Process morning ritual: create MITs, other tasks, and set initial states."""
     journal_entry = JournalEntry(entry_date=date.today())
     db.add(journal_entry)
     db.commit()
     db.refresh(journal_entry)
 
-    # Create MIT tasks
-    for mit_title in [mit1_title, mit2_title, mit3_title]:
-        if mit_title:
-            task = Task(
-                title=mit_title,
-                is_mit=True,
-                state=TaskState.LATER,  # Initially LATER, will be promoted
-                certainty=TaskCertainty.SOFT,
-            )
-            db.add(task)
-            db.commit()
-            db.refresh(task)
-            mit_task_ids.append(task.id)
-
-    journal_entry.mit_task_ids = mit_task_ids
+    journal_entry.mit_task_ids = _create_mit_tasks(db, [mit1_title, mit2_title, mit3_title])
     db.add(journal_entry)
 
-    # Create other tasks
-    for task_title in other_tasks.split("\n"):
-        task_title = task_title.strip()
-        if task_title:
-            task = Task(
-                title=task_title,
-                state=TaskState.LATER,
-                certainty=TaskCertainty.FUZZY,
-            )
-            db.add(task)
-
+    _create_other_tasks(db, other_tasks)
     db.commit()
 
-    # Set initial NOW/NEXT states
-    # Set initial NOW/NEXT states after all tasks are created
-    if not get_now_task(db) and not get_next_task(db):
-        later_tasks = (
-            db.query(Task)
-            .filter(Task.state == TaskState.LATER)
-            .order_by(Task.is_mit.desc(), Task.sort_order)
-            .all()
-        )
-        if later_tasks:
-            # Set the highest priority LATER task to NOW
-            later_tasks[0].state = TaskState.NOW
-            db.add(later_tasks[0])
-            db.flush()  # Flush to make the change visible for the next query
-
-            # Set the next highest priority LATER task to NEXT
-            if len(later_tasks) > 1:
-                later_tasks[1].state = TaskState.NEXT
-                db.add(later_tasks[1])
-    db.commit()  # Commit changes after initial NOW/NEXT setup
+    _seed_now_next(db)
+    db.commit()
 
     return templates.TemplateResponse(
         request,
@@ -173,6 +191,7 @@ async def post_morning_ritual(
 
 @router.get("/calm/ritual/evening", response_class=HTMLResponse)
 async def get_evening_ritual_form(request: Request, db: Session = Depends(get_db)):
+    """Render the evening ritual form for today's journal entry."""
     journal_entry = db.query(JournalEntry).filter(JournalEntry.entry_date == date.today()).first()
     if not journal_entry:
         raise HTTPException(status_code=404, detail="No journal entry for today")
@@ -189,6 +208,7 @@ async def post_evening_ritual(
     gratitude: str = Form(None),
     energy_level: int = Form(None),
 ):
+    """Process evening ritual: save reflection/gratitude, archive active tasks."""
     journal_entry = db.query(JournalEntry).filter(JournalEntry.entry_date == date.today()).first()
     if not journal_entry:
         raise HTTPException(status_code=404, detail="No journal entry for today")
@@ -206,7 +226,7 @@ async def post_evening_ritual(
     )
     for task in active_tasks:
         task.state = TaskState.DEFERRED  # Or DONE, depending on desired archiving logic
-        task.deferred_at = datetime.utcnow()
+        task.deferred_at = datetime.now(UTC)
         db.add(task)
 
     db.commit()
@@ -223,6 +243,7 @@ async def create_new_task(
     is_mit: bool = Form(False),
     certainty: TaskCertainty = Form(TaskCertainty.SOFT),
 ):
+    """Create a new task in LATER state and return updated count."""
     task = Task(
         title=title,
         description=description,
@@ -247,6 +268,7 @@ async def start_task(
     task_id: int,
     db: Session = Depends(get_db),
 ):
+    """Move a task to NOW state, demoting the current NOW to NEXT."""
     current_now_task = get_now_task(db)
     if current_now_task and current_now_task.id != task_id:
         current_now_task.state = TaskState.NEXT  # Demote current NOW to NEXT
@@ -257,7 +279,7 @@ async def start_task(
         raise HTTPException(status_code=404, detail="Task not found")
 
     task.state = TaskState.NOW
-    task.started_at = datetime.utcnow()
+    task.started_at = datetime.now(UTC)
     db.add(task)
     db.commit()
 
@@ -281,12 +303,13 @@ async def complete_task(
     task_id: int,
     db: Session = Depends(get_db),
 ):
+    """Mark a task as DONE and trigger state promotion."""
     task = db.query(Task).filter(Task.id == task_id).first()
     if not task:
         raise HTTPException(status_code=404, detail="Task not found")
 
     task.state = TaskState.DONE
-    task.completed_at = datetime.utcnow()
+    task.completed_at = datetime.now(UTC)
     db.add(task)
     db.commit()
 
@@ -309,12 +332,13 @@ async def defer_task(
     task_id: int,
     db: Session = Depends(get_db),
 ):
+    """Defer a task and trigger state promotion."""
     task = db.query(Task).filter(Task.id == task_id).first()
     if not task:
         raise HTTPException(status_code=404, detail="Task not found")
 
     task.state = TaskState.DEFERRED
-    task.deferred_at = datetime.utcnow()
+    task.deferred_at = datetime.now(UTC)
     db.add(task)
     db.commit()
 
@@ -333,6 +357,7 @@ async def defer_task(
 
 @router.get("/calm/partials/later_tasks_list", response_class=HTMLResponse)
 async def get_later_tasks_list(request: Request, db: Session = Depends(get_db)):
+    """Render the expandable list of LATER tasks."""
     later_tasks = get_later_tasks(db)
     return templates.TemplateResponse(
         "calm/partials/later_tasks_list.html",
@@ -348,6 +373,7 @@ async def reorder_tasks(
     later_task_ids: str = Form(""),
     next_task_id: int | None = Form(None),
 ):
+    """Reorder LATER tasks and optionally promote one to NEXT."""
     # Reorder LATER tasks
     if later_task_ids:
         ids_in_order = [int(x.strip()) for x in later_task_ids.split(",") if x.strip()]

src/dashboard/routes/chat_api.py

@@ -31,6 +31,93 @@ _UPLOAD_DIR = str(Path(settings.repo_root) / "data" / "chat-uploads")
 _MAX_UPLOAD_SIZE = 50 * 1024 * 1024  # 50 MB
 
 
+# ── POST /api/chat — helpers ─────────────────────────────────────────────────
+
+
+async def _parse_chat_body(request: Request) -> tuple[dict | None, JSONResponse | None]:
+    """Parse and validate the JSON request body.
+
+    Returns (body, None) on success or (None, error_response) on failure.
+    """
+    content_length = request.headers.get("content-length")
+    if content_length and int(content_length) > settings.chat_api_max_body_bytes:
+        return None, JSONResponse(status_code=413, content={"error": "Request body too large"})
+
+    try:
+        body = await request.json()
+    except Exception as exc:
+        logger.warning("Chat API JSON parse error: %s", exc)
+        return None, JSONResponse(status_code=400, content={"error": "Invalid JSON"})
+
+    messages = body.get("messages")
+    if not messages or not isinstance(messages, list):
+        return None, JSONResponse(status_code=400, content={"error": "messages array is required"})
+
+    return body, None
+
+
+def _extract_user_message(messages: list[dict]) -> str | None:
+    """Return the text of the last user message, or *None* if absent."""
+    for msg in reversed(messages):
+        if msg.get("role") == "user":
+            content = msg.get("content", "")
+            if isinstance(content, list):
+                text_parts = [
+                    p.get("text", "")
+                    for p in content
+                    if isinstance(p, dict) and p.get("type") == "text"
+                ]
+                return " ".join(text_parts).strip() or None
+            text = str(content).strip()
+            return text or None
+    return None
+
+
+def _build_context_prefix() -> str:
+    """Build the system-context preamble injected before the user message."""
+    now = datetime.now()
+    return (
+        f"[System: Current date/time is "
+        f"{now.strftime('%A, %B %d, %Y at %I:%M %p')}]\n"
+        f"[System: Mobile client]\n\n"
+    )
+
+
+def _notify_thinking_engine() -> None:
+    """Record user activity so the thinking engine knows we're not idle."""
+    try:
+        from timmy.thinking import thinking_engine
+
+        thinking_engine.record_user_input()
+    except Exception:
+        logger.debug("Failed to record user input for thinking engine")
+
+
+async def _process_chat(user_msg: str) -> dict | JSONResponse:
+    """Send *user_msg* to the agent, log the exchange, and return a response."""
+    _notify_thinking_engine()
+    timestamp = datetime.now().strftime("%H:%M:%S")
+
+    try:
+        response_text = await agent_chat(
+            _build_context_prefix() + user_msg,
+            session_id="mobile",
+        )
+        message_log.append(role="user", content=user_msg, timestamp=timestamp, source="api")
+        message_log.append(role="agent", content=response_text, timestamp=timestamp, source="api")
+        return {"reply": response_text, "timestamp": timestamp}
+
+    except Exception as exc:
+        error_msg = f"Agent is offline: {exc}"
+        logger.error("api_chat error: %s", exc)
+        message_log.append(role="user", content=user_msg, timestamp=timestamp, source="api")
+        message_log.append(role="error", content=error_msg, timestamp=timestamp, source="api")
+        return JSONResponse(
+            status_code=503,
+            content={"error": error_msg, "timestamp": timestamp},
+        )
+
+
 # ── POST /api/chat ────────────────────────────────────────────────────────────
 
 
@@ -44,69 +131,15 @@ async def api_chat(request: Request):
     Response:
         {"reply": "...", "timestamp": "HH:MM:SS"}
     """
-    # Enforce request body size limit
-    content_length = request.headers.get("content-length")
-    if content_length and int(content_length) > settings.chat_api_max_body_bytes:
-        return JSONResponse(status_code=413, content={"error": "Request body too large"})
+    body, err = await _parse_chat_body(request)
+    if err:
+        return err
 
-    try:
-        body = await request.json()
-    except Exception:
-        return JSONResponse(status_code=400, content={"error": "Invalid JSON"})
-
-    messages = body.get("messages")
-    if not messages or not isinstance(messages, list):
-        return JSONResponse(status_code=400, content={"error": "messages array is required"})
-
-    # Extract the latest user message text
-    last_user_msg = None
-    for msg in reversed(messages):
-        if msg.get("role") == "user":
-            content = msg.get("content", "")
-            # Handle multimodal content arrays — extract text parts
-            if isinstance(content, list):
-                text_parts = [
-                    p.get("text", "")
-                    for p in content
-                    if isinstance(p, dict) and p.get("type") == "text"
-                ]
-                last_user_msg = " ".join(text_parts).strip()
-            else:
-                last_user_msg = str(content).strip()
-            break
-
-    if not last_user_msg:
+    user_msg = _extract_user_message(body["messages"])
+    if not user_msg:
         return JSONResponse(status_code=400, content={"error": "No user message found"})
 
-    timestamp = datetime.now().strftime("%H:%M:%S")
-
-    try:
-        # Inject context (same pattern as the HTMX chat handler in agents.py)
-        now = datetime.now()
-        context_prefix = (
-            f"[System: Current date/time is "
-            f"{now.strftime('%A, %B %d, %Y at %I:%M %p')}]\n"
-            f"[System: Mobile client]\n\n"
-        )
-        response_text = await agent_chat(
-            context_prefix + last_user_msg,
-            session_id="mobile",
-        )
-
-        message_log.append(role="user", content=last_user_msg, timestamp=timestamp, source="api")
-        message_log.append(role="agent", content=response_text, timestamp=timestamp, source="api")
-
-        return {"reply": response_text, "timestamp": timestamp}
-
-    except Exception as exc:
-        error_msg = f"Agent is offline: {exc}"
-        logger.error("api_chat error: %s", exc)
-        message_log.append(role="user", content=last_user_msg, timestamp=timestamp, source="api")
-        message_log.append(role="error", content=error_msg, timestamp=timestamp, source="api")
-        return JSONResponse(
-            status_code=503,
-            content={"error": error_msg, "timestamp": timestamp},
-        )
+    return await _process_chat(user_msg)
 
 
 # ── POST /api/upload ──────────────────────────────────────────────────────────

src/dashboard/routes/chat_api_v1.py

@@ -0,0 +1,198 @@
+"""Version 1 (v1) JSON REST API for the Timmy Time iPad app.
+
+This module implements the specific endpoints required by the native
+iPad app as defined in the project specification.
+
+Endpoints:
+    POST /api/v1/chat           — Streaming SSE chat response
+    GET  /api/v1/chat/history   — Retrieve chat history with limit
+    POST /api/v1/upload         — Multipart file upload with auto-detection
+    GET  /api/v1/status         — Detailed system and model status
+"""
+
+import json
+import logging
+import os
+import uuid
+from datetime import UTC, datetime
+from pathlib import Path
+
+from fastapi import APIRouter, File, HTTPException, Query, Request, UploadFile
+from fastapi.responses import JSONResponse, StreamingResponse
+
+from config import APP_START_TIME, settings
+from dashboard.routes.health import _check_ollama
+from dashboard.store import message_log
+from timmy.session import _get_agent
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/v1", tags=["chat-api-v1"])
+
+_UPLOAD_DIR = str(Path(settings.repo_root) / "data" / "chat-uploads")
+_MAX_UPLOAD_SIZE = 50 * 1024 * 1024  # 50 MB
+
+
+# ── POST /api/v1/chat ─────────────────────────────────────────────────────────
+
+
+@router.post("/chat")
+async def api_v1_chat(request: Request):
+    """Accept a JSON chat payload and return a streaming SSE response.
+
+    Request body:
+        {
+            "message": "string",
+            "session_id": "string",
+            "attachments": ["id1", "id2"]
+        }
+
+    Response:
+        text/event-stream (SSE)
+    """
+    try:
+        body = await request.json()
+    except Exception as exc:
+        logger.warning("Chat v1 API JSON parse error: %s", exc)
+        return JSONResponse(status_code=400, content={"error": "Invalid JSON"})
+
+    message = body.get("message")
+    session_id = body.get("session_id", "ipad-app")
+    attachments = body.get("attachments", [])
+
+    if not message:
+        return JSONResponse(status_code=400, content={"error": "message is required"})
+
+    # Prepare context for the agent
+    context_prefix = (
+        f"[System: Current date/time is "
+        f"{datetime.now().strftime('%A, %B %d, %Y at %I:%M %p')}]\n"
+        f"[System: iPad App client]\n"
+    )
+
+    if attachments:
+        context_prefix += f"[System: Attachments: {', '.join(attachments)}]\n"
+
+    context_prefix += "\n"
+    full_prompt = context_prefix + message
+
+    async def event_generator():
+        try:
+            agent = _get_agent()
+            # Using streaming mode for SSE
+            async for chunk in agent.arun(full_prompt, stream=True, session_id=session_id):
+                # Agno chunks can be strings or RunOutput
+                content = chunk.content if hasattr(chunk, "content") else str(chunk)
+                if content:
+                    yield f"data: {json.dumps({'text': content})}\n\n"
+
+            yield "data: [DONE]\n\n"
+        except Exception as exc:
+            logger.error("SSE stream error: %s", exc)
+            yield f"data: {json.dumps({'error': str(exc)})}\n\n"
+
+    return StreamingResponse(event_generator(), media_type="text/event-stream")
+
+
+# ── GET /api/v1/chat/history ──────────────────────────────────────────────────
+
+
+@router.get("/chat/history")
+async def api_v1_chat_history(
+    session_id: str = Query("ipad-app"), limit: int = Query(50, ge=1, le=100)
+):
+    """Return recent chat history for a specific session."""
+    # Filter and limit the message log
+    # Note: message_log.all() returns all messages; we filter by source or just return last N
+    all_msgs = message_log.all()
+
+    # In a real implementation, we'd filter by session_id if message_log supported it.
+    # For now, we return the last 'limit' messages.
+    history = [
+        {
+            "role": msg.role,
+            "content": msg.content,
+            "timestamp": msg.timestamp,
+            "source": msg.source,
+        }
+        for msg in all_msgs[-limit:]
+    ]
+
+    return {"messages": history}
+
+
+# ── POST /api/v1/upload ───────────────────────────────────────────────────────
+
+
+@router.post("/upload")
+async def api_v1_upload(file: UploadFile = File(...)):
+    """Accept a file upload, auto-detect type, and return metadata.
+
+    Response:
+        {
+            "id": "string",
+            "type": "image|audio|document|url",
+            "summary": "string",
+            "metadata": {...}
+        }
+    """
+    os.makedirs(_UPLOAD_DIR, exist_ok=True)
+
+    file_id = uuid.uuid4().hex[:12]
+    safe_name = os.path.basename(file.filename or "upload")
+    stored_name = f"{file_id}-{safe_name}"
+    file_path = os.path.join(_UPLOAD_DIR, stored_name)
+
+    # Verify resolved path stays within upload directory
+    resolved = Path(file_path).resolve()
+    upload_root = Path(_UPLOAD_DIR).resolve()
+    if not str(resolved).startswith(str(upload_root)):
+        raise HTTPException(status_code=400, detail="Invalid file name")
+
+    contents = await file.read()
+    if len(contents) > _MAX_UPLOAD_SIZE:
+        raise HTTPException(status_code=413, detail="File too large (max 50 MB)")
+
+    with open(file_path, "wb") as f:
+        f.write(contents)
+
+    # Auto-detect type based on extension/mime
+    mime_type = file.content_type or "application/octet-stream"
+    ext = os.path.splitext(safe_name)[1].lower()
+
+    media_type = "document"
+    if mime_type.startswith("image/") or ext in [".jpg", ".jpeg", ".png", ".heic"]:
+        media_type = "image"
+    elif mime_type.startswith("audio/") or ext in [".m4a", ".mp3", ".wav", ".caf"]:
+        media_type = "audio"
+    elif ext in [".pdf", ".txt", ".md"]:
+        media_type = "document"
+
+    # Placeholder for actual processing (OCR, Whisper, etc.)
+    summary = f"Uploaded {media_type}: {safe_name}"
+
+    return {
+        "id": file_id,
+        "type": media_type,
+        "summary": summary,
+        "url": f"/uploads/{stored_name}",
+        "metadata": {"fileName": safe_name, "mimeType": mime_type, "size": len(contents)},
+    }
+
+
+# ── GET /api/v1/status ────────────────────────────────────────────────────────
+
+
+@router.get("/status")
+async def api_v1_status():
+    """Detailed system and model status."""
+    ollama_status = await _check_ollama()
+    uptime = (datetime.now(UTC) - APP_START_TIME).total_seconds()
+
+    return {
+        "timmy": "online" if ollama_status.status == "healthy" else "offline",
+        "model": settings.ollama_model,
+        "ollama": "running" if ollama_status.status == "healthy" else "stopped",
+        "uptime": f"{int(uptime // 3600)}h {int((uptime % 3600) // 60)}m",
+        "version": "2.0.0-v1-api",
+    }

src/dashboard/routes/daily_run.py

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

src/dashboard/routes/db_explorer.py

@@ -3,6 +3,7 @@
 import asyncio
 import logging
 import sqlite3
+from contextlib import closing
 from pathlib import Path
 
 from fastapi import APIRouter, Request
@@ -39,56 +40,52 @@ def _query_database(db_path: str) -> dict:
     """Open a database read-only and return all tables with their rows."""
     result = {"tables": {}, "error": None}
     try:
-        conn = sqlite3.connect(f"file:{db_path}?mode=ro", uri=True)
-        conn.row_factory = sqlite3.Row
-    except Exception as exc:
-        result["error"] = str(exc)
-        return result
+        with closing(sqlite3.connect(f"file:{db_path}?mode=ro", uri=True)) as conn:
+            conn.row_factory = sqlite3.Row
 
-    try:
-        tables = conn.execute(
-            "SELECT name FROM sqlite_master WHERE type='table' ORDER BY name"
-        ).fetchall()
-        for (table_name,) in tables:
-            try:
-                rows = conn.execute(
-                    f"SELECT * FROM [{table_name}] LIMIT {MAX_ROWS}"  # noqa: S608
-                ).fetchall()
-                columns = (
-                    [
-                        desc[0]
-                        for desc in conn.execute(
-                            f"SELECT * FROM [{table_name}] LIMIT 0"
-                        ).description
-                    ]
-                    if rows
-                    else []
-                )  # noqa: S608
-                if not columns and rows:
-                    columns = list(rows[0].keys())
-                elif not columns:
-                    # Get columns even for empty tables
-                    cursor = conn.execute(f"PRAGMA table_info([{table_name}])")  # noqa: S608
-                    columns = [r[1] for r in cursor.fetchall()]
-                count = conn.execute(f"SELECT COUNT(*) FROM [{table_name}]").fetchone()[0]  # noqa: S608
-                result["tables"][table_name] = {
-                    "columns": columns,
-                    "rows": [dict(r) for r in rows],
-                    "total_count": count,
-                    "truncated": count > MAX_ROWS,
-                }
-            except Exception as exc:
-                result["tables"][table_name] = {
-                    "error": str(exc),
-                    "columns": [],
-                    "rows": [],
-                    "total_count": 0,
-                    "truncated": False,
-                }
+            tables = conn.execute(
+                "SELECT name FROM sqlite_master WHERE type='table' ORDER BY name"
+            ).fetchall()
+            for (table_name,) in tables:
+                try:
+                    rows = conn.execute(
+                        f"SELECT * FROM [{table_name}] LIMIT {MAX_ROWS}"  # noqa: S608
+                    ).fetchall()
+                    columns = (
+                        [
+                            desc[0]
+                            for desc in conn.execute(
+                                f"SELECT * FROM [{table_name}] LIMIT 0"
+                            ).description
+                        ]
+                        if rows
+                        else []
+                    )  # noqa: S608
+                    if not columns and rows:
+                        columns = list(rows[0].keys())
+                    elif not columns:
+                        # Get columns even for empty tables
+                        cursor = conn.execute(f"PRAGMA table_info([{table_name}])")  # noqa: S608
+                        columns = [r[1] for r in cursor.fetchall()]
+                    count = conn.execute(f"SELECT COUNT(*) FROM [{table_name}]").fetchone()[0]  # noqa: S608
+                    result["tables"][table_name] = {
+                        "columns": columns,
+                        "rows": [dict(r) for r in rows],
+                        "total_count": count,
+                        "truncated": count > MAX_ROWS,
+                    }
+                except Exception as exc:
+                    logger.exception("Failed to query table %s", table_name)
+                    result["tables"][table_name] = {
+                        "error": str(exc),
+                        "columns": [],
+                        "rows": [],
+                        "total_count": 0,
+                        "truncated": False,
+                    }
     except Exception as exc:
+        logger.exception("Failed to query database %s", db_path)
         result["error"] = str(exc)
-    finally:
-        conn.close()
 
     return result
 

src/dashboard/routes/experiments.py

@@ -30,8 +30,8 @@ async def experiments_page(request: Request):
     history = []
     try:
         history = get_experiment_history(_workspace())
-    except Exception:
-        logger.debug("Failed to load experiment history", exc_info=True)
+    except Exception as exc:
+        logger.debug("Failed to load experiment history: %s", exc)
 
     return templates.TemplateResponse(
         request,

src/dashboard/routes/grok.py

@@ -52,8 +52,8 @@ async def grok_status(request: Request):
             "estimated_cost_sats": backend.stats.estimated_cost_sats,
             "errors": backend.stats.errors,
         }
-    except Exception:
-        logger.debug("Failed to load Grok stats", exc_info=True)
+    except Exception as exc:
+        logger.warning("Failed to load Grok stats: %s", exc)
 
     return templates.TemplateResponse(
         request,
@@ -94,8 +94,8 @@ async def toggle_grok_mode(request: Request):
             tool_name="grok_mode_toggle",
             success=True,
         )
-    except Exception:
-        logger.debug("Failed to log Grok toggle to Spark", exc_info=True)
+    except Exception as exc:
+        logger.warning("Failed to log Grok toggle to Spark: %s", exc)
 
     return HTMLResponse(
         _render_toggle_card(_grok_mode_active),
@@ -125,16 +125,17 @@ def _run_grok_query(message: str) -> dict:
             from lightning.factory import get_backend as get_ln_backend
 
             ln = get_ln_backend()
-            sats = min(settings.grok_max_sats_per_query, 100)
+            sats = min(settings.grok_max_sats_per_query, settings.grok_sats_hard_cap)
             ln.create_invoice(sats, f"Grok: {message[:50]}")
             invoice_note = f" | {sats} sats"
-        except Exception:
-            logger.debug("Lightning invoice creation failed", exc_info=True)
+        except Exception as exc:
+            logger.warning("Lightning invoice creation failed: %s", exc)
 
     try:
         result = backend.run(message)
         return {"response": f"**[Grok]{invoice_note}:** {result.content}", "error": None}
     except Exception as exc:
+        logger.exception("Grok query failed")
         return {"response": None, "error": f"Grok error: {exc}"}
 
 
@@ -193,6 +194,7 @@ async def grok_stats():
             "model": settings.grok_default_model,
         }
     except Exception as exc:
+        logger.exception("Failed to load Grok stats")
         return {"error": str(exc)}
 
 

src/dashboard/routes/health.py

@@ -6,14 +6,18 @@ for the Mission Control dashboard.
 
 import asyncio
 import logging
+import sqlite3
 import time
+from contextlib import closing
 from datetime import UTC, datetime
+from pathlib import Path
 from typing import Any
 
 from fastapi import APIRouter, Request
 from fastapi.responses import HTMLResponse
 from pydantic import BaseModel
 
+from config import APP_START_TIME as _START_TIME
 from config import settings
 
 logger = logging.getLogger(__name__)
@@ -49,7 +53,6 @@ class HealthStatus(BaseModel):
 
 
 # Simple uptime tracking
-_START_TIME = datetime.now(UTC)
 
 # Ollama health cache (30-second TTL)
 _ollama_cache: DependencyStatus | None = None
@@ -62,7 +65,7 @@ def _check_ollama_sync() -> DependencyStatus:
     try:
         import urllib.request
 
-        url = settings.ollama_url.replace("localhost", "127.0.0.1")
+        url = settings.normalized_ollama_url
         req = urllib.request.Request(
             f"{url}/api/tags",
             method="GET",
@@ -76,8 +79,8 @@ def _check_ollama_sync() -> DependencyStatus:
                     sovereignty_score=10,
                     details={"url": settings.ollama_url, "model": settings.ollama_model},
                 )
-    except Exception:
-        logger.debug("Ollama health check failed", exc_info=True)
+    except Exception as exc:
+        logger.debug("Ollama health check failed: %s", exc)
 
     return DependencyStatus(
         name="Ollama AI",
@@ -101,7 +104,8 @@ async def _check_ollama() -> DependencyStatus:
 
     try:
         result = await asyncio.to_thread(_check_ollama_sync)
-    except Exception:
+    except Exception as exc:
+        logger.debug("Ollama async check failed: %s", exc)
         result = DependencyStatus(
             name="Ollama AI",
             status="unavailable",
@@ -133,13 +137,9 @@ def _check_lightning() -> DependencyStatus:
 def _check_sqlite() -> DependencyStatus:
     """Check SQLite database status."""
     try:
-        import sqlite3
-        from pathlib import Path
-
         db_path = Path(settings.repo_root) / "data" / "timmy.db"
-        conn = sqlite3.connect(str(db_path))
-        conn.execute("SELECT 1")
-        conn.close()
+        with closing(sqlite3.connect(str(db_path))) as conn:
+            conn.execute("SELECT 1")
 
         return DependencyStatus(
             name="SQLite Database",
@@ -148,6 +148,7 @@ def _check_sqlite() -> DependencyStatus:
             details={"path": str(db_path)},
         )
     except Exception as exc:
+        logger.exception("SQLite health check failed")
         return DependencyStatus(
             name="SQLite Database",
             status="unavailable",
@@ -274,3 +275,54 @@ async def component_status():
         },
         "timestamp": datetime.now(UTC).isoformat(),
     }
+
+
+@router.get("/health/snapshot")
+async def health_snapshot():
+    """Quick health snapshot before coding.
+
+    Returns a concise status summary including:
+    - CI pipeline status (pass/fail/unknown)
+    - Critical issues count (P0/P1)
+    - Test flakiness rate
+    - Token economy temperature
+
+    Fast execution (< 5 seconds) for pre-work checks.
+    Refs: #710
+    """
+    import sys
+    from pathlib import Path
+
+    # Import the health snapshot module
+    snapshot_path = Path(settings.repo_root) / "timmy_automations" / "daily_run"
+    if str(snapshot_path) not in sys.path:
+        sys.path.insert(0, str(snapshot_path))
+
+    try:
+        from health_snapshot import generate_snapshot, get_token, load_config
+
+        config = load_config()
+        token = get_token(config)
+
+        # Run the health snapshot (in thread to avoid blocking)
+        snapshot = await asyncio.to_thread(generate_snapshot, config, token)
+
+        return snapshot.to_dict()
+    except Exception as exc:
+        logger.warning("Health snapshot failed: %s", exc)
+        # Return graceful fallback
+        return {
+            "timestamp": datetime.now(UTC).isoformat(),
+            "overall_status": "unknown",
+            "error": str(exc),
+            "ci": {"status": "unknown", "message": "Snapshot failed"},
+            "issues": {"count": 0, "p0_count": 0, "p1_count": 0, "issues": []},
+            "flakiness": {
+                "status": "unknown",
+                "recent_failures": 0,
+                "recent_cycles": 0,
+                "failure_rate": 0.0,
+                "message": "Snapshot failed",
+            },
+            "tokens": {"status": "unknown", "message": "Snapshot failed"},
+        }

src/dashboard/routes/memory.py

@@ -4,7 +4,7 @@ from fastapi import APIRouter, Form, HTTPException, Request
 from fastapi.responses import HTMLResponse, JSONResponse
 
 from dashboard.templating import templates
-from timmy.memory.vector_store import (
+from timmy.memory_system import (
     delete_memory,
     get_memory_stats,
     recall_personal_facts_with_ids,

src/dashboard/routes/quests.py

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

src/dashboard/routes/scorecards.py

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

src/dashboard/routes/sovereignty_metrics.py

@@ -0,0 +1,74 @@
+"""Sovereignty metrics dashboard routes.
+
+Provides API endpoints and HTMX partials for tracking research
+sovereignty progress against graduation targets.
+
+Refs: #981
+"""
+
+import logging
+from typing import Any
+
+from fastapi import APIRouter, Request
+from fastapi.responses import HTMLResponse
+
+from config import settings
+from dashboard.templating import templates
+from infrastructure.sovereignty_metrics import (
+    GRADUATION_TARGETS,
+    get_sovereignty_store,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/sovereignty", tags=["sovereignty"])
+
+
+@router.get("/metrics")
+async def sovereignty_metrics_api() -> dict[str, Any]:
+    """JSON API: full sovereignty metrics summary with trends."""
+    store = get_sovereignty_store()
+    summary = store.get_summary()
+    alerts = store.get_alerts(unacknowledged_only=True)
+    return {
+        "metrics": summary,
+        "alerts": alerts,
+        "targets": GRADUATION_TARGETS,
+        "cost_threshold": settings.sovereignty_api_cost_alert_threshold,
+    }
+
+
+@router.get("/metrics/panel", response_class=HTMLResponse)
+async def sovereignty_metrics_panel(request: Request) -> HTMLResponse:
+    """HTMX partial: sovereignty metrics progress panel."""
+    store = get_sovereignty_store()
+    summary = store.get_summary()
+    alerts = store.get_alerts(unacknowledged_only=True)
+
+    return templates.TemplateResponse(
+        request,
+        "partials/sovereignty_metrics.html",
+        {
+            "metrics": summary,
+            "alerts": alerts,
+            "targets": GRADUATION_TARGETS,
+        },
+    )
+
+
+@router.get("/alerts")
+async def sovereignty_alerts_api() -> dict[str, Any]:
+    """JSON API: sovereignty alerts."""
+    store = get_sovereignty_store()
+    return {
+        "alerts": store.get_alerts(unacknowledged_only=False),
+        "unacknowledged": store.get_alerts(unacknowledged_only=True),
+    }
+
+
+@router.post("/alerts/{alert_id}/acknowledge")
+async def acknowledge_alert(alert_id: int) -> dict[str, bool]:
+    """Acknowledge a sovereignty alert."""
+    store = get_sovereignty_store()
+    success = store.acknowledge_alert(alert_id)
+    return {"success": success}

src/dashboard/routes/system.py

@@ -1,10 +1,12 @@
 """System-level dashboard routes (ledger, upgrades, etc.)."""
 
 import logging
+from pathlib import Path
 
 from fastapi import APIRouter, Request
 from fastapi.responses import HTMLResponse, JSONResponse
 
+from config import settings
 from dashboard.templating import templates
 
 logger = logging.getLogger(__name__)
@@ -14,52 +16,11 @@ router = APIRouter(tags=["system"])
 
 @router.get("/lightning/ledger", response_class=HTMLResponse)
 async def lightning_ledger(request: Request):
-    """Ledger and balance page."""
-    # Mock data for now, as this seems to be a UI-first feature
-    balance = {
-        "available_sats": 1337,
-        "incoming_total_sats": 2000,
-        "outgoing_total_sats": 663,
-        "fees_paid_sats": 5,
-        "net_sats": 1337,
-        "pending_incoming_sats": 0,
-        "pending_outgoing_sats": 0,
-    }
+    """Ledger and balance page backed by the in-memory Lightning ledger."""
+    from lightning.ledger import get_balance, get_transactions
 
-    # Mock transactions
-    from collections import namedtuple
-    from enum import Enum
-
-    class TxType(Enum):
-        incoming = "incoming"
-        outgoing = "outgoing"
-
-    class TxStatus(Enum):
-        completed = "completed"
-        pending = "pending"
-
-    Tx = namedtuple(
-        "Tx", ["tx_type", "status", "amount_sats", "payment_hash", "memo", "created_at"]
-    )
-
-    transactions = [
-        Tx(
-            TxType.outgoing,
-            TxStatus.completed,
-            50,
-            "hash1",
-            "Model inference",
-            "2026-03-04 10:00:00",
-        ),
-        Tx(
-            TxType.incoming,
-            TxStatus.completed,
-            1000,
-            "hash2",
-            "Manual deposit",
-            "2026-03-03 15:00:00",
-        ),
-    ]
+    balance = get_balance()
+    transactions = get_transactions()
 
     return templates.TemplateResponse(
         request,
@@ -68,7 +29,7 @@ async def lightning_ledger(request: Request):
             "balance": balance,
             "transactions": transactions,
             "tx_types": ["incoming", "outgoing"],
-            "tx_statuses": ["completed", "pending"],
+            "tx_statuses": ["pending", "settled", "failed", "expired"],
             "filter_type": None,
             "filter_status": None,
             "stats": {},
@@ -95,11 +56,13 @@ async def self_modify_queue(request: Request):
 
 @router.get("/swarm/mission-control", response_class=HTMLResponse)
 async def mission_control(request: Request):
+    """Render the swarm mission control dashboard page."""
     return templates.TemplateResponse(request, "mission_control.html", {})
 
 
 @router.get("/bugs", response_class=HTMLResponse)
 async def bugs_page(request: Request):
+    """Render the bug tracking page."""
     return templates.TemplateResponse(
         request,
         "bugs.html",
@@ -114,16 +77,19 @@ async def bugs_page(request: Request):
 
 @router.get("/self-coding", response_class=HTMLResponse)
 async def self_coding(request: Request):
+    """Render the self-coding automation status page."""
     return templates.TemplateResponse(request, "self_coding.html", {"stats": {}})
 
 
 @router.get("/hands", response_class=HTMLResponse)
 async def hands_page(request: Request):
+    """Render the hands (automation executions) page."""
     return templates.TemplateResponse(request, "hands.html", {"executions": []})
 
 
 @router.get("/creative/ui", response_class=HTMLResponse)
 async def creative_ui(request: Request):
+    """Render the creative UI playground page."""
     return templates.TemplateResponse(request, "creative.html", {})
 
 
@@ -144,5 +110,83 @@ async def api_notifications():
                 for e in events
             ]
         )
-    except Exception:
+    except Exception as exc:
+        logger.debug("System events fetch error: %s", exc)
         return JSONResponse([])
+
+
+@router.get("/api/briefing/status", response_class=JSONResponse)
+async def api_briefing_status():
+    """Return briefing status including pending approvals and last generated time."""
+    from timmy import approvals
+    from timmy.briefing import engine as briefing_engine
+
+    pending = approvals.list_pending()
+    pending_count = len(pending)
+
+    last_generated = None
+    try:
+        cached = briefing_engine.get_cached()
+        if cached:
+            last_generated = cached.generated_at.isoformat()
+    except Exception:
+        logger.debug("Failed to read briefing cache")
+
+    return JSONResponse(
+        {
+            "status": "ok",
+            "pending_approvals": pending_count,
+            "last_generated": last_generated,
+        }
+    )
+
+
+@router.get("/api/memory/status", response_class=JSONResponse)
+async def api_memory_status():
+    """Return memory database status including file info and indexed files count."""
+    from timmy.memory_system import get_memory_stats
+
+    db_path = Path(settings.repo_root) / "data" / "memory.db"
+    db_exists = db_path.exists()
+    db_size = db_path.stat().st_size if db_exists else 0
+
+    try:
+        stats = get_memory_stats()
+        indexed_files = stats.get("total_entries", 0)
+    except Exception:
+        logger.debug("Failed to get memory stats")
+        indexed_files = 0
+
+    return JSONResponse(
+        {
+            "status": "ok",
+            "db_exists": db_exists,
+            "db_size_bytes": db_size,
+            "indexed_files": indexed_files,
+        }
+    )
+
+
+@router.get("/api/swarm/status", response_class=JSONResponse)
+async def api_swarm_status():
+    """Return swarm worker status and pending tasks count."""
+    from dashboard.routes.tasks import _get_db
+
+    pending_tasks = 0
+    try:
+        with _get_db() as db:
+            row = db.execute(
+                "SELECT COUNT(*) as cnt FROM tasks WHERE status IN ('pending_approval','approved')"
+            ).fetchone()
+            pending_tasks = row["cnt"] if row else 0
+    except Exception:
+        logger.debug("Failed to count pending tasks")
+
+    return JSONResponse(
+        {
+            "status": "ok",
+            "active_workers": 0,
+            "pending_tasks": pending_tasks,
+            "message": "Swarm monitoring endpoint",
+        }
+    )

src/dashboard/routes/tasks.py

@@ -3,7 +3,9 @@
 import logging
 import sqlite3
 import uuid
-from datetime import datetime
+from collections.abc import Generator
+from contextlib import closing, contextmanager
+from datetime import UTC, datetime
 from pathlib import Path
 
 from fastapi import APIRouter, Form, HTTPException, Request
@@ -35,26 +37,27 @@ VALID_STATUSES = {
 VALID_PRIORITIES = {"low", "normal", "high", "urgent"}
 
 
-def _get_db() -> sqlite3.Connection:
+@contextmanager
+def _get_db() -> Generator[sqlite3.Connection, None, None]:
     DB_PATH.parent.mkdir(parents=True, exist_ok=True)
-    conn = sqlite3.connect(str(DB_PATH))
-    conn.row_factory = sqlite3.Row
-    conn.execute("""
-        CREATE TABLE IF NOT EXISTS tasks (
-            id TEXT PRIMARY KEY,
-            title TEXT NOT NULL,
-            description TEXT DEFAULT '',
-            status TEXT DEFAULT 'pending_approval',
-            priority TEXT DEFAULT 'normal',
-            assigned_to TEXT DEFAULT '',
-            created_by TEXT DEFAULT 'operator',
-            result TEXT DEFAULT '',
-            created_at TEXT DEFAULT (datetime('now')),
-            completed_at TEXT
-        )
-    """)
-    conn.commit()
-    return conn
+    with closing(sqlite3.connect(str(DB_PATH))) as conn:
+        conn.row_factory = sqlite3.Row
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS tasks (
+                id TEXT PRIMARY KEY,
+                title TEXT NOT NULL,
+                description TEXT DEFAULT '',
+                status TEXT DEFAULT 'pending_approval',
+                priority TEXT DEFAULT 'normal',
+                assigned_to TEXT DEFAULT '',
+                created_by TEXT DEFAULT 'operator',
+                result TEXT DEFAULT '',
+                created_at TEXT DEFAULT (datetime('now')),
+                completed_at TEXT
+            )
+        """)
+        conn.commit()
+        yield conn
 
 
 def _row_to_dict(row: sqlite3.Row) -> dict:
@@ -101,8 +104,7 @@ class _TaskView:
 @router.get("/tasks", response_class=HTMLResponse)
 async def tasks_page(request: Request):
     """Render the main task queue page with 3-column layout."""
-    db = _get_db()
-    try:
+    with _get_db() as db:
         pending = [
             _TaskView(_row_to_dict(r))
             for r in db.execute(
@@ -121,8 +123,6 @@ async def tasks_page(request: Request):
                 "SELECT * FROM tasks WHERE status IN ('completed','vetoed','failed') ORDER BY completed_at DESC LIMIT 50"
             ).fetchall()
         ]
-    finally:
-        db.close()
 
     return templates.TemplateResponse(
         request,
@@ -143,70 +143,49 @@ async def tasks_page(request: Request):
 # ---------------------------------------------------------------------------
 
 
+def _render_task_list(request: Request, query: str, empty_msg: str) -> HTMLResponse:
+    """Fetch tasks by query and render as HTMX task-card partials."""
+    with _get_db() as db:
+        rows = db.execute(query).fetchall()
+    parts = [
+        templates.TemplateResponse(
+            request, "partials/task_card.html", {"task": _TaskView(_row_to_dict(r))}
+        ).body.decode()
+        for r in rows
+    ]
+    if not parts:
+        return HTMLResponse(f'<div class="empty-column">{empty_msg}</div>')
+    return HTMLResponse("".join(parts))
+
+
 @router.get("/tasks/pending", response_class=HTMLResponse)
 async def tasks_pending(request: Request):
-    db = _get_db()
-    try:
-        rows = db.execute(
-            "SELECT * FROM tasks WHERE status='pending_approval' ORDER BY created_at DESC"
-        ).fetchall()
-    finally:
-        db.close()
-    tasks = [_TaskView(_row_to_dict(r)) for r in rows]
-    parts = []
-    for task in tasks:
-        parts.append(
-            templates.TemplateResponse(
-                request, "partials/task_card.html", {"task": task}
-            ).body.decode()
-        )
-    if not parts:
-        return HTMLResponse('<div class="empty-column">No pending tasks</div>')
-    return HTMLResponse("".join(parts))
+    """Return HTMX partial for pending approval tasks."""
+    return _render_task_list(
+        request,
+        "SELECT * FROM tasks WHERE status='pending_approval' ORDER BY created_at DESC",
+        "No pending tasks",
+    )
 
 
 @router.get("/tasks/active", response_class=HTMLResponse)
 async def tasks_active(request: Request):
-    db = _get_db()
-    try:
-        rows = db.execute(
-            "SELECT * FROM tasks WHERE status IN ('approved','running','paused') ORDER BY created_at DESC"
-        ).fetchall()
-    finally:
-        db.close()
-    tasks = [_TaskView(_row_to_dict(r)) for r in rows]
-    parts = []
-    for task in tasks:
-        parts.append(
-            templates.TemplateResponse(
-                request, "partials/task_card.html", {"task": task}
-            ).body.decode()
-        )
-    if not parts:
-        return HTMLResponse('<div class="empty-column">No active tasks</div>')
-    return HTMLResponse("".join(parts))
+    """Return HTMX partial for active (approved/running/paused) tasks."""
+    return _render_task_list(
+        request,
+        "SELECT * FROM tasks WHERE status IN ('approved','running','paused') ORDER BY created_at DESC",
+        "No active tasks",
+    )
 
 
 @router.get("/tasks/completed", response_class=HTMLResponse)
 async def tasks_completed(request: Request):
-    db = _get_db()
-    try:
-        rows = db.execute(
-            "SELECT * FROM tasks WHERE status IN ('completed','vetoed','failed') ORDER BY completed_at DESC LIMIT 50"
-        ).fetchall()
-    finally:
-        db.close()
-    tasks = [_TaskView(_row_to_dict(r)) for r in rows]
-    parts = []
-    for task in tasks:
-        parts.append(
-            templates.TemplateResponse(
-                request, "partials/task_card.html", {"task": task}
-            ).body.decode()
-        )
-    if not parts:
-        return HTMLResponse('<div class="empty-column">No completed tasks yet</div>')
-    return HTMLResponse("".join(parts))
+    """Return HTMX partial for completed/vetoed/failed tasks (last 50)."""
+    return _render_task_list(
+        request,
+        "SELECT * FROM tasks WHERE status IN ('completed','vetoed','failed') ORDER BY completed_at DESC LIMIT 50",
+        "No completed tasks yet",
+    )
 
 
 # ---------------------------------------------------------------------------
@@ -228,19 +207,16 @@ async def create_task_form(
         raise HTTPException(status_code=400, detail="Task title cannot be empty")
 
     task_id = str(uuid.uuid4())
-    now = datetime.utcnow().isoformat()
+    now = datetime.now(UTC).isoformat()
     priority = priority if priority in VALID_PRIORITIES else "normal"
 
-    db = _get_db()
-    try:
+    with _get_db() as db:
         db.execute(
             "INSERT INTO tasks (id, title, description, priority, assigned_to, created_at) VALUES (?, ?, ?, ?, ?, ?)",
             (task_id, title, description, priority, assigned_to, now),
         )
         db.commit()
         row = db.execute("SELECT * FROM tasks WHERE id=?", (task_id,)).fetchone()
-    finally:
-        db.close()
 
     task = _TaskView(_row_to_dict(row))
     return templates.TemplateResponse(request, "partials/task_card.html", {"task": task})
@@ -253,26 +229,31 @@ async def create_task_form(
 
 @router.post("/tasks/{task_id}/approve", response_class=HTMLResponse)
 async def approve_task(request: Request, task_id: str):
+    """Approve a pending task and move it to active queue."""
     return await _set_status(request, task_id, "approved")
 
 
 @router.post("/tasks/{task_id}/veto", response_class=HTMLResponse)
 async def veto_task(request: Request, task_id: str):
+    """Veto a task, marking it as rejected."""
     return await _set_status(request, task_id, "vetoed")
 
 
 @router.post("/tasks/{task_id}/pause", response_class=HTMLResponse)
 async def pause_task(request: Request, task_id: str):
+    """Pause a running or approved task."""
     return await _set_status(request, task_id, "paused")
 
 
 @router.post("/tasks/{task_id}/cancel", response_class=HTMLResponse)
 async def cancel_task(request: Request, task_id: str):
+    """Cancel a task (marks as vetoed)."""
     return await _set_status(request, task_id, "vetoed")
 
 
 @router.post("/tasks/{task_id}/retry", response_class=HTMLResponse)
 async def retry_task(request: Request, task_id: str):
+    """Retry a failed/vetoed task by moving it back to approved."""
     return await _set_status(request, task_id, "approved")
 
 
@@ -283,16 +264,14 @@ async def modify_task(
     title: str = Form(...),
     description: str = Form(""),
 ):
-    db = _get_db()
-    try:
+    """Update task title and description."""
+    with _get_db() as db:
         db.execute(
             "UPDATE tasks SET title=?, description=? WHERE id=?",
             (title, description, task_id),
         )
         db.commit()
         row = db.execute("SELECT * FROM tasks WHERE id=?", (task_id,)).fetchone()
-    finally:
-        db.close()
     if not row:
         raise HTTPException(404, "Task not found")
     task = _TaskView(_row_to_dict(row))
@@ -302,18 +281,15 @@ async def modify_task(
 async def _set_status(request: Request, task_id: str, new_status: str):
     """Helper to update status and return refreshed task card."""
     completed_at = (
-        datetime.utcnow().isoformat() if new_status in ("completed", "vetoed", "failed") else None
+        datetime.now(UTC).isoformat() if new_status in ("completed", "vetoed", "failed") else None
     )
-    db = _get_db()
-    try:
+    with _get_db() as db:
         db.execute(
             "UPDATE tasks SET status=?, completed_at=COALESCE(?, completed_at) WHERE id=?",
             (new_status, completed_at, task_id),
         )
         db.commit()
         row = db.execute("SELECT * FROM tasks WHERE id=?", (task_id,)).fetchone()
-    finally:
-        db.close()
     if not row:
         raise HTTPException(404, "Task not found")
     task = _TaskView(_row_to_dict(row))
@@ -334,13 +310,12 @@ async def api_create_task(request: Request):
         raise HTTPException(422, "title is required")
 
     task_id = str(uuid.uuid4())
-    now = datetime.utcnow().isoformat()
+    now = datetime.now(UTC).isoformat()
     priority = body.get("priority", "normal")
     if priority not in VALID_PRIORITIES:
         priority = "normal"
 
-    db = _get_db()
-    try:
+    with _get_db() as db:
         db.execute(
             "INSERT INTO tasks (id, title, description, priority, assigned_to, created_by, created_at) "
             "VALUES (?, ?, ?, ?, ?, ?, ?)",
@@ -356,8 +331,6 @@ async def api_create_task(request: Request):
         )
         db.commit()
         row = db.execute("SELECT * FROM tasks WHERE id=?", (task_id,)).fetchone()
-    finally:
-        db.close()
 
     return JSONResponse(_row_to_dict(row), status_code=201)
 
@@ -365,11 +338,8 @@ async def api_create_task(request: Request):
 @router.get("/api/tasks", response_class=JSONResponse)
 async def api_list_tasks():
     """List all tasks as JSON."""
-    db = _get_db()
-    try:
+    with _get_db() as db:
         rows = db.execute("SELECT * FROM tasks ORDER BY created_at DESC").fetchall()
-    finally:
-        db.close()
     return JSONResponse([_row_to_dict(r) for r in rows])
 
 
@@ -382,18 +352,15 @@ async def api_update_status(task_id: str, request: Request):
         raise HTTPException(422, f"Invalid status. Must be one of: {VALID_STATUSES}")
 
     completed_at = (
-        datetime.utcnow().isoformat() if new_status in ("completed", "vetoed", "failed") else None
+        datetime.now(UTC).isoformat() if new_status in ("completed", "vetoed", "failed") else None
     )
-    db = _get_db()
-    try:
+    with _get_db() as db:
         db.execute(
             "UPDATE tasks SET status=?, completed_at=COALESCE(?, completed_at) WHERE id=?",
             (new_status, completed_at, task_id),
         )
         db.commit()
         row = db.execute("SELECT * FROM tasks WHERE id=?", (task_id,)).fetchone()
-    finally:
-        db.close()
     if not row:
         raise HTTPException(404, "Task not found")
     return JSONResponse(_row_to_dict(row))
@@ -402,12 +369,9 @@ async def api_update_status(task_id: str, request: Request):
 @router.delete("/api/tasks/{task_id}", response_class=JSONResponse)
 async def api_delete_task(task_id: str):
     """Delete a task."""
-    db = _get_db()
-    try:
+    with _get_db() as db:
         cursor = db.execute("DELETE FROM tasks WHERE id=?", (task_id,))
         db.commit()
-    finally:
-        db.close()
     if cursor.rowcount == 0:
         raise HTTPException(404, "Task not found")
     return JSONResponse({"success": True, "id": task_id})
@@ -421,8 +385,7 @@ async def api_delete_task(task_id: str):
 @router.get("/api/queue/status", response_class=JSONResponse)
 async def queue_status(assigned_to: str = "default"):
     """Return queue status for the chat panel's agent status indicator."""
-    db = _get_db()
-    try:
+    with _get_db() as db:
         running = db.execute(
             "SELECT * FROM tasks WHERE status='running' AND assigned_to=? LIMIT 1",
             (assigned_to,),
@@ -431,8 +394,6 @@ async def queue_status(assigned_to: str = "default"):
             "SELECT COUNT(*) as cnt FROM tasks WHERE status IN ('pending_approval','approved') AND assigned_to=?",
             (assigned_to,),
         ).fetchone()
-    finally:
-        db.close()
 
     if running:
         return JSONResponse(

src/dashboard/routes/tower.py

@@ -0,0 +1,108 @@
+"""Tower dashboard — real-time Spark visualization via WebSocket.
+
+GET  /tower     — HTML Tower dashboard (Thinking / Predicting / Advising)
+WS   /tower/ws  — WebSocket stream of Spark engine state updates
+"""
+
+import asyncio
+import json
+import logging
+
+from fastapi import APIRouter, Request, WebSocket
+from fastapi.responses import HTMLResponse
+
+from dashboard.templating import templates
+from spark.engine import spark_engine
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/tower", tags=["tower"])
+
+_PUSH_INTERVAL = 5  # seconds between state broadcasts
+
+
+def _spark_snapshot() -> dict:
+    """Build a JSON-serialisable snapshot of Spark state."""
+    status = spark_engine.status()
+
+    timeline = spark_engine.get_timeline(limit=10)
+    events = []
+    for ev in timeline:
+        entry = {
+            "event_type": ev.event_type,
+            "description": ev.description,
+            "importance": ev.importance,
+            "created_at": ev.created_at,
+        }
+        if ev.agent_id:
+            entry["agent_id"] = ev.agent_id[:8]
+        if ev.task_id:
+            entry["task_id"] = ev.task_id[:8]
+        try:
+            entry["data"] = json.loads(ev.data)
+        except (json.JSONDecodeError, TypeError):
+            entry["data"] = {}
+        events.append(entry)
+
+    predictions = spark_engine.get_predictions(limit=5)
+    preds = []
+    for p in predictions:
+        pred = {
+            "task_id": p.task_id[:8] if p.task_id else "?",
+            "accuracy": p.accuracy,
+            "evaluated": p.evaluated_at is not None,
+            "created_at": p.created_at,
+        }
+        try:
+            pred["predicted"] = json.loads(p.predicted_value)
+        except (json.JSONDecodeError, TypeError):
+            pred["predicted"] = {}
+        preds.append(pred)
+
+    advisories = spark_engine.get_advisories()
+    advs = [
+        {
+            "category": a.category,
+            "priority": a.priority,
+            "title": a.title,
+            "detail": a.detail,
+            "suggested_action": a.suggested_action,
+        }
+        for a in advisories
+    ]
+
+    return {
+        "type": "spark_state",
+        "status": status,
+        "events": events,
+        "predictions": preds,
+        "advisories": advs,
+    }
+
+
+@router.get("", response_class=HTMLResponse)
+async def tower_ui(request: Request):
+    """Render the Tower dashboard page."""
+    snapshot = _spark_snapshot()
+    return templates.TemplateResponse(
+        request,
+        "tower.html",
+        {"snapshot": snapshot},
+    )
+
+
+@router.websocket("/ws")
+async def tower_ws(websocket: WebSocket) -> None:
+    """Stream Spark state snapshots to the Tower dashboard."""
+    await websocket.accept()
+    logger.info("Tower WS connected")
+
+    try:
+        # Send initial snapshot
+        await websocket.send_text(json.dumps(_spark_snapshot()))
+
+        while True:
+            await asyncio.sleep(_PUSH_INTERVAL)
+            await websocket.send_text(json.dumps(_spark_snapshot()))
+    except Exception:
+        logger.debug("Tower WS disconnected")

src/dashboard/routes/voice.py

@@ -43,7 +43,8 @@ async def tts_status():
             "available": voice_tts.available,
             "voices": voice_tts.get_voices() if voice_tts.available else [],
         }
-    except Exception:
+    except Exception as exc:
+        logger.debug("Voice config error: %s", exc)
         return {"available": False, "voices": []}
 
 
@@ -58,6 +59,7 @@ async def tts_speak(text: str = Form(...)):
         voice_tts.speak(text)
         return {"spoken": True, "text": text}
     except Exception as exc:
+        logger.exception("TTS speak failed")
         return {"spoken": False, "reason": str(exc)}
 
 
@@ -139,7 +141,8 @@ async def process_voice_input(
 
             if voice_tts.available:
                 voice_tts.speak(response_text)
-        except Exception:
+        except Exception as exc:
+            logger.debug("Voice TTS error: %s", exc)
             pass
 
     return {

src/dashboard/routes/work_orders.py

@@ -3,7 +3,9 @@
 import logging
 import sqlite3
 import uuid
-from datetime import datetime
+from collections.abc import Generator
+from contextlib import closing, contextmanager
+from datetime import UTC, datetime
 from pathlib import Path
 
 from fastapi import APIRouter, Form, HTTPException, Request
@@ -23,28 +25,29 @@ CATEGORIES = ["bug", "feature", "suggestion", "maintenance", "security"]
 VALID_STATUSES = {"submitted", "triaged", "approved", "in_progress", "completed", "rejected"}
 
 
-def _get_db() -> sqlite3.Connection:
+@contextmanager
+def _get_db() -> Generator[sqlite3.Connection, None, None]:
     DB_PATH.parent.mkdir(parents=True, exist_ok=True)
-    conn = sqlite3.connect(str(DB_PATH))
-    conn.row_factory = sqlite3.Row
-    conn.execute("""
-        CREATE TABLE IF NOT EXISTS work_orders (
-            id TEXT PRIMARY KEY,
-            title TEXT NOT NULL,
-            description TEXT DEFAULT '',
-            priority TEXT DEFAULT 'medium',
-            category TEXT DEFAULT 'suggestion',
-            submitter TEXT DEFAULT 'dashboard',
-            related_files TEXT DEFAULT '',
-            status TEXT DEFAULT 'submitted',
-            result TEXT DEFAULT '',
-            rejection_reason TEXT DEFAULT '',
-            created_at TEXT DEFAULT (datetime('now')),
-            completed_at TEXT
-        )
-    """)
-    conn.commit()
-    return conn
+    with closing(sqlite3.connect(str(DB_PATH))) as conn:
+        conn.row_factory = sqlite3.Row
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS work_orders (
+                id TEXT PRIMARY KEY,
+                title TEXT NOT NULL,
+                description TEXT DEFAULT '',
+                priority TEXT DEFAULT 'medium',
+                category TEXT DEFAULT 'suggestion',
+                submitter TEXT DEFAULT 'dashboard',
+                related_files TEXT DEFAULT '',
+                status TEXT DEFAULT 'submitted',
+                result TEXT DEFAULT '',
+                rejection_reason TEXT DEFAULT '',
+                created_at TEXT DEFAULT (datetime('now')),
+                completed_at TEXT
+            )
+        """)
+        conn.commit()
+        yield conn
 
 
 class _EnumLike:
@@ -104,14 +107,11 @@ def _query_wos(db, statuses):
 
 @router.get("/work-orders/queue", response_class=HTMLResponse)
 async def work_orders_page(request: Request):
-    db = _get_db()
-    try:
+    with _get_db() as db:
         pending = _query_wos(db, ["submitted", "triaged"])
         active = _query_wos(db, ["approved", "in_progress"])
         completed = _query_wos(db, ["completed"])
         rejected = _query_wos(db, ["rejected"])
-    finally:
-        db.close()
 
     return templates.TemplateResponse(
         request,
@@ -144,12 +144,11 @@ async def submit_work_order(
     related_files: str = Form(""),
 ):
     wo_id = str(uuid.uuid4())
-    now = datetime.utcnow().isoformat()
+    now = datetime.now(UTC).isoformat()
     priority = priority if priority in PRIORITIES else "medium"
     category = category if category in CATEGORIES else "suggestion"
 
-    db = _get_db()
-    try:
+    with _get_db() as db:
         db.execute(
             "INSERT INTO work_orders (id, title, description, priority, category, submitter, related_files, created_at) "
             "VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
@@ -157,8 +156,6 @@ async def submit_work_order(
         )
         db.commit()
         row = db.execute("SELECT * FROM work_orders WHERE id=?", (wo_id,)).fetchone()
-    finally:
-        db.close()
 
     wo = _WOView(_row_to_dict(row))
     return templates.TemplateResponse(request, "partials/work_order_card.html", {"wo": wo})
@@ -171,11 +168,8 @@ async def submit_work_order(
 
 @router.get("/work-orders/queue/pending", response_class=HTMLResponse)
 async def pending_partial(request: Request):
-    db = _get_db()
-    try:
+    with _get_db() as db:
         wos = _query_wos(db, ["submitted", "triaged"])
-    finally:
-        db.close()
     if not wos:
         return HTMLResponse(
             '<div style="color: var(--text-muted); font-size: 0.8rem; padding: 12px 0;">'
@@ -193,11 +187,8 @@ async def pending_partial(request: Request):
 
 @router.get("/work-orders/queue/active", response_class=HTMLResponse)
 async def active_partial(request: Request):
-    db = _get_db()
-    try:
+    with _get_db() as db:
         wos = _query_wos(db, ["approved", "in_progress"])
-    finally:
-        db.close()
     if not wos:
         return HTMLResponse(
             '<div style="color: var(--text-muted); font-size: 0.8rem; padding: 12px 0;">'
@@ -220,10 +211,9 @@ async def active_partial(request: Request):
 
 async def _update_status(request: Request, wo_id: str, new_status: str, **extra):
     completed_at = (
-        datetime.utcnow().isoformat() if new_status in ("completed", "rejected") else None
+        datetime.now(UTC).isoformat() if new_status in ("completed", "rejected") else None
     )
-    db = _get_db()
-    try:
+    with _get_db() as db:
         sets = ["status=?", "completed_at=COALESCE(?, completed_at)"]
         vals = [new_status, completed_at]
         for col, val in extra.items():
@@ -233,8 +223,6 @@ async def _update_status(request: Request, wo_id: str, new_status: str, **extra)
         db.execute(f"UPDATE work_orders SET {', '.join(sets)} WHERE id=?", vals)
         db.commit()
         row = db.execute("SELECT * FROM work_orders WHERE id=?", (wo_id,)).fetchone()
-    finally:
-        db.close()
     if not row:
         raise HTTPException(404, "Work order not found")
     wo = _WOView(_row_to_dict(row))

src/dashboard/services/__init__.py

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