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

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

.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
 

.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.
 
 ---
 

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/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
@@ -53,19 +54,6 @@ providers:
         context_window: 2048
         capabilities: [text, vision, streaming]
     
-  # Secondary: Local AirLLM (if installed)
-  - name: airllm-local
-    type: airllm
-    enabled: false  # Enable if pip install airllm
-    priority: 2
-    models:
-      - name: 70b
-        default: true
-        capabilities: [text, tools, json, streaming]
-      - name: 8b
-        capabilities: [text, tools, json, streaming]
-      - name: 405b
-        capabilities: [text, tools, json, streaming]
     
   # Tertiary: OpenAI (if API key available)
   - name: openai-backup
@@ -113,13 +101,12 @@ 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
     - 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

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/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/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

@@ -20,6 +20,7 @@ packages = [
     { include = "spark", from = "src" },
     { include = "timmy", from = "src" },
     { include = "timmy_serve", from = "src" },
+    { include = "timmyctl", from = "src" },
 ]
 
 [tool.poetry.dependencies]
@@ -43,9 +44,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 +64,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"]
 dev = ["pytest", "pytest-asyncio", "pytest-cov", "pytest-timeout", "pytest-randomly", "pytest-xdist", "selenium"]
 
 [tool.poetry.group.dev.dependencies]
@@ -79,6 +85,7 @@ mypy = ">=1.0.0"
 [tool.poetry.scripts]
 timmy = "timmy.cli:main"
 timmy-serve = "timmy_serve.cli:main"
+timmyctl = "timmyctl.cli:main"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

scripts/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/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/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/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,27 +74,25 @@ 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).
@@ -112,7 +146,24 @@ class Settings(BaseSettings):
 
     # 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,24 +263,31 @@ 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
 
@@ -276,6 +334,13 @@ class Settings(BaseSettings):
     autoresearch_max_iterations: int = 100
     autoresearch_metric: str = "val_bpb"  # metric to optimise (lower = better)
 
+    # ── Weekly Narrative Summary ───────────────────────────────────────
+    # Generates a human-readable weekly summary of development activity.
+    # Disabling this will stop the weekly narrative generation.
+    weekly_narrative_enabled: bool = True
+    weekly_narrative_lookback_days: int = 7
+    weekly_narrative_output_dir: str = ".loop"
+
     # ── Local Hands (Shell + Git) ──────────────────────────────────────
     # Enable local shell/git execution hands.
     hands_shell_enabled: bool = True
@@ -324,14 +389,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 +416,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 +427,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 +440,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 +504,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,20 @@ from dashboard.routes.memory import router as memory_router
 from dashboard.routes.mobile import router as mobile_router
 from dashboard.routes.models import api_router as models_api_router
 from dashboard.routes.models import router as models_router
+from dashboard.routes.quests import router as quests_router
+from dashboard.routes.scorecards import router as scorecards_router
 from dashboard.routes.spark import router as spark_router
 from dashboard.routes.system import router as system_router
 from dashboard.routes.tasks import router as tasks_router
 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 +162,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 +192,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 +204,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 +218,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 +356,118 @@ 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)."""
+    return [
+        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()),
+    ]
+
+
+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 +475,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 +525,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 +587,7 @@ app.add_middleware(
 app.add_middleware(
     CORSMiddleware,
     allow_origins=_get_cors_origins(),
+    allow_origin_regex=r"https?://100\.\d{1,3}\.\d{1,3}\.\d{1,3}(:\d+)?",
     allow_credentials=True,
     allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"],
     allow_headers=["Content-Type", "Authorization"],
@@ -474,6 +616,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 +625,12 @@ 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.websocket("/ws")
@@ -500,6 +649,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),
@@ -128,13 +128,14 @@ def _run_grok_query(message: str) -> dict:
             sats = min(settings.grok_max_sats_per_query, 100)
             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/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,
@@ -145,13 +145,11 @@ async def tasks_page(request: Request):
 
 @router.get("/tasks/pending", response_class=HTMLResponse)
 async def tasks_pending(request: Request):
-    db = _get_db()
-    try:
+    """Return HTMX partial for pending approval tasks."""
+    with _get_db() as db:
         rows = db.execute(
             "SELECT * FROM tasks WHERE status='pending_approval' ORDER BY created_at DESC"
         ).fetchall()
-    finally:
-        db.close()
     tasks = [_TaskView(_row_to_dict(r)) for r in rows]
     parts = []
     for task in tasks:
@@ -167,13 +165,11 @@ async def tasks_pending(request: Request):
 
 @router.get("/tasks/active", response_class=HTMLResponse)
 async def tasks_active(request: Request):
-    db = _get_db()
-    try:
+    """Return HTMX partial for active (approved/running/paused) tasks."""
+    with _get_db() as db:
         rows = db.execute(
             "SELECT * FROM tasks WHERE status IN ('approved','running','paused') ORDER BY created_at DESC"
         ).fetchall()
-    finally:
-        db.close()
     tasks = [_TaskView(_row_to_dict(r)) for r in rows]
     parts = []
     for task in tasks:
@@ -189,13 +185,11 @@ async def tasks_active(request: Request):
 
 @router.get("/tasks/completed", response_class=HTMLResponse)
 async def tasks_completed(request: Request):
-    db = _get_db()
-    try:
+    """Return HTMX partial for completed/vetoed/failed tasks (last 50)."""
+    with _get_db() as db:
         rows = db.execute(
             "SELECT * FROM tasks WHERE status IN ('completed','vetoed','failed') ORDER BY completed_at DESC LIMIT 50"
         ).fetchall()
-    finally:
-        db.close()
     tasks = [_TaskView(_row_to_dict(r)) for r in rows]
     parts = []
     for task in tasks:
@@ -228,19 +222,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 +244,31 @@ async def create_task_form(
 
 @router.post("/tasks/{task_id}/approve", response_class=HTMLResponse)
 async def approve_task(request: Request, task_id: str):
+    """Approve a pending task and move it to active queue."""
     return await _set_status(request, task_id, "approved")
 
 
 @router.post("/tasks/{task_id}/veto", response_class=HTMLResponse)
 async def veto_task(request: Request, task_id: str):
+    """Veto a task, marking it as rejected."""
     return await _set_status(request, task_id, "vetoed")
 
 
 @router.post("/tasks/{task_id}/pause", response_class=HTMLResponse)
 async def pause_task(request: Request, task_id: str):
+    """Pause a running or approved task."""
     return await _set_status(request, task_id, "paused")
 
 
 @router.post("/tasks/{task_id}/cancel", response_class=HTMLResponse)
 async def cancel_task(request: Request, task_id: str):
+    """Cancel a task (marks as vetoed)."""
     return await _set_status(request, task_id, "vetoed")
 
 
 @router.post("/tasks/{task_id}/retry", response_class=HTMLResponse)
 async def retry_task(request: Request, task_id: str):
+    """Retry a failed/vetoed task by moving it back to approved."""
     return await _set_status(request, task_id, "approved")
 
 
@@ -283,16 +279,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 +296,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 +325,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 +346,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 +353,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 +367,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 +384,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 +400,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 +409,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",
+]

src/dashboard/services/scorecard_service.py

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

src/dashboard/store.py

@@ -1,34 +1,5 @@
-from dataclasses import dataclass
+"""Backward-compatible re-export — canonical home is infrastructure.chat_store."""
 
+from infrastructure.chat_store import DB_PATH, MAX_MESSAGES, Message, MessageLog, message_log
 
-@dataclass
-class Message:
-    role: str  # "user" | "agent" | "error"
-    content: str
-    timestamp: str
-    source: str = "browser"  # "browser" | "api" | "telegram" | "discord" | "system"
-
-
-class MessageLog:
-    """In-memory chat history for the lifetime of the server process."""
-
-    def __init__(self) -> None:
-        self._entries: list[Message] = []
-
-    def append(self, role: str, content: str, timestamp: str, source: str = "browser") -> None:
-        self._entries.append(
-            Message(role=role, content=content, timestamp=timestamp, source=source)
-        )
-
-    def all(self) -> list[Message]:
-        return list(self._entries)
-
-    def clear(self) -> None:
-        self._entries.clear()
-
-    def __len__(self) -> int:
-        return len(self._entries)
-
-
-# Module-level singleton shared across the app
-message_log = MessageLog()
+__all__ = ["DB_PATH", "MAX_MESSAGES", "Message", "MessageLog", "message_log"]

src/dashboard/templates/base.html

@@ -51,6 +51,7 @@
           <a href="/thinking" class="mc-test-link mc-link-thinking">THINKING</a>
           <a href="/swarm/mission-control" class="mc-test-link">MISSION CTRL</a>
           <a href="/swarm/live" class="mc-test-link">SWARM</a>
+          <a href="/scorecards" class="mc-test-link">SCORECARDS</a>
           <a href="/bugs" class="mc-test-link mc-link-bugs">BUGS</a>
         </div>
       </div>
@@ -123,6 +124,7 @@
     <a href="/thinking" class="mc-mobile-link">THINKING</a>
     <a href="/swarm/mission-control" class="mc-mobile-link">MISSION CONTROL</a>
     <a href="/swarm/live" class="mc-mobile-link">SWARM</a>
+    <a href="/scorecards" class="mc-mobile-link">SCORECARDS</a>
     <a href="/bugs" class="mc-mobile-link">BUGS</a>
     <div class="mc-mobile-section-label">INTELLIGENCE</div>
     <a href="/spark/ui" class="mc-mobile-link">SPARK</a>
@@ -327,7 +329,11 @@
         .then(function(data) {
           var list = document.getElementById('notif-list');
           if (!data.length) {
-            list.innerHTML = '<div class="mc-notif-empty">No recent notifications</div>';
+            list.innerHTML = '';
+            var emptyDiv = document.createElement('div');
+            emptyDiv.className = 'mc-notif-empty';
+            emptyDiv.textContent = 'No recent notifications';
+            list.appendChild(emptyDiv);
             return;
           }
           list.innerHTML = '';

src/dashboard/templates/index.html

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

src/dashboard/templates/mission_control.html

@@ -138,6 +138,47 @@
     </div>
 </div>
 
+<!-- Spark Intelligence -->
+{% from "macros.html" import panel %}
+<div class="mc-card-spaced">
+  <div class="card">
+    <div class="card-header">
+      <h2 class="card-title">Spark Intelligence</h2>
+      <div>
+        <span class="badge" id="spark-status-badge">Loading...</span>
+      </div>
+    </div>
+    <div class="grid grid-3">
+      <div class="stat">
+        <div class="stat-value" id="spark-events">-</div>
+        <div class="stat-label">Events</div>
+      </div>
+      <div class="stat">
+        <div class="stat-value" id="spark-memories">-</div>
+        <div class="stat-label">Memories</div>
+      </div>
+      <div class="stat">
+        <div class="stat-value" id="spark-predictions">-</div>
+        <div class="stat-label">Predictions</div>
+      </div>
+    </div>
+  </div>
+  <div class="grid grid-2 mc-section-gap">
+    {% call panel("SPARK TIMELINE", id="spark-timeline-panel",
+                  hx_get="/spark/timeline",
+                  hx_trigger="load, every 10s") %}
+      <div class="spark-timeline-scroll">
+        <p class="chat-history-placeholder">Loading timeline...</p>
+      </div>
+    {% endcall %}
+    {% call panel("SPARK INSIGHTS", id="spark-insights-panel",
+                  hx_get="/spark/insights",
+                  hx_trigger="load, every 30s") %}
+      <p class="chat-history-placeholder">Loading insights...</p>
+    {% endcall %}
+  </div>
+</div>
+
 <!-- Chat History -->
 <div class="card mc-card-spaced">
     <div class="card-header">
@@ -428,7 +469,34 @@ async function loadGrokStats() {
     }
 }
 
+// Load Spark status
+async function loadSparkStatus() {
+    try {
+        var response = await fetch('/spark');
+        var data = await response.json();
+        var st = data.status || {};
+
+        document.getElementById('spark-events').textContent = st.total_events || 0;
+        document.getElementById('spark-memories').textContent = st.total_memories || 0;
+        document.getElementById('spark-predictions').textContent = st.total_predictions || 0;
+
+        var badge = document.getElementById('spark-status-badge');
+        if (st.total_events > 0) {
+            badge.textContent = 'Active';
+            badge.className = 'badge badge-success';
+        } else {
+            badge.textContent = 'Idle';
+            badge.className = 'badge badge-warning';
+        }
+    } catch (error) {
+        var badge = document.getElementById('spark-status-badge');
+        badge.textContent = 'Offline';
+        badge.className = 'badge badge-danger';
+    }
+}
+
 // Initial load
+loadSparkStatus();
 loadSovereignty();
 loadHealth();
 loadSwarmStats();
@@ -442,5 +510,6 @@ setInterval(loadHealth, 10000);
 setInterval(loadSwarmStats, 5000);
 setInterval(updateHeartbeat, 5000);
 setInterval(loadGrokStats, 10000);
+setInterval(loadSparkStatus, 15000);
 </script>
 {% endblock %}

src/dashboard/templates/partials/agent_panel_chat.html

@@ -120,14 +120,17 @@
 
   function updateFromData(data) {
     if (data.is_working && data.current_task) {
-      statusEl.innerHTML = '<span style="color: #ffaa00;">working...</span>';
+      statusEl.textContent = 'working...';
+      statusEl.style.color = '#ffaa00';
       banner.style.display = 'block';
       taskTitle.textContent = data.current_task.title;
     } else if (data.tasks_ahead > 0) {
-      statusEl.innerHTML = '<span style="color: #888;">queue: ' + data.tasks_ahead + ' ahead</span>';
+      statusEl.textContent = 'queue: ' + data.tasks_ahead + ' ahead';
+      statusEl.style.color = '#888';
       banner.style.display = 'none';
     } else {
-      statusEl.innerHTML = '<span style="color: #00ff88;">ready</span>';
+      statusEl.textContent = 'ready';
+      statusEl.style.color = '#00ff88';
       banner.style.display = 'none';
     }
   }

src/dashboard/templates/partials/daily_run_panel.html

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

src/dashboard/templates/partials/history.html

@@ -20,7 +20,7 @@
 {% else %}
 <div class="chat-message agent">
   <div class="msg-meta">TIMMY // SYSTEM</div>
-  <div class="msg-body">Mission Control initialized. Timmy ready — awaiting input.</div>
+  <div class="msg-body">{{ welcome_message | e }}</div>
 </div>
 {% endif %}
 <script>if(typeof scrollChat==='function'){setTimeout(scrollChat,50);}</script>

src/dashboard/templates/partials/quests_panel.html

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

src/dashboard/templates/quests.html

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

src/dashboard/templates/scorecards.html

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

src/dashboard/templates/swarm_live.html

@@ -198,17 +198,43 @@ function addActivityEvent(evt) {
         } catch(e) {}
     }
     
-    item.innerHTML = `
-        <div class="activity-icon">${icon}</div>
-        <div class="activity-content">
-            <div class="activity-label">${label}</div>
-            ${desc ? `<div class="activity-desc">${desc}</div>` : ''}
-            <div class="activity-meta">
-                <span class="activity-time">${time}</span>
-                <span class="activity-source">${evt.source || 'system'}</span>
-            </div>
-        </div>
-    `;
+    // Build DOM safely using createElement and textContent
+    var iconDiv = document.createElement('div');
+    iconDiv.className = 'activity-icon';
+    iconDiv.textContent = icon;
+    
+    var contentDiv = document.createElement('div');
+    contentDiv.className = 'activity-content';
+    
+    var labelDiv = document.createElement('div');
+    labelDiv.className = 'activity-label';
+    labelDiv.textContent = label;
+    contentDiv.appendChild(labelDiv);
+    
+    if (desc) {
+        var descDiv = document.createElement('div');
+        descDiv.className = 'activity-desc';
+        descDiv.textContent = desc;
+        contentDiv.appendChild(descDiv);
+    }
+    
+    var metaDiv = document.createElement('div');
+    metaDiv.className = 'activity-meta';
+    
+    var timeSpan = document.createElement('span');
+    timeSpan.className = 'activity-time';
+    timeSpan.textContent = time;
+    
+    var sourceSpan = document.createElement('span');
+    sourceSpan.className = 'activity-source';
+    sourceSpan.textContent = evt.source || 'system';
+    
+    metaDiv.appendChild(timeSpan);
+    metaDiv.appendChild(sourceSpan);
+    contentDiv.appendChild(metaDiv);
+    
+    item.appendChild(iconDiv);
+    item.appendChild(contentDiv);
     
     // Add to top
     container.insertBefore(item, container.firstChild);

src/dashboard/templates/tower.html

@@ -0,0 +1,180 @@
+{% extends "base.html" %}
+
+{% block title %}Timmy Time — Tower{% endblock %}
+
+{% block extra_styles %}{% endblock %}
+
+{% block content %}
+<div class="container-fluid tower-container py-3">
+
+  <div class="tower-header">
+    <div class="tower-title">TOWER</div>
+    <div class="tower-subtitle">
+      Real-time Spark visualization &mdash;
+      <span id="tower-conn" class="tower-conn-badge tower-conn-connecting">CONNECTING</span>
+    </div>
+  </div>
+
+  <div class="row g-3">
+
+    <!-- Left: THINKING (events) -->
+    <div class="col-12 col-lg-4 d-flex flex-column gap-3">
+      <div class="card mc-panel tower-phase-card">
+        <div class="card-header mc-panel-header tower-phase-thinking">// THINKING</div>
+        <div class="card-body p-3 tower-scroll" id="tower-events">
+          <div class="tower-empty">Waiting for Spark data&hellip;</div>
+        </div>
+      </div>
+    </div>
+
+    <!-- Middle: PREDICTING (EIDOS) -->
+    <div class="col-12 col-lg-4 d-flex flex-column gap-3">
+      <div class="card mc-panel tower-phase-card">
+        <div class="card-header mc-panel-header tower-phase-predicting">// PREDICTING</div>
+        <div class="card-body p-3" id="tower-predictions">
+          <div class="tower-empty">Waiting for Spark data&hellip;</div>
+        </div>
+      </div>
+      <div class="card mc-panel">
+        <div class="card-header mc-panel-header">// EIDOS STATS</div>
+        <div class="card-body p-3">
+          <div class="tower-stat-grid" id="tower-stats">
+            <div class="tower-stat"><span class="tower-stat-label">EVENTS</span><span class="tower-stat-value" id="ts-events">0</span></div>
+            <div class="tower-stat"><span class="tower-stat-label">MEMORIES</span><span class="tower-stat-value" id="ts-memories">0</span></div>
+            <div class="tower-stat"><span class="tower-stat-label">PREDICTIONS</span><span class="tower-stat-value" id="ts-preds">0</span></div>
+            <div class="tower-stat"><span class="tower-stat-label">ACCURACY</span><span class="tower-stat-value" id="ts-accuracy">—</span></div>
+          </div>
+        </div>
+      </div>
+    </div>
+
+    <!-- Right: ADVISING -->
+    <div class="col-12 col-lg-4 d-flex flex-column gap-3">
+      <div class="card mc-panel tower-phase-card">
+        <div class="card-header mc-panel-header tower-phase-advising">// ADVISING</div>
+        <div class="card-body p-3 tower-scroll" id="tower-advisories">
+          <div class="tower-empty">Waiting for Spark data&hellip;</div>
+        </div>
+      </div>
+    </div>
+
+  </div>
+</div>
+
+<script>
+(function() {
+  var ws = null;
+  var badge = document.getElementById('tower-conn');
+
+  function setConn(state) {
+    badge.textContent = state.toUpperCase();
+    badge.className = 'tower-conn-badge tower-conn-' + state;
+  }
+
+  function esc(s) { var d = document.createElement('div'); d.textContent = s; return d.innerHTML; }
+
+  function renderEvents(events) {
+    var el = document.getElementById('tower-events');
+    if (!events || !events.length) { el.innerHTML = '<div class="tower-empty">No events captured yet.</div>'; return; }
+    var html = '';
+    for (var i = 0; i < events.length; i++) {
+      var ev = events[i];
+      var dots = ev.importance >= 0.8 ? '\u25cf\u25cf\u25cf' : ev.importance >= 0.5 ? '\u25cf\u25cf' : '\u25cf';
+      html += '<div class="tower-event tower-etype-' + esc(ev.event_type) + '">'
+        + '<div class="tower-ev-head">'
+        + '<span class="tower-ev-badge">' + esc(ev.event_type.replace(/_/g, ' ').toUpperCase()) + '</span>'
+        + '<span class="tower-ev-dots">' + dots + '</span>'
+        + '</div>'
+        + '<div class="tower-ev-desc">' + esc(ev.description) + '</div>'
+        + '<div class="tower-ev-time">' + esc((ev.created_at || '').slice(0, 19)) + '</div>'
+        + '</div>';
+    }
+    el.innerHTML = html;
+  }
+
+  function renderPredictions(preds) {
+    var el = document.getElementById('tower-predictions');
+    if (!preds || !preds.length) { el.innerHTML = '<div class="tower-empty">No predictions yet.</div>'; return; }
+    var html = '';
+    for (var i = 0; i < preds.length; i++) {
+      var p = preds[i];
+      var cls = p.evaluated ? 'tower-pred-done' : 'tower-pred-pending';
+      var accTxt = p.accuracy != null ? Math.round(p.accuracy * 100) + '%' : 'PENDING';
+      var accCls = p.accuracy != null ? (p.accuracy >= 0.7 ? 'text-success' : p.accuracy < 0.4 ? 'text-danger' : 'text-warning') : '';
+      html += '<div class="tower-pred ' + cls + '">'
+        + '<div class="tower-pred-head">'
+        + '<span class="tower-pred-task">' + esc(p.task_id) + '</span>'
+        + '<span class="tower-pred-acc ' + accCls + '">' + accTxt + '</span>'
+        + '</div>';
+      if (p.predicted) {
+        var pr = p.predicted;
+        html += '<div class="tower-pred-detail">';
+        if (pr.likely_winner) html += '<span>Winner: ' + esc(pr.likely_winner.slice(0, 8)) + '</span> ';
+        if (pr.success_probability != null) html += '<span>Success: ' + Math.round(pr.success_probability * 100) + '%</span> ';
+        html += '</div>';
+      }
+      html += '<div class="tower-ev-time">' + esc((p.created_at || '').slice(0, 19)) + '</div>'
+        + '</div>';
+    }
+    el.innerHTML = html;
+  }
+
+  function renderAdvisories(advs) {
+    var el = document.getElementById('tower-advisories');
+    if (!advs || !advs.length) { el.innerHTML = '<div class="tower-empty">No advisories yet.</div>'; return; }
+    var html = '';
+    for (var i = 0; i < advs.length; i++) {
+      var a = advs[i];
+      var prio = a.priority >= 0.7 ? 'high' : a.priority >= 0.4 ? 'medium' : 'low';
+      html += '<div class="tower-advisory tower-adv-' + prio + '">'
+        + '<div class="tower-adv-head">'
+        + '<span class="tower-adv-cat">' + esc(a.category.replace(/_/g, ' ').toUpperCase()) + '</span>'
+        + '<span class="tower-adv-prio">' + Math.round(a.priority * 100) + '%</span>'
+        + '</div>'
+        + '<div class="tower-adv-title">' + esc(a.title) + '</div>'
+        + '<div class="tower-adv-detail">' + esc(a.detail) + '</div>'
+        + '<div class="tower-adv-action">' + esc(a.suggested_action) + '</div>'
+        + '</div>';
+    }
+    el.innerHTML = html;
+  }
+
+  function renderStats(status) {
+    if (!status) return;
+    document.getElementById('ts-events').textContent = status.events_captured || 0;
+    document.getElementById('ts-memories').textContent = status.memories_stored || 0;
+    var p = status.predictions || {};
+    document.getElementById('ts-preds').textContent = p.total_predictions || 0;
+    var acc = p.avg_accuracy;
+    var accEl = document.getElementById('ts-accuracy');
+    if (acc != null) {
+      accEl.textContent = Math.round(acc * 100) + '%';
+      accEl.className = 'tower-stat-value ' + (acc >= 0.7 ? 'text-success' : acc < 0.4 ? 'text-danger' : 'text-warning');
+    } else {
+      accEl.textContent = '\u2014';
+    }
+  }
+
+  function handleMsg(data) {
+    if (data.type !== 'spark_state') return;
+    renderEvents(data.events);
+    renderPredictions(data.predictions);
+    renderAdvisories(data.advisories);
+    renderStats(data.status);
+  }
+
+  function connect() {
+    var proto = location.protocol === 'https:' ? 'wss:' : 'ws:';
+    ws = new WebSocket(proto + '//' + location.host + '/tower/ws');
+    ws.onopen = function() { setConn('live'); };
+    ws.onclose = function() { setConn('offline'); setTimeout(connect, 3000); };
+    ws.onerror = function() { setConn('offline'); };
+    ws.onmessage = function(e) {
+      try { handleMsg(JSON.parse(e.data)); } catch(err) { console.error('Tower WS parse error', err); }
+    };
+  }
+
+  connect();
+})();
+</script>
+{% endblock %}

src/infrastructure/chat_store.py

@@ -0,0 +1,153 @@
+"""Persistent chat message store backed by SQLite.
+
+Provides the same API as the original in-memory MessageLog so all callers
+(dashboard routes, chat_api, thinking, briefing) work without changes.
+
+Data lives in ``data/chat.db`` — survives server restarts.
+A configurable retention policy (default 500 messages) keeps the DB lean.
+"""
+
+import sqlite3
+import threading
+from collections.abc import Generator
+from contextlib import closing, contextmanager
+from dataclasses import dataclass
+from pathlib import Path
+
+# ── Data dir — resolved relative to repo root (three levels up from this file) ──
+_REPO_ROOT = Path(__file__).resolve().parents[3]
+DB_PATH: Path = _REPO_ROOT / "data" / "chat.db"
+
+# Maximum messages to retain (oldest pruned on append)
+MAX_MESSAGES: int = 500
+
+
+@dataclass
+class Message:
+    role: str  # "user" | "agent" | "error"
+    content: str
+    timestamp: str
+    source: str = "browser"  # "browser" | "api" | "telegram" | "discord" | "system"
+
+
+@contextmanager
+def _get_conn(db_path: Path | None = None) -> Generator[sqlite3.Connection, None, None]:
+    """Open (or create) the chat database and ensure schema exists."""
+    path = db_path or DB_PATH
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with closing(sqlite3.connect(str(path), check_same_thread=False)) as conn:
+        conn.row_factory = sqlite3.Row
+        conn.execute("PRAGMA journal_mode=WAL")
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS chat_messages (
+                id        INTEGER PRIMARY KEY AUTOINCREMENT,
+                role      TEXT NOT NULL,
+                content   TEXT NOT NULL,
+                timestamp TEXT NOT NULL,
+                source    TEXT NOT NULL DEFAULT 'browser'
+            )
+        """)
+        conn.commit()
+        yield conn
+
+
+class MessageLog:
+    """SQLite-backed chat history — drop-in replacement for the old in-memory list."""
+
+    def __init__(self, db_path: Path | None = None) -> None:
+        self._db_path = db_path or DB_PATH
+        self._lock = threading.Lock()
+        self._conn: sqlite3.Connection | None = None
+
+    # Lazy connection — opened on first use, not at import time.
+    def _ensure_conn(self) -> sqlite3.Connection:
+        if self._conn is None:
+            # Open a persistent connection for the class instance
+            path = self._db_path or DB_PATH
+            path.parent.mkdir(parents=True, exist_ok=True)
+            conn = sqlite3.connect(str(path), check_same_thread=False)
+            conn.row_factory = sqlite3.Row
+            conn.execute("PRAGMA journal_mode=WAL")
+            conn.execute("""
+                CREATE TABLE IF NOT EXISTS chat_messages (
+                    id        INTEGER PRIMARY KEY AUTOINCREMENT,
+                    role      TEXT NOT NULL,
+                    content   TEXT NOT NULL,
+                    timestamp TEXT NOT NULL,
+                    source    TEXT NOT NULL DEFAULT 'browser'
+                )
+            """)
+            conn.commit()
+            self._conn = conn
+        return self._conn
+
+    def append(self, role: str, content: str, timestamp: str, source: str = "browser") -> None:
+        with self._lock:
+            conn = self._ensure_conn()
+            conn.execute(
+                "INSERT INTO chat_messages (role, content, timestamp, source) VALUES (?, ?, ?, ?)",
+                (role, content, timestamp, source),
+            )
+            conn.commit()
+            self._prune(conn)
+
+    def all(self) -> list[Message]:
+        with self._lock:
+            conn = self._ensure_conn()
+            rows = conn.execute(
+                "SELECT role, content, timestamp, source FROM chat_messages ORDER BY id"
+            ).fetchall()
+        return [
+            Message(
+                role=r["role"], content=r["content"], timestamp=r["timestamp"], source=r["source"]
+            )
+            for r in rows
+        ]
+
+    def recent(self, limit: int = 50) -> list[Message]:
+        """Return the *limit* most recent messages (oldest-first)."""
+        with self._lock:
+            conn = self._ensure_conn()
+            rows = conn.execute(
+                "SELECT role, content, timestamp, source FROM chat_messages "
+                "ORDER BY id DESC LIMIT ?",
+                (limit,),
+            ).fetchall()
+        return [
+            Message(
+                role=r["role"], content=r["content"], timestamp=r["timestamp"], source=r["source"]
+            )
+            for r in reversed(rows)
+        ]
+
+    def clear(self) -> None:
+        with self._lock:
+            conn = self._ensure_conn()
+            conn.execute("DELETE FROM chat_messages")
+            conn.commit()
+
+    def _prune(self, conn: sqlite3.Connection) -> None:
+        """Keep at most MAX_MESSAGES rows, deleting the oldest."""
+        count = conn.execute("SELECT COUNT(*) FROM chat_messages").fetchone()[0]
+        if count > MAX_MESSAGES:
+            excess = count - MAX_MESSAGES
+            conn.execute(
+                "DELETE FROM chat_messages WHERE id IN "
+                "(SELECT id FROM chat_messages ORDER BY id LIMIT ?)",
+                (excess,),
+            )
+            conn.commit()
+
+    def close(self) -> None:
+        if self._conn is not None:
+            self._conn.close()
+            self._conn = None
+
+    def __len__(self) -> int:
+        with self._lock:
+            conn = self._ensure_conn()
+            return conn.execute("SELECT COUNT(*) FROM chat_messages").fetchone()[0]
+
+
+# Module-level singleton shared across the app
+message_log = MessageLog()

src/infrastructure/db_pool.py

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

src/infrastructure/error_capture.py

@@ -22,6 +22,14 @@ logger = logging.getLogger(__name__)
 # In-memory dedup cache: hash -> last_seen timestamp
 _dedup_cache: dict[str, datetime] = {}
 
+_error_recorder = None
+
+
+def register_error_recorder(fn):
+    """Register a callback for recording errors to session log."""
+    global _error_recorder
+    _error_recorder = fn
+
 
 def _stack_hash(exc: Exception) -> str:
     """Create a stable hash of the exception type + traceback locations.
@@ -87,10 +95,177 @@ def _get_git_context() -> dict:
         ).stdout.strip()
 
         return {"branch": branch, "commit": commit}
-    except Exception:
+    except Exception as exc:
+        logger.warning("Git info capture error: %s", exc)
         return {"branch": "unknown", "commit": "unknown"}
 
 
+def _extract_traceback_info(exc: Exception) -> tuple[str, str, int]:
+    """Extract formatted traceback, affected file, and line number.
+
+    Returns:
+        Tuple of (traceback_string, affected_file, affected_line).
+    """
+    tb_str = "".join(traceback.format_exception(type(exc), exc, exc.__traceback__))
+
+    tb_obj = exc.__traceback__
+    affected_file = "unknown"
+    affected_line = 0
+    while tb_obj and tb_obj.tb_next:
+        tb_obj = tb_obj.tb_next
+    if tb_obj:
+        affected_file = tb_obj.tb_frame.f_code.co_filename
+        affected_line = tb_obj.tb_lineno
+
+    return tb_str, affected_file, affected_line
+
+
+def _log_error_event(
+    exc: Exception,
+    source: str,
+    error_hash: str,
+    affected_file: str,
+    affected_line: int,
+    git_ctx: dict,
+) -> None:
+    """Log the captured error to the event log."""
+    try:
+        from swarm.event_log import EventType, log_event
+
+        log_event(
+            EventType.ERROR_CAPTURED,
+            source=source,
+            data={
+                "error_type": type(exc).__name__,
+                "message": str(exc)[:500],
+                "hash": error_hash,
+                "file": affected_file,
+                "line": affected_line,
+                "git_branch": git_ctx.get("branch", ""),
+                "git_commit": git_ctx.get("commit", ""),
+            },
+        )
+    except Exception as log_exc:
+        logger.debug("Failed to log error event: %s", log_exc)
+
+
+def _build_report_description(
+    exc: Exception,
+    source: str,
+    context: dict | None,
+    error_hash: str,
+    tb_str: str,
+    affected_file: str,
+    affected_line: int,
+    git_ctx: dict,
+) -> str:
+    """Build the markdown description for a bug report task."""
+    parts = [
+        f"**Error:** {type(exc).__name__}: {str(exc)}",
+        f"**Source:** {source}",
+        f"**File:** {affected_file}:{affected_line}",
+        f"**Git:** {git_ctx.get('branch', '?')} @ {git_ctx.get('commit', '?')}",
+        f"**Time:** {datetime.now(UTC).isoformat()}",
+        f"**Hash:** {error_hash}",
+    ]
+
+    if context:
+        ctx_str = ", ".join(f"{k}={v}" for k, v in context.items())
+        parts.append(f"**Context:** {ctx_str}")
+
+    parts.append(f"\n**Stack Trace:**\n```\n{tb_str[:2000]}\n```")
+    return "\n".join(parts)
+
+
+def _log_bug_report_created(source: str, task_id: str, error_hash: str, title: str) -> None:
+    """Log a BUG_REPORT_CREATED event (best-effort)."""
+    try:
+        from swarm.event_log import EventType, log_event
+
+        log_event(
+            EventType.BUG_REPORT_CREATED,
+            source=source,
+            task_id=task_id,
+            data={
+                "error_hash": error_hash,
+                "title": title[:100],
+            },
+        )
+    except Exception as exc:
+        logger.warning("Bug report event log error: %s", exc)
+
+
+def _create_bug_report(
+    exc: Exception,
+    source: str,
+    context: dict | None,
+    error_hash: str,
+    tb_str: str,
+    affected_file: str,
+    affected_line: int,
+    git_ctx: dict,
+) -> str | None:
+    """Create a bug report task and return the task ID (or None on failure)."""
+    try:
+        from swarm.task_queue.models import create_task
+
+        title = f"[BUG] {type(exc).__name__}: {str(exc)[:80]}"
+        description = _build_report_description(
+            exc,
+            source,
+            context,
+            error_hash,
+            tb_str,
+            affected_file,
+            affected_line,
+            git_ctx,
+        )
+
+        task = create_task(
+            title=title,
+            description=description,
+            assigned_to="default",
+            created_by="system",
+            priority="normal",
+            requires_approval=False,
+            auto_approve=True,
+            task_type="bug_report",
+        )
+
+        _log_bug_report_created(source, task.id, error_hash, title)
+        return task.id
+
+    except Exception as task_exc:
+        logger.debug("Failed to create bug report task: %s", task_exc)
+        return None
+
+
+def _notify_bug_report(exc: Exception, source: str) -> None:
+    """Send a push notification about the captured error."""
+    try:
+        from infrastructure.notifications.push import notifier
+
+        notifier.notify(
+            title="Bug Report Filed",
+            message=f"{type(exc).__name__} in {source}: {str(exc)[:80]}",
+            category="system",
+        )
+    except Exception as notify_exc:
+        logger.warning("Bug report notification error: %s", notify_exc)
+
+
+def _record_to_session(exc: Exception, source: str) -> None:
+    """Record the error via the registered session callback."""
+    if _error_recorder is not None:
+        try:
+            _error_recorder(
+                error=f"{type(exc).__name__}: {str(exc)}",
+                context=source,
+            )
+        except Exception as log_exc:
+            logger.warning("Bug report session logging error: %s", log_exc)
+
+
 def capture_error(
     exc: Exception,
     source: str = "unknown",
@@ -117,116 +292,23 @@ def capture_error(
         logger.debug("Duplicate error suppressed: %s (hash=%s)", exc, error_hash)
         return None
 
-    # Format the stack trace
-    tb_str = "".join(traceback.format_exception(type(exc), exc, exc.__traceback__))
-
-    # Extract file/line from traceback
-    tb_obj = exc.__traceback__
-    affected_file = "unknown"
-    affected_line = 0
-    while tb_obj and tb_obj.tb_next:
-        tb_obj = tb_obj.tb_next
-    if tb_obj:
-        affected_file = tb_obj.tb_frame.f_code.co_filename
-        affected_line = tb_obj.tb_lineno
-
+    tb_str, affected_file, affected_line = _extract_traceback_info(exc)
     git_ctx = _get_git_context()
 
-    # 1. Log to event_log
-    try:
-        from swarm.event_log import EventType, log_event
+    _log_error_event(exc, source, error_hash, affected_file, affected_line, git_ctx)
 
-        log_event(
-            EventType.ERROR_CAPTURED,
-            source=source,
-            data={
-                "error_type": type(exc).__name__,
-                "message": str(exc)[:500],
-                "hash": error_hash,
-                "file": affected_file,
-                "line": affected_line,
-                "git_branch": git_ctx.get("branch", ""),
-                "git_commit": git_ctx.get("commit", ""),
-            },
-        )
-    except Exception as log_exc:
-        logger.debug("Failed to log error event: %s", log_exc)
+    task_id = _create_bug_report(
+        exc,
+        source,
+        context,
+        error_hash,
+        tb_str,
+        affected_file,
+        affected_line,
+        git_ctx,
+    )
 
-    # 2. Create bug report task
-    task_id = None
-    try:
-        from swarm.task_queue.models import create_task
-
-        title = f"[BUG] {type(exc).__name__}: {str(exc)[:80]}"
-
-        description_parts = [
-            f"**Error:** {type(exc).__name__}: {str(exc)}",
-            f"**Source:** {source}",
-            f"**File:** {affected_file}:{affected_line}",
-            f"**Git:** {git_ctx.get('branch', '?')} @ {git_ctx.get('commit', '?')}",
-            f"**Time:** {datetime.now(UTC).isoformat()}",
-            f"**Hash:** {error_hash}",
-        ]
-
-        if context:
-            ctx_str = ", ".join(f"{k}={v}" for k, v in context.items())
-            description_parts.append(f"**Context:** {ctx_str}")
-
-        description_parts.append(f"\n**Stack Trace:**\n```\n{tb_str[:2000]}\n```")
-
-        task = create_task(
-            title=title,
-            description="\n".join(description_parts),
-            assigned_to="default",
-            created_by="system",
-            priority="normal",
-            requires_approval=False,
-            auto_approve=True,
-            task_type="bug_report",
-        )
-        task_id = task.id
-
-        # Log the creation event
-        try:
-            from swarm.event_log import EventType, log_event
-
-            log_event(
-                EventType.BUG_REPORT_CREATED,
-                source=source,
-                task_id=task_id,
-                data={
-                    "error_hash": error_hash,
-                    "title": title[:100],
-                },
-            )
-        except Exception:
-            pass
-
-    except Exception as task_exc:
-        logger.debug("Failed to create bug report task: %s", task_exc)
-
-    # 3. Send notification
-    try:
-        from infrastructure.notifications.push import notifier
-
-        notifier.notify(
-            title="Bug Report Filed",
-            message=f"{type(exc).__name__} in {source}: {str(exc)[:80]}",
-            category="system",
-        )
-    except Exception:
-        pass
-
-    # 4. Record in session logger
-    try:
-        from timmy.session_logger import get_session_logger
-
-        session_logger = get_session_logger()
-        session_logger.record_error(
-            error=f"{type(exc).__name__}: {str(exc)}",
-            context=source,
-        )
-    except Exception:
-        pass
+    _notify_bug_report(exc, source)
+    _record_to_session(exc, source)
 
     return task_id

src/infrastructure/events/broadcaster.py

@@ -1,193 +0,0 @@
-"""Event Broadcaster - bridges event_log to WebSocket clients.
-
-When events are logged, they are broadcast to all connected dashboard clients
-via WebSocket for real-time activity feed updates.
-"""
-
-import asyncio
-import logging
-from typing import Optional
-
-try:
-    from swarm.event_log import EventLogEntry
-except ImportError:
-    EventLogEntry = None
-
-logger = logging.getLogger(__name__)
-
-
-class EventBroadcaster:
-    """Broadcasts events to WebSocket clients.
-
-    Usage:
-        from infrastructure.events.broadcaster import event_broadcaster
-        event_broadcaster.broadcast(event)
-    """
-
-    def __init__(self) -> None:
-        self._ws_manager: Optional = None
-
-    def _get_ws_manager(self):
-        """Lazy import to avoid circular deps."""
-        if self._ws_manager is None:
-            try:
-                from infrastructure.ws_manager.handler import ws_manager
-
-                self._ws_manager = ws_manager
-            except Exception as exc:
-                logger.debug("WebSocket manager not available: %s", exc)
-        return self._ws_manager
-
-    async def broadcast(self, event: EventLogEntry) -> int:
-        """Broadcast an event to all connected WebSocket clients.
-
-        Args:
-            event: The event to broadcast
-
-        Returns:
-            Number of clients notified
-        """
-        ws_manager = self._get_ws_manager()
-        if not ws_manager:
-            return 0
-
-        # Build message payload
-        payload = {
-            "type": "event",
-            "payload": {
-                "id": event.id,
-                "event_type": event.event_type.value,
-                "source": event.source,
-                "task_id": event.task_id,
-                "agent_id": event.agent_id,
-                "timestamp": event.timestamp,
-                "data": event.data,
-            },
-        }
-
-        try:
-            # Broadcast to all connected clients
-            count = await ws_manager.broadcast_json(payload)
-            logger.debug("Broadcasted event %s to %d clients", event.id[:8], count)
-            return count
-        except Exception as exc:
-            logger.error("Failed to broadcast event: %s", exc)
-            return 0
-
-    def broadcast_sync(self, event: EventLogEntry) -> None:
-        """Synchronous wrapper for broadcast.
-
-        Use this from synchronous code - it schedules the async broadcast
-        in the event loop if one is running.
-        """
-        try:
-            asyncio.get_running_loop()
-            # Schedule in background, don't wait
-            asyncio.create_task(self.broadcast(event))
-        except RuntimeError:
-            # No event loop running, skip broadcast
-            pass
-
-
-# Global singleton
-event_broadcaster = EventBroadcaster()
-
-
-# Event type to icon/emoji mapping
-EVENT_ICONS = {
-    "task.created": "📝",
-    "task.bidding": "⏳",
-    "task.assigned": "👤",
-    "task.started": "▶️",
-    "task.completed": "✅",
-    "task.failed": "❌",
-    "agent.joined": "🟢",
-    "agent.left": "🔴",
-    "agent.status_changed": "🔄",
-    "bid.submitted": "💰",
-    "auction.closed": "🏁",
-    "tool.called": "🔧",
-    "tool.completed": "⚙️",
-    "tool.failed": "💥",
-    "system.error": "⚠️",
-    "system.warning": "🔶",
-    "system.info": "ℹ️",
-    "error.captured": "🐛",
-    "bug_report.created": "📋",
-}
-
-EVENT_LABELS = {
-    "task.created": "New task",
-    "task.bidding": "Bidding open",
-    "task.assigned": "Task assigned",
-    "task.started": "Task started",
-    "task.completed": "Task completed",
-    "task.failed": "Task failed",
-    "agent.joined": "Agent joined",
-    "agent.left": "Agent left",
-    "agent.status_changed": "Status changed",
-    "bid.submitted": "Bid submitted",
-    "auction.closed": "Auction closed",
-    "tool.called": "Tool called",
-    "tool.completed": "Tool completed",
-    "tool.failed": "Tool failed",
-    "system.error": "Error",
-    "system.warning": "Warning",
-    "system.info": "Info",
-    "error.captured": "Error captured",
-    "bug_report.created": "Bug report filed",
-}
-
-
-def get_event_icon(event_type: str) -> str:
-    """Get emoji icon for event type."""
-    return EVENT_ICONS.get(event_type, "•")
-
-
-def get_event_label(event_type: str) -> str:
-    """Get human-readable label for event type."""
-    return EVENT_LABELS.get(event_type, event_type)
-
-
-def format_event_for_display(event: EventLogEntry) -> dict:
-    """Format event for display in activity feed.
-
-    Returns dict with display-friendly fields.
-    """
-    data = event.data or {}
-
-    # Build description based on event type
-    description = ""
-    if event.event_type.value == "task.created":
-        desc = data.get("description", "")
-        description = desc[:60] + "..." if len(desc) > 60 else desc
-    elif event.event_type.value == "task.assigned":
-        agent = event.agent_id[:8] if event.agent_id else "unknown"
-        bid = data.get("bid_sats", "?")
-        description = f"to {agent} ({bid} sats)"
-    elif event.event_type.value == "bid.submitted":
-        bid = data.get("bid_sats", "?")
-        description = f"{bid} sats"
-    elif event.event_type.value == "agent.joined":
-        persona = data.get("persona_id", "")
-        description = f"Persona: {persona}" if persona else "New agent"
-    else:
-        # Generic: use any string data
-        for key in ["message", "reason", "description"]:
-            if key in data:
-                val = str(data[key])
-                description = val[:60] + "..." if len(val) > 60 else val
-                break
-
-    return {
-        "id": event.id,
-        "icon": get_event_icon(event.event_type.value),
-        "label": get_event_label(event.event_type.value),
-        "type": event.event_type.value,
-        "source": event.source,
-        "description": description,
-        "timestamp": event.timestamp,
-        "time_short": event.timestamp[11:19] if event.timestamp else "",
-        "task_id": event.task_id,
-        "agent_id": event.agent_id,
-    }

src/infrastructure/events/bus.py

@@ -9,7 +9,8 @@ import asyncio
 import json
 import logging
 import sqlite3
-from collections.abc import Callable, Coroutine
+from collections.abc import Callable, Coroutine, Generator
+from contextlib import closing, contextmanager
 from dataclasses import dataclass, field
 from datetime import UTC, datetime
 from pathlib import Path
@@ -63,7 +64,7 @@ class EventBus:
 
         @bus.subscribe("agent.task.*")
         async def handle_task(event: Event):
-            print(f"Task event: {event.data}")
+            logger.debug("Task event: %s", event.data)
 
         await bus.publish(Event(
             type="agent.task.assigned",
@@ -99,51 +100,48 @@ class EventBus:
         if self._persistence_db_path is None:
             return
         self._persistence_db_path.parent.mkdir(parents=True, exist_ok=True)
-        conn = sqlite3.connect(str(self._persistence_db_path))
-        try:
+        with closing(sqlite3.connect(str(self._persistence_db_path))) as conn:
             conn.execute("PRAGMA journal_mode=WAL")
             conn.execute("PRAGMA busy_timeout=5000")
             conn.executescript(_EVENTS_SCHEMA)
             conn.commit()
-        finally:
-            conn.close()
 
-    def _get_persistence_conn(self) -> sqlite3.Connection | None:
+    @contextmanager
+    def _get_persistence_conn(self) -> Generator[sqlite3.Connection | None, None, None]:
         """Get a connection to the persistence database."""
         if self._persistence_db_path is None:
-            return None
-        conn = sqlite3.connect(str(self._persistence_db_path))
-        conn.row_factory = sqlite3.Row
-        conn.execute("PRAGMA busy_timeout=5000")
-        return conn
+            yield None
+            return
+        with closing(sqlite3.connect(str(self._persistence_db_path))) as conn:
+            conn.row_factory = sqlite3.Row
+            conn.execute("PRAGMA busy_timeout=5000")
+            yield conn
 
     def _persist_event(self, event: Event) -> None:
         """Write an event to the persistence database."""
-        conn = self._get_persistence_conn()
-        if conn is None:
-            return
-        try:
-            task_id = event.data.get("task_id", "")
-            agent_id = event.data.get("agent_id", "")
-            conn.execute(
-                "INSERT OR IGNORE INTO events "
-                "(id, event_type, source, task_id, agent_id, data, timestamp) "
-                "VALUES (?, ?, ?, ?, ?, ?, ?)",
-                (
-                    event.id,
-                    event.type,
-                    event.source,
-                    task_id,
-                    agent_id,
-                    json.dumps(event.data),
-                    event.timestamp,
-                ),
-            )
-            conn.commit()
-        except Exception as exc:
-            logger.debug("Failed to persist event: %s", exc)
-        finally:
-            conn.close()
+        with self._get_persistence_conn() as conn:
+            if conn is None:
+                return
+            try:
+                task_id = event.data.get("task_id", "")
+                agent_id = event.data.get("agent_id", "")
+                conn.execute(
+                    "INSERT OR IGNORE INTO events "
+                    "(id, event_type, source, task_id, agent_id, data, timestamp) "
+                    "VALUES (?, ?, ?, ?, ?, ?, ?)",
+                    (
+                        event.id,
+                        event.type,
+                        event.source,
+                        task_id,
+                        agent_id,
+                        json.dumps(event.data),
+                        event.timestamp,
+                    ),
+                )
+                conn.commit()
+            except Exception as exc:
+                logger.debug("Failed to persist event: %s", exc)
 
     # ── Replay ───────────────────────────────────────────────────────────
 
@@ -165,45 +163,43 @@ class EventBus:
         Returns:
             List of Event objects from persistent storage.
         """
-        conn = self._get_persistence_conn()
-        if conn is None:
-            return []
+        with self._get_persistence_conn() as conn:
+            if conn is None:
+                return []
 
-        try:
-            conditions = []
-            params: list = []
+            try:
+                conditions = []
+                params: list = []
 
-            if event_type:
-                conditions.append("event_type = ?")
-                params.append(event_type)
-            if source:
-                conditions.append("source = ?")
-                params.append(source)
-            if task_id:
-                conditions.append("task_id = ?")
-                params.append(task_id)
+                if event_type:
+                    conditions.append("event_type = ?")
+                    params.append(event_type)
+                if source:
+                    conditions.append("source = ?")
+                    params.append(source)
+                if task_id:
+                    conditions.append("task_id = ?")
+                    params.append(task_id)
 
-            where = " AND ".join(conditions) if conditions else "1=1"
-            sql = f"SELECT * FROM events WHERE {where} ORDER BY timestamp DESC LIMIT ?"
-            params.append(limit)
+                where = " AND ".join(conditions) if conditions else "1=1"
+                sql = f"SELECT * FROM events WHERE {where} ORDER BY timestamp DESC LIMIT ?"
+                params.append(limit)
 
-            rows = conn.execute(sql, params).fetchall()
+                rows = conn.execute(sql, params).fetchall()
 
-            return [
-                Event(
-                    id=row["id"],
-                    type=row["event_type"],
-                    source=row["source"],
-                    data=json.loads(row["data"]) if row["data"] else {},
-                    timestamp=row["timestamp"],
-                )
-                for row in rows
-            ]
-        except Exception as exc:
-            logger.debug("Failed to replay events: %s", exc)
-            return []
-        finally:
-            conn.close()
+                return [
+                    Event(
+                        id=row["id"],
+                        type=row["event_type"],
+                        source=row["source"],
+                        data=json.loads(row["data"]) if row["data"] else {},
+                        timestamp=row["timestamp"],
+                    )
+                    for row in rows
+                ]
+            except Exception as exc:
+                logger.debug("Failed to replay events: %s", exc)
+                return []
 
     # ── Subscribe / Publish ──────────────────────────────────────────────
 

src/infrastructure/hands/shell.py

@@ -144,6 +144,65 @@ class ShellHand:
 
         return None
 
+    @staticmethod
+    def _build_run_env(env: dict | None) -> dict:
+        """Merge *env* overrides into a copy of the current environment."""
+        import os
+
+        run_env = os.environ.copy()
+        if env:
+            run_env.update(env)
+        return run_env
+
+    async def _execute_subprocess(
+        self,
+        command: str,
+        effective_timeout: int,
+        cwd: str | None,
+        run_env: dict,
+        start: float,
+    ) -> ShellResult:
+        """Run *command* as a subprocess with timeout enforcement."""
+        proc = await asyncio.create_subprocess_shell(
+            command,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=cwd,
+            env=run_env,
+        )
+
+        try:
+            stdout_bytes, stderr_bytes = await asyncio.wait_for(
+                proc.communicate(), timeout=effective_timeout
+            )
+        except TimeoutError:
+            proc.kill()
+            await proc.wait()
+            latency = (time.time() - start) * 1000
+            logger.warning("Shell command timed out after %ds: %s", effective_timeout, command)
+            return ShellResult(
+                command=command,
+                success=False,
+                exit_code=-1,
+                error=f"Command timed out after {effective_timeout}s",
+                latency_ms=latency,
+                timed_out=True,
+            )
+
+        latency = (time.time() - start) * 1000
+        exit_code = proc.returncode if proc.returncode is not None else -1
+        stdout = stdout_bytes.decode("utf-8", errors="replace").strip()
+        stderr = stderr_bytes.decode("utf-8", errors="replace").strip()
+
+        return ShellResult(
+            command=command,
+            success=exit_code == 0,
+            exit_code=exit_code,
+            stdout=stdout,
+            stderr=stderr,
+            latency_ms=latency,
+        )
+
     async def run(
         self,
         command: str,
@@ -164,7 +223,6 @@ class ShellHand:
         """
         start = time.time()
 
-        # Validate
         validation_error = self._validate_command(command)
         if validation_error:
             return ShellResult(
@@ -178,52 +236,8 @@ class ShellHand:
         cwd = working_dir or self._working_dir
 
         try:
-            import os
-
-            run_env = os.environ.copy()
-            if env:
-                run_env.update(env)
-
-            proc = await asyncio.create_subprocess_shell(
-                command,
-                stdout=asyncio.subprocess.PIPE,
-                stderr=asyncio.subprocess.PIPE,
-                cwd=cwd,
-                env=run_env,
-            )
-
-            try:
-                stdout_bytes, stderr_bytes = await asyncio.wait_for(
-                    proc.communicate(), timeout=effective_timeout
-                )
-            except TimeoutError:
-                proc.kill()
-                await proc.wait()
-                latency = (time.time() - start) * 1000
-                logger.warning("Shell command timed out after %ds: %s", effective_timeout, command)
-                return ShellResult(
-                    command=command,
-                    success=False,
-                    exit_code=-1,
-                    error=f"Command timed out after {effective_timeout}s",
-                    latency_ms=latency,
-                    timed_out=True,
-                )
-
-            latency = (time.time() - start) * 1000
-            exit_code = proc.returncode or 0
-            stdout = stdout_bytes.decode("utf-8", errors="replace").strip()
-            stderr = stderr_bytes.decode("utf-8", errors="replace").strip()
-
-            return ShellResult(
-                command=command,
-                success=exit_code == 0,
-                exit_code=exit_code,
-                stdout=stdout,
-                stderr=stderr,
-                latency_ms=latency,
-            )
-
+            run_env = self._build_run_env(env)
+            return await self._execute_subprocess(command, effective_timeout, cwd, run_env, start)
         except Exception as exc:
             latency = (time.time() - start) * 1000
             logger.warning("Shell command failed: %s — %s", command, exc)

src/infrastructure/matrix_config.py

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

src/infrastructure/models/multimodal.py

@@ -13,7 +13,7 @@ import logging
 from dataclasses import dataclass, field
 from enum import Enum, auto
 
-from config import settings
+from config import normalize_ollama_url, settings
 
 logger = logging.getLogger(__name__)
 
@@ -93,18 +93,6 @@ KNOWN_MODEL_CAPABILITIES: dict[str, set[ModelCapability]] = {
         ModelCapability.VISION,
     },
     # Qwen series
-    "qwen3.5": {
-        ModelCapability.TEXT,
-        ModelCapability.TOOLS,
-        ModelCapability.JSON,
-        ModelCapability.STREAMING,
-    },
-    "qwen3.5:latest": {
-        ModelCapability.TEXT,
-        ModelCapability.TOOLS,
-        ModelCapability.JSON,
-        ModelCapability.STREAMING,
-    },
     "qwen2.5": {
         ModelCapability.TEXT,
         ModelCapability.TOOLS,
@@ -271,9 +259,8 @@ DEFAULT_FALLBACK_CHAINS: dict[ModelCapability, list[str]] = {
     ],
     ModelCapability.TOOLS: [
         "llama3.1:8b-instruct",  # Best tool use
-        "qwen3.5:latest",  # Qwen 3.5 — strong tool use
-        "llama3.2:3b",  # Smaller but capable
         "qwen2.5:7b",  # Reliable fallback
+        "llama3.2:3b",  # Smaller but capable
     ],
     ModelCapability.AUDIO: [
         # Audio models are less common in Ollama
@@ -320,7 +307,7 @@ class MultiModalManager:
             import json
             import urllib.request
 
-            url = self.ollama_url.replace("localhost", "127.0.0.1")
+            url = normalize_ollama_url(self.ollama_url)
             req = urllib.request.Request(
                 f"{url}/api/tags",
                 method="GET",
@@ -475,7 +462,7 @@ class MultiModalManager:
 
             logger.info("Pulling model: %s", model_name)
 
-            url = self.ollama_url.replace("localhost", "127.0.0.1")
+            url = normalize_ollama_url(self.ollama_url)
             req = urllib.request.Request(
                 f"{url}/api/pull",
                 method="POST",

src/infrastructure/models/registry.py

@@ -11,6 +11,8 @@ model roles (student, teacher, judge/PRM) run on dedicated resources.
 import logging
 import sqlite3
 import threading
+from collections.abc import Generator
+from contextlib import closing, contextmanager
 from dataclasses import dataclass
 from datetime import UTC, datetime
 from enum import StrEnum
@@ -60,36 +62,37 @@ class CustomModel:
             self.registered_at = datetime.now(UTC).isoformat()
 
 
-def _get_conn() -> sqlite3.Connection:
+@contextmanager
+def _get_conn() -> 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("PRAGMA journal_mode=WAL")
-    conn.execute("PRAGMA busy_timeout=5000")
-    conn.execute("""
-        CREATE TABLE IF NOT EXISTS custom_models (
-            name            TEXT PRIMARY KEY,
-            format          TEXT NOT NULL,
-            path            TEXT NOT NULL,
-            role            TEXT NOT NULL DEFAULT 'general',
-            context_window  INTEGER NOT NULL DEFAULT 4096,
-            description     TEXT NOT NULL DEFAULT '',
-            registered_at   TEXT NOT NULL,
-            active          INTEGER NOT NULL DEFAULT 1,
-            default_temperature REAL NOT NULL DEFAULT 0.7,
-            max_tokens      INTEGER NOT NULL DEFAULT 2048
-        )
-        """)
-    conn.execute("""
-        CREATE TABLE IF NOT EXISTS agent_model_assignments (
-            agent_id    TEXT PRIMARY KEY,
-            model_name  TEXT NOT NULL,
-            assigned_at TEXT NOT NULL,
-            FOREIGN KEY (model_name) REFERENCES custom_models(name)
-        )
-        """)
-    conn.commit()
-    return conn
+    with closing(sqlite3.connect(str(DB_PATH))) as conn:
+        conn.row_factory = sqlite3.Row
+        conn.execute("PRAGMA journal_mode=WAL")
+        conn.execute("PRAGMA busy_timeout=5000")
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS custom_models (
+                name            TEXT PRIMARY KEY,
+                format          TEXT NOT NULL,
+                path            TEXT NOT NULL,
+                role            TEXT NOT NULL DEFAULT 'general',
+                context_window  INTEGER NOT NULL DEFAULT 4096,
+                description     TEXT NOT NULL DEFAULT '',
+                registered_at   TEXT NOT NULL,
+                active          INTEGER NOT NULL DEFAULT 1,
+                default_temperature REAL NOT NULL DEFAULT 0.7,
+                max_tokens      INTEGER NOT NULL DEFAULT 2048
+            )
+            """)
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS agent_model_assignments (
+                agent_id    TEXT PRIMARY KEY,
+                model_name  TEXT NOT NULL,
+                assigned_at TEXT NOT NULL,
+                FOREIGN KEY (model_name) REFERENCES custom_models(name)
+            )
+            """)
+        conn.commit()
+        yield conn
 
 
 class ModelRegistry:
@@ -105,23 +108,22 @@ class ModelRegistry:
     def _load_from_db(self) -> None:
         """Bootstrap cache from SQLite."""
         try:
-            conn = _get_conn()
-            for row in conn.execute("SELECT * FROM custom_models WHERE active = 1").fetchall():
-                self._models[row["name"]] = CustomModel(
-                    name=row["name"],
-                    format=ModelFormat(row["format"]),
-                    path=row["path"],
-                    role=ModelRole(row["role"]),
-                    context_window=row["context_window"],
-                    description=row["description"],
-                    registered_at=row["registered_at"],
-                    active=bool(row["active"]),
-                    default_temperature=row["default_temperature"],
-                    max_tokens=row["max_tokens"],
-                )
-            for row in conn.execute("SELECT * FROM agent_model_assignments").fetchall():
-                self._agent_assignments[row["agent_id"]] = row["model_name"]
-            conn.close()
+            with _get_conn() as conn:
+                for row in conn.execute("SELECT * FROM custom_models WHERE active = 1").fetchall():
+                    self._models[row["name"]] = CustomModel(
+                        name=row["name"],
+                        format=ModelFormat(row["format"]),
+                        path=row["path"],
+                        role=ModelRole(row["role"]),
+                        context_window=row["context_window"],
+                        description=row["description"],
+                        registered_at=row["registered_at"],
+                        active=bool(row["active"]),
+                        default_temperature=row["default_temperature"],
+                        max_tokens=row["max_tokens"],
+                    )
+                for row in conn.execute("SELECT * FROM agent_model_assignments").fetchall():
+                    self._agent_assignments[row["agent_id"]] = row["model_name"]
         except Exception as exc:
             logger.warning("Failed to load model registry from DB: %s", exc)
 
@@ -130,29 +132,28 @@ class ModelRegistry:
     def register(self, model: CustomModel) -> CustomModel:
         """Register a new custom model."""
         with self._lock:
-            conn = _get_conn()
-            conn.execute(
-                """
-                INSERT OR REPLACE INTO custom_models
-                    (name, format, path, role, context_window, description,
-                     registered_at, active, default_temperature, max_tokens)
-                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-                """,
-                (
-                    model.name,
-                    model.format.value,
-                    model.path,
-                    model.role.value,
-                    model.context_window,
-                    model.description,
-                    model.registered_at,
-                    int(model.active),
-                    model.default_temperature,
-                    model.max_tokens,
-                ),
-            )
-            conn.commit()
-            conn.close()
+            with _get_conn() as conn:
+                conn.execute(
+                    """
+                    INSERT OR REPLACE INTO custom_models
+                        (name, format, path, role, context_window, description,
+                         registered_at, active, default_temperature, max_tokens)
+                    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                    """,
+                    (
+                        model.name,
+                        model.format.value,
+                        model.path,
+                        model.role.value,
+                        model.context_window,
+                        model.description,
+                        model.registered_at,
+                        int(model.active),
+                        model.default_temperature,
+                        model.max_tokens,
+                    ),
+                )
+                conn.commit()
             self._models[model.name] = model
             logger.info("Registered model: %s (%s)", model.name, model.format.value)
             return model
@@ -162,11 +163,10 @@ class ModelRegistry:
         with self._lock:
             if name not in self._models:
                 return False
-            conn = _get_conn()
-            conn.execute("DELETE FROM custom_models WHERE name = ?", (name,))
-            conn.execute("DELETE FROM agent_model_assignments WHERE model_name = ?", (name,))
-            conn.commit()
-            conn.close()
+            with _get_conn() as conn:
+                conn.execute("DELETE FROM custom_models WHERE name = ?", (name,))
+                conn.execute("DELETE FROM agent_model_assignments WHERE model_name = ?", (name,))
+                conn.commit()
             del self._models[name]
             # Remove any agent assignments using this model
             self._agent_assignments = {
@@ -193,13 +193,12 @@ class ModelRegistry:
             return False
         with self._lock:
             model.active = active
-            conn = _get_conn()
-            conn.execute(
-                "UPDATE custom_models SET active = ? WHERE name = ?",
-                (int(active), name),
-            )
-            conn.commit()
-            conn.close()
+            with _get_conn() as conn:
+                conn.execute(
+                    "UPDATE custom_models SET active = ? WHERE name = ?",
+                    (int(active), name),
+                )
+                conn.commit()
         return True
 
     # ── Agent-model assignments ────────────────────────────────────────────
@@ -210,17 +209,16 @@ class ModelRegistry:
             return False
         with self._lock:
             now = datetime.now(UTC).isoformat()
-            conn = _get_conn()
-            conn.execute(
-                """
-                INSERT OR REPLACE INTO agent_model_assignments
-                    (agent_id, model_name, assigned_at)
-                VALUES (?, ?, ?)
-                """,
-                (agent_id, model_name, now),
-            )
-            conn.commit()
-            conn.close()
+            with _get_conn() as conn:
+                conn.execute(
+                    """
+                    INSERT OR REPLACE INTO agent_model_assignments
+                        (agent_id, model_name, assigned_at)
+                    VALUES (?, ?, ?)
+                    """,
+                    (agent_id, model_name, now),
+                )
+                conn.commit()
             self._agent_assignments[agent_id] = model_name
             logger.info("Assigned model %s to agent %s", model_name, agent_id)
         return True
@@ -230,13 +228,12 @@ class ModelRegistry:
         with self._lock:
             if agent_id not in self._agent_assignments:
                 return False
-            conn = _get_conn()
-            conn.execute(
-                "DELETE FROM agent_model_assignments WHERE agent_id = ?",
-                (agent_id,),
-            )
-            conn.commit()
-            conn.close()
+            with _get_conn() as conn:
+                conn.execute(
+                    "DELETE FROM agent_model_assignments WHERE agent_id = ?",
+                    (agent_id,),
+                )
+                conn.commit()
             del self._agent_assignments[agent_id]
         return True
 

src/infrastructure/presence.py

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

src/infrastructure/protocol.py

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

src/infrastructure/router/__init__.py

@@ -2,6 +2,7 @@
 
 from .api import router
 from .cascade import CascadeRouter, Provider, ProviderStatus, get_router
+from .history import HealthHistoryStore, get_history_store
 
 __all__ = [
     "CascadeRouter",
@@ -9,4 +10,6 @@ __all__ = [
     "ProviderStatus",
     "get_router",
     "router",
+    "HealthHistoryStore",
+    "get_history_store",
 ]

src/infrastructure/router/api.py

@@ -8,6 +8,7 @@ from fastapi import APIRouter, Depends, HTTPException
 from pydantic import BaseModel
 
 from .cascade import CascadeRouter, get_router
+from .history import HealthHistoryStore, get_history_store
 
 logger = logging.getLogger(__name__)
 router = APIRouter(prefix="/api/v1/router", tags=["router"])
@@ -183,6 +184,33 @@ async def run_health_check(
     }
 
 
+@router.post("/reload")
+async def reload_config(
+    cascade: Annotated[CascadeRouter, Depends(get_cascade_router)],
+) -> dict[str, Any]:
+    """Hot-reload providers.yaml without restart.
+
+    Preserves circuit breaker state and metrics for existing providers.
+    """
+    try:
+        result = cascade.reload_config()
+        return {"status": "ok", **result}
+    except Exception as exc:
+        logger.error("Config reload failed: %s", exc)
+        raise HTTPException(status_code=500, detail=f"Reload failed: {exc}") from exc
+
+
+@router.get("/history")
+async def get_history(
+    hours: int = 24,
+    store: Annotated[HealthHistoryStore, Depends(get_history_store)] = None,
+) -> list[dict[str, Any]]:
+    """Get provider health history for the last N hours."""
+    if store is None:
+        store = get_history_store()
+    return store.get_history(hours=hours)
+
+
 @router.get("/config")
 async def get_config(
     cascade: Annotated[CascadeRouter, Depends(get_cascade_router)],

src/infrastructure/router/cascade.py

@@ -18,6 +18,8 @@ from enum import Enum
 from pathlib import Path
 from typing import Any
 
+from config import settings
+
 try:
     import yaml
 except ImportError:
@@ -100,7 +102,7 @@ class Provider:
     """LLM provider configuration and state."""
 
     name: str
-    type: str  # ollama, openai, anthropic, airllm
+    type: str  # ollama, openai, anthropic
     enabled: bool
     priority: int
     url: str | None = None
@@ -219,65 +221,56 @@ class CascadeRouter:
                 raise RuntimeError("PyYAML not installed")
 
             content = self.config_path.read_text()
-            # Expand environment variables
             content = self._expand_env_vars(content)
             data = yaml.safe_load(content)
 
-            # Load cascade settings
-            cascade = data.get("cascade", {})
-
-            # Load fallback chains
-            fallback_chains = data.get("fallback_chains", {})
-
-            # Load multi-modal settings
-            multimodal = data.get("multimodal", {})
-
-            self.config = RouterConfig(
-                timeout_seconds=cascade.get("timeout_seconds", 30),
-                max_retries_per_provider=cascade.get("max_retries_per_provider", 2),
-                retry_delay_seconds=cascade.get("retry_delay_seconds", 1),
-                circuit_breaker_failure_threshold=cascade.get("circuit_breaker", {}).get(
-                    "failure_threshold", 5
-                ),
-                circuit_breaker_recovery_timeout=cascade.get("circuit_breaker", {}).get(
-                    "recovery_timeout", 60
-                ),
-                circuit_breaker_half_open_max_calls=cascade.get("circuit_breaker", {}).get(
-                    "half_open_max_calls", 2
-                ),
-                auto_pull_models=multimodal.get("auto_pull", True),
-                fallback_chains=fallback_chains,
-            )
-
-            # Load providers
-            for p_data in data.get("providers", []):
-                # Skip disabled providers
-                if not p_data.get("enabled", False):
-                    continue
-
-                provider = Provider(
-                    name=p_data["name"],
-                    type=p_data["type"],
-                    enabled=p_data.get("enabled", True),
-                    priority=p_data.get("priority", 99),
-                    url=p_data.get("url"),
-                    api_key=p_data.get("api_key"),
-                    base_url=p_data.get("base_url"),
-                    models=p_data.get("models", []),
-                )
-
-                # Check if provider is actually available
-                if self._check_provider_available(provider):
-                    self.providers.append(provider)
-                else:
-                    logger.warning("Provider %s not available, skipping", provider.name)
-
-            # Sort by priority
-            self.providers.sort(key=lambda p: p.priority)
+            self.config = self._parse_router_config(data)
+            self._load_providers(data)
 
         except Exception as exc:
             logger.error("Failed to load config: %s", exc)
 
+    def _parse_router_config(self, data: dict) -> RouterConfig:
+        """Build a RouterConfig from parsed YAML data."""
+        cascade = data.get("cascade", {})
+        cb = cascade.get("circuit_breaker", {})
+        multimodal = data.get("multimodal", {})
+
+        return RouterConfig(
+            timeout_seconds=cascade.get("timeout_seconds", 30),
+            max_retries_per_provider=cascade.get("max_retries_per_provider", 2),
+            retry_delay_seconds=cascade.get("retry_delay_seconds", 1),
+            circuit_breaker_failure_threshold=cb.get("failure_threshold", 5),
+            circuit_breaker_recovery_timeout=cb.get("recovery_timeout", 60),
+            circuit_breaker_half_open_max_calls=cb.get("half_open_max_calls", 2),
+            auto_pull_models=multimodal.get("auto_pull", True),
+            fallback_chains=data.get("fallback_chains", {}),
+        )
+
+    def _load_providers(self, data: dict) -> None:
+        """Load, filter, and sort providers from parsed YAML data."""
+        for p_data in data.get("providers", []):
+            if not p_data.get("enabled", False):
+                continue
+
+            provider = Provider(
+                name=p_data["name"],
+                type=p_data["type"],
+                enabled=p_data.get("enabled", True),
+                priority=p_data.get("priority", 99),
+                url=p_data.get("url"),
+                api_key=p_data.get("api_key"),
+                base_url=p_data.get("base_url"),
+                models=p_data.get("models", []),
+            )
+
+            if self._check_provider_available(provider):
+                self.providers.append(provider)
+            else:
+                logger.warning("Provider %s not available, skipping", provider.name)
+
+        self.providers.sort(key=lambda p: p.priority)
+
     def _expand_env_vars(self, content: str) -> str:
         """Expand ${VAR} syntax in YAML content.
 
@@ -301,19 +294,11 @@ class CascadeRouter:
                 # Can't check without requests, assume available
                 return True
             try:
-                url = provider.url or "http://localhost:11434"
+                url = provider.url or settings.ollama_url
                 response = requests.get(f"{url}/api/tags", timeout=5)
                 return response.status_code == 200
-            except Exception:
-                return False
-
-        elif provider.type == "airllm":
-            # Check if airllm is installed
-            try:
-                import importlib.util
-
-                return importlib.util.find_spec("airllm") is not None
-            except (ImportError, ModuleNotFoundError):
+            except Exception as exc:
+                logger.debug("Ollama provider check error: %s", exc)
                 return False
 
         elif provider.type in ("openai", "anthropic", "grok"):
@@ -394,6 +379,101 @@ class CascadeRouter:
 
         return None
 
+    def _select_model(
+        self, provider: Provider, model: str | None, content_type: ContentType
+    ) -> tuple[str | None, bool]:
+        """Select the best model for the request, with vision fallback.
+
+        Returns:
+            Tuple of (selected_model, is_fallback_model).
+        """
+        selected_model = model or provider.get_default_model()
+        is_fallback = False
+
+        if content_type != ContentType.TEXT and selected_model:
+            if provider.type == "ollama" and self._mm_manager:
+                from infrastructure.models.multimodal import ModelCapability
+
+                if content_type == ContentType.VISION:
+                    supports = self._mm_manager.model_supports(
+                        selected_model, ModelCapability.VISION
+                    )
+                    if not supports:
+                        fallback = self._get_fallback_model(provider, selected_model, content_type)
+                        if fallback:
+                            logger.info(
+                                "Model %s doesn't support vision, falling back to %s",
+                                selected_model,
+                                fallback,
+                            )
+                            selected_model = fallback
+                            is_fallback = True
+                        else:
+                            logger.warning(
+                                "No vision-capable model found on %s, trying anyway",
+                                provider.name,
+                            )
+
+        return selected_model, is_fallback
+
+    async def _attempt_with_retry(
+        self,
+        provider: Provider,
+        messages: list[dict],
+        model: str | None,
+        temperature: float,
+        max_tokens: int | None,
+        content_type: ContentType,
+    ) -> dict:
+        """Try a provider with retries, returning the result dict.
+
+        Raises:
+            RuntimeError: If all retry attempts fail.
+            Returns error strings collected during retries via the exception message.
+        """
+        errors: list[str] = []
+        for attempt in range(self.config.max_retries_per_provider):
+            try:
+                return await self._try_provider(
+                    provider=provider,
+                    messages=messages,
+                    model=model,
+                    temperature=temperature,
+                    max_tokens=max_tokens,
+                    content_type=content_type,
+                )
+            except Exception as exc:
+                error_msg = str(exc)
+                logger.warning(
+                    "Provider %s attempt %d failed: %s",
+                    provider.name,
+                    attempt + 1,
+                    error_msg,
+                )
+                errors.append(f"{provider.name}: {error_msg}")
+
+                if attempt < self.config.max_retries_per_provider - 1:
+                    await asyncio.sleep(self.config.retry_delay_seconds)
+
+        raise RuntimeError("; ".join(errors))
+
+    def _is_provider_available(self, provider: Provider) -> bool:
+        """Check if a provider should be tried (enabled + circuit breaker)."""
+        if not provider.enabled:
+            logger.debug("Skipping %s (disabled)", provider.name)
+            return False
+
+        if provider.status == ProviderStatus.UNHEALTHY:
+            if self._can_close_circuit(provider):
+                provider.circuit_state = CircuitState.HALF_OPEN
+                provider.half_open_calls = 0
+                logger.info("Circuit breaker half-open for %s", provider.name)
+            else:
+                logger.debug("Skipping %s (circuit open)", provider.name)
+                return False
+
+        return True
+
     async def complete(
         self,
         messages: list[dict],
@@ -420,7 +500,6 @@ class CascadeRouter:
         Raises:
             RuntimeError: If all providers fail
         """
-        # Detect content type for multi-modal routing
         content_type = self._detect_content_type(messages)
         if content_type != ContentType.TEXT:
             logger.debug("Detected %s content, selecting appropriate model", content_type.value)
@@ -428,93 +507,34 @@ class CascadeRouter:
         errors = []
 
         for provider in self.providers:
-            # Skip disabled providers
-            if not provider.enabled:
-                logger.debug("Skipping %s (disabled)", provider.name)
+            if not self._is_provider_available(provider):
                 continue
 
-            # Skip unhealthy providers (circuit breaker)
-            if provider.status == ProviderStatus.UNHEALTHY:
-                # Check if circuit breaker can close
-                if self._can_close_circuit(provider):
-                    provider.circuit_state = CircuitState.HALF_OPEN
-                    provider.half_open_calls = 0
-                    logger.info("Circuit breaker half-open for %s", provider.name)
-                else:
-                    logger.debug("Skipping %s (circuit open)", provider.name)
-                    continue
+            selected_model, is_fallback_model = self._select_model(provider, model, content_type)
 
-            # Determine which model to use
-            selected_model = model or provider.get_default_model()
-            is_fallback_model = False
+            try:
+                result = await self._attempt_with_retry(
+                    provider,
+                    messages,
+                    selected_model,
+                    temperature,
+                    max_tokens,
+                    content_type,
+                )
+            except RuntimeError as exc:
+                errors.append(str(exc))
+                self._record_failure(provider)
+                continue
 
-            # For non-text content, check if model supports it
-            if content_type != ContentType.TEXT and selected_model:
-                if provider.type == "ollama" and self._mm_manager:
-                    from infrastructure.models.multimodal import ModelCapability
+            self._record_success(provider, result.get("latency_ms", 0))
+            return {
+                "content": result["content"],
+                "provider": provider.name,
+                "model": result.get("model", selected_model or provider.get_default_model()),
+                "latency_ms": result.get("latency_ms", 0),
+                "is_fallback_model": is_fallback_model,
+            }
 
-                    # Check if selected model supports the required capability
-                    if content_type == ContentType.VISION:
-                        supports = self._mm_manager.model_supports(
-                            selected_model, ModelCapability.VISION
-                        )
-                        if not supports:
-                            # Find fallback model
-                            fallback = self._get_fallback_model(
-                                provider, selected_model, content_type
-                            )
-                            if fallback:
-                                logger.info(
-                                    "Model %s doesn't support vision, falling back to %s",
-                                    selected_model,
-                                    fallback,
-                                )
-                                selected_model = fallback
-                                is_fallback_model = True
-                            else:
-                                logger.warning(
-                                    "No vision-capable model found on %s, trying anyway",
-                                    provider.name,
-                                )
-
-            # Try this provider
-            for attempt in range(self.config.max_retries_per_provider):
-                try:
-                    result = await self._try_provider(
-                        provider=provider,
-                        messages=messages,
-                        model=selected_model,
-                        temperature=temperature,
-                        max_tokens=max_tokens,
-                        content_type=content_type,
-                    )
-
-                    # Success! Update metrics and return
-                    self._record_success(provider, result.get("latency_ms", 0))
-                    return {
-                        "content": result["content"],
-                        "provider": provider.name,
-                        "model": result.get(
-                            "model", selected_model or provider.get_default_model()
-                        ),
-                        "latency_ms": result.get("latency_ms", 0),
-                        "is_fallback_model": is_fallback_model,
-                    }
-
-                except Exception as exc:
-                    error_msg = str(exc)
-                    logger.warning(
-                        "Provider %s attempt %d failed: %s", provider.name, attempt + 1, error_msg
-                    )
-                    errors.append(f"{provider.name}: {error_msg}")
-
-                    if attempt < self.config.max_retries_per_provider - 1:
-                        await asyncio.sleep(self.config.retry_delay_seconds)
-
-            # All retries failed for this provider
-            self._record_failure(provider)
-
-        # All providers failed
         raise RuntimeError(f"All providers failed: {'; '.join(errors)}")
 
     async def _try_provider(
@@ -535,6 +555,7 @@ class CascadeRouter:
                 messages=messages,
                 model=model or provider.get_default_model(),
                 temperature=temperature,
+                max_tokens=max_tokens,
                 content_type=content_type,
             )
         elif provider.type == "openai":
@@ -575,23 +596,26 @@ class CascadeRouter:
         messages: list[dict],
         model: str,
         temperature: float,
+        max_tokens: int | None = None,
         content_type: ContentType = ContentType.TEXT,
     ) -> dict:
         """Call Ollama API with multi-modal support."""
         import aiohttp
 
-        url = f"{provider.url}/api/chat"
+        url = f"{provider.url or settings.ollama_url}/api/chat"
 
         # Transform messages for Ollama format (including images)
         transformed_messages = self._transform_messages_for_ollama(messages)
 
+        options = {"temperature": temperature}
+        if max_tokens:
+            options["num_predict"] = max_tokens
+
         payload = {
             "model": model,
             "messages": transformed_messages,
             "stream": False,
-            "options": {
-                "temperature": temperature,
-            },
+            "options": options,
         }
 
         timeout = aiohttp.ClientTimeout(total=self.config.timeout_seconds)
@@ -735,7 +759,7 @@ class CascadeRouter:
 
         client = openai.AsyncOpenAI(
             api_key=provider.api_key,
-            base_url=provider.base_url or "https://api.x.ai/v1",
+            base_url=provider.base_url or settings.xai_base_url,
             timeout=httpx.Timeout(300.0),
         )
 
@@ -814,6 +838,66 @@ class CascadeRouter:
         provider.status = ProviderStatus.HEALTHY
         logger.info("Circuit breaker CLOSED for %s", provider.name)
 
+    def reload_config(self) -> dict:
+        """Hot-reload providers.yaml, preserving runtime state.
+
+        Re-reads the config file, rebuilds the provider list, and
+        preserves circuit breaker state and metrics for providers
+        that still exist after reload.
+
+        Returns:
+            Summary dict with added/removed/preserved counts.
+        """
+        # Snapshot current runtime state keyed by provider name
+        old_state: dict[
+            str, tuple[ProviderMetrics, CircuitState, float | None, int, ProviderStatus]
+        ] = {}
+        for p in self.providers:
+            old_state[p.name] = (
+                p.metrics,
+                p.circuit_state,
+                p.circuit_opened_at,
+                p.half_open_calls,
+                p.status,
+            )
+
+        old_names = set(old_state.keys())
+
+        # Reload from disk
+        self.providers = []
+        self._load_config()
+
+        # Restore preserved state
+        new_names = {p.name for p in self.providers}
+        preserved = 0
+        for p in self.providers:
+            if p.name in old_state:
+                metrics, circuit, opened_at, half_open, status = old_state[p.name]
+                p.metrics = metrics
+                p.circuit_state = circuit
+                p.circuit_opened_at = opened_at
+                p.half_open_calls = half_open
+                p.status = status
+                preserved += 1
+
+        added = new_names - old_names
+        removed = old_names - new_names
+
+        logger.info(
+            "Config reloaded: %d providers (%d preserved, %d added, %d removed)",
+            len(self.providers),
+            preserved,
+            len(added),
+            len(removed),
+        )
+
+        return {
+            "total_providers": len(self.providers),
+            "preserved": preserved,
+            "added": sorted(added),
+            "removed": sorted(removed),
+        }
+
     def get_metrics(self) -> dict:
         """Get metrics for all providers."""
         return {

src/infrastructure/router/history.py

@@ -0,0 +1,152 @@
+"""Provider health history — time-series snapshots for dashboard visualization."""
+
+import asyncio
+import logging
+import sqlite3
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+_store: "HealthHistoryStore | None" = None
+
+
+class HealthHistoryStore:
+    """Stores timestamped provider health snapshots in SQLite."""
+
+    def __init__(self, db_path: str = "data/router_history.db") -> None:
+        self.db_path = db_path
+        if db_path != ":memory:":
+            Path(db_path).parent.mkdir(parents=True, exist_ok=True)
+        self._conn = sqlite3.connect(db_path, check_same_thread=False)
+        self._conn.row_factory = sqlite3.Row
+        self._init_schema()
+        self._bg_task: asyncio.Task | None = None
+
+    def _init_schema(self) -> None:
+        self._conn.execute("""
+            CREATE TABLE IF NOT EXISTS snapshots (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                timestamp TEXT NOT NULL,
+                provider_name TEXT NOT NULL,
+                status TEXT NOT NULL,
+                error_rate REAL NOT NULL,
+                avg_latency_ms REAL NOT NULL,
+                circuit_state TEXT NOT NULL,
+                total_requests INTEGER NOT NULL
+            )
+        """)
+        self._conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_snapshots_ts
+            ON snapshots(timestamp)
+        """)
+        self._conn.commit()
+
+    def record_snapshot(self, providers: list[dict]) -> None:
+        """Record a health snapshot for all providers."""
+        ts = datetime.now(UTC).isoformat()
+        rows = [
+            (
+                ts,
+                p["name"],
+                p["status"],
+                p["error_rate"],
+                p["avg_latency_ms"],
+                p["circuit_state"],
+                p["total_requests"],
+            )
+            for p in providers
+        ]
+        self._conn.executemany(
+            """INSERT INTO snapshots
+               (timestamp, provider_name, status, error_rate,
+                avg_latency_ms, circuit_state, total_requests)
+               VALUES (?, ?, ?, ?, ?, ?, ?)""",
+            rows,
+        )
+        self._conn.commit()
+
+    def get_history(self, hours: int = 24) -> list[dict]:
+        """Return snapshots from the last N hours, grouped by timestamp."""
+        cutoff = (datetime.now(UTC) - timedelta(hours=hours)).isoformat()
+        rows = self._conn.execute(
+            """SELECT timestamp, provider_name, status, error_rate,
+                      avg_latency_ms, circuit_state, total_requests
+               FROM snapshots WHERE timestamp >= ? ORDER BY timestamp""",
+            (cutoff,),
+        ).fetchall()
+
+        # Group by timestamp
+        snapshots: dict[str, list[dict]] = {}
+        for row in rows:
+            ts = row["timestamp"]
+            if ts not in snapshots:
+                snapshots[ts] = []
+            snapshots[ts].append(
+                {
+                    "name": row["provider_name"],
+                    "status": row["status"],
+                    "error_rate": row["error_rate"],
+                    "avg_latency_ms": row["avg_latency_ms"],
+                    "circuit_state": row["circuit_state"],
+                    "total_requests": row["total_requests"],
+                }
+            )
+
+        return [{"timestamp": ts, "providers": providers} for ts, providers in snapshots.items()]
+
+    def prune(self, keep_hours: int = 168) -> int:
+        """Remove snapshots older than keep_hours. Returns rows deleted."""
+        cutoff = (datetime.now(UTC) - timedelta(hours=keep_hours)).isoformat()
+        cursor = self._conn.execute("DELETE FROM snapshots WHERE timestamp < ?", (cutoff,))
+        self._conn.commit()
+        return cursor.rowcount
+
+    def close(self) -> None:
+        """Close the database connection."""
+        if self._bg_task and not self._bg_task.done():
+            self._bg_task.cancel()
+        self._conn.close()
+
+    def _capture_snapshot(self, cascade_router) -> None:  # noqa: ANN001
+        """Capture current provider state as a snapshot."""
+        providers = []
+        for p in cascade_router.providers:
+            providers.append(
+                {
+                    "name": p.name,
+                    "status": p.status.value,
+                    "error_rate": round(p.metrics.error_rate, 4),
+                    "avg_latency_ms": round(p.metrics.avg_latency_ms, 2),
+                    "circuit_state": p.circuit_state.value,
+                    "total_requests": p.metrics.total_requests,
+                }
+            )
+        self.record_snapshot(providers)
+
+    async def start_background_task(
+        self,
+        cascade_router,
+        interval_seconds: int = 60,  # noqa: ANN001
+    ) -> None:
+        """Start periodic snapshot capture."""
+
+        async def _loop() -> None:
+            while True:
+                try:
+                    self._capture_snapshot(cascade_router)
+                    logger.debug("Recorded health snapshot")
+                except Exception:
+                    logger.exception("Failed to record health snapshot")
+                await asyncio.sleep(interval_seconds)
+
+        self._bg_task = asyncio.create_task(_loop())
+        logger.info("Health history background task started (interval=%ds)", interval_seconds)
+
+
+def get_history_store() -> HealthHistoryStore:
+    """Get or create the singleton history store."""
+    global _store  # noqa: PLW0603
+    if _store is None:
+        _store = HealthHistoryStore()
+    return _store

src/infrastructure/visitor.py

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

src/infrastructure/world/__init__.py

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