chore: bump version to 0.5.6

Prompt template runtime wiring, security hardening, scheduler/channel/MQ
template support, migration 010.

.github/workflows/publish.yml

@@ -5,6 +5,7 @@ on:
     tags: ["v*"]
 
 permissions:
+  contents: write
   id-token: write
 
 jobs:
@@ -19,3 +20,10 @@ jobs:
       - run: pip install build
       - run: python -m build
       - uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          draft: false
+          prerelease: ${{ contains(github.ref, '-') }}

QUICKSTART.md

@@ -0,0 +1,92 @@
+# Bootstrap Wizard
+
+Interactive, AI-guided setup for Turnstone deployments. Instead of manually
+editing `.env` files and reading deployment docs, the wizard walks you through
+every decision conversationally and generates all the config files for you.
+
+## Quick Start
+
+```bash
+turnstone-bootstrap
+```
+
+That's it — no flags, no arguments. The wizard prompts for everything.
+
+## How It Works
+
+1. **Pick a model** — Choose OpenAI, Anthropic, or a local/vLLM endpoint to
+   power the wizard. Local endpoints auto-detect available models.
+2. **Answer questions** — The AI walks you through deployment mode, LLM
+   provider, database, authentication, ports, and optional features.
+3. **Review generated files** — Each file is previewed before writing. You
+   confirm or reject every write.
+4. **Start the stack** — The wizard prints the exact `docker compose` command
+   and a `setup.sh` script to create your first admin user, roles, and policies.
+
+## What Gets Generated
+
+| File | Purpose |
+|------|---------|
+| `.env` | All environment variables for `compose.yaml` |
+| `setup.sh` | Post-start script: creates admin user, roles, tool policies, prompt templates via the API |
+| `docker-compose.override.yaml` | Only if customizations beyond env vars are needed |
+
+## Requirements
+
+- **Python 3.11+** with turnstone installed (`pip install turnstone`)
+- **An LLM API key** — for the wizard itself (OpenAI, Anthropic, or a local
+  model). This can differ from the LLM your deployment will use.
+- **Docker & Docker Compose** — needed to run the stack. The wizard detects
+  whether Docker is installed and gives platform-specific install instructions
+  if it's missing. You can still generate config files without Docker.
+
+## Deployment Modes
+
+The wizard supports two deployment modes:
+
+- **Single-node production** (`docker compose --profile production up`) —
+  1 server + bridge + console + PostgreSQL + Redis. Good for most use cases.
+- **Multi-node cluster** (`docker compose --profile cluster up`) —
+  10-node server/bridge fleet + PostgreSQL + Redis. For high-throughput or
+  HA deployments.
+
+## Example Session
+
+```
+$ turnstone-bootstrap
+
+ Turnstone Bootstrap Wizard  v0.5.4
+ ────────────────────────────────────────────────
+
+ Which provider for this wizard?
+   [1] OpenAI
+   [2] Anthropic
+   [3] OpenAI-compatible (local/vLLM)
+
+ > 3
+
+ Base URL [http://localhost:8000/v1]:
+ API key (press Enter for 'none'):
+
+ Querying http://localhost:8000/v1 for available models...
+ Found model: Qwen/Qwen3-32B
+
+ Connected to Qwen/Qwen3-32B. Handing off to AI assistant...
+
+> (AI walks you through the rest interactively)
+```
+
+## Tips
+
+- **Re-run safely** — running the wizard again detects your existing `.env`
+  and offers to update it rather than overwriting.
+- **Duplicate writes are skipped** — if the LLM tries to write the same file
+  twice with identical content, it's silently ignored.
+- **Type `quit` to exit** at any time during the conversation.
+- **Ctrl+C** is handled gracefully — press once to interrupt, twice to exit.
+
+## See Also
+
+- [Docker Deployment](docker.md) — manual compose setup and profiles
+- [Security](security.md) — auth architecture and token types
+- [Governance](governance.md) — roles, policies, and templates

README.md

@@ -11,61 +11,18 @@ Named after the [Ruddy Turnstone](https://en.wikipedia.org/wiki/Ruddy_turnstone)
 
 ## What it does
 
-Turnstone gives LLMs tools — shell, files, search, web, planning — and orchestrates multi-turn conversations where the model investigates, acts, and reports. It runs as:
+Turnstone gives LLMs tools — shell, files, search, web, planning — and orchestrates multi-turn conversations where the model investigates, acts, and reports. Native deferred tool loading for Anthropic and OpenAI APIs reduces token overhead and improves tool selection accuracy when MCP servers expose many tools; local models (vLLM, llama.cpp) get a transparent client-side BM25 fallback. It runs as:
 
 - **Interactive sessions** — terminal CLI or browser UI with parallel workstreams
 - **Queue-driven agents** — trigger workstreams via message queue, stream progress, approve or auto-approve tool use
 - **Multi-node clusters** — generic work load-balances across nodes, directed work routes to a specific server
 - **Cluster dashboard** — real-time view of all nodes and workstreams, workstream creation with node targeting, reverse proxy for server UIs (only the console port needs network access)
+- **Governance & compliance** — role-based access control, tool policies, usage tracking, and append-only audit logs
 - **Cluster simulator** — test the stack at scale (up to 1000 nodes) without an LLM backend
 
-```mermaid
-graph LR
-    subgraph Clients
-        CLI[turnstone CLI]
-        UI[Browser UI]
-        SDK[SDK / API]
-        Discord[Discord / Slack]
-    end
-
-    Console[turnstone-console<br/><i>dashboard + proxy</i>]
-    Channel[turnstone-channel<br/><i>platform gateway</i>]
-
-    subgraph Cluster
-        Redis[(Redis MQ)]
-        DB[(PostgreSQL / SQLite)]
-
-        subgraph Node A
-            BridgeA[bridge]
-            ServerA[server]
-        end
-        subgraph Node B
-            BridgeB[bridge]
-            ServerB[server]
-        end
-    end
-
-    LLM[LLM Provider<br/><i>OpenAI · Anthropic · local</i>]
-
-    CLI --> ServerA
-    UI --> ServerB
-    SDK --> Redis
-    Discord --> Channel
-
-    Channel <--> Redis
-    Console --> Redis
-    Redis --> BridgeA & BridgeB
-    BridgeA --> ServerA
-    BridgeB --> ServerB
-    ServerA & ServerB --> LLM
-
-    ServerA & ServerB --> DB
-    Console --> DB
-    Channel --> DB
-    ServerA -.->|notify| Channel
-    BridgeA & BridgeB -.->|events| Redis
-    Console -.->|proxy| ServerA & ServerB
-```
+<p align="center">
+  <img src="docs/diagrams/architecture-overview.svg" alt="Turnstone system architecture — data flow from clients through gateways, Redis MQ, cluster nodes, to LLM providers" width="960"/>
+</p>
 
 ## Quickstart
 
@@ -171,6 +128,23 @@ Detailed UML diagrams are available in [`docs/diagrams/`](docs/diagrams/):
 | [Deployment](docs/diagrams/png/12-deployment.png) | Docker Compose service topology |
 | [SDK Architecture](docs/diagrams/png/13-sdk-architecture.png) | Python + TypeScript client libraries |
 | [Storage Architecture](docs/diagrams/png/14-storage-architecture.png) | Pluggable database backends (SQLite + PostgreSQL) |
+| [Auth Architecture](docs/diagrams/png/15-auth-architecture.png) | JWT, scopes, token types, login flows |
+| [Channel Architecture](docs/diagrams/png/16-channel-architecture.png) | Discord/Slack adapter protocol and routing |
+| [Notify Flow](docs/diagrams/png/17-notify-flow.png) | Channel notification dispatch |
+| [Watch Architecture](docs/diagrams/png/18-watch-architecture.png) | Periodic command polling daemon |
+| [Governance Architecture](docs/diagrams/png/19-governance-architecture.png) | RBAC, policies, audit, usage enforcement flow |
+
+### Governance
+
+Turnstone includes a built-in governance layer for enterprise deployments — manage who can do what, which tools run unattended, and where every token goes.
+
+- **RBAC** — 15 granular permissions, 3 built-in roles (admin / operator / viewer), custom roles, privilege escalation prevention
+- **Tool policies** — glob-pattern rules (`allow` / `deny` / `ask`) with priority ordering; automate approvals or lock down dangerous tools
+- **Prompt templates** — reusable system messages with `{{variable}}` substitution and categories
+- **Usage tracking** — per-request token and tool metrics, aggregation by day / model / user, automatic 90-day pruning
+- **Audit logging** — append-only event trail for all admin mutations, IP-aware, 365-day retention
+
+All governance features are managed through the console admin panel (10 tabs) and the full REST API. See [docs/governance.md](docs/governance.md) for setup and configuration.
 
 ## Multi-node routing
 
@@ -195,12 +169,12 @@ Bridges BLPOP from their per-node queue (priority) then the shared queue. Direct
 
 ## Tools
 
-14 built-in tools, 2 agent tools, plus external tools via MCP:
+16 built-in tools, 2 agent tools, plus external tools via MCP:
 
 | Tool | Description | Auto-approved |
 |------|-------------|:---:|
 | `bash` | Execute shell commands | |
-| `read_file` | Read file contents | yes |
+| `read_file` | Read file contents (text or images with vision models) | yes |
 | `write_file` | Write/create files | |
 | `edit_file` | Fuzzy-match file editing | |
 | `search` | Search files by name/content | yes |
@@ -211,13 +185,17 @@ Bridges BLPOP from their per-node queue (priority) then the shared queue. Direct
 | `remember` | Save persistent facts | yes |
 | `recall` | Search memories and history | yes |
 | `forget` | Remove a memory | yes |
+| `notify` | Send notifications to linked channels | yes |
+| `watch` | Periodic command polling with conditions | |
 | `task` | Spawn autonomous sub-agent | |
 | `plan` | Explore codebase, write .plan.md | |
 | `mcp__*` | External tools from MCP servers | |
 
+When the total tool count exceeds a configurable threshold (default 20), MCP tools are automatically deferred using native `defer_loading` on Anthropic and OpenAI APIs, or a transparent client-side BM25 search for local models. The LLM discovers deferred tools on demand via a `tool_search` capability — no configuration needed beyond `--tool-search auto` (the default).
+
 ### MCP Tool Servers
 
-Turnstone supports the [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) for connecting external tool servers. MCP tools are discovered at startup, converted to OpenAI function-calling format, and merged with built-in tools. Each MCP tool is prefixed with `mcp__{server}__{tool}` to avoid name collisions.
+Turnstone supports the [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) for connecting external tool servers. MCP tools are discovered at startup, converted to OpenAI function-calling format, and merged with built-in tools. Each MCP tool is prefixed with `mcp__{server}__{tool}` to avoid name collisions. Tool lists stay fresh via push notifications (`tools.listChanged`), periodic polling for servers without push, and manual `/mcp refresh`.
 
 Configure via `config.toml` or `--mcp-config`:
 
@@ -237,7 +215,7 @@ turnstone --mcp-config ~/.config/turnstone/mcp.json
 turnstone-server --mcp-config ~/.config/turnstone/mcp.json
 ```
 
-Use `/mcp` in the REPL to list connected tools. MCP tools require user approval by default (overridden by `--skip-permissions` or UI auto-approve).
+Use `/mcp` in the REPL to list connected tools, `/mcp refresh` to re-fetch tool lists from servers. MCP tools require user approval by default (overridden by `--skip-permissions` or UI auto-approve).
 
 ### Multi-Model and Multi-Provider Support
 
@@ -292,6 +270,9 @@ agent_model = ""       # model alias for plan/task sub-agents
 [tools]
 timeout = 30
 skip_permissions = false
+search = "auto"            # "auto" (enable when >threshold tools), "on", "off"
+search_threshold = 20      # min tools before tool search activates
+search_max_results = 5     # max tools returned per search query
 
 [server]
 host = "0.0.0.0"
@@ -332,6 +313,7 @@ path = ".turnstone.db" # SQLite file path (relative to working directory)
 
 [mcp]
 config_path = ""       # path to MCP JSON config file (alternative to TOML sections)
+refresh_interval = 14400  # periodic refresh for servers without push notifications (seconds, 0 to disable)
 
 [mcp.servers.example]  # one section per MCP server
 command = "npx"

compose.yaml

@@ -2,11 +2,12 @@
 # Turnstone Docker Compose Stack
 #
 # Usage:
-#   Default (SQLite):     docker compose up
+#   Infra only:           docker compose up
+#   Single node:          docker compose --profile production up
 #   Production (PG):      DB_BACKEND=postgresql docker compose --profile production up
-#                         (or set DB_BACKEND=postgresql in .env)
+#   10-node cluster:      docker compose --profile cluster up
+#   Cluster + DDG:        docker compose --profile ddgCluster up
 #   With simulator:       docker compose --profile sim up
-#   Scale bridges:        docker compose up --scale bridge=3
 # =============================================================================
 
 name: turnstone
@@ -28,6 +29,8 @@ services:
     image: postgres:17-alpine
     profiles:
       - production
+      - cluster
+      - ddgCluster
     environment:
       POSTGRES_DB: turnstone
       POSTGRES_USER: ${POSTGRES_USER:-turnstone}
@@ -87,6 +90,8 @@ services:
     build:
       context: .
       dockerfile: Dockerfile
+    profiles:
+      - production
     command:
       - sh
       - -c
@@ -98,10 +103,12 @@ services:
         --api-key "$${OPENAI_API_KEY}"
         $${MODEL:+--model $$MODEL}
         $${SKIP_PERMISSIONS:+--skip-permissions}
+        $${MCP_CONFIG:+--mcp-config $$MCP_CONFIG}
     ports:
       - "${SERVER_PORT:-8080}:8080"
     volumes:
       - turnstone-data:/data
+      - ./docker/mcp-ddg.json:/etc/turnstone/mcp-ddg.json:ro
     environment:
       - LLM_BASE_URL=${LLM_BASE_URL:-http://host.docker.internal:8000/v1}
       - OPENAI_API_KEY=${OPENAI_API_KEY:-dummy}
@@ -111,6 +118,7 @@ services:
       - TURNSTONE_AUTH_TOKEN=${TURNSTONE_AUTH_TOKEN:-}
       - TURNSTONE_JWT_SECRET=${TURNSTONE_JWT_SECRET:-}
       - MODEL=${MODEL:-}
+      - MCP_CONFIG=${MCP_CONFIG:-}
       - TURNSTONE_DB_BACKEND=${DB_BACKEND:-sqlite}
       - TURNSTONE_DB_URL=${DATABASE_URL:-}
       - TURNSTONE_NODE_ID=${TURNSTONE_NODE_ID:-}
@@ -124,6 +132,9 @@ services:
       postgres:
         condition: service_healthy
         required: false
+      ddg-search:
+        condition: service_healthy
+        required: false
     healthcheck:
       test: ["CMD", "python", "/usr/local/bin/healthcheck.py", "http://127.0.0.1:8080/health"]
       interval: 10s
@@ -140,6 +151,8 @@ services:
     build:
       context: .
       dockerfile: Dockerfile
+    profiles:
+      - production
     command:
       - turnstone-bridge
       - --server-url=http://server:8080
@@ -206,6 +219,8 @@ services:
       dockerfile: Dockerfile
     profiles:
       - production
+      - cluster
+      - ddgCluster
     command:
       - sh
       - -c
@@ -233,6 +248,39 @@ services:
         required: false
     restart: unless-stopped
 
+  # -------------------------------------------------------------------
+  # ddg-search — DuckDuckGo Search MCP server (HTTP transport)
+  # Provides web search + content fetch tools to turnstone via MCP.
+  # No API key required.
+  #
+  # Start with: MCP_CONFIG=/etc/turnstone/mcp-ddg.json \
+  #             docker compose --profile ddgCluster up
+  # -------------------------------------------------------------------
+  ddg-search:
+    image: python:3.13-slim
+    profiles:
+      - ddgCluster
+    command:
+      - sh
+      - -c
+      - >-
+        pip install --no-cache-dir duckduckgo-mcp-server &&
+        python -c "from mcp.server.transport_security import TransportSecuritySettings; import duckduckgo_mcp_server.server as s; s.safe_search=s.SafeSearchMode.OFF; s.mcp.settings.host='0.0.0.0'; s.mcp.settings.port=3000; s.mcp.settings.transport_security=TransportSecuritySettings(enable_dns_rebinding_protection=False); s.mcp.run(transport='streamable-http')"
+    networks:
+      - turnstone-net
+    healthcheck:
+      test: ["CMD-SHELL", "python -c \"import socket; s=socket.create_connection(('0.0.0.0',3000),2); s.close()\""]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+      start_period: 30s
+    deploy:
+      resources:
+        limits:
+          memory: 256M
+          cpus: '0.25'
+    restart: unless-stopped
+
   # -------------------------------------------------------------------
   # turnstone-sim — Multi-node cluster simulator (no LLM needed)
   # Start with: docker compose --profile sim up
@@ -272,3 +320,224 @@ services:
       redis:
         condition: service_healthy
     restart: "no"
+
+  # ===================================================================
+  # 10-node cluster (profile: cluster)
+  #
+  # Each node is a server + bridge pair.  All share the same PostgreSQL
+  # and Redis instances.  Access via console at :8090.
+  #
+  # Start:  docker compose --profile cluster up
+  # ===================================================================
+
+  # -- cluster servers ------------------------------------------------
+
+  server-1: &cluster-server
+    build: { context: ., dockerfile: Dockerfile }
+    profiles: [cluster, ddgCluster]
+    command: &cluster-server-cmd
+      - sh
+      - -c
+      - >-
+        turnstone-server
+        --host 0.0.0.0
+        --port 8080
+        --base-url "$${LLM_BASE_URL}"
+        --api-key "$${OPENAI_API_KEY}"
+        $${MODEL:+--model $$MODEL}
+        $${SKIP_PERMISSIONS:+--skip-permissions}
+        $${MCP_CONFIG:+--mcp-config $$MCP_CONFIG}
+    volumes:
+      - turnstone-data:/data
+      - ./docker/mcp-ddg.json:/etc/turnstone/mcp-ddg.json:ro
+    environment: &cluster-server-env
+      LLM_BASE_URL: ${LLM_BASE_URL:-http://host.docker.internal:8000/v1}
+      OPENAI_API_KEY: ${OPENAI_API_KEY:-dummy}
+      TAVILY_API_KEY: ${TAVILY_API_KEY:-}
+      SKIP_PERMISSIONS: ${SKIP_PERMISSIONS:-}
+      TURNSTONE_AUTH_ENABLED: ${TURNSTONE_AUTH_ENABLED:-}
+      TURNSTONE_AUTH_TOKEN: ${TURNSTONE_AUTH_TOKEN:-}
+      TURNSTONE_JWT_SECRET: ${TURNSTONE_JWT_SECRET:-}
+      MODEL: ${MODEL:-}
+      MCP_CONFIG: ${MCP_CONFIG:-}
+      TURNSTONE_DB_BACKEND: ${DB_BACKEND:-postgresql}
+      TURNSTONE_DB_URL: ${DATABASE_URL:-postgresql://${POSTGRES_USER:-turnstone}:${POSTGRES_PASSWORD:?}@postgres:5432/turnstone}
+      TURNSTONE_NODE_ID: node-1
+    extra_hosts: ["host.docker.internal:host-gateway"]
+    networks: [turnstone-net]
+    depends_on:
+      redis: { condition: service_healthy }
+      postgres: { condition: service_healthy }
+      ddg-search: { condition: service_healthy, required: false }
+    healthcheck:
+      test: ["CMD", "python", "/usr/local/bin/healthcheck.py", "http://127.0.0.1:8080/health"]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+      start_period: 15s
+    deploy:
+      resources:
+        limits: { memory: 384M, cpus: '0.5' }
+    restart: unless-stopped
+
+  server-2:
+    <<: *cluster-server
+    environment: { <<: *cluster-server-env, TURNSTONE_NODE_ID: node-2 }
+  server-3:
+    <<: *cluster-server
+    environment: { <<: *cluster-server-env, TURNSTONE_NODE_ID: node-3 }
+  server-4:
+    <<: *cluster-server
+    environment: { <<: *cluster-server-env, TURNSTONE_NODE_ID: node-4 }
+  server-5:
+    <<: *cluster-server
+    environment: { <<: *cluster-server-env, TURNSTONE_NODE_ID: node-5 }
+  server-6:
+    <<: *cluster-server
+    environment: { <<: *cluster-server-env, TURNSTONE_NODE_ID: node-6 }
+  server-7:
+    <<: *cluster-server
+    environment: { <<: *cluster-server-env, TURNSTONE_NODE_ID: node-7 }
+  server-8:
+    <<: *cluster-server
+    environment: { <<: *cluster-server-env, TURNSTONE_NODE_ID: node-8 }
+  server-9:
+    <<: *cluster-server
+    environment: { <<: *cluster-server-env, TURNSTONE_NODE_ID: node-9 }
+  server-10:
+    <<: *cluster-server
+    environment: { <<: *cluster-server-env, TURNSTONE_NODE_ID: node-10 }
+
+  # -- cluster bridges ------------------------------------------------
+
+  bridge-1: &cluster-bridge
+    build: { context: ., dockerfile: Dockerfile }
+    profiles: [cluster, ddgCluster]
+    command:
+      - turnstone-bridge
+      - --server-url=http://server-1:8080
+      - --redis-host=redis
+      - --redis-port=6379
+      - --heartbeat-ttl=${HEARTBEAT_TTL:-60}
+      - --approval-timeout=${APPROVAL_TIMEOUT:-3600}
+    environment: &cluster-bridge-env
+      REDIS_PASSWORD: ${REDIS_PASSWORD:-}
+      TURNSTONE_AUTH_TOKEN: ${TURNSTONE_AUTH_TOKEN:-}
+      TURNSTONE_JWT_SECRET: ${TURNSTONE_JWT_SECRET:-}
+    networks: [turnstone-net]
+    depends_on:
+      server-1: { condition: service_healthy }
+      redis: { condition: service_healthy }
+    deploy:
+      resources:
+        limits: { memory: 256M, cpus: '0.25' }
+    restart: unless-stopped
+
+  bridge-2:
+    <<: *cluster-bridge
+    command:
+      - turnstone-bridge
+      - --server-url=http://server-2:8080
+      - --redis-host=redis
+      - --redis-port=6379
+      - --heartbeat-ttl=${HEARTBEAT_TTL:-60}
+      - --approval-timeout=${APPROVAL_TIMEOUT:-3600}
+    depends_on:
+      server-2: { condition: service_healthy }
+      redis: { condition: service_healthy }
+  bridge-3:
+    <<: *cluster-bridge
+    command:
+      - turnstone-bridge
+      - --server-url=http://server-3:8080
+      - --redis-host=redis
+      - --redis-port=6379
+      - --heartbeat-ttl=${HEARTBEAT_TTL:-60}
+      - --approval-timeout=${APPROVAL_TIMEOUT:-3600}
+    depends_on:
+      server-3: { condition: service_healthy }
+      redis: { condition: service_healthy }
+  bridge-4:
+    <<: *cluster-bridge
+    command:
+      - turnstone-bridge
+      - --server-url=http://server-4:8080
+      - --redis-host=redis
+      - --redis-port=6379
+      - --heartbeat-ttl=${HEARTBEAT_TTL:-60}
+      - --approval-timeout=${APPROVAL_TIMEOUT:-3600}
+    depends_on:
+      server-4: { condition: service_healthy }
+      redis: { condition: service_healthy }
+  bridge-5:
+    <<: *cluster-bridge
+    command:
+      - turnstone-bridge
+      - --server-url=http://server-5:8080
+      - --redis-host=redis
+      - --redis-port=6379
+      - --heartbeat-ttl=${HEARTBEAT_TTL:-60}
+      - --approval-timeout=${APPROVAL_TIMEOUT:-3600}
+    depends_on:
+      server-5: { condition: service_healthy }
+      redis: { condition: service_healthy }
+  bridge-6:
+    <<: *cluster-bridge
+    command:
+      - turnstone-bridge
+      - --server-url=http://server-6:8080
+      - --redis-host=redis
+      - --redis-port=6379
+      - --heartbeat-ttl=${HEARTBEAT_TTL:-60}
+      - --approval-timeout=${APPROVAL_TIMEOUT:-3600}
+    depends_on:
+      server-6: { condition: service_healthy }
+      redis: { condition: service_healthy }
+  bridge-7:
+    <<: *cluster-bridge
+    command:
+      - turnstone-bridge
+      - --server-url=http://server-7:8080
+      - --redis-host=redis
+      - --redis-port=6379
+      - --heartbeat-ttl=${HEARTBEAT_TTL:-60}
+      - --approval-timeout=${APPROVAL_TIMEOUT:-3600}
+    depends_on:
+      server-7: { condition: service_healthy }
+      redis: { condition: service_healthy }
+  bridge-8:
+    <<: *cluster-bridge
+    command:
+      - turnstone-bridge
+      - --server-url=http://server-8:8080
+      - --redis-host=redis
+      - --redis-port=6379
+      - --heartbeat-ttl=${HEARTBEAT_TTL:-60}
+      - --approval-timeout=${APPROVAL_TIMEOUT:-3600}
+    depends_on:
+      server-8: { condition: service_healthy }
+      redis: { condition: service_healthy }
+  bridge-9:
+    <<: *cluster-bridge
+    command:
+      - turnstone-bridge
+      - --server-url=http://server-9:8080
+      - --redis-host=redis
+      - --redis-port=6379
+      - --heartbeat-ttl=${HEARTBEAT_TTL:-60}
+      - --approval-timeout=${APPROVAL_TIMEOUT:-3600}
+    depends_on:
+      server-9: { condition: service_healthy }
+      redis: { condition: service_healthy }
+  bridge-10:
+    <<: *cluster-bridge
+    command:
+      - turnstone-bridge
+      - --server-url=http://server-10:8080
+      - --redis-host=redis
+      - --redis-port=6379
+      - --heartbeat-ttl=${HEARTBEAT_TTL:-60}
+      - --approval-timeout=${APPROVAL_TIMEOUT:-3600}
+    depends_on:
+      server-10: { condition: service_healthy }
+      redis: { condition: service_healthy }

demo.svg

@@ -1,221 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 860 520" font-family="ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,monospace" font-size="13">
-  <style>
-    @keyframes pulse-green  { 0%,100% { opacity:0.5 } 50% { opacity:1 } }
-    @keyframes pulse-yellow { 0%,100% { opacity:0.4 } 50% { opacity:1 } }
-    @keyframes pulse-blue   { 0%,100% { opacity:0.3 } 50% { opacity:1 } }
-    @keyframes fadein { from { opacity:0 } to { opacity:1 } }
-    .pg { animation: pulse-green 2s infinite }
-    .py { animation: pulse-yellow 1.8s infinite }
-    .pb { animation: pulse-blue 2.2s infinite }
-    .f1 { animation: fadein 0.4s 0.2s both }
-    .f2 { animation: fadein 0.4s 0.4s both }
-    .f3 { animation: fadein 0.4s 0.6s both }
-    .f4 { animation: fadein 0.4s 0.8s both }
-    .f5 { animation: fadein 0.4s 1.0s both }
-    .f6 { animation: fadein 0.4s 1.3s both }
-    .f7 { animation: fadein 0.4s 1.5s both }
-    .f8 { animation: fadein 0.4s 1.7s both }
-    .f9 { animation: fadein 0.4s 1.9s both }
-    .f10 { animation: fadein 0.4s 2.1s both }
-    .f11 { animation: fadein 0.4s 2.3s both }
-    .f12 { animation: fadein 0.4s 2.5s both }
-  </style>
-
-  <!-- Window chrome -->
-  <rect rx="10" width="860" height="520" fill="#1a1b26"/>
-  <rect width="860" height="36" rx="10" fill="#16161e"/>
-  <rect y="26" width="860" height="10" fill="#16161e"/>
-  <circle cx="20" cy="18" r="6" fill="#f7768e"/>
-  <circle cx="40" cy="18" r="6" fill="#e0af68"/>
-  <circle cx="60" cy="18" r="6" fill="#9ece6a"/>
-  <text x="430" y="22" text-anchor="middle" fill="#565f89" font-size="12">turnstone — console</text>
-
-  <!-- Header -->
-  <rect y="36" width="860" height="30" fill="#24283b"/>
-  <rect y="66" width="860" height="1" fill="#3b4261"/>
-  <text x="16" y="56" fill="#7aa2f7" font-size="14" font-weight="bold">turnstone console</text>
-  <text x="200" y="56" fill="#565f89" font-size="12">6 nodes · 10 workstreams</text>
-
-  <!-- ====== State cards ====== -->
-  <g transform="translate(16, 78)" class="f1" opacity="0">
-    <!-- RUN card -->
-    <rect x="0" y="0" width="156" height="64" rx="6" fill="#24283b" stroke="#3b4261"/>
-    <rect x="0" y="0" width="156" height="3" rx="6" fill="#9ece6a"/>
-    <text x="78" y="30" text-anchor="middle" fill="#a9b1d6" font-size="22" font-weight="bold">3</text>
-    <text x="78" y="50" text-anchor="middle" fill="#565f89" font-size="10">▸ RUN</text>
-
-    <!-- THINK card -->
-    <rect x="168" y="0" width="156" height="64" rx="6" fill="#24283b" stroke="#3b4261"/>
-    <rect x="168" y="0" width="156" height="3" rx="6" fill="#7aa2f7"/>
-    <text x="246" y="30" text-anchor="middle" fill="#a9b1d6" font-size="22" font-weight="bold">2</text>
-    <text x="246" y="50" text-anchor="middle" fill="#565f89" font-size="10">◌ THINK</text>
-
-    <!-- ATTN card -->
-    <rect x="336" y="0" width="156" height="64" rx="6" fill="#24283b" stroke="#3b4261"/>
-    <rect x="336" y="0" width="156" height="3" rx="6" fill="#e0af68"/>
-    <text x="414" y="30" text-anchor="middle" fill="#a9b1d6" font-size="22" font-weight="bold">1</text>
-    <text x="414" y="50" text-anchor="middle" fill="#565f89" font-size="10">◆ ATTN</text>
-
-    <!-- ERR card -->
-    <rect x="504" y="0" width="156" height="64" rx="6" fill="#24283b" stroke="#3b4261"/>
-    <rect x="504" y="0" width="156" height="3" rx="6" fill="#f7768e"/>
-    <text x="582" y="30" text-anchor="middle" fill="#a9b1d6" font-size="22" font-weight="bold">0</text>
-    <text x="582" y="50" text-anchor="middle" fill="#565f89" font-size="10">✖ ERR</text>
-
-    <!-- IDLE card -->
-    <rect x="672" y="0" width="156" height="64" rx="6" fill="#24283b" stroke="#3b4261"/>
-    <rect x="672" y="0" width="156" height="3" rx="6" fill="#565f89"/>
-    <text x="750" y="30" text-anchor="middle" fill="#a9b1d6" font-size="22" font-weight="bold">4</text>
-    <text x="750" y="50" text-anchor="middle" fill="#565f89" font-size="10">· IDLE</text>
-  </g>
-
-  <!-- Aggregate bar -->
-  <text x="16" y="160" fill="#565f89" font-size="11" class="f2" opacity="0">197k tokens · 42 tool calls</text>
-
-  <!-- ====== NODES section ====== -->
-  <text x="16" y="182" fill="#7aa2f7" font-size="12" font-weight="bold" class="f3" opacity="0">NODES</text>
-
-  <!-- Node column headers -->
-  <g transform="translate(0, 190)" class="f4" opacity="0">
-    <rect width="860" height="20" fill="#24283b"/>
-    <rect y="20" width="860" height="1" fill="#3b4261"/>
-    <text y="14" fill="#565f89" font-size="10" letter-spacing="0.5">
-      <tspan x="36">NODE</tspan>
-      <tspan x="560">WS</tspan>
-      <tspan x="610">RUN</tspan>
-      <tspan x="660">ATTN</tspan>
-      <tspan x="710">TOKENS</tspan>
-      <tspan x="790">LOAD</tspan>
-    </text>
-  </g>
-
-  <!-- Node rows -->
-  <g transform="translate(0, 214)">
-
-    <!-- Node 1: db-west-04 — 3 ws, 1 running, has-running bar -->
-    <g class="f5" opacity="0">
-      <rect y="0" width="860" height="38" fill="#1a1b26"/>
-      <rect y="0" width="3" height="38" fill="#9ece6a"/>
-      <circle cx="22" cy="19" r="4" fill="#9ece6a"/>
-      <text x="36" y="23" fill="#a9b1d6" font-size="12" font-weight="bold">db-west-04</text>
-      <text x="566" y="23" fill="#a9b1d6" font-size="11">3</text>
-      <text x="616" y="23" fill="#a9b1d6" font-size="11">1</text>
-      <text x="666" y="23" fill="#565f89" font-size="11">0</text>
-      <text x="710" y="23" fill="#565f89" font-size="11">57.6k</text>
-      <!-- Load bar: 3/10 = 30% -->
-      <rect x="770" y="15" width="60" height="6" rx="3" fill="#292e42"/>
-      <rect x="770" y="15" width="18" height="6" rx="3" fill="#9ece6a"/>
-      <text x="838" y="23" fill="#565f89" font-size="11">30%</text>
-    </g>
-
-    <!-- Node 2: api-east-01 — 3 ws, 1 attention, has-attention bar -->
-    <g class="f6" opacity="0">
-      <rect y="40" width="860" height="38" fill="#24283b"/>
-      <rect y="40" width="3" height="38" fill="#e0af68"/>
-      <circle cx="22" cy="59" r="4" fill="#9ece6a"/>
-      <text x="36" y="63" fill="#a9b1d6" font-size="12" font-weight="bold">api-east-01</text>
-      <text x="566" y="63" fill="#a9b1d6" font-size="11">3</text>
-      <text x="616" y="63" fill="#565f89" font-size="11">0</text>
-      <text x="666" y="63" fill="#a9b1d6" font-size="11">1</text>
-      <text x="710" y="63" fill="#565f89" font-size="11">109k</text>
-      <!-- Load bar: 3/10 = 30% -->
-      <rect x="770" y="55" width="60" height="6" rx="3" fill="#292e42"/>
-      <rect x="770" y="55" width="18" height="6" rx="3" fill="#9ece6a"/>
-      <text x="838" y="63" fill="#565f89" font-size="11">30%</text>
-    </g>
-
-    <!-- Node 3: sre-node-03 — 2 ws, 1 running, has-running bar -->
-    <g class="f7" opacity="0">
-      <rect y="80" width="860" height="38" fill="#1a1b26"/>
-      <rect y="80" width="3" height="38" fill="#9ece6a"/>
-      <circle cx="22" cy="99" r="4" fill="#9ece6a"/>
-      <text x="36" y="103" fill="#a9b1d6" font-size="12" font-weight="bold">sre-node-03</text>
-      <text x="566" y="103" fill="#a9b1d6" font-size="11">2</text>
-      <text x="616" y="103" fill="#a9b1d6" font-size="11">1</text>
-      <text x="666" y="103" fill="#565f89" font-size="11">0</text>
-      <text x="710" y="103" fill="#565f89" font-size="11">64.4k</text>
-      <!-- Load bar: 2/10 = 20% -->
-      <rect x="770" y="95" width="60" height="6" rx="3" fill="#292e42"/>
-      <rect x="770" y="95" width="12" height="6" rx="3" fill="#9ece6a"/>
-      <text x="838" y="103" fill="#565f89" font-size="11">20%</text>
-    </g>
-
-    <!-- Node 4: analytics-02 — 1 ws, thinking, has-thinking bar -->
-    <g class="f8" opacity="0">
-      <rect y="120" width="860" height="38" fill="#24283b"/>
-      <rect y="120" width="3" height="38" fill="#7aa2f7"/>
-      <circle cx="22" cy="139" r="4" fill="#9ece6a"/>
-      <text x="36" y="143" fill="#a9b1d6" font-size="12" font-weight="bold">analytics-02</text>
-      <text x="566" y="143" fill="#a9b1d6" font-size="11">1</text>
-      <text x="616" y="143" fill="#565f89" font-size="11">0</text>
-      <text x="666" y="143" fill="#565f89" font-size="11">0</text>
-      <text x="710" y="143" fill="#565f89" font-size="11">18.3k</text>
-      <!-- Load bar: 1/10 = 10% -->
-      <rect x="770" y="135" width="60" height="6" rx="3" fill="#292e42"/>
-      <rect x="770" y="135" width="6" height="6" rx="3" fill="#9ece6a"/>
-      <text x="838" y="143" fill="#565f89" font-size="11">10%</text>
-    </g>
-
-    <!-- Node 5: data-ops-05 — 1 ws, thinking, has-thinking bar -->
-    <g class="f9" opacity="0">
-      <rect y="160" width="860" height="38" fill="#1a1b26"/>
-      <rect y="160" width="3" height="38" fill="#7aa2f7"/>
-      <circle cx="22" cy="179" r="4" fill="#9ece6a"/>
-      <text x="36" y="183" fill="#a9b1d6" font-size="12" font-weight="bold">data-ops-05</text>
-      <text x="566" y="183" fill="#a9b1d6" font-size="11">1</text>
-      <text x="616" y="183" fill="#565f89" font-size="11">0</text>
-      <text x="666" y="183" fill="#565f89" font-size="11">0</text>
-      <text x="710" y="183" fill="#565f89" font-size="11">8.7k</text>
-      <!-- Load bar: 1/10 = 10% -->
-      <rect x="770" y="175" width="60" height="6" rx="3" fill="#292e42"/>
-      <rect x="770" y="175" width="6" height="6" rx="3" fill="#9ece6a"/>
-      <text x="838" y="183" fill="#565f89" font-size="11">10%</text>
-    </g>
-
-    <!-- Node 6: ml-gpu-07 — 0 ws, empty, no bar -->
-    <g class="f10" opacity="0">
-      <rect y="200" width="860" height="38" fill="#24283b"/>
-      <rect y="200" width="3" height="38" fill="transparent"/>
-      <circle cx="22" cy="219" r="4" fill="#9ece6a"/>
-      <text x="36" y="223" fill="#a9b1d6" font-size="12" font-weight="bold">ml-gpu-07</text>
-      <text x="566" y="223" fill="#565f89" font-size="11">0</text>
-      <text x="616" y="223" fill="#565f89" font-size="11">0</text>
-      <text x="666" y="223" fill="#565f89" font-size="11">0</text>
-      <text x="710" y="223" fill="#565f89" font-size="11">0</text>
-      <!-- Load bar: 0/10 = 0% (empty track) -->
-      <rect x="770" y="215" width="60" height="6" rx="3" fill="#292e42"/>
-      <text x="842" y="223" fill="#565f89" font-size="11">0%</text>
-    </g>
-
-  </g>
-
-  <!-- ====== Footer ====== -->
-  <g transform="translate(0, 468)" class="f12" opacity="0">
-    <rect width="860" height="1" fill="#3b4261"/>
-    <rect y="1" width="860" height="24" fill="#16161e"/>
-
-    <circle cx="20" cy="14" r="3" fill="#9ece6a"/>
-    <text x="28" y="18" fill="#565f89" font-size="10">db-west-04</text>
-
-    <circle cx="120" cy="14" r="3" fill="#9ece6a"/>
-    <text x="128" y="18" fill="#565f89" font-size="10">api-east-01</text>
-
-    <circle cx="225" cy="14" r="3" fill="#9ece6a"/>
-    <text x="233" y="18" fill="#565f89" font-size="10">sre-node-03</text>
-
-    <circle cx="335" cy="14" r="3" fill="#9ece6a"/>
-    <text x="343" y="18" fill="#565f89" font-size="10">analytics-02</text>
-
-    <circle cx="450" cy="14" r="3" fill="#9ece6a"/>
-    <text x="458" y="18" fill="#565f89" font-size="10">data-ops-05</text>
-
-    <circle cx="560" cy="14" r="3" fill="#9ece6a"/>
-    <text x="568" y="18" fill="#565f89" font-size="10">ml-gpu-07</text>
-
-    <text x="680" y="18" fill="#3b4261" font-size="10">258k tokens · 42 calls · 12m</text>
-  </g>
-
-  <!-- Bottom edge -->
-  <rect y="493" width="860" height="27" fill="#16161e"/>
-  <rect y="510" width="860" height="10" rx="10" fill="#16161e"/>
-</svg>

docker/mcp-ddg.json

@@ -0,0 +1,7 @@
+{
+  "mcpServers": {
+    "ddg": {
+      "url": "http://ddg-search:3000/mcp"
+    }
+  }
+}

docs/api-reference.md

@@ -448,6 +448,14 @@ after `/clear` or `/new` commands).
 {"type": "clear_ui"}
 ```
 
+**`cancelled`** -- the generation was cancelled by the user (via the Stop
+button or `POST /v1/api/cancel`). The client should finalize any in-progress
+assistant message with whatever partial content was streamed.
+
+```json
+{"type": "cancelled"}
+```
+
 #### Keepalive
 
 The server sends an SSE comment every 5 seconds when no events are pending:
@@ -460,13 +468,13 @@ The server sends an SSE comment every 5 seconds when no events are pending:
 This prevents proxies and browsers from closing the connection due to
 inactivity.
 
-#### Generation mechanism
+#### Multi-consumer fan-out
 
-Each new SSE connection to a workstream increments an internal
-`_sse_generation` counter. The previous SSE handler detects the generation
-mismatch and exits its event loop, ensuring only one active SSE connection per
-workstream at a time. The event queue is drained of stale events before the new
-connection begins streaming.
+Each SSE connection to a workstream receives its own delivery queue.  Events
+produced by the worker thread are fanned out to all registered listener queues,
+so multiple consumers (browser, bridge, console proxy, SDK) can connect
+simultaneously and each receives every event.  On reconnect the client receives
+a full history replay, so no catch-up mechanism is needed.
 
 ---
 
@@ -515,8 +523,8 @@ Returns a list of all active workstreams.
 ```json
 {
   "workstreams": [
-    {"id": "abc123", "name": "default", "state": "idle", "session_id": "a1b2c3d4e5f6"},
-    {"id": "def456", "name": "hacker-news", "state": "thinking", "session_id": "c5d6e7f8a9b0"}
+    {"id": "abc123", "name": "default", "state": "idle"},
+    {"id": "def456", "name": "hacker-news", "state": "thinking"}
   ]
 }
 ```
@@ -528,22 +536,21 @@ Each workstream object:
 | `id`         | string      | Unique workstream routing identifier                   |
 | `name`       | string      | Display name (alias if set, otherwise `ws-xxxx`)       |
 | `state`      | string      | Current state (see state values above)                 |
-| `session_id` | string/null | Session ID of the workstream's `ChatSession`, used for deduplication against `/v1/api/sessions` |
 
 ---
 
-### `GET /v1/api/sessions`
+### `GET /v1/api/workstreams/saved`
 
-Returns a list of saved sessions from the database, ordered by most recently
+Returns a list of saved workstreams from the database, ordered by most recently
 updated.
 
 **Response:**
 
 ```json
 {
-  "sessions": [
+  "workstreams": [
     {
-      "session_id": "a1b2c3d4e5f6",
+      "ws_id": "a1b2c3d4e5f6",
       "alias": "refactor",
       "title": "JWT Authentication Refactor",
       "created": "2026-03-01 10:00:00",
@@ -554,18 +561,16 @@ updated.
 }
 ```
 
-Each session object:
+Each saved workstream object:
 
 | Field           | Type        | Description                                |
 |-----------------|-------------|--------------------------------------------|
-| `session_id`    | string      | Unique 32-char hex UUID session identifier |
+| `ws_id`         | string      | Unique workstream identifier               |
 | `alias`         | string/null | User-assigned short name                   |
 | `title`         | string/null | LLM-generated title                        |
-| `created`       | string      | ISO timestamp of session creation          |
+| `created`       | string      | ISO timestamp of workstream creation       |
 | `updated`       | string      | ISO timestamp of last message              |
-| `message_count` | int         | Number of messages in the session          |
-| `node_id`       | string/null | Server node that created the session       |
-| `ws_id`         | string/null | Workstream the session belongs to          |
+| `message_count` | int         | Number of messages in the workstream       |
 
 ---
 
@@ -704,6 +709,43 @@ containing the resumed session's messages.
 
 ---
 
+### `POST /v1/api/cancel`
+
+Cancels the active generation in a workstream. Sets a cooperative cancellation
+flag that is checked at multiple points in the generation loop (per streaming
+chunk, before tool execution, inside bash commands). The session transitions to
+`idle` state and preserves any partial content already streamed.
+
+If the workstream is waiting for tool approval or plan review, the pending
+prompt is automatically denied/rejected to unblock the worker thread.
+
+Calling this endpoint when the workstream is already idle is a harmless no-op.
+
+**Request body:**
+
+```json
+{"ws_id": "abc123"}
+```
+
+| Field  | Type   | Required | Description          |
+|--------|--------|----------|----------------------|
+| `ws_id`| string | yes      | Target workstream ID |
+
+**Response:**
+
+```json
+{"status": "ok"}
+```
+
+**Error responses:**
+
+| Status | Body                               | Condition              |
+|--------|------------------------------------|------------------------|
+| 400    | `{"error": "No session"}`          | Session not initialized|
+| 404    | `{"error": "Unknown workstream"}`  | `ws_id` not found      |
+
+---
+
 ### `POST /v1/api/workstreams/new`
 
 Creates a new workstream. The server supports up to 10 concurrent workstreams.
@@ -721,7 +763,8 @@ All fields are optional. The body can be empty or an empty JSON object.
 | `name`           | string | auto    | Workstream display name                                        |
 | `model`          | string | default | Model alias from the registry (`[models.*]`)                   |
 | `auto_approve`   | bool   | false   | Auto-approve all tool calls for this workstream                |
-| `resume_session` | string | ""      | Session ID to resume atomically during creation (empty = fresh)|
+| `resume_ws`      | string | ""      | Workstream ID to resume atomically during creation (empty = fresh)|
+| `template`       | string | ""      | Prompt template name (replaces default templates; 400 if not found)|
 
 **Response (success):**
 
@@ -777,6 +820,79 @@ Status code: `400`
 
 ---
 
+### `GET /v1/api/watches`
+
+List active watches on this server node. Optionally filter by workstream.
+Requires `write` scope.
+
+**Query parameters:**
+
+| Parameter | Type   | Required | Description                        |
+|-----------|--------|----------|------------------------------------|
+| `ws_id`   | string | no       | Filter to watches for this workstream. If omitted, returns all watches on the node. |
+
+**Response:**
+
+```json
+{
+  "watches": [
+    {
+      "watch_id": "abc123def456...",
+      "ws_id": "ws-1",
+      "node_id": "host_a1b2",
+      "name": "pr-review",
+      "command": "gh pr view --json state",
+      "interval_secs": 300.0,
+      "stop_on": "data[\"state\"] == \"MERGED\"",
+      "max_polls": 100,
+      "poll_count": 5,
+      "last_output": "{\"state\": \"OPEN\"}",
+      "last_poll": "2026-03-09T12:00:00",
+      "next_poll": "2026-03-09T12:05:00",
+      "active": 1,
+      "created": "2026-03-09T11:30:00"
+    }
+  ]
+}
+```
+
+---
+
+### `POST /v1/api/watches/{watch_id}/cancel`
+
+Cancel an active watch. Sets `active=0` and clears `next_poll`.
+Requires `write` scope. Verifies node ownership in multi-node deployments.
+
+**Path parameters:**
+
+| Parameter  | Type   | Description     |
+|------------|--------|-----------------|
+| `watch_id` | string | Watch ID to cancel |
+
+**Response (success):**
+
+```json
+{"status": "ok", "watch_id": "abc123def456..."}
+```
+
+**Error (not found):**
+
+```json
+{"error": "Watch not found"}
+```
+
+Status code: `404`
+
+**Error (wrong node):**
+
+```json
+{"error": "Watch belongs to another node"}
+```
+
+Status code: `403`
+
+---
+
 ### `OPTIONS` (any path)
 
 Handles CORS preflight requests.

docs/architecture.md

@@ -3,7 +3,7 @@
 Turnstone is an AI orchestration platform with tool use, parallel workstreams, and persistent
 memory. It connects to any OpenAI-compatible API (local vLLM, OpenAI, etc.) or
 Anthropic's native Messages API via pluggable provider adapters, and gives the
-model 14 built-in tools plus external tools via MCP (Model Context Protocol) for
+model 18 built-in tools plus external tools via MCP (Model Context Protocol) for
 reading, writing, searching, planning, and executing code.
 
 The core design principle is a **UI-agnostic engine with pluggable frontends**.
@@ -42,7 +42,9 @@ turnstone/
       __init__.py     create_provider() + create_client() factory functions
     workstream.py     Parallel workstream manager (WorkstreamState, Workstream, WorkstreamManager)
     tools.py          Tool schema loader (JSON -> OpenAI function-calling format)
-    mcp_client.py     MCPClientManager — MCP server connections, tool discovery, async-sync bridge
+    mcp_client.py     MCPClientManager — MCP server connections, tool discovery, dynamic refresh, async-sync bridge
+    tool_search.py    Dynamic tool search — BM25 index, session-scoped tool visibility
+    watch.py          WatchRunner daemon — periodic command polling, condition DSL, result dispatch
     model_registry.py ModelRegistry — named model configs, lazy client creation, fallback routing
     memory.py         Persistence facade (delegates to storage backend)
     storage/          Pluggable storage: StorageBackend protocol, SQLite + PostgreSQL
@@ -94,7 +96,7 @@ turnstone/
       style.css       Page-specific UI styles (dashboard layout, approval blocks)
       app.js          Page-specific client-side JavaScript (SSE, workstreams, markdown)
   tools/
-    *.json            14 tool schemas (OpenAI function-calling format + turnstone metadata)
+    *.json            15 tool schemas (OpenAI function-calling format + turnstone metadata)
 ```
 
 Both UIs share a common design system extracted into `turnstone/shared_static/`: design tokens, login overlay, toast notifications, theme toggle, keyboard shortcuts, and utility functions. Each UI imports `base.css` and the shared JS modules at `/shared/`, then adds only page-specific code at `/static/`.
@@ -127,6 +129,7 @@ A user message flows through the system as follows:
      |                                  on_reasoning_token() / on_content_token()
      |                                  accumulate tool_calls from deltas
      |                                  track finish_reason
+     |                                  _check_cancelled() per chunk (cooperative cancel)
      v
  finish_reason check:
      +--- "length"  --> warn, discard partial tool_calls
@@ -172,11 +175,13 @@ Phase 2: APPROVE (serial, blocking)
   _emit_state("running")
 
 Phase 3: EXECUTE (parallel)
+  _check_cancelled()  <-- cancellation checkpoint before execution starts
   if len(items) == 1:
     run_one(items[0])
   else:
     ThreadPoolExecutor(max_workers=4).map(run_one, items)
   Bash tool streams stdout line-by-line via ui.on_tool_output_chunk(call_id, line)
+    (cancel_event also checked per line — kills process group on cancel)
   Final output (stdout + stderr) delivered via ui.on_tool_result(call_id, name, output)
   call_id links tool_info items → streaming chunks → final result
   For plan tool: post-execution gate via ui.on_plan_review()
@@ -207,6 +212,11 @@ The engine emits state changes via `_emit_state()` which calls
   "idle"       --->  no more tool calls, turn complete
       |
   (or "error"  --->  exception or KeyboardInterrupt)
+
+  cancel() may be called from any state. It sets a cooperative flag
+  checked at each streaming chunk, before tool execution, and inside
+  bash commands. The session transitions to "idle" with partial
+  content preserved, emitting on_info("[Generation cancelled]").
 ```
 
 ---
@@ -472,7 +482,7 @@ independently, then returns the final content as the tool result.
 
 - **task**: uses `self._task_tools` (`TASK_AGENT_TOOLS` + MCP tools)
 - **plan**: uses `self._agent_tools` (`AGENT_TOOLS` + MCP tools). Writes output
-  to `.plan-<session_id>.md` — unique per `ChatSession` so concurrent workstreams
+  to `.plan-<ws_id>.md` — unique per `ChatSession` so concurrent workstreams
   don't collide. On repeat invocations the prior `plan` tool call and its result
   are forwarded from `self.messages` so the agent refines the existing plan rather
   than starting over. Planning instructions are injected as a developer message
@@ -497,17 +507,32 @@ bridges this with a background asyncio event loop in a daemon thread.
 1. `create_mcp_client()` reads server configs from TOML or JSON
 2. `MCPClientManager.start()` launches the background event loop thread
 3. `_connect_all()` connects to each server (stdio subprocess or HTTP), runs
-   `initialize()` + `list_tools()`, converts schemas to OpenAI format
-4. `ChatSession.__init__` receives the manager and builds `self._tools` (built-in + MCP)
+   `initialize()` + `list_tools()`, converts schemas to OpenAI format, detects
+   `tools.listChanged` capability for push notification support
+4. `ChatSession.__init__` receives the manager, builds `self._tools` (built-in + MCP),
+   and registers a listener callback for tool-change notifications
 5. `_prepare_tool()` routes MCP tools to `_prepare_mcp_tool()` / `_exec_mcp_tool()`
 6. `_exec_mcp_tool()` calls `call_tool_sync()` which dispatches to the async loop
    via `asyncio.run_coroutine_threadsafe()`
 
+**Tool refresh:** Three mechanisms keep tools up-to-date without restart:
+- **Push:** Servers declaring `tools.listChanged` send `ToolListChangedNotification`;
+  the registered `message_handler` triggers immediate single-server refresh.
+- **Periodic:** Servers without push support are polled on a staggered interval
+  (default 4 h, configurable via `[mcp] refresh_interval` or `--mcp-refresh-interval`).
+- **Manual:** `/mcp refresh [server]` calls `refresh_sync()` for on-demand refresh
+  (also attempts reconnection for disconnected servers).
+
+When tools change, `_rebuild_tools()` creates new `_tools`/`_tool_map` objects
+(copy-on-write for thread safety) and notifies listener callbacks. Each `ChatSession`
+rebuilds its merged tool lists and reconstructs `ToolSearchManager` (preserving
+expanded tools).
+
 **Tool naming:** `mcp__{server}__{tool}` — double underscore delimiter, validated
 at connection time (server names with `__` are rejected).
 
-**Error isolation:** Per-server connection failures are caught and logged; other
-servers still connect. Tool execution errors return error strings to the LLM
+**Error isolation:** Per-server connection/refresh failures are caught and logged; other
+servers are unaffected. Tool execution errors return error strings to the LLM
 rather than crashing the session.
 
 ### Provider Adapter Layer
@@ -544,21 +569,23 @@ LLMProvider (protocol)
 |------|--------|
 | `StreamChunk` | `content_delta`, `reasoning_delta`, `tool_call_deltas`, `info_delta`, `usage`, `finish_reason` |
 | `CompletionResult` | `content`, `tool_calls`, `finish_reason`, `usage` |
-| `ModelCapabilities` | `context_window`, `max_output_tokens`, `supports_temperature`, `token_param`, `thinking_mode`, `supports_effort`, `supports_web_search` |
+| `ModelCapabilities` | `context_window`, `max_output_tokens`, `supports_temperature`, `token_param`, `thinking_mode`, `supports_effort`, `supports_web_search`, `supports_tool_search`, `supports_vision` |
 | `UsageInfo` | `prompt_tokens`, `completion_tokens`, `total_tokens` |
 
 **OpenAIProvider** (`_openai.py`): passes messages through unchanged (they are
-already in OpenAI format). Model capability lookup table covers
-GPT-5/5.1/5.2, O-series, and search models (`gpt-5-search-api`).
+already in OpenAI format), including multi-part content blocks (text + images)
+in tool results. Model capability lookup table covers GPT-5/5.1/5.2/5.3/5.4,
+O-series, and search models (`gpt-5-search-api`) — all with `supports_vision`.
 For search models, injects `web_search_options` and removes the `web_search`
 function tool (the model always searches). Citations from `url_citation`
 annotations are formatted as footnotes. Unknown models (local servers) get
-permissive defaults and use Tavily for web search.
+permissive defaults with `supports_vision=False` and use Tavily for web search.
 
 **AnthropicProvider** (`_anthropic.py`): converts OpenAI-format messages to
 Anthropic content blocks, maps `system`/`developer` roles to the `system`
 parameter, groups consecutive `tool` result messages into user-role content
-blocks, and translates tool schemas from OpenAI function-calling format to
+blocks (converting `image_url` parts to Anthropic's `image` source format),
+and translates tool schemas from OpenAI function-calling format to
 Anthropic's `input_schema` format. Supports both manual and adaptive thinking
 modes, with effort parameter support for models like Claude Opus 4.6 and
 Sonnet 4.6. Replaces the `web_search` function tool with Anthropic's native
@@ -604,6 +631,18 @@ agent_model = "claude"
 
 Each `[models.*]` entry produces a `ModelConfig` with a `provider` field
 (default: `"openai"`). Supported values: `"openai"` and `"anthropic"`.
+An optional `[models.*.capabilities]` sub-table overrides per-model
+`ModelCapabilities` flags (useful for local models whose capabilities
+cannot be detected programmatically):
+
+```toml
+[models.qwen-vl]
+base_url = "http://localhost:8000/v1"
+model = "qwen-3.5-vl"
+
+[models.qwen-vl.capabilities]
+supports_vision = true
+```
 
 **Lifecycle:**
 1. `load_model_registry()` reads `[models.*]` sections from config.toml and
@@ -688,8 +727,11 @@ memories
   created  TEXT NOT NULL
   updated  TEXT NOT NULL
 
-sessions
-  session_id  TEXT PRIMARY KEY
+workstreams
+  ws_id       TEXT PRIMARY KEY
+  node_id     TEXT NOT NULL
+  name        TEXT NOT NULL
+  state       TEXT NOT NULL DEFAULT 'idle'
   alias       TEXT UNIQUE            -- user-assigned short name (nullable)
   title       TEXT                   -- LLM-generated title (nullable)
   created     TEXT NOT NULL
@@ -697,7 +739,7 @@ sessions
 
 conversations
   id            INTEGER PRIMARY KEY AUTOINCREMENT
-  session_id    TEXT NOT NULL
+  ws_id         TEXT NOT NULL
   timestamp     TEXT NOT NULL
   role          TEXT NOT NULL        -- user | assistant | tool_call | tool_result
   content       TEXT
@@ -706,8 +748,8 @@ conversations
   tool_call_id  TEXT                 -- links tool_call ↔ tool_result for resume
   provider_data TEXT                 -- raw provider content (e.g. Anthropic encrypted)
 
-session_config
-  session_id  TEXT NOT NULL          -- composite PK with key
+workstream_config
+  ws_id       TEXT NOT NULL          -- composite PK with key
   key         TEXT NOT NULL
   value       TEXT
 
@@ -722,22 +764,20 @@ and are the single source of truth for both backends and Alembic migrations.
 
 | Method | Purpose |
 |--------|---------|
-| `register_session(session_id, title, node_id, ws_id)` | Create a sessions row (no-op if exists) |
-| `save_message(session_id, role, content, ...)` | Log a message to conversations |
-| `load_session_messages(session_id)` | Reconstruct OpenAI message format from DB rows |
-| `list_sessions(limit)` | List sessions with >=1 message, ordered by updated DESC |
-| `delete_session(session_id)` | Delete session and all its messages |
-| `prune_sessions(retention_days)` | Remove empty sessions and old unnamed sessions |
-| `resolve_session(alias_or_id)` | Resolve alias, exact id, or id prefix to full session_id |
-| `save_session_config(session_id, config)` | Persist session configuration key/value pairs |
-| `load_session_config(session_id)` | Retrieve session configuration |
-| `set_session_alias(session_id, alias)` | Set user-friendly alias (returns False if taken) |
-| `get_session_name(session_id)` | Return alias if set, else title, else None |
-| `update_session_title(session_id, title)` | Set/update LLM-generated title |
 | `register_workstream(ws_id, node_id, name, state)` | Create a workstreams row (no-op if exists) |
+| `save_message(ws_id, role, content, ...)` | Log a message to conversations |
+| `load_messages(ws_id)` | Reconstruct OpenAI message format from DB rows |
+| `list_workstreams_with_history(limit)` | List workstreams with >=1 message, ordered by updated DESC |
+| `delete_workstream(ws_id)` | Delete workstream and cascade conversations + config |
+| `prune_workstreams(retention_days)` | Remove empty workstreams and old unnamed workstreams |
+| `resolve_workstream(alias_or_id)` | Resolve alias, exact id, or id prefix to full ws_id |
+| `save_workstream_config(ws_id, config)` | Persist workstream configuration key/value pairs |
+| `load_workstream_config(ws_id)` | Retrieve workstream configuration |
+| `set_workstream_alias(ws_id, alias)` | Set user-friendly alias (returns False if taken) |
+| `get_workstream_display_name(ws_id)` | Return alias if set, else title, else None |
+| `update_workstream_title(ws_id, title)` | Set/update LLM-generated title |
 | `update_workstream_state(ws_id, state)` | Update workstream state and bump timestamp |
 | `update_workstream_name(ws_id, name)` | Update workstream display name |
-| `delete_workstream(ws_id)` | Delete a workstream row |
 | `list_workstreams(node_id, limit)` | List workstreams, optionally by node |
 | `kv_get(key)` / `kv_set(key, value)` / `kv_delete(key)` | Generic key-value store (backs memories table) |
 | `kv_list()` / `kv_search(query)` | List or search key-value pairs |
@@ -757,59 +797,59 @@ pool_size = 5                       # PostgreSQL connection pool size
 
 Environment variables: `TURNSTONE_DB_BACKEND`, `TURNSTONE_DB_URL`, `TURNSTONE_DB_PATH`.
 
-### Session Persistence and Resume
+### Persistence and Resume
 
-Each `ChatSession` generates a full 32-char hex UUID `_session_id` on creation
-and registers it in the `sessions` table with the server's `node_id` and the
-owning `ws_id`. Messages are saved to `conversations` as they happen via
-`save_message()`. Workstreams are persisted to the `workstreams` table on
-creation, with state changes tracked via `update_workstream_state()`.
+`ws_id` is the sole persistent identity for both routing and conversation
+history. There is no separate `session_id` — the `workstreams` table holds
+alias, title, and state alongside the routing fields (`node_id`, `name`).
+Messages are saved to `conversations` (keyed by `ws_id`) as they happen
+via `save_message()`. Workstream state changes are tracked via
+`update_workstream_state()`.
 
 **Auto-titling:** After the first complete exchange (user message + assistant
 response), a background thread calls the LLM with a title-generation prompt
 (`reasoning_effort: "low"`, `max_completion_tokens: 200`). The generated
-title (3-8 words) is stored in `sessions.title`.
+title (3-8 words) is stored in `workstreams.title`.
 
-**Resume flow:** `ChatSession.resume_session(session_id)` calls
-`load_session_messages()` which reconstructs the OpenAI message format from
-database rows:
+**Resume flow:** `ChatSession.resume(ws_id)` calls `load_messages()` which
+reconstructs the OpenAI message format from database rows:
 
 - `user` and `assistant` rows map directly
 - Consecutive `tool_call` rows are grouped into one assistant message's
   `tool_calls` array, paired with subsequent `tool_result` rows via
   `tool_call_id` (or positional matching for legacy data)
-- **Interrupted session repair:** If the last assistant message has
-  `tool_calls` but fewer tool results than expected (session was
+- **Interrupted conversation repair:** If the last assistant message has
+  `tool_calls` but fewer tool results than expected (conversation was
   interrupted mid-execution), the incomplete turn is stripped so the
   LLM can re-generate cleanly
-- The session adopts the old `_session_id`, so new messages continue in
-  the same session
+- The `ChatSession` adopts the resumed `_ws_id`, so new messages continue
+  in the same workstream
 
 **Config persistence:** LLM-affecting parameters (`temperature`,
 `reasoning_effort`, `max_tokens`, `instructions`, `creative_mode`) are
-persisted to the `session_config` table on creation and whenever changed
-via slash commands. `resume_session()` restores these values so resumed
-sessions behave identically to the original.
+persisted to the `workstream_config` table on creation and whenever changed
+via slash commands. `resume()` restores these values so resumed workstreams
+behave identically to the original.
 
 **`/clear` vs `/new`:** `/clear` wipes in-memory context but preserves
-messages in the database for future resume. `/new` starts a fresh session
-(new `_session_id`), leaving the old session resumable.
+messages in the database for future resume. `/new` starts a fresh workstream
+(new `_ws_id`), leaving the old workstream resumable.
 
-**Resolution:** `resolve_session()` accepts aliases, exact session IDs, or
-session ID prefixes, enabling `turnstone --resume refactor` or `/resume abc12`.
+**Resolution:** `resolve_workstream()` accepts aliases, exact workstream IDs,
+or ID prefixes, enabling `turnstone --resume refactor` or `/resume abc12`.
 
-**Session listing:** `list_sessions()` only returns sessions that have at
-least one saved message (`WHERE EXISTS` on `conversations`). Sessions
-registered but never used (e.g., from process startup) are invisible until
-a message is sent.
+**Workstream listing:** `list_workstreams_with_history()` only returns
+workstreams that have at least one saved message (`WHERE EXISTS` on
+`conversations`). Workstreams registered but never used (e.g., from process
+startup) are invisible until a message is sent.
 
-**Session pruning:** `prune_sessions(retention_days, log_fn)` runs once at
-startup (CLI and server). It removes:
-- Sessions with no messages (orphaned registrations)
-- Unnamed sessions (`alias IS NULL`) older than `retention_days` days (default 90)
+**Workstream pruning:** `prune_workstreams(retention_days, log_fn)` runs once
+at startup (CLI and server). It removes:
+- Workstreams with no messages (orphaned registrations)
+- Unnamed workstreams (`alias IS NULL`) older than `retention_days` days (default 90)
 
-Named (aliased) sessions are never age-pruned. Configure with
-`--session-retention-days N` (0 = disable age pruning).
+Named (aliased) workstreams are never age-pruned. Configure with
+`--retention-days N` (0 = disable age pruning).
 
 ---
 
@@ -947,7 +987,7 @@ Three hierarchical scopes control endpoint access:
 
 | Scope | Grants | Endpoints |
 |-------|--------|-----------|
-| `read` | SSE streams, workstream listing, sessions | GET endpoints |
+| `read` | SSE streams, workstream listing, history | GET endpoints |
 | `write` | `read` + send, command, workstream create/close | POST to `/api/send`, `/api/command`, etc. |
 | `approve` | `write` + tool approval, admin operations | POST to `/api/approve`, `/api/admin/*` |
 
@@ -1081,7 +1121,7 @@ context manager handles startup/shutdown (health monitor, MCP client,
 registry).
 
 Each workstream's `WebUI` has:
-- `_event_queue` (per-workstream SSE events, `queue.Queue`)
+- `_listeners` (per-client SSE queues, fan-out on `_enqueue()`)
 - `_approval_event` / `_plan_event` (`threading.Event` for blocking)
 - `_global_queue` (class variable, shared, for state broadcasts)
 
@@ -1141,6 +1181,10 @@ bridge auto-approves via `POST /v1/api/approve`. Otherwise, it publishes an
 `BLPOP` of a Redis response queue (`turnstone:resp:{request_id}`) until the client pushes
 a response or the approval timeout (default 3600s / 1 hour) expires.
 
+**Cancellation:** The `CancelMessage` (type `"cancel"`) is a routed inbound message.
+The bridge dispatches it to `POST /v1/api/cancel` on the server owning the workstream,
+which sets the cooperative cancel flag and unblocks any pending approval/plan waits.
+
 **Completion detection:** The bridge tracks which `correlation_id` maps to which
 `ws_id` for active sends. When the global SSE reports `ws_state → idle` for a tracked
 workstream, the bridge emits a synthetic `TurnCompleteEvent` with the correlation ID.
@@ -1155,6 +1199,9 @@ for existing workstreams are auto-routed via `turnstone:ws:{ws_id}` ownership ke
 If a bridge picks up a shared-queue message for a workstream owned by another node, it
 re-routes to that node's queue (1 extra hop). Bridges publish heartbeats to
 `turnstone:node:{node_id}` with configurable TTL for node discovery.
+On startup, `_recover_workstreams` re-registers ownership of existing
+workstreams and publishes `WorkstreamCreatedEvent` to the cluster channel
+so the console collector picks them up immediately.
 
 ### Cluster Console
 
@@ -1180,7 +1227,10 @@ The console HTTP layer is a Starlette/ASGI app served by uvicorn. The SSE
 endpoint uses `EventSourceResponse` with the same listener queue pattern as
 the main server. `ClusterCollector`'s background threads (event subscriber,
 node discovery, poll loop) use sync Redis clients and `ThreadPoolExecutor`
-for parallel HTTP polling.
+for parallel HTTP polling. The poll loop diffs workstream IDs between poll
+cycles and fans out synthetic `ws_created`/`ws_closed` SSE events for any
+changes, ensuring browser clients stay in sync even when real-time cluster
+events are missed (e.g. bridge startup recovery).
 
 The console has two write-path capabilities:
 
@@ -1239,7 +1289,7 @@ typed event dataclasses.
 
 **Two client pairs** (sync + async):
 
-- `TurnstoneServer` / `AsyncTurnstoneServer` — server API (workstreams, chat, streaming, sessions)
+- `TurnstoneServer` / `AsyncTurnstoneServer` — server API (workstreams, chat, streaming)
 - `TurnstoneConsole` / `AsyncTurnstoneConsole` — console API (cluster overview, nodes, workstreams)
 
 **Design**: async-first with thin sync wrappers. `_BaseClient` provides httpx
@@ -1279,11 +1329,11 @@ The `ChannelRouter` manages bidirectional routing: it maps platform
 channel/thread IDs to turnstone workstream IDs, handles workstream
 creation and stale-route recovery, and resolves platform users to
 turnstone identities via the `channel_users` table. When an evicted
-workstream is reactivated, the router uses atomic session resume via the
-`resume_session` field on `CreateWorkstreamMessage` — the server resumes
-the old session during workstream creation in a single HTTP request,
-eliminating ordering fragility. The bridge emits a `SessionResumedEvent`
-to confirm success.
+workstream is reactivated, the router uses atomic resume via the
+`resume_ws` field on `CreateWorkstreamMessage` — the server resumes
+the old workstream's conversation during creation in a single HTTP
+request, eliminating ordering fragility. The bridge emits a
+`WorkstreamResumedEvent` to confirm success.
 
 Discord ships as the first adapter. See [channels.md](channels.md) for
 setup instructions, configuration reference, and the adapter development
@@ -1302,3 +1352,28 @@ gateway validates the JWT, resolves the target (username lookup via
 the appropriate `ChannelAdapter.send()`. Delivery retries up to 3 times
 with backoff, re-querying the service registry on each attempt. See
 [Notification Flow diagram](diagrams/png/17-notify-flow.png).
+
+---
+
+## Governance
+
+> See also: [Governance documentation](governance.md) | [Governance Architecture diagram](diagrams/19-governance-architecture.puml)
+
+Turnstone governance extends the Phase 1 auth system with role-based access
+control (RBAC), tool execution policies, prompt templates, usage tracking,
+and audit logging. The permission model has two layers: legacy scopes
+(`read`, `write`, `approve`) checked by `AuthMiddleware`, and 15 granular
+permissions checked per-endpoint by `require_permission()`. Three built-in
+roles (admin, operator, viewer) are seeded by migration 008; custom roles
+can be created with any permission subset. JWTs carry both `scopes` and
+`permissions` claims for backward compatibility.
+
+Tool policies use glob pattern matching (`fnmatch`) with priority-ordered
+first-match-wins evaluation to control tool execution (allow/deny/ask).
+Prompt templates provide reusable system messages with `{{variable}}`
+substitution. Usage events are recorded per-LLM-request for token
+accounting. An append-only audit log captures all admin mutations.
+
+The console admin panel adds 5 governance tabs (Roles, Policies, Templates,
+Usage, Audit) for a total of 10 tabs, all permission-gated. Both Python
+and TypeScript SDKs expose governance methods on the console client.

docs/channels.md

@@ -136,11 +136,11 @@ An admin can also force-link or unlink users via the console admin panel
   1.5 seconds.
 - If the workstream is evicted for capacity, the next message in the
   thread auto-creates a new workstream and atomically resumes the
-  previous session via the `resume_session` field on
-  `CreateWorkstreamMessage`. The server resumes the session during
-  workstream creation (same HTTP request), and the bridge emits a
-  `SessionResumedEvent` back to the channel. The thread receives a
-  *"Session resumed: {name} ({count} messages restored)"* confirmation.
+  previous workstream via the `resume_ws` field on
+  `CreateWorkstreamMessage`. The server resumes the workstream during
+  creation (same HTTP request), and the bridge emits a
+  `WorkstreamResumedEvent` back to the channel. The thread receives a
+  *"Resumed: {name} ({count} messages restored)"* confirmation.
 
 ### Slash Commands
 
@@ -232,14 +232,12 @@ See [Security: Database Schema](security.md#database-schema) for the
 3. **Eviction** — the server evicts an idle workstream for capacity. The
    route is preserved and the thread stays open.
 4. **Reactivation** — the next message in the thread detects the stale
-   route (no MQ owner), looks up the old session via
-   `get_session_id_by_ws()`, and creates a new workstream with
-   `resume_session` set atomically on the `CreateWorkstreamMessage`. The
-   server resumes the session during creation (no separate command
-   needed). The bridge emits a `SessionResumedEvent` to the channel, and
-   the thread displays *"Session resumed: {name} ({count} messages
-   restored)"*. If the old session was pruned, the workstream starts
-   fresh with no error.
+   route (no MQ owner) and creates a new workstream with the old `ws_id`
+   as `resume_ws` on the `CreateWorkstreamMessage`. The server resumes
+   the workstream during creation (no separate command or reverse lookup
+   needed). The bridge emits a `WorkstreamResumedEvent` to the channel, and
+   the thread displays *"Resumed: {name} ({count} messages restored)"*.
+   If the old workstream was pruned, a fresh one starts with no error.
 5. **Close** — `/close` command closes the workstream via MQ, deletes the
    route, unsubscribes from events, and archives the Discord thread.
 

docs/console.md

@@ -61,6 +61,8 @@ The collector (`turnstone/console/collector.py`) maintains an in-memory snapshot
 
 3. **Poll loop** — fetches `GET /v1/api/dashboard` and `GET /health` from each known node every 10 seconds. Uses `ThreadPoolExecutor(max_workers=50)` for parallelism. Each poll replaces the node's workstream list with the authoritative server data.
 
+A `get_snapshot()` method builds the full cluster state under a single lock acquisition — overview aggregates and per-node workstream lists in one atomic read. This is served both as a REST endpoint and as the initial SSE event on client connect.
+
 ### Thread Safety
 
 All reads and writes to the node/workstream map are protected by a single `threading.Lock`. Query methods acquire the lock, copy data, and release before returning.
@@ -146,6 +148,38 @@ Single node detail with all its workstreams.
 }
 ```
 
+### `GET /v1/api/cluster/snapshot`
+
+Full cluster state in a single response — all nodes with their workstreams plus overview aggregates. Built under a single lock for internal consistency. Used by the browser on initial load and SSE reconnect.
+
+```json
+{
+  "nodes": [
+    {
+      "node_id": "db-west-04",
+      "server_url": "http://10.0.3.4:8080",
+      "max_ws": 10,
+      "reachable": true,
+      "version": "0.3.0",
+      "health": {"status": "ok", "version": "0.3.0"},
+      "aggregate": {"total_tokens": 48200, "total_tool_calls": 156},
+      "workstreams": [
+        {"id": "a1b2c3d4", "name": "perf-db-west", "state": "running", ...}
+      ]
+    }
+  ],
+  "overview": {
+    "nodes": 847,
+    "workstreams": 4219,
+    "states": {"running": 1847, "thinking": 312, "attention": 89, "idle": 1940, "error": 31},
+    "aggregate": {"total_tokens": 12400000, "total_tool_calls": 34200},
+    "version_drift": false,
+    "versions": ["0.3.0"]
+  },
+  "timestamp": 1709294400.0
+}
+```
+
 ### `POST /v1/api/cluster/workstreams/new`
 
 Create a new workstream on a target node. Dispatches a `CreateWorkstreamMessage` through the Redis MQ pipeline — the bridge on the target node picks it up and creates the workstream on the server. Requires `write` scope.
@@ -182,7 +216,7 @@ Creation is asynchronous — the response confirms the MQ message was dispatched
 
 ### `GET /v1/api/cluster/events`
 
-Server-Sent Events stream for real-time cluster updates.
+Server-Sent Events stream for real-time cluster updates. The first event is always a `snapshot` containing the full cluster state (same shape as `GET /v1/api/cluster/snapshot` with an added `type: "snapshot"` field), followed by incremental events:
 
 ```
 data: {"type":"cluster_state","ws_id":"a1b2","node_id":"db-west-04","state":"running"}
@@ -326,7 +360,7 @@ The server UI uses root-relative URLs (`/v1/api/send`, `/static/app.js`, `/share
 
 ### SSE Proxy
 
-SSE streams (`/v1/api/events`, `/v1/api/events/global`) are proxied by creating a per-connection `httpx.AsyncClient(timeout=None)`, streaming the upstream response via `aiter_text()`, parsing SSE framing (`\n\n` delimiters), and re-emitting events through `EventSourceResponse`. Each proxied SSE stream requires its own httpx client since the shared client's 30-second timeout would kill long-lived connections.
+SSE streams (`/v1/api/events`, `/v1/api/events/global`) are proxied as raw byte passthrough — the console opens an `httpx.AsyncClient.stream()` to the upstream server (with `read=None` and `pool=None` timeouts since SSE connections are long-lived) and relays every byte via `StreamingResponse`. This preserves server-side ping comments, event framing, and keepalives verbatim without parsing or re-encoding.
 
 ### Authentication
 
@@ -368,6 +402,8 @@ On submit, `POST /v1/api/cluster/workstreams/new` dispatches the creation reques
 
 All five views receive live updates via SSE — state cards update counts, node rows update metrics, workstream rows update state indicators.
 
+The browser maintains a local `clusterState` object that mirrors the cluster snapshot. It is initialized from the SSE `snapshot` event on connect (or via `GET /v1/api/cluster/snapshot` on initial page load) and updated incrementally by SSE events. View navigation reads from local state — no API round-trips needed after the initial snapshot.
+
 ### 5. Admin Panel
 
 Accessed via the "admin" button in the header (visible when authenticated

docs/diagrams/02-package-structure.puml

@@ -40,7 +40,8 @@ package "turnstone/core/" <<Rectangle>> {
     component [auth.py\nAuthentication] as auth <<core>>
     component [healthcheck.py\nBackendHealthMonitor] as healthcheck <<core>>
     component [ratelimit.py\nRateLimiter] as ratelimit <<core>>
-    component [mcp_client.py\nMCPClientManager] as mcp <<core>>
+    component [mcp_client.py\nMCPClientManager\n(push + periodic refresh)] as mcp <<core>>
+    component [tool_search.py\nToolSearchManager, BM25] as toolsearch <<core>>
     component [model_registry.py\nModelRegistry] as registry <<core>>
 }
 
@@ -95,7 +96,7 @@ package "turnstone/sdk/" <<Rectangle>> {
 
 ' Tool schemas
 package "turnstone/tools/" <<Rectangle>> {
-    component [*.json\n14 tool schemas] as schemas <<artifact>>
+    component [*.json\n18 tool schemas] as schemas <<artifact>>
 }
 
 ' Entry point dependencies
@@ -136,6 +137,7 @@ session --> edit
 session --> web
 session --> healthcheck
 session --> mcp : optional
+session --> toolsearch : optional
 session --> registry : optional
 registry --> providers
 healthcheck --> metrics

docs/diagrams/03-core-engine-classes.puml

@@ -41,7 +41,7 @@ class "WorkstreamTerminalUI" as WsTermUI {
 }
 
 class "WebUI" as WebUI {
-    - _event_queue: Queue
+    - _listeners: list[Queue]
     - _approval_event: Event
     - _plan_event: Event
     - _ws_prompt_tokens: int
@@ -108,6 +108,8 @@ class "ModelCapabilities" as ModelCaps <<frozen>> {
     + thinking_mode: str
     + supports_effort: bool
     + supports_web_search: bool
+    + supports_tool_search: bool
+    + supports_vision: bool
 }
 
 ' ChatSession
@@ -118,8 +120,9 @@ class "ChatSession" as ChatSession {
     - ui: SessionUI
     - messages: list[dict]
     - _msg_tokens: list[int]
-    - _session_id: str
+    - _ws_id: str
     - _mcp_client: MCPClientManager | None
+    - _tool_search: ToolSearchManager | None
     - _registry: ModelRegistry | None
     + model_alias: str | None {property}
     - _tools: list[dict]
@@ -130,7 +133,7 @@ class "ChatSession" as ChatSession {
     --
     + send(user_input: str)
     + handle_command(command: str)
-    + resume_session(session_id: str)
+    + resume(ws_id: str)
     - _save_config()
     - _stream_response(stream) → dict
     - _create_stream_with_retry(msgs) → Stream (+ fallback)
@@ -139,6 +142,12 @@ class "ChatSession" as ChatSession {
     - _prepare_tool(tc) → item dict
     - _prepare_mcp_tool(call_id, name, args) → item dict
     - _exec_mcp_tool(item) → (call_id, output)
+    - _get_active_tools() → list[dict]
+    - _prepare_tool_search() → None
+    - _exec_tool_search(item) → (call_id, output)
+    - _on_mcp_tools_changed()
+    - _rebuild_tool_search()
+    + close()
     - _run_agent(messages, tools, ...) → str
     - _compact_messages(auto: bool)
     - _full_messages() → list[dict]
@@ -201,22 +210,58 @@ enum "WorkstreamState" as WsState {
 ' MCPClientManager
 class "MCPClientManager" as MCPMgr {
     - _sessions: dict[str, ClientSession]
+    - _per_server_tools: dict[str, list[dict]]
+    - _per_server_resources: dict[str, list[dict]]
+    - _per_server_prompts: dict[str, list[dict]]
     - _tools: list[dict]
     - _tool_map: dict[str, tuple]
+    - _resource_map: dict[str, tuple]
+    - _prompt_map: dict[str, tuple]
+    - _supports_list_changed: dict[str, bool]
+    - _listeners: list[Callable]
     --
     + start()
     + get_tools() → list[dict]
+    + get_resources() → list[dict]
+    + get_prompts() → list[dict]
     + is_mcp_tool(name) → bool
     + call_tool_sync(name, args) → str
+    + read_resource_sync(uri) → str
+    + get_prompt_sync(name, args?) → list[dict]
+    + refresh_sync(server?) → dict
+    + add_listener(callback)
+    + remove_listener(callback)
+    + server_names: list[str] {property}
     + shutdown()
     --
     Background asyncio event loop
     bridges async MCP SDK to
     sync ChatSession dispatch.
+    Push + periodic + manual refresh.
+    Resources + prompts discovered
+    alongside tools at startup.
     --
     core/mcp_client.py
 }
 
+' ToolSearchManager
+class "ToolSearchManager" as ToolSearchMgr {
+    - _all_tools: list[dict]
+    - _always_on: list[dict]
+    - _deferred: list[dict]
+    - _expanded: dict[str, None]
+    - _index: BM25Index
+    --
+    + should_activate() → bool
+    + get_visible_tools() → list[dict]
+    + get_deferred_tools() → list[dict]
+    + get_expanded_names() → list[str]
+    + search(query, k) → list[dict]
+    + expand_visible(names) → list[dict]
+    + get_search_tool_definition() → dict
+    + format_search_results(tools) → str
+}
+
 ' ModelRegistry
 class "ModelRegistry" as ModelReg {
     - _models: dict[str, ModelConfig]
@@ -317,6 +362,7 @@ LLMProvider <|.. AnthropicProv
 ChatSession --> SessionUI : uses
 ChatSession --> LLMProvider : delegates LLM calls
 ChatSession --> MCPMgr : optional
+ChatSession --o ToolSearchMgr : _tool_search
 ChatSession --> ModelReg : optional
 ChatSession <|-- HeadlessSession
 

docs/diagrams/04-conversation-turn.puml

@@ -18,7 +18,7 @@ User -> CS : send(user_input)
 activate CS
 
 CS -> CS : messages.append({role: "user", content: input})
-CS -> DB : save_message(session_id, "user", input)
+CS -> DB : save_message(ws_id, "user", input)
 
 == LLM Call Loop ==
 
@@ -57,6 +57,14 @@ group loop [while tool_calls present]
         end
     end
 
+        note right of CS
+          **Cancellation checkpoint:**
+          _check_cancelled() runs per chunk.
+          If cancel_event is set, raises
+          GenerationCancelled — preserves
+          partial content, emits idle state.
+        end note
+
     LLM --> CS : stream complete (usage stats)
     deactivate LLM
 
@@ -65,8 +73,8 @@ group loop [while tool_calls present]
 
     CS -> CS : _update_token_table()\ncalibrate chars_per_token ratio
     CS -> CS : messages.append(assistant_msg)
-    CS -> DB : save_message(session_id, "assistant", content)
-    CS -> DB : save_message(session_id, "tool_call", ...) ×N
+    CS -> DB : save_message(ws_id, "assistant", content)
+    CS -> DB : save_message(ws_id, "tool_call", ...) ×N
 
     == Tool Dispatch (if tool_calls) ==
 
@@ -112,7 +120,7 @@ group loop [while tool_calls present]
         note right of TP
           Parallel execution:
           bash → Popen + line-by-line streaming
-          read_file → open().read()
+          read_file → open().read() or base64 image
           search → grep subprocess
           edit_file → string replace
           task/plan → _run_agent() sub-loop
@@ -136,7 +144,7 @@ group loop [while tool_calls present]
 
         loop for each result
             CS -> CS : messages.append({role: "tool", ...})
-            CS -> DB : save_message(session_id, "tool_result", ...)
+            CS -> DB : save_message(ws_id, "tool_result", ...)
         end
 
         opt user_feedback from approval
@@ -144,6 +152,12 @@ group loop [while tool_calls present]
         end
 
         note right of CS : Loop back for next LLM call
+
+    else GenerationCancelled
+        CS -> CS : Preserve partial content\nor roll back incomplete tools
+        CS -> UI : on_info("[Generation cancelled]")
+        CS -> UI : on_state_change("idle")
+        CS --> User : return (no re-raise)
     end
 
 end

docs/diagrams/05-tool-pipeline.puml

@@ -24,27 +24,31 @@ partition "Phase 1: Prepare" #E8F5E9 {
         :Dispatch to _prepare_{func_name}();
 
         note right
-            **Dispatch table (14 tools):**
-            ┌─────────────┬──────────────────┐
-            │ Tool        │ Needs Approval?  │
-            ├─────────────┼──────────────────┤
-            │ bash        │ ✓ Yes            │
-            │ read_file   │ ✗ Auto-approve   │
-            │ write_file  │ ✓ Yes            │
-            │ edit_file   │ ✓ Yes            │
-            │ search      │ ✗ Auto-approve   │
-            │ math        │ ✓ Yes            │
-            │ man         │ ✗ Auto-approve   │
-            │ web_fetch   │ ✓ Yes            │
-            │ web_search  │ ✓ Yes            │
-            │ task        │ ✓ Yes            │
-            │ plan        │ ✓ Yes            │
-            │ remember    │ ✗ Auto-approve   │
-            │ recall      │ ✗ Auto-approve   │
-            │ forget      │ ✗ Auto-approve   │
-            ├─────────────┼──────────────────┤
-            │ mcp__*      │ ✓ Yes (external) │
-            └─────────────┴──────────────────┘
+            **Dispatch table (18 tools):**
+            ┌───────────────┬──────────────────┐
+            │ Tool          │ Needs Approval?  │
+            ├───────────────┼──────────────────┤
+            │ bash          │ ✓ Yes            │
+            │ read_file     │ ✗ Auto-approve   │
+            │ write_file    │ ✓ Yes            │
+            │ edit_file     │ ✓ Yes            │
+            │ search        │ ✗ Auto-approve   │
+            │ math          │ ✗ Auto-approve   │
+            │ man           │ ✗ Auto-approve   │
+            │ web_fetch     │ ✗ Auto-approve   │
+            │ web_search    │ ✗ Auto-approve   │
+            │ tool_search   │ ✗ Auto-approve   │
+            │ task          │ ✓ Yes            │
+            │ plan          │ ✓ Yes            │
+            │ remember      │ ✗ Auto-approve   │
+            │ recall        │ ✗ Auto-approve   │
+            │ forget        │ ✗ Auto-approve   │
+            │ notify        │ ✗ Auto-approve   │
+            │ read_resource │ ✓ Yes            │
+            │ use_prompt    │ ✓ Yes            │
+            ├───────────────┼──────────────────┤
+            │ mcp__*        │ ✓ Yes (external) │
+            └───────────────┴──────────────────┘
         end note
 
         :Build item dict:
@@ -86,6 +90,8 @@ partition "Phase 2: Approve" #FFF3E0 {
 }
 
 partition "Phase 3: Execute" #E3F2FD {
+    :_check_cancelled();
+    note right: Cancellation checkpoint:\nraises GenerationCancelled if\ncancel event is set
     if (single tool call?) then (yes)
         :Execute sequentially:\nrun_one(items[0]);
     else (multiple)
@@ -98,7 +104,7 @@ partition "Phase 3: Execute" #E3F2FD {
         if item.denied → return denial message
         else → item["execute"](item)
           ├─ _exec_bash: subprocess.run(["bash", script.sh])
-          ├─ _exec_read_file: open().readlines()
+          ├─ _exec_read_file: open().readlines() or _exec_read_image (base64)
           ├─ _exec_write_file: makedirs + write
           ├─ _exec_edit_file: find_occurrences + replace
           ├─ _exec_search: grep subprocess
@@ -106,11 +112,15 @@ partition "Phase 3: Execute" #E3F2FD {
           ├─ _exec_man: man/info subprocess
           ├─ _exec_web_fetch: httpx.get + LLM summary
           ├─ _exec_web_search: Tavily API POST (fallback for local models)
+          ├─ _exec_tool_search: BM25 search + expand_visible()
           ├─ _exec_task: _run_agent(TASK_AGENT_TOOLS)
           ├─ _exec_plan: _run_agent(AGENT_TOOLS, read-only)
+          ├─ _exec_notify: HTTP POST to channel gateway
           ├─ _exec_remember: SQLite INSERT OR REPLACE
           ├─ _exec_recall: SQLite FTS5/LIKE search
           ├─ _exec_forget: SQLite DELETE
+          ├─ _exec_read_resource: MCPClientManager.read_resource_sync()
+          ├─ _exec_use_prompt: MCPClientManager.get_prompt_sync()
           └─ _exec_mcp_tool: MCPClientManager.call_tool_sync()
     end note
 

docs/diagrams/06-mq-protocol.puml

@@ -79,6 +79,12 @@ package "Inbound Messages (Client → Bridge)" #FFF3E0 {
         type = "list_nodes"
     }
 
+    class CancelMessage {
+        type = "cancel"
+        --
+        + ws_id: str
+    }
+
     IM <|-- SendMessage
     IM <|-- ApproveMessage
     IM <|-- PlanFeedbackMessage
@@ -88,6 +94,7 @@ package "Inbound Messages (Client → Bridge)" #FFF3E0 {
     IM <|-- ListWorkstreamsMessage
     IM <|-- HealthMessage
     IM <|-- ListNodesMessage
+    IM <|-- CancelMessage
 }
 
 package "Outbound Events (Bridge → Client)" #E3F2FD {

docs/diagrams/09-workstream-states.puml

@@ -40,6 +40,12 @@ running --> error : Exception during\ntool execution
 
 error --> thinking : New send() call\n_emit_state("thinking")
 
+thinking --> idle : cancel() called\n_emit_state("idle")
+
+running --> idle : cancel() called\n_emit_state("idle")
+
+attention --> idle : cancel() unblocks\napproval/plan wait\n_emit_state("idle")
+
 note right of thinking
   **Emitted via:**
   session._emit_state(state)

docs/diagrams/11-console-data-flow.puml

@@ -78,7 +78,19 @@ activate NodeA
 NodeA --> CC : {status:"ok", version:"0.3.0",\nmodel:"...", workstreams:{...}}
 deactivate NodeA
 
+CC -> CC : Diff old vs new workstream IDs
 CC -> CC : Replace NodeSnapshot["nodeA"]\n.workstreams, .health, .aggregate
+CC -> CC : _fanout(ws_created) for\nnewly appeared workstreams
+CC -> CC : _fanout(ws_closed) for\nremoved workstreams
+
+note right of CC
+  Poll-diff fanout ensures
+  browser SSE clients learn
+  about workstreams that
+  appeared without a real-time
+  cluster event (e.g. bridge
+  startup recovery).
+end note
 
 CC -x NodeB : (SKIPPED: sim:// URL)
 
@@ -89,10 +101,15 @@ deactivate CC
 Browser -> Server : GET /v1/api/cluster/events
 activate Server
 
+Server -> CC : get_snapshot()
+CC --> Server : ClusterSnapshot\n(full current state)
+
 Server -> CC : register_listener(queue)
 note right : Per-client queue.Queue(maxsize=500)\nSSE via EventSourceResponse + run_in_executor()
 
-loop continuous
+Server -> Browser : data: {"type":"snapshot",...}\n(full state as first SSE event)
+
+loop continuous (incremental updates)
     CC -> Server : event via listener queue\n(from any of the 3 threads)
     Server -> Browser : data: {"type":"cluster_state",...}\n\n
 end
@@ -105,6 +122,13 @@ Browser -> Server : connection closed
 Server -> CC : unregister_listener(queue)
 deactivate Server
 
+== Browser REST: Snapshot ==
+
+Browser -> Server : GET /v1/api/cluster/snapshot
+Server -> CC : get_snapshot()
+CC --> Server : ClusterSnapshot\n(full current state)
+Server --> Browser : JSON response
+
 == Browser REST Requests ==
 
 Browser -> Server : GET /v1/api/cluster/overview

docs/diagrams/13-sdk-architecture.puml

@@ -32,10 +32,11 @@ package "turnstone/sdk/ (Python)" {
         + approve()
         + plan_feedback()
         + command()
+        + cancel(ws_id)
         + stream_events(ws_id)
         + stream_global_events()
         + send_and_wait()
-        + list_sessions()
+        + list_saved_workstreams()
         + login() / logout()
         + health()
     }
@@ -45,6 +46,7 @@ package "turnstone/sdk/ (Python)" {
         + nodes()
         + workstreams()
         + node_detail()
+        + snapshot()
         + create_workstream()
         + stream_cluster_events()
         + login() / logout()
@@ -129,6 +131,7 @@ package "sdk/typescript/ (TypeScript)" {
     class "TurnstoneConsole" as TSConsole <<ts>> {
         + overview()
         + nodes()
+        + snapshot()
         + clusterEvents()
         ...
     }

docs/diagrams/14-storage-architecture.puml

@@ -13,23 +13,19 @@ skinparam class {
 
 ' -- Protocol --
 interface "StorageBackend" as SB <<protocol>> {
-    +register_session(session_id, title, node_id, ws_id)
-    +save_message(session_id, role, content, ...)
-    +load_session_messages(session_id) → list[dict]
-    +list_sessions(limit) → list
-    +delete_session(session_id) → bool
-    +prune_sessions(retention_days) → (int, int)
-    +resolve_session(alias_or_id) → str | None
-    +save_session_config(session_id, config)
-    +load_session_config(session_id) → dict
-    +set_session_alias(session_id, alias) → bool
-    +get_session_name(session_id) → str | None
-    +update_session_title(session_id, title)
+    +save_message(ws_id, role, content, ...)
+    +load_messages(ws_id) → list[dict]
     +register_workstream(ws_id, node_id, name, state)
     +update_workstream_state(ws_id, state)
     +update_workstream_name(ws_id, name)
+    +set_workstream_alias(ws_id, alias) → bool
+    +update_workstream_title(ws_id, title)
+    +resolve_workstream(alias_or_id) → str | None
     +delete_workstream(ws_id) → bool
+    +prune_workstreams(retention_days) → (int, int)
     +list_workstreams(node_id, limit) → list
+    +save_workstream_config(ws_id, config)
+    +load_workstream_config(ws_id) → dict
     +kv_get(key) → str | None
     +kv_set(key, value) → str | None
     +kv_delete(key) → bool
@@ -68,9 +64,8 @@ class "_schema.py" as Schema <<schema>> {
     +metadata: MetaData
     +memories: Table
     +conversations: Table
-    +sessions: Table (node_id, ws_id, user_id)
-    +workstreams: Table (node_id, user_id, state)
-    +session_config: Table
+    +workstreams: Table (node_id, alias, title, state)
+    +workstream_config: Table
     +users: Table (username, password_hash)
     +api_tokens: Table (token_hash, scopes)
     +channel_users: Table (channel_type)
@@ -106,14 +101,14 @@ class "_registry.py" as Registry {
 
 ' -- Facade --
 class "memory.py" as Facade <<facade>> {
-    +register_session()
     +save_message()
-    +load_session_messages()
+    +load_messages()
     +register_workstream()
     +update_workstream_state()
+    +save_workstream_config()
     +save_memory() / delete_memory()
     +search_memories()
-    +... (all 22 functions)
+    +... (all delegated functions)
     --
     Thin delegation to
     get_storage()

docs/diagrams/16-channel-architecture.puml

@@ -195,13 +195,13 @@ note right of Bot
   5. Broker.push_inbound(SendMessage)
   6. Bridge pops from Redis, drives server
 
-  **Session Resume (evicted workstreams)**
+  **Workstream Resume (evicted workstreams)**
   1. Stale route detected (no MQ owner)
-  2. Old session looked up via get_session_id_by_ws()
+  2. Existing ws_id reused directly from route
   3. CreateWorkstreamMessage sent with
-     resume_session=<old_session_id>
+     resume_ws=<ws_id>
   4. Server resumes atomically during creation
-  5. Bridge emits SessionResumedEvent → thread
+  5. Bridge emits WorkstreamResumedEvent → thread
 end note
 
 note right of Broker

docs/diagrams/18-watch-architecture.puml

@@ -0,0 +1,166 @@
+@startuml
+!theme plain
+title Turnstone — Watch Tool Architecture
+
+skinparam participant {
+    BackgroundColor<<server>> #FFE0B2
+    BackgroundColor<<storage>> #B3E5FC
+    BackgroundColor<<session>> #C8E6C9
+    BackgroundColor<<ui>> #E8EAF6
+}
+
+participant "ChatSession\n(session.py)" as Session <<session>>
+participant "WatchRunner\n(watch.py)" as Runner <<server>>
+participant "StorageBackend\n(SQLite)" as Storage <<storage>>
+participant "WebUI / SSE\n(server.py)" as UI <<ui>>
+
+== Create Phase ==
+
+Session -> Session : _prepare_watch(action="create")
+note right
+  Validates:
+  - command via is_command_blocked()
+  - poll_every → parse_duration()
+  - stop_on → validate_condition()
+  - max watches limit (5)
+  - duplicate name check
+  needs_approval = True
+end note
+
+Session -> Storage : create_watch(watch_id, ws_id,\nnode_id, command, interval,\nstop_on, max_polls, next_poll)
+
+Session --> UI : tool_result:\n"Watch 'pr-review' created"
+
+== Poll Phase (WatchRunner daemon, every 15s) ==
+
+Runner -> Storage : list_due_watches(now)
+Storage --> Runner : due_watches[]
+note right
+  Filters:
+  active=1 AND
+  next_poll <= now AND
+  node_id matches
+end note
+
+loop for each due watch
+
+    Runner -> Runner : is_command_blocked()?
+    alt blocked
+        Runner -> Storage : update_watch(active=False)
+    else safe
+
+        Runner -> Runner : subprocess.run(command)
+        note right
+          timeout = tool_timeout
+          start_new_session = True
+          output truncated at 64KB
+        end note
+
+        Runner -> Runner : evaluate_condition(\nstop_on, output,\nexit_code, prev_output)
+        note right
+          **Variables:**
+          output, data, exit_code,
+          prev_output, changed
+
+          **Safe builtins only:**
+          len, str, int, sorted, ...
+          No import/open/exec/eval
+
+          **stop_on=None:**
+          fires on change (skip 1st poll)
+        end note
+
+        alt condition fired OR max_polls reached
+            Runner -> Storage : update_watch(\npoll_count++,\nlast_output, active=False)
+            Runner -> Runner : format_watch_message()
+            Runner -> Runner : _dispatch_result(ws_id, msg)
+        else not fired
+            Runner -> Storage : update_watch(\npoll_count++,\nlast_output, next_poll)
+        end
+
+    end
+end
+
+== Dispatch Phase ==
+
+note over Runner, Session
+  **Three dispatch paths:**
+end note
+
+alt Path A: workstream active + idle
+    Runner -> Session : dispatch_fn(message)\n→ _watch_pending.put()
+    Session -> Session : _dispatch_pending_watch()\n→ self.send(message)
+    Session -> UI : SSE: thinking, content,\ntool calls...
+    note right
+      Watch result appears as
+      synthetic user message.
+      Model sees it and responds.
+      Depth guard: max 5 chains.
+    end note
+
+else Path B: workstream active + busy
+    Runner -> Session : dispatch_fn(message)\n→ _watch_pending.put()
+    note right
+      Queued. Dispatched when
+      current send() reaches IDLE.
+    end note
+
+else Path C: workstream evicted
+    Runner -> Runner : restore_fn(ws_id)
+    note right
+      1. mgr.create() — may evict
+         another idle workstream
+      2. session.resume(ws_id)
+      3. set_watch_runner()
+      4. register new dispatch_fn
+    end note
+    Runner -> Session : restored dispatch_fn(message)
+end
+
+== Cancel / List ==
+
+Session -> Storage : list_watches_for_ws(ws_id)
+note right : action="list" (auto-approve)
+
+Session -> Storage : update_watch(active=False)
+note right : action="cancel" (auto-approve)
+
+== Server Lifecycle ==
+
+note over Runner, Storage
+  **Startup:**
+  1. WatchRunner created in main() with storage + node_id
+  2. restore_fn closure captures WorkstreamManager
+  3. Initial workstream: session.set_watch_runner(runner)
+  4. _lifespan(): runner.start() — daemon thread begins
+
+  **New workstream:**
+  session.set_watch_runner(runner) in create_workstream()
+  → registers dispatch_fn for ws_id
+
+  **Eviction / close:**
+  session.close() → runner.remove_dispatch_fn(ws_id)
+  Watches remain active in DB — WatchRunner uses restore_fn
+
+  **Restart recovery:**
+  Overdue watches fire ONE immediate poll
+  next_poll updated to now + interval
+  Normal cadence resumes
+
+  **Shutdown:**
+  _lifespan(): runner.stop() — joins thread
+end note
+
+== REST API ==
+
+note over UI, Storage
+  **GET /v1/api/watches[?ws_id=X]**
+  List active watches (for node or workstream)
+
+  **POST /v1/api/watches/{watch_id}/cancel**
+  Cancel a watch (sets active=False)
+
+  Both require write scope
+end note
+
+@enduml

docs/diagrams/19-governance-architecture.puml

@@ -0,0 +1,81 @@
+@startuml
+!theme plain
+skinparam backgroundColor #FFFFFF
+skinparam defaultFontName "IBM Plex Mono"
+skinparam componentStyle rectangle
+
+title Turnstone Governance Architecture
+
+package "Auth Flow" {
+  [Login/Token Auth] as auth
+  [_load_user_permissions()] as perms
+  [_permissions_to_scopes()] as scopes
+  [create_jwt()] as jwt
+}
+
+package "Middleware" {
+  [AuthMiddleware\n(scope check)] as mw
+  [require_permission()\n(granular check)] as rp
+}
+
+package "Governance Storage" {
+  database "roles" as roles_db
+  database "user_roles" as ur_db
+  database "orgs" as orgs_db
+  database "tool_policies" as tp_db
+  database "prompt_templates" as pt_db
+  database "usage_events" as ue_db
+  database "audit_events" as ae_db
+}
+
+package "Runtime Enforcement" {
+  [evaluate_tool_policies_batch()] as eval
+  [WebUI.approve_tools()] as approve
+  [record_usage_event()] as usage
+  [record_audit()] as audit
+}
+
+package "Template Runtime" {
+  [_load_templates()] as tload
+  [_render_template()\n{{model}}, {{ws_id}}, {{node_id}}] as trender
+  [_init_system_messages()] as tsys
+  [set_template() / /template] as tset
+}
+
+package "Console UI" {
+  [Admin Panel\n10 tabs] as ui
+  [governance.js] as govjs
+  [sessionStorage\npermissions] as ss
+}
+
+auth --> perms : user_id
+perms --> roles_db : JOIN user_roles + roles
+perms --> scopes : permission set
+scopes --> jwt : scopes + permissions
+
+jwt --> mw : JWT in cookie/header
+mw --> rp : scope OK → check permission
+
+rp --> ui : 403 or allow
+
+eval --> tp_db : list_tool_policies()
+approve --> eval : tool names
+approve --> ae_db : (via audit)
+
+usage --> ue_db : on_status()
+audit --> ae_db : admin handlers
+
+govjs --> roles_db : /v1/api/admin/roles
+govjs --> tp_db : /v1/api/admin/policies
+govjs --> pt_db : /v1/api/admin/templates
+govjs --> ue_db : /v1/api/admin/usage
+govjs --> ae_db : /v1/api/admin/audit
+
+tload --> pt_db : list_default_templates()\nor get_by_name()
+tload --> trender : template content
+trender --> tsys : rendered content
+tset --> tload : name or None
+
+auth -[hidden]-> mw
+mw -[hidden]-> approve
+@enduml

docs/diagrams/20-mcp-architecture.puml

@@ -0,0 +1,158 @@
+@startuml
+!theme plain
+title Turnstone — MCP Architecture (Resources, Prompts, Tools)
+
+skinparam participant {
+    BackgroundColor<<mcp>> #E1BEE7
+    BackgroundColor<<session>> #C8E6C9
+    BackgroundColor<<storage>> #B3E5FC
+    BackgroundColor<<server>> #FFE0B2
+    BackgroundColor<<ui>> #E8EAF6
+}
+
+participant "MCP Server\n(external)" as MCPSrv <<mcp>>
+participant "MCPClientManager\n(mcp_client.py)" as MCPMgr <<mcp>>
+participant "ChatSession\n(session.py)" as Session <<session>>
+participant "StorageBackend\n(governance)" as Storage <<storage>>
+participant "Server / Console\n(health + UI)" as UI <<server>>
+
+== Startup: Connection & Discovery ==
+
+MCPMgr -> MCPSrv : initialize (stdio or HTTP)
+MCPSrv --> MCPMgr : capabilities\n(tools, resources, prompts)
+
+MCPMgr -> MCPSrv : tools/list
+MCPSrv --> MCPMgr : Tool[]
+
+opt resources capability
+  MCPMgr -> MCPSrv : resources/list
+  MCPSrv --> MCPMgr : Resource[]
+  MCPMgr -> MCPSrv : resources/templates/list
+  MCPSrv --> MCPMgr : ResourceTemplate[]
+end
+
+opt prompts capability
+  MCPMgr -> MCPSrv : prompts/list
+  MCPSrv --> MCPMgr : Prompt[]
+end
+
+note over MCPMgr
+  Per-server storage:
+  _per_server_tools, _per_server_resources, _per_server_prompts
+  Copy-on-write rebuild into _tools, _resources, _prompts
+  Prefix: mcp__{server}__{name}
+end note
+
+MCPMgr -> Session : notify tool listeners
+MCPMgr -> Session : notify resource listeners
+
+== Governance Sync (on connect & refresh) ==
+
+MCPMgr -> Storage : sync_prompts_to_storage()
+note right
+  For each MCP prompt:
+  - Manual template exists? → skip
+  - MCP template exists? → update
+    (reset is_default=False)
+  - New? → create (origin="mcp",
+    readonly=True, is_default=False)
+  Removed prompts → delete
+  Protected by _sync_lock
+end note
+
+== set_storage() from entry point ==
+
+UI -> MCPMgr : set_storage(backend)
+note right
+  If servers already connected,
+  triggers immediate sync
+end note
+
+== Runtime: Tool Execution ==
+
+Session -> Session : _prepare_mcp_tool(func_name, args)
+note right
+  approval_label = func_name
+  (e.g. mcp__github__search)
+  needs_approval = True
+end note
+Session -> MCPMgr : call_tool_sync(name, args)
+MCPMgr -> MCPSrv : tools/call
+MCPSrv --> MCPMgr : ToolResult
+MCPMgr --> Session : output (text)
+
+== Runtime: Resource Read ==
+
+Session -> Session : _prepare_read_resource(uri)
+note right
+  approval_label = mcp_resource__{normalized_uri}
+  URI normalized (.. resolved)
+  needs_approval = True
+end note
+Session -> MCPMgr : read_resource_sync(uri)
+MCPMgr -> MCPSrv : resources/read
+MCPSrv --> MCPMgr : ReadResourceResult
+MCPMgr --> Session : content (text/blob)
+
+== Runtime: Prompt Invocation ==
+
+Session -> Session : _prepare_use_prompt(name, arguments)
+note right
+  approval_label = mcp__srv__prompt
+  Validated via is_mcp_prompt()
+  needs_approval = True
+end note
+Session -> MCPMgr : get_prompt_sync(name, args)
+MCPMgr -> MCPSrv : prompts/get
+MCPSrv --> MCPMgr : GetPromptResult
+MCPMgr --> Session : messages [{role, content}]
+
+== Three-Tier Refresh ==
+
+group Push Notifications
+  MCPSrv -> MCPMgr : ToolListChangedNotification
+  MCPMgr -> MCPMgr : _refresh_server_tools()
+
+  MCPSrv -> MCPMgr : ResourceListChangedNotification
+  MCPMgr -> MCPMgr : _refresh_server_resources()
+
+  MCPSrv -> MCPMgr : PromptListChangedNotification
+  MCPMgr -> MCPMgr : _refresh_server_prompts()
+  MCPMgr -> Storage : sync_prompts_to_storage()
+end
+
+group Periodic Polling (default 4h)
+  MCPMgr -> MCPMgr : _periodic_refresh()
+  note right
+    Only polls capabilities
+    without push support.
+    Staggered per-server.
+  end note
+end
+
+group Manual Refresh
+  Session -> MCPMgr : refresh_sync()
+  note right: /mcp refresh [server]
+end
+
+== Policy Evaluation ==
+
+note over Session
+  Tool policies use fnmatch on approval_label:
+  - mcp__github__* → allow (all GitHub tools/prompts)
+  - mcp_resource__file:///docs/* → allow
+  - mcp_resource__* → deny (block all resource reads)
+  - mcp__untrusted__* → ask
+end note
+
+== UI Visibility ==
+
+UI -> MCPMgr : server_count, get_resources(), get_prompts()
+note over UI
+  /health → mcp.servers, mcp.resources, mcp.prompts
+  Server UI: magenta status badge
+  Console: cluster status bar + node detail
+  System message: <mcp-resources> + <mcp-prompts> catalogs
+end note
+
+@enduml

docs/diagrams/architecture-overview.svg

@@ -0,0 +1,286 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 540" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif">
+  <defs>
+    <!-- Arrowhead markers -->
+    <marker id="arrow" viewBox="0 0 10 7" refX="10" refY="3.5" markerWidth="8" markerHeight="6" orient="auto-start-auto">
+      <path d="M 0 0 L 10 3.5 L 0 7 z" fill="#484f58"/>
+    </marker>
+    <marker id="arrow-blue" viewBox="0 0 10 7" refX="10" refY="3.5" markerWidth="8" markerHeight="6" orient="auto-start-auto">
+      <path d="M 0 0 L 10 3.5 L 0 7 z" fill="#58a6ff"/>
+    </marker>
+    <marker id="arrow-green" viewBox="0 0 10 7" refX="10" refY="3.5" markerWidth="8" markerHeight="6" orient="auto-start-auto">
+      <path d="M 0 0 L 10 3.5 L 0 7 z" fill="#3fb950"/>
+    </marker>
+    <marker id="arrow-orange" viewBox="0 0 10 7" refX="10" refY="3.5" markerWidth="8" markerHeight="6" orient="auto-start-auto">
+      <path d="M 0 0 L 10 3.5 L 0 7 z" fill="#f0883e"/>
+    </marker>
+    <marker id="arrow-coral" viewBox="0 0 10 7" refX="10" refY="3.5" markerWidth="8" markerHeight="6" orient="auto-start-auto">
+      <path d="M 0 0 L 10 3.5 L 0 7 z" fill="#f47067"/>
+    </marker>
+    <marker id="arrow-muted" viewBox="0 0 10 7" refX="10" refY="3.5" markerWidth="8" markerHeight="6" orient="auto-start-auto">
+      <path d="M 0 0 L 10 3.5 L 0 7 z" fill="#8b949e"/>
+    </marker>
+
+    <!-- Card shadow filter -->
+    <filter id="shadow" x="-4%" y="-4%" width="108%" height="112%">
+      <feDropShadow dx="0" dy="1" stdDeviation="2" flood-color="#000" flood-opacity="0.4"/>
+    </filter>
+  </defs>
+
+  <!-- Background -->
+  <rect width="1200" height="540" rx="8" fill="#0d1117"/>
+
+  <!-- Title -->
+  <text x="600" y="36" text-anchor="middle" fill="#e6edf3" font-size="15" font-weight="700" letter-spacing="3">TURNSTONE</text>
+  <text x="600" y="54" text-anchor="middle" fill="#8b949e" font-size="11" letter-spacing="1">SYSTEM ARCHITECTURE</text>
+
+  <!-- ==================== COLUMN HEADERS ==================== -->
+  <text x="90" y="86" text-anchor="middle" fill="#58a6ff" font-size="9" font-weight="600" letter-spacing="2">CLIENTS</text>
+  <text x="276" y="86" text-anchor="middle" fill="#3fb950" font-size="9" font-weight="600" letter-spacing="2">GATEWAYS</text>
+  <text x="480" y="86" text-anchor="middle" fill="#f0883e" font-size="9" font-weight="600" letter-spacing="2">MESSAGE QUEUE</text>
+  <text x="700" y="86" text-anchor="middle" fill="#f47067" font-size="9" font-weight="600" letter-spacing="2">CLUSTER NODES</text>
+  <text x="940" y="86" text-anchor="middle" fill="#f778ba" font-size="9" font-weight="600" letter-spacing="2">LLM PROVIDERS</text>
+
+  <!-- ==================== CLIENT BOXES ==================== -->
+  <!-- CLI -->
+  <g filter="url(#shadow)">
+    <rect x="30" y="108" width="120" height="46" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="30" y="108" width="120" height="5" rx="5" fill="#58a6ff"/>
+    <rect x="30" y="108" width="120" height="5" fill="#58a6ff"/>
+    <rect x="30" y="111" width="120" height="2" fill="#161b22"/>
+    <text x="90" y="130" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">CLI</text>
+    <text x="90" y="145" text-anchor="middle" fill="#8b949e" font-size="9">terminal REPL</text>
+  </g>
+
+  <!-- Browser UI -->
+  <g filter="url(#shadow)">
+    <rect x="30" y="174" width="120" height="46" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="30" y="174" width="120" height="5" rx="5" fill="#58a6ff"/>
+    <rect x="30" y="174" width="120" height="5" fill="#58a6ff"/>
+    <rect x="30" y="177" width="120" height="2" fill="#161b22"/>
+    <text x="90" y="196" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">Browser UI</text>
+    <text x="90" y="211" text-anchor="middle" fill="#8b949e" font-size="9">HTTP + SSE</text>
+  </g>
+
+  <!-- SDK / API -->
+  <g filter="url(#shadow)">
+    <rect x="30" y="244" width="120" height="46" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="30" y="244" width="120" height="5" rx="5" fill="#58a6ff"/>
+    <rect x="30" y="244" width="120" height="5" fill="#58a6ff"/>
+    <rect x="30" y="247" width="120" height="2" fill="#161b22"/>
+    <text x="90" y="266" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">SDK / API</text>
+    <text x="90" y="281" text-anchor="middle" fill="#8b949e" font-size="9">programmatic</text>
+  </g>
+
+  <!-- Discord / Slack -->
+  <g filter="url(#shadow)">
+    <rect x="30" y="314" width="120" height="46" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="30" y="314" width="120" height="5" rx="5" fill="#58a6ff"/>
+    <rect x="30" y="314" width="120" height="5" fill="#58a6ff"/>
+    <rect x="30" y="317" width="120" height="2" fill="#161b22"/>
+    <text x="90" y="336" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">Discord / Slack</text>
+    <text x="90" y="351" text-anchor="middle" fill="#8b949e" font-size="9">chat platforms</text>
+  </g>
+
+  <!-- ==================== GATEWAY BOXES ==================== -->
+  <!-- Console -->
+  <g filter="url(#shadow)">
+    <rect x="216" y="118" width="120" height="58" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="216" y="118" width="120" height="5" rx="5" fill="#3fb950"/>
+    <rect x="216" y="118" width="120" height="5" fill="#3fb950"/>
+    <rect x="216" y="121" width="120" height="2" fill="#161b22"/>
+    <text x="276" y="142" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">Console</text>
+    <text x="276" y="157" text-anchor="middle" fill="#8b949e" font-size="9">dashboard + proxy</text>
+    <text x="276" y="169" text-anchor="middle" fill="#8b949e" font-size="9">cluster management</text>
+  </g>
+
+  <!-- Channel Gateway -->
+  <g filter="url(#shadow)">
+    <rect x="216" y="292" width="120" height="58" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="216" y="292" width="120" height="5" rx="5" fill="#3fb950"/>
+    <rect x="216" y="292" width="120" height="5" fill="#3fb950"/>
+    <rect x="216" y="295" width="120" height="2" fill="#161b22"/>
+    <text x="276" y="316" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">Channel Gateway</text>
+    <text x="276" y="331" text-anchor="middle" fill="#8b949e" font-size="9">platform adapter</text>
+    <text x="276" y="343" text-anchor="middle" fill="#8b949e" font-size="9">Discord, Slack, ...</text>
+  </g>
+
+  <!-- ==================== REDIS MQ ==================== -->
+  <g filter="url(#shadow)">
+    <rect x="420" y="168" width="120" height="132" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="420" y="168" width="120" height="5" rx="5" fill="#f0883e"/>
+    <rect x="420" y="168" width="120" height="5" fill="#f0883e"/>
+    <rect x="420" y="171" width="120" height="2" fill="#161b22"/>
+    <text x="480" y="198" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">Redis MQ</text>
+    <line x1="438" y1="210" x2="522" y2="210" stroke="#30363d" stroke-width="1"/>
+    <text x="480" y="228" text-anchor="middle" fill="#8b949e" font-size="9">inbound queues</text>
+    <text x="480" y="243" text-anchor="middle" fill="#8b949e" font-size="9">event pub/sub</text>
+    <text x="480" y="258" text-anchor="middle" fill="#8b949e" font-size="9">node heartbeats</text>
+    <text x="480" y="273" text-anchor="middle" fill="#8b949e" font-size="9">workstream routing</text>
+    <text x="480" y="288" text-anchor="middle" fill="#8b949e" font-size="9">cluster state</text>
+  </g>
+
+  <!-- ==================== CLUSTER NODES ==================== -->
+  <!-- Cluster outline -->
+  <rect x="598" y="100" width="204" height="310" rx="8" fill="none" stroke="#30363d" stroke-width="1" stroke-dasharray="4,3"/>
+  <text x="700" y="422" text-anchor="middle" fill="#30363d" font-size="9" letter-spacing="1">CLUSTER</text>
+
+  <!-- Node A -->
+  <g filter="url(#shadow)">
+    <rect x="614" y="118" width="170" height="100" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="614" y="118" width="170" height="5" rx="5" fill="#f47067"/>
+    <rect x="614" y="118" width="170" height="5" fill="#f47067"/>
+    <rect x="614" y="121" width="170" height="2" fill="#161b22"/>
+    <text x="699" y="142" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">Node A</text>
+    <line x1="632" y1="152" x2="766" y2="152" stroke="#30363d" stroke-width="1"/>
+    <!-- Bridge -->
+    <rect x="626" y="162" width="70" height="28" rx="3" fill="#1c2128" stroke="#30363d" stroke-width="1"/>
+    <text x="661" y="180" text-anchor="middle" fill="#8b949e" font-size="9">bridge</text>
+    <!-- Server -->
+    <rect x="704" y="162" width="70" height="28" rx="3" fill="#1c2128" stroke="#30363d" stroke-width="1"/>
+    <text x="739" y="180" text-anchor="middle" fill="#8b949e" font-size="9">server</text>
+    <!-- Arrow bridge to server -->
+    <line x1="696" y1="176" x2="702" y2="176" stroke="#484f58" stroke-width="1" marker-end="url(#arrow)"/>
+    <!-- Tools label -->
+    <text x="699" y="206" text-anchor="middle" fill="#484f58" font-size="8">14 tools + MCP</text>
+  </g>
+
+  <!-- Node B -->
+  <g filter="url(#shadow)">
+    <rect x="614" y="238" width="170" height="100" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="614" y="238" width="170" height="5" rx="5" fill="#f47067"/>
+    <rect x="614" y="238" width="170" height="5" fill="#f47067"/>
+    <rect x="614" y="241" width="170" height="2" fill="#161b22"/>
+    <text x="699" y="262" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">Node B</text>
+    <line x1="632" y1="272" x2="766" y2="272" stroke="#30363d" stroke-width="1"/>
+    <!-- Bridge -->
+    <rect x="626" y="282" width="70" height="28" rx="3" fill="#1c2128" stroke="#30363d" stroke-width="1"/>
+    <text x="661" y="300" text-anchor="middle" fill="#8b949e" font-size="9">bridge</text>
+    <!-- Server -->
+    <rect x="704" y="282" width="70" height="28" rx="3" fill="#1c2128" stroke="#30363d" stroke-width="1"/>
+    <text x="739" y="300" text-anchor="middle" fill="#8b949e" font-size="9">server</text>
+    <!-- Arrow bridge to server -->
+    <line x1="696" y1="296" x2="702" y2="296" stroke="#484f58" stroke-width="1" marker-end="url(#arrow)"/>
+    <!-- Tools label -->
+    <text x="699" y="326" text-anchor="middle" fill="#484f58" font-size="8">14 tools + MCP</text>
+  </g>
+
+  <!-- ==================== LLM PROVIDERS ==================== -->
+  <!-- OpenAI -->
+  <g filter="url(#shadow)">
+    <rect x="870" y="130" width="140" height="46" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="870" y="130" width="140" height="5" rx="5" fill="#f778ba"/>
+    <rect x="870" y="130" width="140" height="5" fill="#f778ba"/>
+    <rect x="870" y="133" width="140" height="2" fill="#161b22"/>
+    <text x="940" y="153" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">OpenAI</text>
+    <text x="940" y="167" text-anchor="middle" fill="#8b949e" font-size="9">GPT-5, o-series</text>
+  </g>
+
+  <!-- Anthropic -->
+  <g filter="url(#shadow)">
+    <rect x="870" y="196" width="140" height="46" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="870" y="196" width="140" height="5" rx="5" fill="#f778ba"/>
+    <rect x="870" y="196" width="140" height="5" fill="#f778ba"/>
+    <rect x="870" y="199" width="140" height="2" fill="#161b22"/>
+    <text x="940" y="219" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">Anthropic</text>
+    <text x="940" y="233" text-anchor="middle" fill="#8b949e" font-size="9">Claude 4.5 / 4.6</text>
+  </g>
+
+  <!-- Local / vLLM -->
+  <g filter="url(#shadow)">
+    <rect x="870" y="262" width="140" height="46" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="870" y="262" width="140" height="5" rx="5" fill="#f778ba"/>
+    <rect x="870" y="262" width="140" height="5" fill="#f778ba"/>
+    <rect x="870" y="265" width="140" height="2" fill="#161b22"/>
+    <text x="940" y="285" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">Local / vLLM</text>
+    <text x="940" y="299" text-anchor="middle" fill="#8b949e" font-size="9">llama.cpp, NIM</text>
+  </g>
+
+  <!-- ==================== STORAGE ==================== -->
+  <g filter="url(#shadow)">
+    <rect x="614" y="450" width="170" height="52" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="614" y="450" width="170" height="5" rx="5" fill="#bc8cff"/>
+    <rect x="614" y="450" width="170" height="5" fill="#bc8cff"/>
+    <rect x="614" y="453" width="170" height="2" fill="#161b22"/>
+    <text x="699" y="476" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">PostgreSQL / SQLite</text>
+    <text x="699" y="492" text-anchor="middle" fill="#8b949e" font-size="9">conversations, memory, auth</text>
+  </g>
+  <text x="699" y="444" text-anchor="middle" fill="#bc8cff" font-size="9" font-weight="600" letter-spacing="2">STORAGE</text>
+
+  <!-- ==================== CONNECTION LINES ==================== -->
+
+  <!-- CLIENT -> GATEWAY connections -->
+  <!-- Browser -> Console -->
+  <line x1="150" y1="197" x2="214" y2="155" stroke="#58a6ff" stroke-width="1.2" stroke-opacity="0.6" marker-end="url(#arrow-blue)"/>
+  <!-- Discord -> Channel -->
+  <line x1="150" y1="337" x2="214" y2="325" stroke="#58a6ff" stroke-width="1.2" stroke-opacity="0.6" marker-end="url(#arrow-blue)"/>
+
+  <!-- CLI -> direct to Node A server (top path, curved) -->
+  <path d="M 150 131 C 200 131, 200 100, 400 100 L 400 100 C 500 100, 570 140, 612 168" stroke="#58a6ff" stroke-width="1.2" stroke-opacity="0.5" fill="none" stroke-dasharray="6,3" marker-end="url(#arrow-blue)"/>
+  <text x="370" y="96" fill="#484f58" font-size="8" text-anchor="middle">direct</text>
+
+  <!-- SDK -> Redis (direct push) -->
+  <line x1="150" y1="267" x2="418" y2="240" stroke="#58a6ff" stroke-width="1.2" stroke-opacity="0.6" marker-end="url(#arrow-blue)"/>
+
+  <!-- GATEWAY -> REDIS connections -->
+  <!-- Console -> Redis -->
+  <line x1="336" y1="160" x2="418" y2="200" stroke="#3fb950" stroke-width="1.2" stroke-opacity="0.6" marker-end="url(#arrow-green)"/>
+  <!-- Channel -> Redis -->
+  <line x1="336" y1="318" x2="418" y2="272" stroke="#3fb950" stroke-width="1.2" stroke-opacity="0.6" marker-end="url(#arrow-green)"/>
+
+  <!-- REDIS -> NODE connections -->
+  <!-- Redis -> Node A bridge -->
+  <line x1="540" y1="210" x2="624" y2="176" stroke="#f0883e" stroke-width="1.2" stroke-opacity="0.6" marker-end="url(#arrow-orange)"/>
+  <!-- Redis -> Node B bridge -->
+  <line x1="540" y1="260" x2="624" y2="296" stroke="#f0883e" stroke-width="1.2" stroke-opacity="0.6" marker-end="url(#arrow-orange)"/>
+
+  <!-- Console -> Node (proxy, dashed) -->
+  <path d="M 336 147 C 380 130, 500 108, 612 145" stroke="#3fb950" stroke-width="1" stroke-opacity="0.4" fill="none" stroke-dasharray="4,3" marker-end="url(#arrow-green)"/>
+  <text x="468" y="120" fill="#484f58" font-size="8" text-anchor="middle">proxy</text>
+
+  <!-- NODE -> LLM connections -->
+  <!-- Node A -> LLM providers -->
+  <line x1="784" y1="168" x2="868" y2="155" stroke="#f47067" stroke-width="1.2" stroke-opacity="0.5" marker-end="url(#arrow-coral)"/>
+  <line x1="784" y1="176" x2="868" y2="219" stroke="#f47067" stroke-width="1.2" stroke-opacity="0.3"/>
+  <line x1="784" y1="180" x2="868" y2="282" stroke="#f47067" stroke-width="1.2" stroke-opacity="0.2"/>
+
+  <!-- Node B -> LLM providers -->
+  <line x1="784" y1="288" x2="868" y2="163" stroke="#f47067" stroke-width="1.2" stroke-opacity="0.2"/>
+  <line x1="784" y1="296" x2="868" y2="222" stroke="#f47067" stroke-width="1.2" stroke-opacity="0.3"/>
+  <line x1="784" y1="300" x2="868" y2="288" stroke="#f47067" stroke-width="1.2" stroke-opacity="0.5" marker-end="url(#arrow-coral)"/>
+
+  <!-- NODE -> STORAGE connections -->
+  <line x1="680" y1="338" x2="680" y2="448" stroke="#bc8cff" stroke-width="1.2" stroke-opacity="0.4" stroke-dasharray="4,3" marker-end="url(#arrow-muted)"/>
+  <line x1="718" y1="218" x2="718" y2="236" stroke="#484f58" stroke-width="1" stroke-opacity="0.3" stroke-dasharray="2,2"/>
+
+  <!-- Extensibility hint -->
+  <text x="699" y="392" text-anchor="middle" fill="#30363d" font-size="10">...</text>
+
+  <!-- Event flow: Bridges -> Redis (dashed, bidirectional feel) -->
+  <line x1="624" y1="186" x2="542" y2="220" stroke="#f0883e" stroke-width="1" stroke-opacity="0.3" stroke-dasharray="3,3"/>
+  <line x1="624" y1="286" x2="542" y2="250" stroke="#f0883e" stroke-width="1" stroke-opacity="0.3" stroke-dasharray="3,3"/>
+  <text x="574" y="242" fill="#484f58" font-size="7" text-anchor="middle">events</text>
+
+  <!-- ==================== FLOW LABELS ==================== -->
+  <!-- Interactive flow label -->
+  <rect x="30" y="395" width="10" height="10" rx="2" fill="none" stroke="#58a6ff" stroke-width="1.5" stroke-dasharray="3,2"/>
+  <text x="46" y="404" fill="#8b949e" font-size="9">interactive (direct)</text>
+
+  <!-- Queue flow label -->
+  <rect x="160" y="395" width="10" height="10" rx="2" fill="none" stroke="#f0883e" stroke-width="1.5"/>
+  <text x="176" y="404" fill="#8b949e" font-size="9">queue-driven</text>
+
+  <!-- Proxy/event label -->
+  <rect x="275" y="395" width="10" height="10" rx="2" fill="none" stroke="#3fb950" stroke-width="1.5" stroke-dasharray="3,2"/>
+  <text x="291" y="404" fill="#8b949e" font-size="9">proxy / events</text>
+
+  <!-- ==================== BOTTOM DETAILS ==================== -->
+  <line x1="30" y1="430" x2="1170" y2="430" stroke="#21262d" stroke-width="1"/>
+
+  <!-- Routing rules at bottom, left-aligned -->
+  <text x="44" y="456" fill="#30363d" font-size="9" font-weight="600" letter-spacing="1">ROUTING</text>
+  <circle cx="44" cy="474" r="3" fill="#f47067" opacity="0.6"/>
+  <text x="54" y="477" fill="#484f58" font-size="9">target_node set  &#x2192;  route to specific node queue</text>
+  <circle cx="44" cy="494" r="3" fill="#f0883e" opacity="0.6"/>
+  <text x="54" y="497" fill="#484f58" font-size="9">ws_id set  &#x2192;  route to owning node</text>
+  <circle cx="44" cy="514" r="3" fill="#58a6ff" opacity="0.6"/>
+  <text x="54" y="517" fill="#484f58" font-size="9">neither  &#x2192;  shared queue, any node picks up</text></svg>

docs/diagrams/png/01-system-context.png

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:9a1b0361c466327d0011a488847ea3c0365983713537d4a7c27cd7f5538ba33c
-size 164829
+oid sha256:d8ce6d2a43a991655c3f64a20b6e810fdb2f78eb767acc3d3d1b8d2c9f443181
+size 165011

docs/diagrams/png/02-package-structure.png

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:7d75da92a657525bcbb7a425dc6c8d3cafe074c3ac3bff3cf4b1d44aea607b50
-size 330156
+oid sha256:c9daca81971ba7a8ed6736d23d5373c69435158fa6240b9880d14fc4759ab580
+size 329673

docs/diagrams/png/03-core-engine-classes.png

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:637458e0d78df82752746e519cd7300a830c8ce211f21625694ad0c162ca316d
-size 481637
+oid sha256:01fbb3338df6426cefc2811541a865f268673b4febf32f524c264d120bc068fa
+size 589546

docs/diagrams/png/04-conversation-turn.png

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:dc3b64c9e48153641af62ed43fbc1d89a31d1a8a61e7e71cfc550c805000310d
-size 288290
+oid sha256:da9d32000e3d92d92ce621661ced60f276f9b5be652f5ed6123b400505415f4a
+size 319702

docs/diagrams/png/05-tool-pipeline.png

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:b842683d238664a3e35d04358fecfc56cefd013f7dca5f13357b0376f881e1b3
-size 245043
+oid sha256:6dd3c923d1e1c49b5f91d8d342fb4b0d49a46d432460379ad146a9e3b075a05a
+size 277234

docs/diagrams/png/06-mq-protocol.png

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:b22d5980fe5cc4b8466ba0797113dc8fa83fab8df24b5dacceaf97e62e2e25b0
-size 187649
+oid sha256:d17f3feacf7bc9f64dfea19464143bc9b6ef0da5d55e6d57c0bc5a73d5724eba
+size 184466

docs/diagrams/png/07-message-routing.png

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:90e4f74be795b530e711faa87bc6eb2b3bf6abb68d8fac8ebff7aaf30c6fbe53
+oid sha256:09535722ba975e47cf0557a40b6c481f125ff2022c396f79715c3bba9f715871
 size 222032

docs/diagrams/png/08-redis-key-schema.png

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:d33b9b3affcdb07086b5aebca8a3b9c2b009cdfc6f360950a0e72e65fbcb8f17
-size 201602
+oid sha256:ed457b10b534b5fc2a5e190b281d7ded4dd1615da2229d67a373cf5dddccd059
+size 201601

docs/diagrams/png/09-workstream-states.png

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:adac93a0bb062d7199b819a600a0983ff011a75d16928fb80322cbb41f9284ea
-size 158866
+oid sha256:7896c6e041b6dbb89d034468fa980c8fe645df5eb969d45ef966ccc6399edac2
+size 200083

docs/diagrams/png/10-simulator-architecture.png

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:69f201cff948cb0a19810b7c4ad26d346f869ee2dd3141eba4f353332efa2e21
-size 373649
+oid sha256:35cf3a6942f62dabcbbe012ac2f9e6f155332c894692981b076de5a25c1f3330
+size 374055

docs/diagrams/png/11-console-data-flow.png

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:97e7210cd8f1ad195f4d5e25e778d82df3c08c5c6e0f09722e84a7a453714867
-size 411664
+oid sha256:a74b4b8b5dbfb1a51a01100b731477968942b01218bad9451a3d5a9cb3003294
+size 411665

docs/diagrams/png/12-deployment.png

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:4c3214ef416c1dfe4fa17834c2b6f4071a8093cfdb2b862848ca79938f726a13
+oid sha256:84524f4bc900708ac8adf081591d336f862830188eb8505e71a0f071b339d923
 size 252599

docs/diagrams/png/13-sdk-architecture.png

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:c9823a41e09611c5c0530d9fc12ad4139cfcc3ae238dc665b2888ec94d7d6781
-size 195708
+oid sha256:e7c3e40c10425d721f833390ae3531c09af501157fd3142531ba4eba86ff719d
+size 197112

docs/diagrams/png/14-storage-architecture.png

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:733aa17cbfdab60a601cac6adf439c657dd3535e3d6c33c69c2ef93ba8ec5989
-size 251042
+oid sha256:5faa5335152685cf1c8bf77ed93847d751cde59e1afed651e5991113f2f0f31b
+size 242670

docs/diagrams/png/15-auth-architecture.png

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:f4b2a2010335f986511c8dabaf49ec046ac02e577f9bc9924897e045f860bb13
-size 248808
+oid sha256:af5ab3126bf685afe68e24bc4b0ed97371d0ebdb77bf4d76c0331ab120580cc0
+size 248809

docs/diagrams/png/16-channel-architecture.png

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:6049cc0b07480df88d0d93aa977a1e97f64b41588325ff41d98be0e39431fc5c
-size 431712
+oid sha256:1380065cbb5f95b5ea7dc6b2a00986c455b82888af60784980dffbd936460dcf
+size 431129

docs/diagrams/png/17-notify-flow.png

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:f55e177e0838a16d9bc4f07b162b4b6a966cc596c9d0a022d35a3c84f23e7b02
+oid sha256:f0f6097840fccdbfe16cd5e4c9f5d063b2c36942460a944df68b8ec947e63ea3
 size 221452

docs/diagrams/png/18-watch-architecture.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:96176a09e65e90dadc32d5e9ed778423842be89204d2cf382225f53a90cfaf01
+size 258547

docs/diagrams/png/19-governance-architecture.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a889d4bb84c4afa3c822c3acb7021395a9463462f7aeae5382e583b783412814
+size 144960

docs/diagrams/png/20-mcp-architecture.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8e6dc5142c7908314ce01229b3c4f13bf9450adcbb62a178838bd4cf81d9f4da
+size 250417

docs/docker.md

@@ -28,6 +28,8 @@ Console dashboard: http://localhost:8090
 | `bridge` | — | default | Redis-to-HTTP bridge (multi-node routing) |
 | `console` | 8090 | default | Cluster dashboard |
 | `channel` | — | production | Channel gateway (Discord, Slack, etc.) |
+| `server-1`…`server-10` | — | cluster | 10-node server fleet (PostgreSQL required) |
+| `bridge-1`…`bridge-10` | — | cluster | Matching bridge fleet |
 | `sim` | — | sim | Multi-node cluster simulator |
 
 ## Profiles
@@ -44,6 +46,12 @@ docker compose up
 docker compose --profile production up
 ```
 
+**Cluster** — 10-node server/bridge fleet sharing PostgreSQL and Redis. Access all nodes via the console at `:8090`. Requires `POSTGRES_PASSWORD`:
+
+```bash
+docker compose --profile cluster up
+```
+
 **Sim** — adds the simulator. Can run alongside the full stack or standalone with just Redis and the console:
 
 ```bash
@@ -135,13 +143,13 @@ The channel service runs in the `production` profile. When `TURNSTONE_DISCORD_TO
 
 ## Scaling
 
-Scale to multiple server/bridge pairs:
+For multi-node testing, use the `cluster` profile which provides 10 dedicated server+bridge pairs with unique node IDs (`node-1` through `node-10`), resource limits, and shared PostgreSQL:
 
 ```bash
-docker compose up --scale server=3 --scale bridge=3
+POSTGRES_PASSWORD=secret docker compose --profile cluster up
 ```
 
-Each bridge auto-generates a unique node ID from its container hostname. When scaling `server`, remove the host port mapping (or use a reverse proxy) to avoid port conflicts.
+The default `server` and `bridge` also run alongside the cluster nodes (11 total). All nodes are accessible via the console dashboard at `:8090`.
 
 ## Volumes
 

docs/governance.md

@@ -0,0 +1,184 @@
+# Governance
+
+Turnstone governance provides role-based access control (RBAC), tool execution
+policies, prompt templates, usage tracking, and audit logging for the admin
+console.
+
+## Architecture
+
+See [diagram: 19-governance-architecture.puml](diagrams/19-governance-architecture.puml).
+
+### RBAC (Roles & Permissions)
+
+The permission model has two layers:
+
+1. **Scopes** (legacy) — `read`, `write`, `approve`. Checked by `AuthMiddleware`
+   on every request based on URL path classification.
+2. **Permissions** (granular) — 15 permission strings checked per-endpoint by
+   `require_permission()`.
+
+**Built-in roles** (seeded by migration 008):
+
+| Role | Permissions |
+|------|-------------|
+| admin | read, write, approve, admin.users, admin.roles, admin.orgs, admin.policies, admin.templates, admin.audit, admin.usage, admin.schedules, admin.watches, tools.approve, workstreams.create, workstreams.close |
+| operator | read, write, workstreams.create, workstreams.close |
+| viewer | read |
+
+Custom roles can be created with any subset of the 15 valid permissions.
+
+**Auth flow:**
+1. User logs in (password or API token) → `_load_user_permissions()` aggregates
+   permissions from all assigned roles
+2. `_permissions_to_scopes()` derives legacy scopes (any `admin.*` → `approve`)
+3. JWT created with both `scopes` and `permissions` claims
+4. Middleware checks scope → handler checks permission via `require_permission()`
+
+### Tool Policies
+
+Admin-defined rules that control tool execution:
+
+- **Pattern matching**: Glob syntax via `fnmatch` (e.g., `bash*`, `file_write`, `*`)
+- **Actions**: `allow` (auto-approve), `deny` (block), `ask` (normal approval flow)
+- **Priority**: Higher priority evaluated first, first match wins
+- **Enforcement**: `evaluate_tool_policies_batch()` called in `WebUI.approve_tools()`
+  before the `auto_approve` check
+- **MCP granular policies**: MCP resources and prompts are evaluated using their
+  `approval_label` for fine-grained control:
+  - Resource reads: `mcp_resource__{uri}` (e.g., `mcp_resource__file:///docs/*` to allow,
+    `mcp_resource__*` to deny all)
+  - Prompt invocations: `mcp__{server}__{prompt}` (e.g., `mcp__trusted__*` to allow,
+    `mcp__*` to require approval for all)
+  - Built-in tools continue to use `func_name` for backward compatibility
+
+### Prompt Templates
+
+Admin-curated system message templates injected at workstream startup:
+
+- **Runtime behavior**: Templates are loaded once at session creation and injected
+  into the system message *before* user `instructions`. Templates set the baseline;
+  instructions customize per-workstream behavior.
+- **Default templates**: All `is_default=true` templates auto-apply to new
+  workstreams, concatenated in alphabetical order by name. Use name prefixes
+  (e.g. `01-safety`, `02-style`) to control ordering.
+- **Explicit selection**: `--template <name>` CLI flag, `template` field on
+  `POST /v1/api/workstreams/new`, console creation modal dropdown, scheduled task
+  config, and channel adapter config. An explicit template *replaces* defaults.
+- **Variables**: Three built-in placeholders resolved at load time:
+  `{{model}}` (active model name), `{{ws_id}}` (workstream ID),
+  `{{node_id}}` (server node ID). Unrecognized placeholders are kept as-is.
+- **Runtime switching**: `/template <name>` to switch, `/template clear` to revert
+  to defaults, `/template` to show current. Persisted across resume.
+- **Categories**: general, engineering, support, custom, mcp
+- **Content limit**: 32 KB per template (enforced on create/update)
+- **Storage**: `prompt_templates` table with JSON `variables` array. Migration 010
+  adds `template` column to `scheduled_tasks`.
+- **MCP sync**: MCP server prompts auto-sync into prompt_templates with
+  `origin="mcp"`, `mcp_server` set, and `readonly=True`. Manual templates take
+  precedence on name collision. MCP-synced content updates reset `is_default` to
+  prevent compromised servers from injecting defaults. Admin UI shows origin badge
+  and disables edit/delete for MCP-sourced templates.
+
+### Usage Tracking
+
+Per-LLM-request token and tool call metrics:
+
+- **Recording**: `on_status()` in `WebUI` records a `usage_event` after each
+  LLM response with prompt/completion tokens, tool call count, model, ws_id
+- **Querying**: `GET /v1/api/admin/usage` with `group_by` (day/hour/model/user)
+  and time range filtering
+- **Pruning**: `prune_usage_events(retention_days=90)` and
+  `prune_audit_events(retention_days=365)` run automatically via the
+  console scheduler's periodic cleanup cycle
+
+### Audit Logging
+
+Append-only trail of admin actions:
+
+- **Recording**: `record_audit()` helper called from all admin mutation handlers
+- **Events captured**: user.create, user.delete, token.create, token.revoke,
+  channel.link, channel.unlink, role.create, role.update, role.delete,
+  role.assign, role.unassign, policy.create, policy.update, policy.delete,
+  template.create, template.update, template.delete, org.update
+- **Querying**: `GET /v1/api/admin/audit` with action/user/time filters + pagination
+
+## Database Schema
+
+Migration 008 adds 7 tables:
+
+| Table | Purpose |
+|-------|---------|
+| `orgs` | Organizations (single default org for now) |
+| `roles` | Named permission bundles (3 builtin + custom) |
+| `user_roles` | User-to-role assignments (composite PK) |
+| `tool_policies` | Per-tool approve/deny/ask rules |
+| `prompt_templates` | Reusable system message templates |
+| `usage_events` | Per-request token/tool metrics |
+| `audit_events` | Admin action log |
+
+Also adds `org_id` column to `users` table.
+
+## API Endpoints
+
+All under `/v1/api/admin/` (requires `approve` scope + granular permission).
+
+| Group | Endpoints | Permission |
+|-------|-----------|------------|
+| Users / Tokens / Channels | 9 (CRUD) | `admin.users` |
+| Roles | 7 (CRUD + assignment) | `admin.roles` / `admin.users` |
+| Orgs | 3 (list, get, update) | `admin.orgs` |
+| Tool Policies | 4 (CRUD) | `admin.policies` |
+| Prompt Templates | 4 (CRUD) | `admin.templates` |
+| Schedules | 6 (CRUD + runs) | `admin.schedules` |
+| Watches | 3 (list, create, cancel) | `admin.watches` |
+| Usage | 1 (aggregated query) | `admin.usage` |
+| Audit | 1 (paginated, filtered) | `admin.audit` |
+
+Full OpenAPI spec at `/openapi.json` and Swagger UI at `/docs`.
+
+## Admin Console UI
+
+5 new tabs added to the admin panel (10 total):
+
+- **Roles** — CRUD roles, permission checkbox grid, user role assignment modal
+- **Policies** — CRUD tool policies with colored action badges (green/red/amber)
+- **Templates** — CRUD prompt templates with wide modal, textarea editor
+- **Usage** — Summary readouts + CSS bar chart, time range + group-by selectors
+- **Audit** — Filterable log with relative timestamps, load-more pagination
+
+Tabs are permission-gated: hidden if the user lacks the required permission.
+
+## SDK
+
+Both Python and TypeScript console SDKs expose governance methods:
+
+**Python** (`TurnstoneConsole` / `AsyncTurnstoneConsole`):
+- `list_roles()`, `create_role()`, `update_role()`, `delete_role()`
+- `list_user_roles()`, `assign_role()`, `unassign_role()`
+- `list_orgs()`, `get_org()`, `update_org()`
+- `list_policies()`, `create_policy()`, `update_policy()`, `delete_policy()`
+- `list_templates()`, `create_template()`, `update_template()`, `delete_template()`
+- `get_usage(since, group_by=...)`, `get_audit(action=..., limit=...)`
+
+**TypeScript** (`TurnstoneConsole`):
+- Same methods with camelCase naming and typed interfaces
+
+## Security Considerations
+
+- **Privilege escalation prevented**: `admin_assign_role` blocks self-assignment
+  and requires caller to hold a superset of the target role's permissions
+- **Permission validation**: Role create/update validates permissions against
+  a 15-item allowlist (`_VALID_PERMISSIONS`)
+- **Self-deletion blocked**: `admin_delete_user` rejects attempts to delete
+  your own account (matching the self-assignment guard on role endpoints)
+- **Field allowlists**: Storage `update_*` methods filter fields against
+  allowlists (`_ROLE_MUTABLE`, `_POLICY_MUTABLE`, etc.) — handler bugs
+  cannot overwrite `role_id`, `builtin`, `created`, or other protected columns
+- **Bootstrap safety**: `handle_auth_setup` fails and rolls back if admin role
+  assignment fails, preventing locked-out first user
+- **API token RBAC**: `_authenticate_api_token` loads permissions from user's
+  roles, ensuring API tokens are subject to RBAC enforcement
+- **Policy evaluation is fail-open**: If storage is unavailable, tool policies
+  degrade to the existing approval flow (not auto-approve)
+- **Audit IP resolution**: `_audit_context()` prefers `X-Forwarded-For` for
+  client IP when behind a reverse proxy, falling back to `request.client.host`

docs/sdk.md

@@ -75,10 +75,11 @@ Both `TurnstoneServer` (sync) and `AsyncTurnstoneServer` (async) expose:
 | | `approve(*, ws_id, approved, feedback, always)` | `StatusResponse` |
 | | `plan_feedback(*, ws_id, feedback)` | `StatusResponse` |
 | | `command(*, ws_id, command)` | `StatusResponse` |
+| | `cancel(ws_id)` | `StatusResponse` |
 | **Streaming** | `stream_events(ws_id)` | `Iterator[ServerEvent]` |
 | | `stream_global_events()` | `Iterator[ServerEvent]` |
 | **High-level** | `send_and_wait(message, ws_id, *, timeout, on_event)` | `TurnResult` |
-| **Sessions** | `list_sessions()` | `ListSessionsResponse` |
+| **Saved** | `list_saved_workstreams()` | `ListSavedWorkstreamsResponse` |
 | **Auth** | `login(username=..., password=...)` | `AuthLoginResponse` |
 | | `login(token="ts_xxx")` | `AuthLoginResponse` |
 | | `logout()` | `StatusResponse` |
@@ -95,6 +96,7 @@ Both `TurnstoneConsole` (sync) and `AsyncTurnstoneConsole` (async) expose:
 | | `nodes(*, sort, limit, offset)` | `ClusterNodesResponse` |
 | | `workstreams(*, state, node, search, sort, page, per_page)` | `ClusterWorkstreamsResponse` |
 | | `node_detail(node_id)` | `NodeDetailResponse` |
+| | `snapshot()` | `ClusterSnapshotResponse` |
 | | `create_workstream(*, node_id, name, model, initial_message)` | `ConsoleCreateWsResponse` |
 | **Schedules** | `list_schedules()` | `ListSchedulesResponse` |
 | | `create_schedule(*, name, schedule_type, initial_message, ...)` | `ScheduleInfo` |
@@ -128,6 +130,7 @@ SSE events are deserialized into typed dataclasses. Use `event.type` to discrimi
 | `error` | `ErrorEvent` | `message` |
 | `info` | `InfoEvent` | `message` |
 | `stream_end` | `StreamEndEvent` | — |
+| `cancelled` | `CancelledEvent` | — |
 
 **Global events** (from `stream_global_events()`):
 
@@ -146,6 +149,9 @@ SSE events are deserialized into typed dataclasses. Use `event.type` to discrimi
 | `node_lost` | `NodeLostEvent` | `node_id` |
 | `cluster_state` | `ClusterStateEvent` | `ws_id`, `node_id`, `state`, `tokens` |
 | `ws_created` | `ClusterWsCreatedEvent` | `ws_id`, `node_id`, `name` |
+| `ws_closed` | `ClusterWsClosedEvent` | `ws_id` |
+| `ws_rename` | `ClusterWsRenameEvent` | `ws_id`, `name` |
+| `snapshot` | `ClusterSnapshotEvent` | `nodes`, `overview`, `timestamp` |
 
 ### TurnResult
 

docs/security.md

@@ -73,7 +73,7 @@ Scopes are hierarchical — higher scopes imply all lower ones.
 
 | Scope | Grants | Implies |
 |-------|--------|---------|
-| `read` | View workstreams, sessions, history | — |
+| `read` | View workstreams, saved workstreams, history | — |
 | `write` | Send messages, create/close workstreams | `read` |
 | `approve` | Approve tool calls, admin endpoints | `read`, `write` |
 
@@ -92,6 +92,34 @@ Public paths bypass authentication entirely: `/`, `/health`, `/metrics`,
 `/static/*`, `/shared/*`, `/docs`, `/openapi.json`, `/api/auth/login`,
 `/api/auth/logout`, `/api/auth/status`, `/api/auth/setup`.
 
+### RBAC (Granular Permissions)
+
+> See also: [Governance documentation](governance.md)
+
+Scopes provide coarse endpoint-level access control. For finer-grained
+enforcement, the governance layer adds 15 named permissions checked
+per-endpoint by `require_permission()`. Permissions are bundled into
+roles; users are assigned roles via the `user_roles` join table.
+
+At login, `_load_user_permissions()` aggregates all permissions from
+the user's assigned roles. `_permissions_to_scopes()` derives legacy
+scopes for backward compatibility (e.g., any `admin.*` permission
+implies the `approve` scope). The JWT carries both `scopes` and
+`permissions` claims.
+
+Three built-in roles are seeded by migration 008:
+
+| Role | Permissions |
+|------|-------------|
+| admin | All 15 permissions |
+| operator | read, write, workstreams.create, workstreams.close |
+| viewer | read |
+
+Custom roles can be created with any subset of the valid permissions.
+Role creation and update validate permissions against a static allowlist.
+Self-assignment is blocked, and assigning a role requires the caller to
+hold a superset of the target role's permissions.
+
 ---
 
 ## Login Flows

docs/tools.md

@@ -1,6 +1,6 @@
 # Tools Reference
 
-turnstone exposes 15 built-in tools plus any number of external MCP tools to the
+turnstone exposes 18 built-in tools plus any number of external MCP tools to the
 LLM via the OpenAI function-calling interface. Built-in tools are defined as JSON
 files under `turnstone/tools/` and loaded at startup by `turnstone/core/tools.py`.
 MCP tools are discovered from configured MCP servers at startup by
@@ -46,11 +46,12 @@ schema plus turnstone-specific metadata keys:
 
 | Name                | Description |
 |---------------------|-------------|
-| `TOOLS`             | All 15 tool definitions (sent to the model). |
+| `TOOLS`             | All 18 tool definitions (sent to the model). |
 | `AGENT_TOOLS`       | Tools with `agent: true` -- available to plan sub-agents. Read-only tools. |
 | `TASK_AGENT_TOOLS`  | Tools with `task_agent: true` -- available to task sub-agents. Includes write operations. |
 | `AGENT_AUTO_TOOLS`  | Set of tool names with `auto_approve: true` -- no user confirmation needed. |
 | `TASK_AUTO_TOOLS`   | Same as `AGENT_AUTO_TOOLS` (identical filter). |
+| `BUILTIN_TOOL_NAMES`| Frozenset of all 18 built-in tool names. Used by tool search to distinguish always-on tools from deferrable MCP tools. |
 | `PRIMARY_KEY_MAP`   | Dict mapping tool name to its `primary_key` parameter name. |
 
 ---
@@ -68,6 +69,9 @@ Tool execution follows a three-phase pipeline inside `ChatSession._execute_tools
 - Parses the JSON arguments (with fallback for malformed JSON).
 - If JSON parsing fails entirely, uses `PRIMARY_KEY_MAP` to map a bare string
   to the correct parameter.
+- Dispatches to the matching `_prepare_{func_name}()` handler. There are 18
+  built-in tools plus `tool_search` (synthetic, client-side BM25 fallback) and
+  the generic `_prepare_mcp_tool()` handler for MCP tools.
 - Validates arguments and builds a preview dict containing:
   - `call_id`, `func_name`, `header`, `preview` (for display)
   - `needs_approval` (bool)
@@ -164,6 +168,8 @@ Every tool defines a `primary_key`. The mapping is:
 | `recall`     | `query`     |
 | `forget`     | `key`       |
 | `notify`     | `message`   |
+| `read_resource` | `uri`    |
+| `use_prompt` | `name`     |
 
 ---
 
@@ -185,15 +191,17 @@ Execute a bash command and return stdout + stderr.
 
 ### read_file
 
-Read the contents of a file, returning numbered lines.
+Read the contents of a file, returning numbered lines for text files or
+base64-encoded image data for supported image formats.
 
 | Parameter | Type    | Required | Description |
 |-----------|---------|----------|-------------|
 | `path`    | string  | yes      | Absolute or relative file path. |
-| `offset`  | integer | no       | Line number to start from (1-based, default: 1). |
-| `limit`   | integer | no       | Maximum number of lines to read. Omit for full file. |
+| `offset`  | integer | no       | Line number to start from (1-based, default: 1). Text files only. |
+| `limit`   | integer | no       | Maximum number of lines to read. Omit for full file. Text files only. |
 
-- **What it does**: Reads the file and returns content with line numbers. Must be called before `edit_file` on the same path (the session tracks which files have been read).
+- **What it does**: For text files, reads and returns content with line numbers. For image files (PNG, JPEG, GIF, WebP, BMP, TIFF, ICO), returns image data as multi-part content when the model supports vision, or a text description when it does not. SVG files are read as text. Images larger than 4 MB are rejected. Must be called before `edit_file` on the same path (the session tracks which files have been read).
+- **Vision support**: Controlled by `ModelCapabilities.supports_vision`. All commercial OpenAI and Anthropic models have vision enabled. Local models (vLLM, llama.cpp, NIM) default to off — enable via `[models.*.capabilities] supports_vision = true` in config.toml.
 - **Auto-approve**: Yes.
 - **Agent availability**: `agent` and `task_agent`.
 
@@ -337,7 +345,7 @@ Plan before implementing -- an autonomous agent explores the codebase and writes
 |-----------|--------|----------|-------------|
 | `prompt`  | string | yes      | What to plan -- the goal, constraints, and scope. |
 
-- **What it does**: Spawns a planning sub-agent with `AGENT_TOOLS` (read-only tools: `read_file`, `search`, `math`, `man`, `web_fetch`, `web_search`). The agent explores the codebase and writes a structured plan to `.plan-<session_id>.md` (unique per session, so concurrent workstreams never collide). If the `plan` tool has been called before in the same session, the prior plan is passed to the agent as context so it refines rather than restarts. After completion, the user is prompted to review and can accept, reject, or annotate the plan.
+- **What it does**: Spawns a planning sub-agent with `AGENT_TOOLS` (read-only tools: `read_file`, `search`, `math`, `man`, `web_fetch`, `web_search`). The agent explores the codebase and writes a structured plan to `.plan-<ws_id>.md` (unique per workstream, so concurrent workstreams never collide). If the `plan` tool has been called before in the same session, the prior plan is passed to the agent as context so it refines rather than restarts. After completion, the user is prompted to review and can accept, reject, or annotate the plan.
 - **Auto-approve**: No -- requires user confirmation, plus post-execution review gate.
 - **Agent availability**: Not available to sub-agents (top-level only).
 
@@ -416,6 +424,81 @@ Provide either `username` for user-based targeting or `channel_type` +
 
 ---
 
+### watch
+
+Set up periodic polling of a shell command within the current workstream.
+Results are injected back into the conversation as synthetic user messages,
+triggering the model to respond and act. Use for monitoring CI/CD pipelines,
+PR reviews, deployments, file changes, etc.
+
+| Parameter   | Type    | Required | Description |
+|-------------|---------|----------|-------------|
+| `action`    | string  | yes      | `create`, `list`, or `cancel`. |
+| `command`   | string  | create   | Shell command to poll periodically. |
+| `poll_every`| string  | no       | Poll interval as duration (`30s`, `5m`, `1h`). Default: `5m`. |
+| `stop_on`   | string  | no       | Python expression for stop condition (see below). Omit for change detection. |
+| `name`      | string  | create   | Human-readable watch name (e.g. `pr-review`). Used as identifier for cancel. |
+| `max_polls` | integer | no       | Max poll cycles before auto-cancel. Default: 100. |
+
+**Actions:**
+
+- `create` — Start a new watch. Requires approval (same as bash — runs shell
+  commands). Persists to the `watches` table; the server-level `WatchRunner`
+  daemon polls every 15 seconds for due watches.
+- `list` — Show all active watches in this workstream. Auto-approved.
+- `cancel` — Stop a watch by name or ID prefix. Auto-approved.
+
+**Stop condition DSL** — The `stop_on` parameter accepts a Python expression
+evaluated after each poll. Available variables:
+
+| Variable      | Type       | Description |
+|---------------|------------|-------------|
+| `output`      | `str`      | stdout (+stderr) of the command. |
+| `data`        | `Any`      | `json.loads(output)`, or `None` if not valid JSON. |
+| `exit_code`   | `int`      | Process exit code. |
+| `prev_output` | `str|None` | Previous poll's stdout (`None` on first poll). |
+| `changed`     | `bool`     | `True` if output differs from previous poll. |
+
+Safe builtins: `len`, `str`, `int`, `float`, `bool`, `abs`, `min`, `max`,
+`any`, `all`, `isinstance`, `sorted`. No `import`, `open`, `exec`, or
+`eval`. Security model: equivalent to `bash` — the model already has shell
+access.
+
+**Examples:**
+```
+data["state"] == "MERGED"
+"error" in output
+exit_code != 0
+changed and "ready" in output.lower()
+data.get("mergedAt") is not None
+```
+
+**Lifecycle:**
+
+1. Model calls `watch(action="create", ...)` — persisted to SQLite.
+2. `WatchRunner` daemon polls for due watches every 15s.
+3. Each poll runs the command, evaluates the condition.
+4. When the condition fires (or max polls reached), the result is injected
+   as a synthetic user message and the watch auto-cancels.
+5. If the workstream was evicted, it is restored before injection.
+6. Watches survive server restart (overdue watches fire once on recovery).
+
+**Constraints:**
+
+- Max 5 active watches per workstream.
+- Poll interval: 10s–24h.
+- Output truncated at 64 KB.
+- Max 5 consecutive watch dispatches per worker thread (depth guard).
+- Duplicate names rejected within the same workstream.
+
+- **Auto-approve**: `create` requires approval; `list` and `cancel` are auto-approved.
+- **Agent availability**: Main session only — not available to plan/task sub-agents.
+
+> See [Watch Architecture](diagrams/png/18-watch-architecture.png) for the
+> full poll → evaluate → dispatch flow.
+
+---
+
 ## Summary Table
 
 | Tool         | Category   | Auto-approve | agent | task_agent | primary_key |
@@ -435,11 +518,87 @@ Provide either `username` for user-based targeting or `channel_type` +
 | `recall`     | Memory     | Yes          | No    | No         | `query`     |
 | `forget`     | Memory     | Yes          | No    | No         | `key`       |
 | `notify`     | Notify     | Yes          | Yes   | Yes        | `message`   |
+| `watch`      | Monitor    | No (create)  | No    | No         | `command`   |
+| `read_resource`| MCP      | No           | Yes   | Yes        | `uri`       |
+| `use_prompt` | MCP        | No           | Yes   | Yes        | `name`      |
+| `tool_search`| Search     | Yes          | No    | No         | `query`     |
+
+---
+
+## Dynamic Tool Search
+
+When many MCP tools are connected, the total tool count can grow large enough to
+consume significant context window tokens and reduce model accuracy. Dynamic tool
+search addresses this by deferring tools the model is unlikely to need on the
+current turn and letting it search for them on demand.
+
+### Three-tier approach
+
+Tool search uses the best available mechanism for each provider:
+
+1. **Anthropic (native)** -- Models that support it receive `defer_loading: true`
+   on deferred tool definitions plus the `tool_search_tool_bm25_20251119` server-side
+   search tool. Anthropic's API handles search and expansion transparently.
+
+2. **OpenAI GPT-5.4+ (native)** -- Models with hosted tool search receive
+   `defer_loading: true` on deferred definitions. The API handles search internally.
+
+3. **vLLM / llama.cpp / NIM (client-side BM25)** -- A synthetic `tool_search`
+   function tool is injected into the tool list. When the model calls it,
+   `_exec_tool_search()` runs a pure-Python BM25 index over tool names and
+   descriptions, then expands the matched tools into the visible set.
+
+### Configuration
+
+Tool search is configured in `config.toml` under the `[tools]` section:
+
+```toml
+[tools]
+search = "auto"           # "auto", "on", or "off"
+search_threshold = 20     # minimum total tool count to activate
+search_max_results = 5    # max tools returned per search call
+```
+
+CLI flags override the config file:
+
+- `--tool-search {auto,on,off}` -- force tool search on or off, or let turnstone
+  decide based on threshold (default: `auto`).
+- `--tool-search-threshold N` -- minimum tool count to activate (default: 20).
+- `--tool-search-max-results N` -- max results per search (default: 5).
+
+### How it works
+
+1. **Threshold check**: At session startup, `ToolSearchManager.should_activate()`
+   counts total tools (built-in + MCP). If the count is below the threshold, tool
+   search stays off and all tools are sent to the model directly.
+
+2. **Partitioning**: When active, tools are split into two sets:
+   - **Always-on** -- the 18 built-in tools (members of `BUILTIN_TOOL_NAMES`).
+     These are always visible to the model.
+   - **Deferred** -- all MCP tools. These are not sent in the tool list unless
+     the model searches for them.
+
+3. **Search and expand**: When the model calls `tool_search` (client-side) or the
+   provider's native search returns results, the matched tools are added to the
+   visible set via `expand_visible()`. Once expanded, a tool stays visible for
+   the remainder of the session.
+
+4. **Multi-turn persistence**: Expanded tools are never removed. This avoids
+   confusing the model when it references a tool it discovered in an earlier turn.
+
+### Agent exemption
+
+Plan and task sub-agents do not use tool search. They operate on scoped tool
+sets (`AGENT_TOOLS` for plan agents, `TASK_AGENT_TOOLS` for task agents) with
+MCP tools merged in. Tool search is only active for the top-level session,
+where the model can interactively search for tools it needs.
 
 ---
 
 ## MCP Tools (External)
 
+> See also: [MCP Architecture diagram](diagrams/png/20-mcp-architecture.png)
+
 Turnstone supports the [Model Context Protocol](https://modelcontextprotocol.io/)
 (MCP) for connecting external tool servers — GitHub, databases, filesystems, or any
 MCP-compatible service.
@@ -451,13 +610,17 @@ MCP-compatible service.
 
 2. **Discovery**: At startup, `MCPClientManager` connects to each configured server
    (via stdio subprocess or HTTP), performs the MCP `initialize` handshake, and calls
-   `tools/list` to discover available tools.
+   `tools/list` to discover available tools. During the handshake, the manager checks
+   each server's capabilities for `tools.listChanged` support (push notifications).
 
 3. **Schema conversion**: Each MCP tool's `inputSchema` is converted to OpenAI
    function-calling format. The tool name is prefixed: `mcp__{server}__{tool}`.
 
-4. **Merging**: MCP tools are appended after the 14 built-in tools via
+4. **Merging**: MCP tools are appended after the 18 built-in tools via
    `merge_mcp_tools()`. Built-in tools appear first, giving them natural LLM priority.
+   When dynamic tool search is active, MCP tools are deferred rather than directly
+   visible -- the model discovers them via search as needed (see
+   [Dynamic Tool Search](#dynamic-tool-search) above).
 
 5. **Dispatch**: When the LLM calls an MCP tool, `_prepare_mcp_tool()` builds a
    generic approval preview and `_exec_mcp_tool()` calls `MCPClientManager.call_tool_sync()`,
@@ -530,3 +693,182 @@ MCP tools (3):
   mcp__github__create_issue  [MCP: github] Create a GitHub issue
   mcp__postgres__query       [MCP: postgres] Run a SQL query
 ```
+
+### Dynamic tool refresh
+
+MCP tool lists stay up-to-date without restart through three mechanisms:
+
+1. **Push notifications** -- MCP servers that declare `tools.listChanged: true` in
+   their capabilities send `notifications/tools/list_changed` when their tool list
+   changes. `MCPClientManager` registers a `message_handler` on each `ClientSession`
+   that triggers an immediate refresh for that server.
+
+2. **Periodic timer** -- Servers that do *not* support push notifications are polled
+   on a configurable interval (default 4 hours). The timer is staggered using a
+   launch-time seed (`monotonic_ns ^ pid`) so cluster nodes don't all hit MCP
+   servers simultaneously. Configure via `[mcp] refresh_interval` in `config.toml`
+   or `--mcp-refresh-interval SECONDS` on the CLI. Set to `0` to disable.
+
+3. **Manual** -- `/mcp refresh` re-fetches tools from all servers immediately.
+   `/mcp refresh <server>` targets a single server. If a server has disconnected,
+   manual refresh attempts reconnection.
+
+When tools change, `MCPClientManager` rebuilds its merged tool list using copy-on-write
+(new list/dict objects assigned atomically) and notifies all active `ChatSession`
+instances via registered listener callbacks. Each session rebuilds its `_tools`,
+`_task_tools`, `_agent_tools`, and reconstructs its `ToolSearchManager` (if active),
+preserving the set of previously expanded (discovered) tools.
+
+```toml
+[mcp]
+refresh_interval = 14400  # seconds (default 4h), 0 to disable
+```
+
+```
+/mcp refresh
+MCP refresh complete:
+  github: +1 added
+    + mcp__github__create_pr
+  postgres: no changes
+
+/mcp refresh github
+MCP refresh complete:
+  github: no changes
+```
+
+---
+
+## MCP Resources
+
+MCP servers can expose **resources** -- named data items (files, database rows,
+API responses) addressable by URI. turnstone discovers resources at startup and
+makes them available to the model via the `read_resource` built-in tool.
+
+### Discovery
+
+During the MCP `initialize` handshake, `MCPClientManager` checks each server's
+capabilities for the `resources` capability. For servers that declare it:
+
+1. `list_resources` fetches static resources (fixed URIs).
+2. `list_resource_templates` fetches URI templates (parameterized patterns like
+   `db://tables/{table}/rows/{id}`).
+
+Both are stored as `{uri, name, description, mimeType, server}` dicts and
+merged into a unified catalog.
+
+### Resource catalog in system message
+
+The first 50 resources are injected into the system message as an XML-delimited
+block so the model knows what URIs are available:
+
+```xml
+<mcp-resources>
+  file:///project/README.md  Project readme
+  db://users/schema  User table schema
+</mcp-resources>
+Use read_resource(uri='...') to access the resources listed above.
+```
+
+### read_resource tool
+
+| Parameter | Type   | Required | Description |
+|-----------|--------|----------|-------------|
+| `uri`     | string | yes      | The resource URI to read. |
+
+- **What it does**: Reads the resource from its MCP server via `MCPClientManager.read_resource_sync()`. Returns text content for text resources or base64-encoded data for binary resources. Output is truncated by the standard tool output limiter.
+- **Auto-approve**: No -- requires user confirmation (reads external data).
+- **Agent availability**: `agent` and `task_agent`.
+
+### Capability guards
+
+The `read_resource` tool schema is always loaded (it is a built-in JSON schema),
+but resource discovery only runs for servers that declare the `resources`
+capability. Servers without the capability contribute zero resources to the
+catalog.
+
+### Refresh
+
+Resource lists stay current through the same three-tier mechanism as tool lists:
+
+1. **Push** -- Servers declaring `resources.listChanged: true` send
+   `notifications/resources/list_changed`, triggering an immediate refresh.
+2. **Periodic** -- Servers without push are polled on the configured refresh
+   interval (default 4 hours, same timer as tools).
+3. **Manual** -- `/mcp refresh` re-fetches resources alongside tools.
+
+---
+
+## MCP Prompts
+
+MCP servers can also expose **prompts** -- reusable message templates with
+optional arguments. turnstone discovers prompts at startup for servers that
+declare the `prompts` capability.
+
+### Discovery
+
+Prompt discovery mirrors resource discovery: `list_prompts` is called during
+the `initialize` handshake. Each prompt is stored with its prefixed name
+(`mcp__{server}__{prompt}`), description, and argument schema.
+
+### use_prompt tool
+
+| Parameter   | Type   | Required | Description |
+|-------------|--------|----------|-------------|
+| `name`      | string | yes      | The prompt name (e.g. `mcp__server__prompt_name`). |
+| `arguments` | object | no       | Key-value argument pairs for the prompt. Values must be strings. |
+
+- **What it does**: Invokes an MCP prompt template by name via `MCPClientManager.get_prompt_sync()`, expanding it into messages. Returns the expanded prompt content formatted as `[role]: content` blocks joined with blank lines. The prompt catalog is listed in the system message so the model knows which prompts are available. Output is truncated by the standard tool output limiter.
+- **Auto-approve**: No -- requires user confirmation (invokes external prompt servers).
+- **Agent availability**: `agent` and `task_agent`.
+
+### Invocation
+
+`MCPClientManager.get_prompt_sync()` calls the server's `get_prompt` method
+with the provided arguments and returns the expanded messages. The `use_prompt`
+built-in tool exposes this to the model as a function call.
+
+### Governance Sync
+
+Discovered MCP prompts are automatically synced into the `prompt_templates`
+governance table as first-class governed templates:
+
+- **Origin tracking**: MCP-sourced templates have `origin="mcp"` and
+  `mcp_server` set to the server name. Manual templates have
+  `origin="manual"`.
+- **Read-only**: MCP-sourced templates are `readonly=True`. The admin API
+  returns 403 on update/delete attempts. The admin UI disables edit/delete
+  buttons and shows an origin badge.
+- **Precedence**: If a manual template and MCP prompt share the same name,
+  the manual template wins and the MCP prompt is skipped (with a log
+  warning).
+- **Lifecycle**: Templates are created on connect, updated on prompt list
+  refresh, and removed when the MCP server no longer exposes the prompt.
+  The sync runs automatically on connect, on `PromptListChangedNotification`,
+  and on manual `/mcp refresh`.
+- **Schema**: Migration 009 adds `origin`, `mcp_server`, and `readonly`
+  columns to the `prompt_templates` table.
+
+The `use_prompt` tool allows the model to invoke any discovered MCP prompt at
+runtime. A catalog of up to 30 prompts is injected into the system message
+inside `<mcp-prompts>` XML tags so the model can discover available prompts.
+
+---
+
+## MCP UI Visibility
+
+MCP server, resource, and prompt counts are surfaced across the UI:
+
+- **Server `/health` endpoint**: Returns `mcp.servers`, `mcp.resources`,
+  `mcp.prompts` when MCP is configured
+- **Server UI**: Magenta status badge in the header showing server count,
+  with resource/prompt counts in tooltip
+- **Console cluster status bar**: MCP metrics (servers/resources/prompts)
+  with magenta LED dot indicator, shown after a divider from workstream
+  metrics
+- **Console node detail**: Per-node MCP summary showing server, resource,
+  and prompt counts
+- **Console collector**: Aggregates MCP counts across all nodes in the
+  cluster overview
+
+MCP indicators use the `--magenta` design token for consistent theming
+across light and dark modes.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "turnstone"
-version = "0.4.2"
+version = "0.5.6"
 description = "Multi-node AI orchestration platform with tool use, agent routing, and cluster simulation."
 readme = "README.md"
 license = "BUSL-1.1"
@@ -62,6 +62,7 @@ turnstone-console = "turnstone.console.server:main"
 turnstone-sim = "turnstone.sim.cli:main"
 turnstone-admin = "turnstone.admin:main"
 turnstone-channel = "turnstone.channels.cli:main"
+turnstone-bootstrap = "turnstone.bootstrap:main"
 
 [tool.hatch.build.targets.wheel]
 include = [

sdk/typescript/openapi-console.json

@@ -10,9 +10,7 @@
       "get": {
         "summary": "Cluster state summary",
         "operationId": "v1_api_cluster_overview_get",
-        "tags": [
-          "Cluster"
-        ],
+        "tags": ["Cluster"],
         "responses": {
           "200": {
             "description": "Success",
@@ -31,9 +29,7 @@
       "get": {
         "summary": "Paginated node list",
         "operationId": "v1_api_cluster_nodes_get",
-        "tags": [
-          "Cluster"
-        ],
+        "tags": ["Cluster"],
         "parameters": [
           {
             "name": "sort",
@@ -42,11 +38,7 @@
             "schema": {
               "type": "string",
               "default": "activity",
-              "enum": [
-                "activity",
-                "tokens",
-                "name"
-              ]
+              "enum": ["activity", "tokens", "name"]
             },
             "description": "Sort field"
           },
@@ -89,9 +81,7 @@
       "get": {
         "summary": "Filtered workstream list",
         "operationId": "v1_api_cluster_workstreams_get",
-        "tags": [
-          "Cluster"
-        ],
+        "tags": ["Cluster"],
         "parameters": [
           {
             "name": "state",
@@ -99,13 +89,7 @@
             "required": false,
             "schema": {
               "type": "string",
-              "enum": [
-                "running",
-                "thinking",
-                "attention",
-                "idle",
-                "error"
-              ]
+              "enum": ["running", "thinking", "attention", "idle", "error"]
             },
             "description": "Filter by state"
           },
@@ -134,11 +118,7 @@
             "schema": {
               "type": "string",
               "default": "state",
-              "enum": [
-                "state",
-                "tokens",
-                "name"
-              ]
+              "enum": ["state", "tokens", "name"]
             },
             "description": "Sort field"
           },
@@ -181,9 +161,7 @@
       "get": {
         "summary": "Single node detail",
         "operationId": "v1_api_cluster_node_{node_id}_get",
-        "tags": [
-          "Cluster"
-        ],
+        "tags": ["Cluster"],
         "parameters": [
           {
             "name": "node_id",
@@ -222,9 +200,7 @@
       "post": {
         "summary": "Create workstream via MQ dispatch",
         "operationId": "v1_api_cluster_workstreams_new_post",
-        "tags": [
-          "Cluster"
-        ],
+        "tags": ["Cluster"],
         "requestBody": {
           "required": true,
           "content": {
@@ -283,9 +259,7 @@
       "get": {
         "summary": "Cluster SSE event stream",
         "operationId": "v1_api_cluster_events_get",
-        "tags": [
-          "Streaming"
-        ],
+        "tags": ["Streaming"],
         "description": "Server-Sent Events stream for real-time cluster updates. Returns text/event-stream with node_joined, node_lost, cluster_state, ws_created, ws_closed, ws_rename events.",
         "responses": {
           "200": {
@@ -298,9 +272,7 @@
       "post": {
         "summary": "Authenticate with a token",
         "operationId": "v1_api_auth_login_post",
-        "tags": [
-          "Auth"
-        ],
+        "tags": ["Auth"],
         "requestBody": {
           "required": true,
           "content": {
@@ -339,9 +311,7 @@
       "post": {
         "summary": "Clear auth cookie",
         "operationId": "v1_api_auth_logout_post",
-        "tags": [
-          "Auth"
-        ],
+        "tags": ["Auth"],
         "responses": {
           "200": {
             "description": "Success",
@@ -360,9 +330,7 @@
       "get": {
         "summary": "Console health check",
         "operationId": "health_get",
-        "tags": [
-          "Observability"
-        ],
+        "tags": ["Observability"],
         "responses": {
           "200": {
             "description": "Success",
@@ -389,9 +357,7 @@
             "type": "string"
           }
         },
-        "required": [
-          "error"
-        ],
+        "required": ["error"],
         "title": "ErrorResponse",
         "type": "object"
       },
@@ -400,9 +366,7 @@
         "properties": {
           "status": {
             "default": "ok",
-            "examples": [
-              "ok"
-            ],
+            "examples": ["ok"],
             "title": "Status",
             "type": "string"
           }
@@ -419,9 +383,7 @@
             "type": "string"
           }
         },
-        "required": [
-          "token"
-        ],
+        "required": ["token"],
         "title": "AuthLoginRequest",
         "type": "object"
       },
@@ -435,17 +397,12 @@
           },
           "role": {
             "description": "Assigned role",
-            "examples": [
-              "full",
-              "read"
-            ],
+            "examples": ["full", "read"],
             "title": "Role",
             "type": "string"
           }
         },
-        "required": [
-          "role"
-        ],
+        "required": ["role"],
         "title": "AuthLoginResponse",
         "type": "object"
       },
@@ -557,9 +514,7 @@
             "type": "integer"
           }
         },
-        "required": [
-          "nodes"
-        ],
+        "required": ["nodes"],
         "title": "ClusterNodesResponse",
         "type": "object"
       },
@@ -632,9 +587,7 @@
             "type": "string"
           }
         },
-        "required": [
-          "node_id"
-        ],
+        "required": ["node_id"],
         "title": "ClusterNodeInfo",
         "type": "object"
       },
@@ -668,9 +621,7 @@
             "type": "integer"
           }
         },
-        "required": [
-          "workstreams"
-        ],
+        "required": ["workstreams"],
         "title": "ClusterWorkstreamsResponse",
         "type": "object"
       },
@@ -726,9 +677,7 @@
             "type": "integer"
           }
         },
-        "required": [
-          "id"
-        ],
+        "required": ["id"],
         "title": "ClusterWorkstreamInfo",
         "type": "object"
       },
@@ -771,9 +720,7 @@
             "type": "boolean"
           }
         },
-        "required": [
-          "node_id"
-        ],
+        "required": ["node_id"],
         "title": "NodeDetailResponse",
         "type": "object"
       },
@@ -802,6 +749,12 @@
             "description": "Optional first message sent after creation",
             "title": "Initial Message",
             "type": "string"
+          },
+          "template": {
+            "default": "",
+            "description": "Prompt template name (replaces default templates)",
+            "title": "Template",
+            "type": "string"
           }
         },
         "title": "ConsoleCreateWsRequest",
@@ -832,9 +785,7 @@
         "properties": {
           "status": {
             "default": "ok",
-            "examples": [
-              "ok"
-            ],
+            "examples": ["ok"],
             "title": "Status",
             "type": "string"
           },

sdk/typescript/openapi-server.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "turnstone Server API",
-    "version": "0.3.0",
+    "version": "0.4.2",
     "description": "Single-node workstream management, chat interaction, and real-time streaming."
   },
   "paths": {
@@ -10,9 +10,7 @@
       "get": {
         "summary": "List active workstreams",
         "operationId": "v1_api_workstreams_get",
-        "tags": [
-          "Workstreams"
-        ],
+        "tags": ["Workstreams"],
         "responses": {
           "200": {
             "description": "Success",
@@ -31,9 +29,7 @@
       "get": {
         "summary": "Dashboard with workstream details and aggregates",
         "operationId": "v1_api_dashboard_get",
-        "tags": [
-          "Workstreams"
-        ],
+        "tags": ["Workstreams"],
         "responses": {
           "200": {
             "description": "Success",
@@ -52,9 +48,7 @@
       "post": {
         "summary": "Create a new workstream",
         "operationId": "v1_api_workstreams_new_post",
-        "tags": [
-          "Workstreams"
-        ],
+        "tags": ["Workstreams"],
         "requestBody": {
           "required": true,
           "content": {
@@ -93,9 +87,7 @@
       "post": {
         "summary": "Close a workstream",
         "operationId": "v1_api_workstreams_close_post",
-        "tags": [
-          "Workstreams"
-        ],
+        "tags": ["Workstreams"],
         "requestBody": {
           "required": true,
           "content": {
@@ -134,9 +126,7 @@
       "post": {
         "summary": "Send a user message",
         "operationId": "v1_api_send_post",
-        "tags": [
-          "Chat"
-        ],
+        "tags": ["Chat"],
         "requestBody": {
           "required": true,
           "content": {
@@ -185,9 +175,7 @@
       "post": {
         "summary": "Approve or deny a tool call",
         "operationId": "v1_api_approve_post",
-        "tags": [
-          "Chat"
-        ],
+        "tags": ["Chat"],
         "requestBody": {
           "required": true,
           "content": {
@@ -226,9 +214,7 @@
       "post": {
         "summary": "Respond to a plan review",
         "operationId": "v1_api_plan_post",
-        "tags": [
-          "Chat"
-        ],
+        "tags": ["Chat"],
         "requestBody": {
           "required": true,
           "content": {
@@ -267,9 +253,7 @@
       "post": {
         "summary": "Execute a slash command",
         "operationId": "v1_api_command_post",
-        "tags": [
-          "Chat"
-        ],
+        "tags": ["Chat"],
         "requestBody": {
           "required": true,
           "content": {
@@ -314,13 +298,60 @@
         }
       }
     },
+    "/v1/api/cancel": {
+      "post": {
+        "summary": "Cancel the active generation in a workstream",
+        "operationId": "v1_api_cancel_post",
+        "tags": ["Chat"],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CancelRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/StatusResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Error 400",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Error 404",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/v1/api/events": {
       "get": {
         "summary": "Per-workstream SSE event stream",
         "operationId": "v1_api_events_get",
-        "tags": [
-          "Streaming"
-        ],
+        "tags": ["Streaming"],
         "description": "Opens a Server-Sent Events stream scoped to a single workstream. Returns text/event-stream. See API reference for event types.",
         "parameters": [
           {
@@ -354,9 +385,7 @@
       "get": {
         "summary": "Global SSE event stream",
         "operationId": "v1_api_events_global_get",
-        "tags": [
-          "Streaming"
-        ],
+        "tags": ["Streaming"],
         "description": "Global Server-Sent Events stream for state-change broadcasts across all workstreams. Returns text/event-stream.",
         "responses": {
           "200": {
@@ -365,20 +394,18 @@
         }
       }
     },
-    "/v1/api/sessions": {
+    "/v1/api/workstreams/saved": {
       "get": {
-        "summary": "List saved sessions",
-        "operationId": "v1_api_sessions_get",
-        "tags": [
-          "Sessions"
-        ],
+        "summary": "List saved workstreams",
+        "operationId": "v1_api_workstreams_saved_get",
+        "tags": ["Workstreams"],
         "responses": {
           "200": {
             "description": "Success",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/ListSessionsResponse"
+                  "$ref": "#/components/schemas/ListSavedWorkstreamsResponse"
                 }
               }
             }
@@ -390,9 +417,7 @@
       "post": {
         "summary": "Authenticate with a token",
         "operationId": "v1_api_auth_login_post",
-        "tags": [
-          "Auth"
-        ],
+        "tags": ["Auth"],
         "requestBody": {
           "required": true,
           "content": {
@@ -427,13 +452,89 @@
         }
       }
     },
+    "/v1/api/auth/setup": {
+      "post": {
+        "summary": "Create first admin user",
+        "operationId": "v1_api_auth_setup_post",
+        "tags": ["Auth"],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AuthSetupRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AuthSetupResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Error 400",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "Error 409",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Error 503",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/api/auth/status": {
+      "get": {
+        "summary": "Return auth state",
+        "operationId": "v1_api_auth_status_get",
+        "tags": ["Auth"],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AuthStatusResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/v1/api/auth/logout": {
       "post": {
         "summary": "Clear auth cookie",
         "operationId": "v1_api_auth_logout_post",
-        "tags": [
-          "Auth"
-        ],
+        "tags": ["Auth"],
         "responses": {
           "200": {
             "description": "Success",
@@ -452,9 +553,7 @@
       "get": {
         "summary": "Server health check",
         "operationId": "health_get",
-        "tags": [
-          "Observability"
-        ],
+        "tags": ["Observability"],
         "responses": {
           "200": {
             "description": "Success",
@@ -481,9 +580,7 @@
             "type": "string"
           }
         },
-        "required": [
-          "error"
-        ],
+        "required": ["error"],
         "title": "ErrorResponse",
         "type": "object"
       },
@@ -492,9 +589,7 @@
         "properties": {
           "status": {
             "default": "ok",
-            "examples": [
-              "ok"
-            ],
+            "examples": ["ok"],
             "title": "Status",
             "type": "string"
           }
@@ -503,17 +598,27 @@
         "type": "object"
       },
       "AuthLoginRequest": {
-        "description": "POST /v1/api/auth/login request body.",
+        "description": "POST /v1/api/auth/login request body.\n\nEither username+password or token must be provided.",
         "properties": {
+          "username": {
+            "default": "",
+            "description": "Login username",
+            "title": "Username",
+            "type": "string"
+          },
+          "password": {
+            "default": "",
+            "description": "Login password",
+            "title": "Password",
+            "type": "string"
+          },
           "token": {
-            "description": "Bearer token to authenticate",
+            "default": "",
+            "description": "Legacy: bearer token to authenticate",
             "title": "Token",
             "type": "string"
           }
         },
-        "required": [
-          "token"
-        ],
         "title": "AuthLoginRequest",
         "type": "object"
       },
@@ -525,22 +630,116 @@
             "title": "Status",
             "type": "string"
           },
+          "user_id": {
+            "default": "",
+            "description": "Authenticated user ID",
+            "title": "User Id",
+            "type": "string"
+          },
           "role": {
-            "description": "Assigned role",
-            "examples": [
-              "full",
-              "read"
-            ],
+            "description": "Legacy role",
+            "examples": ["full", "read"],
             "title": "Role",
             "type": "string"
+          },
+          "scopes": {
+            "default": "",
+            "description": "Comma-separated scopes",
+            "examples": ["read,write,approve"],
+            "title": "Scopes",
+            "type": "string"
+          },
+          "jwt": {
+            "default": "",
+            "description": "JWT session token (if JWT auth is configured)",
+            "title": "Jwt",
+            "type": "string"
           }
         },
-        "required": [
-          "role"
-        ],
+        "required": ["role"],
         "title": "AuthLoginResponse",
         "type": "object"
       },
+      "AuthSetupRequest": {
+        "description": "POST /v1/api/auth/setup request body.",
+        "properties": {
+          "username": {
+            "description": "Login username (1-64 ASCII characters)",
+            "title": "Username",
+            "type": "string"
+          },
+          "display_name": {
+            "description": "Display name",
+            "title": "Display Name",
+            "type": "string"
+          },
+          "password": {
+            "description": "Password (minimum 8 characters)",
+            "title": "Password",
+            "type": "string"
+          }
+        },
+        "required": ["username", "display_name", "password"],
+        "title": "AuthSetupRequest",
+        "type": "object"
+      },
+      "AuthSetupResponse": {
+        "description": "POST /v1/api/auth/setup success response.",
+        "properties": {
+          "status": {
+            "default": "ok",
+            "title": "Status",
+            "type": "string"
+          },
+          "user_id": {
+            "title": "User Id",
+            "type": "string"
+          },
+          "username": {
+            "title": "Username",
+            "type": "string"
+          },
+          "role": {
+            "default": "full",
+            "title": "Role",
+            "type": "string"
+          },
+          "scopes": {
+            "default": "approve,read,write",
+            "title": "Scopes",
+            "type": "string"
+          },
+          "jwt": {
+            "default": "",
+            "description": "JWT session token",
+            "title": "Jwt",
+            "type": "string"
+          }
+        },
+        "required": ["user_id", "username"],
+        "title": "AuthSetupResponse",
+        "type": "object"
+      },
+      "AuthStatusResponse": {
+        "description": "GET /v1/api/auth/status response.",
+        "properties": {
+          "auth_enabled": {
+            "title": "Auth Enabled",
+            "type": "boolean"
+          },
+          "has_users": {
+            "title": "Has Users",
+            "type": "boolean"
+          },
+          "setup_required": {
+            "title": "Setup Required",
+            "type": "boolean"
+          }
+        },
+        "required": ["auth_enabled", "has_users", "setup_required"],
+        "title": "AuthStatusResponse",
+        "type": "object"
+      },
       "SendRequest": {
         "properties": {
           "message": {
@@ -554,10 +753,7 @@
             "type": "string"
           }
         },
-        "required": [
-          "message",
-          "ws_id"
-        ],
+        "required": ["message", "ws_id"],
         "title": "SendRequest",
         "type": "object"
       },
@@ -565,17 +761,12 @@
         "properties": {
           "status": {
             "description": "'ok' or 'busy'",
-            "examples": [
-              "ok",
-              "busy"
-            ],
+            "examples": ["ok", "busy"],
             "title": "Status",
             "type": "string"
           }
         },
-        "required": [
-          "status"
-        ],
+        "required": ["status"],
         "title": "SendResponse",
         "type": "object"
       },
@@ -611,10 +802,7 @@
             "type": "string"
           }
         },
-        "required": [
-          "approved",
-          "ws_id"
-        ],
+        "required": ["approved", "ws_id"],
         "title": "ApproveRequest",
         "type": "object"
       },
@@ -631,10 +819,7 @@
             "type": "string"
           }
         },
-        "required": [
-          "feedback",
-          "ws_id"
-        ],
+        "required": ["feedback", "ws_id"],
         "title": "PlanFeedbackRequest",
         "type": "object"
       },
@@ -651,13 +836,22 @@
             "type": "string"
           }
         },
-        "required": [
-          "command",
-          "ws_id"
-        ],
+        "required": ["command", "ws_id"],
         "title": "CommandRequest",
         "type": "object"
       },
+      "CancelRequest": {
+        "properties": {
+          "ws_id": {
+            "description": "Target workstream ID",
+            "title": "Ws Id",
+            "type": "string"
+          }
+        },
+        "required": ["ws_id"],
+        "title": "CancelRequest",
+        "type": "object"
+      },
       "CreateWorkstreamRequest": {
         "properties": {
           "name": {
@@ -677,6 +871,18 @@
             "description": "Auto-approve all tool calls",
             "title": "Auto Approve",
             "type": "boolean"
+          },
+          "resume_ws": {
+            "default": "",
+            "description": "Workstream ID to resume atomically during creation (empty = fresh start)",
+            "title": "Resume Ws",
+            "type": "string"
+          },
+          "template": {
+            "default": "",
+            "description": "Prompt template name (replaces default templates)",
+            "title": "Template",
+            "type": "string"
           }
         },
         "title": "CreateWorkstreamRequest",
@@ -693,12 +899,21 @@
             "description": "Assigned workstream name",
             "title": "Name",
             "type": "string"
+          },
+          "resumed": {
+            "default": false,
+            "description": "Whether a previous workstream was resumed",
+            "title": "Resumed",
+            "type": "boolean"
+          },
+          "message_count": {
+            "default": 0,
+            "description": "Number of messages in the resumed workstream",
+            "title": "Message Count",
+            "type": "integer"
           }
         },
-        "required": [
-          "ws_id",
-          "name"
-        ],
+        "required": ["ws_id", "name"],
         "title": "CreateWorkstreamResponse",
         "type": "object"
       },
@@ -710,9 +925,7 @@
             "type": "string"
           }
         },
-        "required": [
-          "ws_id"
-        ],
+        "required": ["ws_id"],
         "title": "CloseWorkstreamRequest",
         "type": "object"
       },
@@ -726,9 +939,7 @@
             "type": "array"
           }
         },
-        "required": [
-          "workstreams"
-        ],
+        "required": ["workstreams"],
         "title": "ListWorkstreamsResponse",
         "type": "object"
       },
@@ -745,25 +956,9 @@
           "state": {
             "title": "State",
             "type": "string"
-          },
-          "session_id": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "default": null,
-            "title": "Session Id"
           }
         },
-        "required": [
-          "id",
-          "name",
-          "state"
-        ],
+        "required": ["id", "name", "state"],
         "title": "WorkstreamInfo",
         "type": "object"
       },
@@ -780,10 +975,7 @@
             "$ref": "#/components/schemas/DashboardAggregate"
           }
         },
-        "required": [
-          "workstreams",
-          "aggregate"
-        ],
+        "required": ["workstreams", "aggregate"],
         "title": "DashboardResponse",
         "type": "object"
       },
@@ -837,18 +1029,6 @@
             "title": "State",
             "type": "string"
           },
-          "session_id": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "default": null,
-            "title": "Session Id"
-          },
           "title": {
             "default": "",
             "title": "Title",
@@ -895,34 +1075,28 @@
             "type": "string"
           }
         },
-        "required": [
-          "id",
-          "name",
-          "state"
-        ],
+        "required": ["id", "name", "state"],
         "title": "DashboardWorkstream",
         "type": "object"
       },
-      "ListSessionsResponse": {
+      "ListSavedWorkstreamsResponse": {
         "properties": {
-          "sessions": {
+          "workstreams": {
             "items": {
-              "$ref": "#/components/schemas/SessionInfo"
+              "$ref": "#/components/schemas/SavedWorkstreamInfo"
             },
-            "title": "Sessions",
+            "title": "Workstreams",
             "type": "array"
           }
         },
-        "required": [
-          "sessions"
-        ],
-        "title": "ListSessionsResponse",
+        "required": ["workstreams"],
+        "title": "ListSavedWorkstreamsResponse",
         "type": "object"
       },
-      "SessionInfo": {
+      "SavedWorkstreamInfo": {
         "properties": {
-          "session_id": {
-            "title": "Session Id",
+          "ws_id": {
+            "title": "Ws Id",
             "type": "string"
           },
           "alias": {
@@ -962,22 +1136,14 @@
             "type": "integer"
           }
         },
-        "required": [
-          "session_id",
-          "created",
-          "updated",
-          "message_count"
-        ],
-        "title": "SessionInfo",
+        "required": ["ws_id", "created", "updated", "message_count"],
+        "title": "SavedWorkstreamInfo",
         "type": "object"
       },
       "HealthResponse": {
         "properties": {
           "status": {
-            "examples": [
-              "ok",
-              "degraded"
-            ],
+            "examples": ["ok", "degraded"],
             "title": "Status",
             "type": "string"
           },
@@ -1017,38 +1183,58 @@
               }
             ],
             "default": null
+          },
+          "mcp": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/McpStatus"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null
           }
         },
-        "required": [
-          "status"
-        ],
+        "required": ["status"],
         "title": "HealthResponse",
         "type": "object"
       },
+      "McpStatus": {
+        "properties": {
+          "servers": {
+            "default": 0,
+            "title": "Servers",
+            "type": "integer"
+          },
+          "resources": {
+            "default": 0,
+            "title": "Resources",
+            "type": "integer"
+          },
+          "prompts": {
+            "default": 0,
+            "title": "Prompts",
+            "type": "integer"
+          }
+        },
+        "title": "McpStatus",
+        "type": "object"
+      },
       "BackendStatus": {
         "properties": {
           "status": {
-            "examples": [
-              "up",
-              "down"
-            ],
+            "examples": ["up", "down"],
             "title": "Status",
             "type": "string"
           },
           "circuit_state": {
-            "examples": [
-              "closed",
-              "open",
-              "half_open"
-            ],
+            "examples": ["closed", "open", "half_open"],
             "title": "Circuit State",
             "type": "string"
           }
         },
-        "required": [
-          "status",
-          "circuit_state"
-        ],
+        "required": ["status", "circuit_state"],
         "title": "BackendStatus",
         "type": "object"
       },

sdk/typescript/src/console.ts

@@ -1,23 +1,40 @@
 import { BaseClient, type ClientOptions } from "./base.js";
 import type { ClusterEvent } from "./events.js";
 import type {
+  AuditQueryOptions,
+  AuditResponse,
   AuthLoginResponse,
   AuthSetupResponse,
   AuthStatusResponse,
   ClusterNodesResponse,
   ClusterOverviewResponse,
+  ClusterSnapshotResponse,
   ClusterWorkstreamsResponse,
   ConsoleCreateWsRequest,
   ConsoleCreateWsResponse,
   ConsoleHealthResponse,
+  CreatePolicyOptions,
+  CreateRoleOptions,
   CreateScheduleRequest,
+  CreateTemplateOptions,
   ListScheduleRunsResponse,
   ListSchedulesResponse,
   NodeDetailResponse,
   NodesOptions,
+  OrgInfo,
+  PromptTemplateInfo,
+  RoleInfo,
   ScheduleInfo,
   StatusResponse,
+  ToolPolicyInfo,
+  UpdateOrgOptions,
+  UpdatePolicyOptions,
+  UpdateRoleOptions,
   UpdateScheduleRequest,
+  UpdateTemplateOptions,
+  UsageQueryOptions,
+  UsageResponse,
+  UserRoleInfo,
   WorkstreamsOptions,
 } from "./types.js";
 
@@ -33,6 +50,10 @@ export class TurnstoneConsole extends BaseClient {
     return this.request("GET", "/v1/api/cluster/overview");
   }
 
+  async snapshot(): Promise<ClusterSnapshotResponse> {
+    return this.request("GET", "/v1/api/cluster/snapshot");
+  }
+
   async nodes(opts?: NodesOptions): Promise<ClusterNodesResponse> {
     return this.request("GET", "/v1/api/cluster/nodes", {
       params: {
@@ -152,4 +173,125 @@ export class TurnstoneConsole extends BaseClient {
       params: { limit: opts?.limit ?? 50 },
     });
   }
+
+  // -- Governance: Roles ------------------------------------------------------
+
+  async listRoles(): Promise<{ roles: RoleInfo[] }> {
+    return this.request("GET", "/v1/api/admin/roles");
+  }
+
+  async createRole(opts: CreateRoleOptions): Promise<RoleInfo> {
+    return this.request("POST", "/v1/api/admin/roles", { json: opts });
+  }
+
+  async updateRole(roleId: string, opts: UpdateRoleOptions): Promise<RoleInfo> {
+    return this.request("PUT", `/v1/api/admin/roles/${roleId}`, {
+      json: opts,
+    });
+  }
+
+  async deleteRole(roleId: string): Promise<StatusResponse> {
+    return this.request("DELETE", `/v1/api/admin/roles/${roleId}`);
+  }
+
+  async listUserRoles(userId: string): Promise<{ roles: UserRoleInfo[] }> {
+    return this.request("GET", `/v1/api/admin/users/${userId}/roles`);
+  }
+
+  async assignRole(userId: string, roleId: string): Promise<StatusResponse> {
+    return this.request("POST", `/v1/api/admin/users/${userId}/roles`, {
+      json: { role_id: roleId },
+    });
+  }
+
+  async unassignRole(userId: string, roleId: string): Promise<StatusResponse> {
+    return this.request(
+      "DELETE",
+      `/v1/api/admin/users/${userId}/roles/${roleId}`,
+    );
+  }
+
+  // -- Governance: Organizations ----------------------------------------------
+
+  async listOrgs(): Promise<{ orgs: OrgInfo[] }> {
+    return this.request("GET", "/v1/api/admin/orgs");
+  }
+
+  async getOrg(orgId: string): Promise<OrgInfo> {
+    return this.request("GET", `/v1/api/admin/orgs/${orgId}`);
+  }
+
+  async updateOrg(orgId: string, opts: UpdateOrgOptions): Promise<OrgInfo> {
+    return this.request("PUT", `/v1/api/admin/orgs/${orgId}`, { json: opts });
+  }
+
+  // -- Governance: Tool Policies ----------------------------------------------
+
+  async listPolicies(): Promise<{ policies: ToolPolicyInfo[] }> {
+    return this.request("GET", "/v1/api/admin/policies");
+  }
+
+  async createPolicy(opts: CreatePolicyOptions): Promise<ToolPolicyInfo> {
+    return this.request("POST", "/v1/api/admin/policies", { json: opts });
+  }
+
+  async updatePolicy(
+    policyId: string,
+    opts: UpdatePolicyOptions,
+  ): Promise<ToolPolicyInfo> {
+    return this.request("PUT", `/v1/api/admin/policies/${policyId}`, {
+      json: opts,
+    });
+  }
+
+  async deletePolicy(policyId: string): Promise<StatusResponse> {
+    return this.request("DELETE", `/v1/api/admin/policies/${policyId}`);
+  }
+
+  // -- Governance: Prompt Templates -------------------------------------------
+
+  async listTemplates(): Promise<{ templates: PromptTemplateInfo[] }> {
+    return this.request("GET", "/v1/api/admin/templates");
+  }
+
+  async createTemplate(
+    opts: CreateTemplateOptions,
+  ): Promise<PromptTemplateInfo> {
+    return this.request("POST", "/v1/api/admin/templates", { json: opts });
+  }
+
+  async updateTemplate(
+    templateId: string,
+    opts: UpdateTemplateOptions,
+  ): Promise<PromptTemplateInfo> {
+    return this.request("PUT", `/v1/api/admin/templates/${templateId}`, {
+      json: opts,
+    });
+  }
+
+  async deleteTemplate(templateId: string): Promise<StatusResponse> {
+    return this.request("DELETE", `/v1/api/admin/templates/${templateId}`);
+  }
+
+  // -- Governance: Usage & Audit ----------------------------------------------
+
+  async getUsage(opts: UsageQueryOptions): Promise<UsageResponse> {
+    const params: Record<string, string> = { since: opts.since };
+    if (opts.until) params.until = opts.until;
+    if (opts.user_id) params.user_id = opts.user_id;
+    if (opts.model) params.model = opts.model;
+    if (opts.group_by) params.group_by = opts.group_by;
+    return this.request("GET", "/v1/api/admin/usage", { params });
+  }
+
+  async getAudit(opts?: AuditQueryOptions): Promise<AuditResponse> {
+    const params: Record<string, string> = {};
+    if (opts?.action) params.action = opts.action;
+    if (opts?.user_id) params.user_id = opts.user_id;
+    if (opts?.since) params.since = opts.since;
+    if (opts?.until) params.until = opts.until;
+    if (opts?.limit !== undefined) params.limit = String(opts.limit);
+    if (opts?.offset !== undefined) params.offset = String(opts.offset);
+    return this.request("GET", "/v1/api/admin/audit", { params });
+  }
 }

sdk/typescript/src/events.ts

@@ -1,3 +1,5 @@
+import type { ClusterOverviewResponse, ClusterSnapshotNode } from "./types.js";
+
 // ---------------------------------------------------------------------------
 // Server SSE events
 // ---------------------------------------------------------------------------
@@ -46,6 +48,12 @@ export interface ApproveRequestEvent {
   items: Array<Record<string, unknown>>;
 }
 
+export interface ApprovalResolvedEvent {
+  type: "approval_resolved";
+  approved: boolean;
+  feedback: string;
+}
+
 export interface ToolResultEvent {
   type: "tool_result";
   call_id: string;
@@ -93,6 +101,10 @@ export interface ClearUiEvent {
   type: "clear_ui";
 }
 
+export interface CancelledEvent {
+  type: "cancelled";
+}
+
 // Global events
 
 export interface WsStateEvent {
@@ -135,6 +147,7 @@ export type ServerEvent =
   | StreamEndEvent
   | ToolInfoEvent
   | ApproveRequestEvent
+  | ApprovalResolvedEvent
   | ToolResultEvent
   | ToolOutputChunkEvent
   | StatusEvent
@@ -143,6 +156,7 @@ export type ServerEvent =
   | ErrorEvent
   | BusyErrorEvent
   | ClearUiEvent
+  | CancelledEvent
   | WsStateEvent
   | WsActivityEvent
   | WsRenameEvent
@@ -191,6 +205,13 @@ export interface ClusterWsRenameEvent {
   name: string;
 }
 
+export interface ClusterSnapshotEvent {
+  type: "snapshot";
+  nodes: ClusterSnapshotNode[];
+  overview: ClusterOverviewResponse;
+  timestamp: number;
+}
+
 /** Discriminated union of all console cluster SSE event types. */
 export type ClusterEvent =
   | NodeJoinedEvent
@@ -198,7 +219,8 @@ export type ClusterEvent =
   | ClusterStateEvent
   | ClusterWsCreatedEvent
   | ClusterWsClosedEvent
-  | ClusterWsRenameEvent;
+  | ClusterWsRenameEvent
+  | ClusterSnapshotEvent;
 
 // ---------------------------------------------------------------------------
 // Type guards
@@ -234,6 +256,16 @@ export function isApproveRequestEvent(
   return e.type === "approve_request";
 }
 
+export function isApprovalResolvedEvent(
+  e: ServerEvent,
+): e is ApprovalResolvedEvent {
+  return e.type === "approval_resolved";
+}
+
 export function isPlanReviewEvent(e: ServerEvent): e is PlanReviewEvent {
   return e.type === "plan_review";
 }
+
+export function isCancelledEvent(e: ServerEvent): e is CancelledEvent {
+  return e.type === "cancelled";
+}

sdk/typescript/src/index.ts

@@ -37,6 +37,7 @@ export type {
   StreamEndEvent,
   ToolInfoEvent,
   ApproveRequestEvent,
+  ApprovalResolvedEvent,
   ToolResultEvent,
   ToolOutputChunkEvent,
   StatusEvent,
@@ -45,6 +46,7 @@ export type {
   ErrorEvent,
   BusyErrorEvent,
   ClearUiEvent,
+  CancelledEvent,
   WsStateEvent,
   WsActivityEvent,
   WsRenameEvent,
@@ -55,6 +57,7 @@ export type {
   ClusterWsCreatedEvent,
   ClusterWsClosedEvent,
   ClusterWsRenameEvent,
+  ClusterSnapshotEvent,
 } from "./events.js";
 
 export {
@@ -65,7 +68,9 @@ export {
   isToolResultEvent,
   isWsStateEvent,
   isApproveRequestEvent,
+  isApprovalResolvedEvent,
   isPlanReviewEvent,
+  isCancelledEvent,
 } from "./events.js";
 
 // Request/response types
@@ -83,9 +88,10 @@ export type {
   DashboardWorkstream,
   DashboardAggregate,
   DashboardResponse,
-  SessionInfo,
-  ListSessionsResponse,
+  SavedWorkstreamInfo,
+  ListSavedWorkstreamsResponse,
   BackendStatus,
+  McpStatus,
   WorkstreamCounts,
   HealthResponse,
   AuthLoginRequest,
@@ -97,6 +103,8 @@ export type {
   ClusterOverviewResponse,
   ClusterNodeInfo,
   ClusterNodesResponse,
+  ClusterSnapshotNode,
+  ClusterSnapshotResponse,
   ClusterWorkstreamInfo,
   ClusterWorkstreamsResponse,
   NodeDetailResponse,
@@ -109,6 +117,24 @@ export type {
   ScheduleRunInfo,
   ListSchedulesResponse,
   ListScheduleRunsResponse,
+  RoleInfo,
+  CreateRoleOptions,
+  UpdateRoleOptions,
+  UserRoleInfo,
+  OrgInfo,
+  UpdateOrgOptions,
+  ToolPolicyInfo,
+  CreatePolicyOptions,
+  UpdatePolicyOptions,
+  PromptTemplateInfo,
+  CreateTemplateOptions,
+  UpdateTemplateOptions,
+  UsageBreakdownItem,
+  UsageResponse,
+  UsageQueryOptions,
+  AuditEventInfo,
+  AuditQueryOptions,
+  AuditResponse,
   TurnResult,
   SendAndWaitOptions,
   NodesOptions,

sdk/typescript/src/server.ts

@@ -8,7 +8,7 @@ import type {
   CreateWorkstreamResponse,
   DashboardResponse,
   HealthResponse,
-  ListSessionsResponse,
+  ListSavedWorkstreamsResponse,
   ListWorkstreamsResponse,
   SendAndWaitOptions,
   SendResponse,
@@ -86,6 +86,12 @@ export class TurnstoneServer extends BaseClient {
     });
   }
 
+  async cancel(wsId: string): Promise<StatusResponse> {
+    return this.request("POST", "/v1/api/cancel", {
+      json: { ws_id: wsId },
+    });
+  }
+
   // -- Streaming ------------------------------------------------------------
 
   async *streamEvents(wsId: string): AsyncIterableIterator<ServerEvent> {
@@ -178,10 +184,10 @@ export class TurnstoneServer extends BaseClient {
     return result;
   }
 
-  // -- Sessions -------------------------------------------------------------
+  // -- Saved workstreams ----------------------------------------------------
 
-  async listSessions(): Promise<ListSessionsResponse> {
-    return this.request("GET", "/v1/api/sessions");
+  async listSavedWorkstreams(): Promise<ListSavedWorkstreamsResponse> {
+    return this.request("GET", "/v1/api/workstreams/saved");
   }
 
   // -- Auth -----------------------------------------------------------------

sdk/typescript/src/types.ts

@@ -71,14 +71,14 @@ export interface CreateWorkstreamRequest {
   name?: string;
   model?: string;
   auto_approve?: boolean;
-  resume_session?: string;
+  resume_ws?: string;
+  template?: string;
 }
 
 export interface CreateWorkstreamResponse {
   ws_id: string;
   name: string;
   resumed?: boolean;
-  session_id?: string;
   message_count?: number;
 }
 
@@ -90,7 +90,6 @@ export interface WorkstreamInfo {
   id: string;
   name: string;
   state: string;
-  session_id?: string | null;
 }
 
 export interface ListWorkstreamsResponse {
@@ -101,7 +100,6 @@ export interface DashboardWorkstream {
   id: string;
   name: string;
   state: string;
-  session_id?: string | null;
   title?: string;
   tokens?: number;
   context_ratio?: number;
@@ -128,11 +126,11 @@ export interface DashboardResponse {
 }
 
 // ---------------------------------------------------------------------------
-// Server API — Sessions
+// Server API — Saved workstreams
 // ---------------------------------------------------------------------------
 
-export interface SessionInfo {
-  session_id: string;
+export interface SavedWorkstreamInfo {
+  ws_id: string;
   alias?: string | null;
   title?: string | null;
   created: string;
@@ -140,8 +138,8 @@ export interface SessionInfo {
   message_count: number;
 }
 
-export interface ListSessionsResponse {
-  sessions: SessionInfo[];
+export interface ListSavedWorkstreamsResponse {
+  workstreams: SavedWorkstreamInfo[];
 }
 
 // ---------------------------------------------------------------------------
@@ -162,6 +160,12 @@ export interface WorkstreamCounts {
   error?: number;
 }
 
+export interface McpStatus {
+  servers: number;
+  resources: number;
+  prompts: number;
+}
+
 export interface HealthResponse {
   status: string;
   version?: string;
@@ -169,6 +173,7 @@ export interface HealthResponse {
   model?: string;
   workstreams?: WorkstreamCounts;
   backend?: BackendStatus | null;
+  mcp?: McpStatus | null;
 }
 
 // ---------------------------------------------------------------------------
@@ -247,11 +252,29 @@ export interface NodeDetailResponse {
   aggregate: ClusterAggregate;
 }
 
+export interface ClusterSnapshotNode {
+  node_id: string;
+  server_url: string;
+  max_ws: number;
+  reachable: boolean;
+  version: string;
+  health: Record<string, string>;
+  aggregate: Record<string, number>;
+  workstreams: ClusterWorkstreamInfo[];
+}
+
+export interface ClusterSnapshotResponse {
+  nodes: ClusterSnapshotNode[];
+  overview: ClusterOverviewResponse;
+  timestamp: number;
+}
+
 export interface ConsoleCreateWsRequest {
   node_id?: string;
   name?: string;
   model?: string;
   initial_message?: string;
+  template?: string;
 }
 
 export interface ConsoleCreateWsResponse {
@@ -340,6 +363,176 @@ export interface ListScheduleRunsResponse {
   runs: ScheduleRunInfo[];
 }
 
+// ---------------------------------------------------------------------------
+// Console API — Governance: Roles
+// ---------------------------------------------------------------------------
+
+export interface RoleInfo {
+  role_id: string;
+  name: string;
+  display_name: string;
+  permissions: string;
+  builtin: boolean;
+  org_id: string;
+  created: string;
+  updated: string;
+}
+
+export interface CreateRoleOptions {
+  name: string;
+  display_name?: string;
+  permissions?: string;
+}
+
+export interface UpdateRoleOptions {
+  display_name?: string;
+  permissions?: string;
+}
+
+export interface UserRoleInfo extends RoleInfo {
+  assigned_by: string;
+  assignment_created: string;
+}
+
+// ---------------------------------------------------------------------------
+// Console API — Governance: Orgs
+// ---------------------------------------------------------------------------
+
+export interface OrgInfo {
+  org_id: string;
+  name: string;
+  display_name: string;
+  settings: string;
+  created: string;
+  updated: string;
+}
+
+export interface UpdateOrgOptions {
+  display_name?: string;
+  settings?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Console API — Governance: Tool Policies
+// ---------------------------------------------------------------------------
+
+export interface ToolPolicyInfo {
+  policy_id: string;
+  name: string;
+  tool_pattern: string;
+  action: string;
+  priority: number;
+  org_id: string;
+  enabled: boolean;
+  created_by: string;
+  created: string;
+  updated: string;
+}
+
+export interface CreatePolicyOptions {
+  name: string;
+  tool_pattern: string;
+  action: string;
+  priority?: number;
+  org_id?: string;
+  enabled?: boolean;
+}
+
+export interface UpdatePolicyOptions {
+  name?: string;
+  tool_pattern?: string;
+  action?: string;
+  priority?: number;
+  enabled?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Console API — Governance: Prompt Templates
+// ---------------------------------------------------------------------------
+
+export interface PromptTemplateInfo {
+  template_id: string;
+  name: string;
+  category: string;
+  content: string;
+  variables: string;
+  is_default: boolean;
+  org_id: string;
+  created_by: string;
+  created: string;
+  updated: string;
+  origin: string;
+  mcp_server: string;
+  readonly: boolean;
+}
+
+export interface CreateTemplateOptions {
+  name: string;
+  content: string;
+  category?: string;
+  variables?: string;
+  is_default?: boolean;
+  org_id?: string;
+}
+
+export interface UpdateTemplateOptions {
+  name?: string;
+  content?: string;
+  category?: string;
+  variables?: string;
+  is_default?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Console API — Governance: Usage & Audit
+// ---------------------------------------------------------------------------
+
+export interface UsageBreakdownItem {
+  key?: string;
+  prompt_tokens: number;
+  completion_tokens: number;
+  tool_calls_count: number;
+}
+
+export interface UsageResponse {
+  summary: UsageBreakdownItem[];
+  breakdown: UsageBreakdownItem[];
+}
+
+export interface UsageQueryOptions {
+  since: string;
+  until?: string;
+  user_id?: string;
+  model?: string;
+  group_by?: string;
+}
+
+export interface AuditEventInfo {
+  event_id: string;
+  timestamp: string;
+  user_id: string;
+  action: string;
+  resource_type: string;
+  resource_id: string;
+  detail: string;
+  ip_address: string;
+  created: string;
+}
+
+export interface AuditQueryOptions {
+  action?: string;
+  user_id?: string;
+  since?: string;
+  until?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export interface AuditResponse {
+  events: AuditEventInfo[];
+  total: number;
+}
+
 // ---------------------------------------------------------------------------
 // SDK-specific types
 // ---------------------------------------------------------------------------

sdk/typescript/tests/events.test.ts

@@ -6,6 +6,7 @@ import {
   isToolResultEvent,
   isWsStateEvent,
   isApproveRequestEvent,
+  isApprovalResolvedEvent,
   isPlanReviewEvent,
   isReasoningEvent,
 } from "../src/events.js";
@@ -62,6 +63,15 @@ describe("event type guards", () => {
     expect(isApproveRequestEvent(e)).toBe(true);
   });
 
+  it("isApprovalResolvedEvent", () => {
+    const e: ServerEvent = {
+      type: "approval_resolved",
+      approved: false,
+      feedback: "Approval timed out",
+    };
+    expect(isApprovalResolvedEvent(e)).toBe(true);
+  });
+
   it("isPlanReviewEvent", () => {
     const e: ServerEvent = { type: "plan_review", content: "## Plan" };
     expect(isPlanReviewEvent(e)).toBe(true);

tests.json

@@ -59,7 +59,7 @@
       "user_prompt": "Change the default port from 8000 to 9000 in both server.py and config.py",
       "setup": {
         "files": {
-          "server.py": "from config import PORT\n\ndef run():\n    print(f'Listening on port {PORT}')\n",
+          "server.py": "import socket\n\ndef run():\n    sock = socket.socket()\n    sock.bind(('localhost', 8000))\n    print('Server running on port 8000')\n",
           "config.py": "PORT = 8000\nHOST = 'localhost'\n"
         }
       },
@@ -126,7 +126,7 @@
           "app.py": "import sqlite3\nfrom flask import Flask, jsonify\n\napp = Flask(__name__)\nDB = 'data.db'\n\ndef get_db():\n    return sqlite3.connect(DB)\n\n@app.route('/users')\ndef list_users():\n    db = get_db()\n    users = db.execute('SELECT * FROM users').fetchall()\n    db.close()\n    return jsonify(users)\n\n@app.route('/users/<int:uid>')\ndef get_user(uid):\n    db = get_db()\n    user = db.execute('SELECT * FROM users WHERE id=?', (uid,)).fetchone()\n    db.close()\n    return jsonify(user)\n\nif __name__ == '__main__':\n    app.run(port=8000)\n"
         }
       },
-      "expected_actions": [{ "tool": "plan" }],
+      "expected_actions": [{ "tool": "create_plan" }],
       "match_mode": "subset"
     },
     {
@@ -175,6 +175,24 @@
         { "tool": "man", "args_pattern": { "page": "tar" } }
       ],
       "match_mode": "subset"
+    },
+    {
+      "id": "math-calculation",
+      "description": "Use the math tool for precise calculations, not bash or mental math",
+      "user_prompt": "What is 2^64 - 1? Use the math tool to calculate it precisely.",
+      "expected_actions": [
+        { "tool": "math", "args_pattern": { "code": "2.*64" } }
+      ],
+      "match_mode": "subset"
+    },
+    {
+      "id": "web-search-query",
+      "description": "Use web_search for general knowledge lookups, not web_fetch",
+      "user_prompt": "Search the web for the current population of Tokyo",
+      "expected_actions": [
+        { "tool": "web_search", "args_pattern": { "query": "Tokyo" } }
+      ],
+      "match_mode": "subset"
     }
   ]
 }

tests/test_audit.py

@@ -0,0 +1,58 @@
+"""Tests for turnstone.core.audit."""
+
+import json
+
+import pytest
+
+from turnstone.core.audit import record_audit
+from turnstone.core.storage._sqlite import SQLiteBackend
+
+
+@pytest.fixture
+def storage(tmp_path):
+    path = str(tmp_path / "test.db")
+    backend = SQLiteBackend(path)
+    yield backend
+    backend.close()
+
+
+def test_record_audit_basic(storage):
+    record_audit(
+        storage, "user-1", "user.create", "user", "u123", {"username": "alice"}, "127.0.0.1"
+    )
+    events = storage.list_audit_events()
+    assert len(events) == 1
+    ev = events[0]
+    assert ev["user_id"] == "user-1"
+    assert ev["action"] == "user.create"
+    assert ev["resource_type"] == "user"
+    assert ev["resource_id"] == "u123"
+    assert ev["ip_address"] == "127.0.0.1"
+    detail = json.loads(ev["detail"])
+    assert detail["username"] == "alice"
+
+
+def test_record_audit_no_detail(storage):
+    record_audit(storage, "user-1", "token.revoke", "token", "t456")
+    events = storage.list_audit_events()
+    assert len(events) == 1
+    assert events[0]["detail"] == "{}"
+
+
+def test_record_audit_silent_on_failure():
+    """record_audit should not raise even if storage is broken."""
+
+    class BrokenStorage:
+        def record_audit_event(self, **kw):
+            raise RuntimeError("boom")
+
+    # Should not raise
+    record_audit(BrokenStorage(), "u1", "test.action")
+
+
+def test_record_audit_generates_unique_ids(storage):
+    record_audit(storage, "u1", "a.one")
+    record_audit(storage, "u1", "a.two")
+    events = storage.list_audit_events()
+    assert len(events) == 2
+    assert events[0]["event_id"] != events[1]["event_id"]

tests/test_auth.py

@@ -719,7 +719,7 @@ class TestServerAuth:
         srv_mod._metrics.model = "test-model"
 
         mock_session = MagicMock()
-        mock_session.session_id = "test-session-id"
+        mock_session.ws_id = "test-session-id"
 
         mock_ws = MagicMock()
         mock_ws.id = "test-ws"
@@ -937,7 +937,7 @@ class TestServerLogin:
         srv_mod._metrics.model = "test-model"
 
         mock_session = MagicMock()
-        mock_session.session_id = "test-session-id"
+        mock_session.ws_id = "test-session-id"
 
         mock_ws = MagicMock()
         mock_ws.id = "test-ws"

tests/test_bootstrap.py

@@ -0,0 +1,630 @@
+"""Tests for the bootstrap wizard module."""
+
+from __future__ import annotations
+
+import os
+import socket
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+from turnstone.bootstrap import (
+    SYSTEM_PROMPT,
+    TOOLS,
+    _BootstrapLLM,
+    _FinishError,
+    _mask_secrets,
+    _tool_check_docker,
+    _tool_check_port,
+    _tool_finish,
+    _tool_generate_secret,
+    _tool_read_file,
+    _tool_validate_api_key,
+    _tool_write_file,
+    execute_tool,
+)
+
+# ---------------------------------------------------------------------------
+# Tool function tests
+# ---------------------------------------------------------------------------
+
+
+class TestReadFile:
+    def test_existing_file(self, tmp_path: Path) -> None:
+        f = tmp_path / "test.txt"
+        f.write_text("hello world")
+        result = _tool_read_file(tmp_path, {"path": "test.txt"})
+        assert result == "hello world"
+
+    def test_missing_file(self, tmp_path: Path) -> None:
+        result = _tool_read_file(tmp_path, {"path": "nope.txt"})
+        assert "Error: file not found" in result
+
+    def test_nested_path(self, tmp_path: Path) -> None:
+        sub = tmp_path / "sub"
+        sub.mkdir()
+        f = sub / "nested.txt"
+        f.write_text("nested content")
+        result = _tool_read_file(tmp_path, {"path": "sub/nested.txt"})
+        assert result == "nested content"
+
+    def test_path_traversal_blocked(self, tmp_path: Path) -> None:
+        result = _tool_read_file(tmp_path, {"path": "../../etc/passwd"})
+        assert "escapes project directory" in result
+
+    def test_absolute_path_blocked(self, tmp_path: Path) -> None:
+        result = _tool_read_file(tmp_path, {"path": "/etc/passwd"})
+        assert "escapes project directory" in result
+
+
+class TestWriteFile:
+    def test_write_confirmed(self, tmp_path: Path) -> None:
+        with patch("builtins.input", return_value="y"):
+            result = _tool_write_file(tmp_path, {"path": "out.txt", "content": "data\n"})
+        assert "written successfully" in result
+        assert (tmp_path / "out.txt").read_text() == "data\n"
+
+    def test_write_declined(self, tmp_path: Path) -> None:
+        with patch("builtins.input", return_value="n"):
+            result = _tool_write_file(tmp_path, {"path": "out.txt", "content": "data\n"})
+        assert "declined" in result
+        assert not (tmp_path / "out.txt").exists()
+
+    def test_write_creates_parent_dirs(self, tmp_path: Path) -> None:
+        with patch("builtins.input", return_value="y"):
+            result = _tool_write_file(tmp_path, {"path": "a/b/c.txt", "content": "deep\n"})
+        assert "written successfully" in result
+        assert (tmp_path / "a" / "b" / "c.txt").read_text() == "deep\n"
+
+    def test_sh_files_are_executable(self, tmp_path: Path) -> None:
+        with patch("builtins.input", return_value="y"):
+            _tool_write_file(tmp_path, {"path": "setup.sh", "content": "#!/bin/bash\n"})
+        mode = (tmp_path / "setup.sh").stat().st_mode
+        assert mode & 0o110  # user + group executable, not world
+
+    def test_path_traversal_blocked(self, tmp_path: Path) -> None:
+        result = _tool_write_file(tmp_path, {"path": "../../escape.txt", "content": "bad\n"})
+        assert "escapes project directory" in result
+
+    def test_default_enter_confirms(self, tmp_path: Path) -> None:
+        with patch("builtins.input", return_value=""):
+            result = _tool_write_file(tmp_path, {"path": "ok.txt", "content": "ok\n"})
+        assert "written successfully" in result
+
+    def test_duplicate_write_skipped(self, tmp_path: Path) -> None:
+        (tmp_path / "dup.txt").write_text("same\n")
+        result = _tool_write_file(tmp_path, {"path": "dup.txt", "content": "same\n"})
+        assert "already exists" in result
+
+    def test_different_content_still_prompts(self, tmp_path: Path) -> None:
+        (tmp_path / "changed.txt").write_text("old\n")
+        with patch("builtins.input", return_value="y"):
+            result = _tool_write_file(tmp_path, {"path": "changed.txt", "content": "new\n"})
+        assert "written successfully" in result
+        assert (tmp_path / "changed.txt").read_text() == "new\n"
+
+
+class TestGenerateSecret:
+    def test_default_length(self) -> None:
+        secret = _tool_generate_secret({})
+        assert len(secret) == 64  # 32 bytes -> 64 hex chars
+
+    def test_custom_length(self) -> None:
+        secret = _tool_generate_secret({"length": 16})
+        assert len(secret) == 32
+
+    def test_uniqueness(self) -> None:
+        s1 = _tool_generate_secret({})
+        s2 = _tool_generate_secret({})
+        assert s1 != s2
+
+    def test_invalid_length_fallback(self) -> None:
+        secret = _tool_generate_secret({"length": -1})
+        assert len(secret) == 64  # falls back to 32 bytes
+
+    def test_excessive_length_capped(self) -> None:
+        secret = _tool_generate_secret({"length": 99999})
+        assert len(secret) == 64  # falls back to 32 bytes
+
+
+class TestCheckPort:
+    def test_available_port(self) -> None:
+        # Pick a random high port that's likely free
+        result = _tool_check_port({"port": 59123})
+        assert "AVAILABLE" in result or "IN USE" in result
+
+    def test_in_use_port(self) -> None:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+            sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            sock.bind(("127.0.0.1", 0))
+            port = sock.getsockname()[1]
+            sock.listen(1)
+            result = _tool_check_port({"port": port})
+        assert "IN USE" in result
+
+    def test_invalid_port(self) -> None:
+        result = _tool_check_port({"port": -1})
+        assert "Error" in result
+
+    def test_port_zero(self) -> None:
+        result = _tool_check_port({"port": 0})
+        assert "Error" in result
+
+
+class TestCheckDocker:
+    def test_docker_installed(self) -> None:
+        mock_docker = MagicMock()
+        mock_docker.returncode = 0
+        mock_docker.stdout = "24.0.7"
+
+        mock_compose = MagicMock()
+        mock_compose.returncode = 0
+        mock_compose.stdout = "2.24.5"
+
+        with patch("subprocess.run", side_effect=[mock_docker, mock_compose]):
+            result = _tool_check_docker({})
+        assert "Docker: installed" in result
+        assert "Docker Compose: installed" in result
+
+    def test_docker_not_installed(self) -> None:
+        with patch("subprocess.run", side_effect=FileNotFoundError):
+            result = _tool_check_docker({})
+        assert "NOT installed" in result or "NOT available" in result
+
+    def test_docker_daemon_not_running(self) -> None:
+        mock_docker = MagicMock()
+        mock_docker.returncode = 1
+        mock_docker.stderr = "Cannot connect to the Docker daemon"
+
+        mock_compose = MagicMock()
+        mock_compose.returncode = 1
+
+        with patch("subprocess.run", side_effect=[mock_docker, mock_compose]):
+            result = _tool_check_docker({})
+        assert "NOT running" in result
+
+
+class TestValidateApiKey:
+    def test_openai_success(self) -> None:
+        mock_client = MagicMock()
+        mock_client.models.list.return_value = []
+        with patch("openai.OpenAI", return_value=mock_client):
+            result = _tool_validate_api_key({"provider": "openai", "api_key": "sk-test"})
+        assert "Success" in result
+
+    def test_openai_failure(self) -> None:
+        with patch("openai.OpenAI") as mock_cls:
+            mock_cls.return_value.models.list.side_effect = Exception("Invalid key")
+            result = _tool_validate_api_key({"provider": "openai", "api_key": "bad"})
+        assert "Failed" in result
+
+    def test_unknown_provider(self) -> None:
+        result = _tool_validate_api_key({"provider": "unknown", "api_key": "x"})
+        assert "unknown" in result
+
+
+class TestExecuteTool:
+    def test_unknown_tool(self, tmp_path: Path) -> None:
+        result = execute_tool("nonexistent", {}, tmp_path)
+        assert "unknown tool" in result
+
+    def test_dispatches_correctly(self, tmp_path: Path) -> None:
+        f = tmp_path / "hello.txt"
+        f.write_text("hi")
+        result = execute_tool("read_file", {"path": "hello.txt"}, tmp_path)
+        assert result == "hi"
+
+    def test_finish_raises(self, tmp_path: Path) -> None:
+        import pytest
+
+        with pytest.raises(_FinishError, match="All done"):
+            execute_tool("finish", {"summary": "All done"}, tmp_path)
+
+
+class TestFinishTool:
+    def test_raises_with_summary(self) -> None:
+        import pytest
+
+        with pytest.raises(_FinishError) as exc_info:
+            _tool_finish({"summary": "Configured production deployment."})
+        assert exc_info.value.summary == "Configured production deployment."
+
+    def test_default_summary(self) -> None:
+        import pytest
+
+        with pytest.raises(_FinishError) as exc_info:
+            _tool_finish({})
+        assert exc_info.value.summary == "Setup complete."
+
+
+# ---------------------------------------------------------------------------
+# Secret masking tests
+# ---------------------------------------------------------------------------
+
+
+class TestMaskSecrets:
+    def test_masks_api_key(self) -> None:
+        text = "OPENAI_API_KEY=sk-1234567890abcdef"
+        result = _mask_secrets(text)
+        assert "sk-1" in result
+        assert "cdef" in result
+        assert "1234567890abcde" not in result
+
+    def test_preserves_comments(self) -> None:
+        text = "# OPENAI_API_KEY=sk-1234567890abcdef"
+        result = _mask_secrets(text)
+        assert result == text
+
+    def test_preserves_short_values(self) -> None:
+        text = "TOKEN=short"
+        result = _mask_secrets(text)
+        assert result == text
+
+    def test_preserves_non_sensitive(self) -> None:
+        text = "MODEL=gpt-5.4"
+        result = _mask_secrets(text)
+        assert result == text
+
+
+# ---------------------------------------------------------------------------
+# Message conversion tests (Anthropic)
+# ---------------------------------------------------------------------------
+
+
+class TestAnthropicConversion:
+    """Test the Anthropic message/tool conversion inside _BootstrapLLM."""
+
+    def _make_llm(self) -> _BootstrapLLM:
+        return _BootstrapLLM("anthropic", MagicMock(), "test-model")
+
+    def test_tool_format_conversion(self) -> None:
+        """OpenAI tool format should convert to Anthropic format."""
+        llm = self._make_llm()
+        # The conversion happens inside _complete_anthropic; we test indirectly
+        # by checking the tools passed to the mock client
+        mock_response = MagicMock()
+        mock_response.content = [MagicMock(type="text", text="hello")]
+        mock_response.stop_reason = "end_turn"
+        llm.client.messages.create.return_value = mock_response
+
+        llm.complete(
+            [{"role": "system", "content": "sys"}, {"role": "user", "content": "hi"}],
+            TOOLS[:1],  # Just read_file
+        )
+
+        call_kwargs = llm.client.messages.create.call_args[1]
+        api_tools = call_kwargs["tools"]
+        assert len(api_tools) == 1
+        assert api_tools[0]["name"] == "read_file"
+        assert "input_schema" in api_tools[0]
+        assert "description" in api_tools[0]
+
+    def test_system_message_extraction(self) -> None:
+        """System message should be extracted to system parameter."""
+        llm = self._make_llm()
+        mock_response = MagicMock()
+        mock_response.content = [MagicMock(type="text", text="ok")]
+        mock_response.stop_reason = "end_turn"
+        llm.client.messages.create.return_value = mock_response
+
+        llm.complete(
+            [{"role": "system", "content": "test system"}, {"role": "user", "content": "hi"}],
+            [],
+        )
+
+        call_kwargs = llm.client.messages.create.call_args[1]
+        assert call_kwargs["system"] == "test system"
+        # System should NOT appear in messages
+        for msg in call_kwargs["messages"]:
+            assert msg["role"] != "system"
+
+    def test_tool_result_conversion(self) -> None:
+        """OpenAI tool result messages should convert to Anthropic format."""
+        llm = self._make_llm()
+        mock_response = MagicMock()
+        mock_response.content = [MagicMock(type="text", text="got it")]
+        mock_response.stop_reason = "end_turn"
+        llm.client.messages.create.return_value = mock_response
+
+        messages = [
+            {"role": "system", "content": "sys"},
+            {"role": "user", "content": "hi"},
+            {
+                "role": "assistant",
+                "content": "",
+                "tool_calls": [
+                    {
+                        "id": "tc_1",
+                        "type": "function",
+                        "function": {"name": "check_docker", "arguments": "{}"},
+                    }
+                ],
+            },
+            {
+                "role": "tool",
+                "tool_call_id": "tc_1",
+                "content": "Docker: installed",
+            },
+        ]
+        llm.complete(messages, TOOLS)
+
+        call_kwargs = llm.client.messages.create.call_args[1]
+        api_messages = call_kwargs["messages"]
+
+        # Find the tool_result message
+        tool_result_found = False
+        for msg in api_messages:
+            if msg["role"] == "user" and isinstance(msg.get("content"), list):
+                for block in msg["content"]:
+                    if isinstance(block, dict) and block.get("type") == "tool_result":
+                        assert block["tool_use_id"] == "tc_1"
+                        assert block["content"] == "Docker: installed"
+                        tool_result_found = True
+        assert tool_result_found
+
+    def test_tool_use_blocks_in_assistant(self) -> None:
+        """Assistant messages with tool_calls should convert to content blocks."""
+        llm = self._make_llm()
+        mock_response = MagicMock()
+        mock_response.content = [MagicMock(type="text", text="ok")]
+        mock_response.stop_reason = "end_turn"
+        llm.client.messages.create.return_value = mock_response
+
+        messages = [
+            {"role": "system", "content": "sys"},
+            {"role": "user", "content": "hi"},
+            {
+                "role": "assistant",
+                "content": "Let me check",
+                "tool_calls": [
+                    {
+                        "id": "tc_1",
+                        "type": "function",
+                        "function": {"name": "check_docker", "arguments": "{}"},
+                    }
+                ],
+            },
+            {"role": "tool", "tool_call_id": "tc_1", "content": "ok"},
+        ]
+        llm.complete(messages, TOOLS)
+
+        call_kwargs = llm.client.messages.create.call_args[1]
+        api_messages = call_kwargs["messages"]
+
+        # First message should be user "hi"
+        assert api_messages[0]["role"] == "user"
+        # Second should be assistant with content blocks
+        assistant_msg = api_messages[1]
+        assert assistant_msg["role"] == "assistant"
+        assert isinstance(assistant_msg["content"], list)
+        # Should have text block + tool_use block
+        types = [b["type"] for b in assistant_msg["content"]]
+        assert "text" in types
+        assert "tool_use" in types
+
+
+class TestOpenAICompletion:
+    """Test the OpenAI path of _BootstrapLLM."""
+
+    def test_text_response(self) -> None:
+        llm = _BootstrapLLM("openai", MagicMock(), "gpt-5.4")
+        mock_choice = MagicMock()
+        mock_choice.message.content = "Hello!"
+        mock_choice.message.tool_calls = None
+        mock_choice.finish_reason = "stop"
+        llm.client.chat.completions.create.return_value = MagicMock(choices=[mock_choice])
+
+        content, tool_calls, reason = llm.complete([{"role": "user", "content": "hi"}], TOOLS)
+        assert content == "Hello!"
+        assert tool_calls is None
+        assert reason == "stop"
+
+    def test_tool_call_response(self) -> None:
+        llm = _BootstrapLLM("openai", MagicMock(), "gpt-5.4")
+
+        mock_tc = MagicMock()
+        mock_tc.id = "call_123"
+        mock_tc.function.name = "check_docker"
+        mock_tc.function.arguments = "{}"
+
+        mock_choice = MagicMock()
+        mock_choice.message.content = ""
+        mock_choice.message.tool_calls = [mock_tc]
+        mock_choice.finish_reason = "tool_calls"
+        llm.client.chat.completions.create.return_value = MagicMock(choices=[mock_choice])
+
+        content, tool_calls, reason = llm.complete(
+            [{"role": "user", "content": "check docker"}], TOOLS
+        )
+        assert tool_calls is not None
+        assert len(tool_calls) == 1
+        assert tool_calls[0]["function"]["name"] == "check_docker"
+        assert tool_calls[0]["id"] == "call_123"
+
+    def test_no_content(self) -> None:
+        llm = _BootstrapLLM("openai", MagicMock(), "gpt-5.4")
+        mock_choice = MagicMock()
+        mock_choice.message.content = None
+        mock_choice.message.tool_calls = None
+        mock_choice.finish_reason = "stop"
+        llm.client.chat.completions.create.return_value = MagicMock(choices=[mock_choice])
+
+        content, tool_calls, reason = llm.complete([{"role": "user", "content": "hi"}], [])
+        assert content == ""
+        assert tool_calls is None
+
+
+# ---------------------------------------------------------------------------
+# Conversation loop tests
+# ---------------------------------------------------------------------------
+
+
+class TestConversationLoop:
+    def test_quit_exits(self) -> None:
+        """User typing 'quit' should exit the loop."""
+        llm = MagicMock(spec=_BootstrapLLM)
+        llm.complete.return_value = ("What would you like?", None, "stop")
+
+        with patch("builtins.input", return_value="quit"):
+            from turnstone.bootstrap import _run_conversation
+
+            _run_conversation(llm, Path("/tmp"))
+
+    def test_tool_calls_executed(self, tmp_path: Path) -> None:
+        """Tool calls should be executed and results fed back."""
+        llm = MagicMock(spec=_BootstrapLLM)
+        # First call: LLM returns a tool call
+        llm.complete.side_effect = [
+            (
+                "",
+                [
+                    {
+                        "id": "tc_1",
+                        "type": "function",
+                        "function": {"name": "generate_secret", "arguments": "{}"},
+                    }
+                ],
+                "tool_calls",
+            ),
+            # Second call: LLM responds with text after seeing tool result
+            ("Here's your secret!", None, "stop"),
+        ]
+
+        with patch("builtins.input", return_value="quit"):
+            from turnstone.bootstrap import _run_conversation
+
+            _run_conversation(llm, tmp_path)
+
+        # Verify two calls were made
+        assert llm.complete.call_count == 2
+        # Verify tool result was fed back in second call's messages
+        second_call_messages = llm.complete.call_args_list[1][0][0]
+        tool_results = [m for m in second_call_messages if m.get("role") == "tool"]
+        assert len(tool_results) == 1
+        assert tool_results[0]["tool_call_id"] == "tc_1"
+        # Result should be a 64-char hex string
+        assert len(tool_results[0]["content"]) == 64
+
+    def test_empty_input_skipped(self) -> None:
+        """Empty user input should be skipped."""
+        llm = MagicMock(spec=_BootstrapLLM)
+        llm.complete.return_value = ("Ask me something.", None, "stop")
+
+        call_count = 0
+
+        def mock_input(prompt: str = "") -> str:
+            nonlocal call_count
+            call_count += 1
+            if call_count <= 2:
+                return ""  # Empty inputs
+            return "quit"
+
+        with patch("builtins.input", side_effect=mock_input):
+            from turnstone.bootstrap import _run_conversation
+
+            _run_conversation(llm, Path("/tmp"))
+
+    def test_finish_tool_exits_loop(self, tmp_path: Path) -> None:
+        """LLM calling finish tool should exit the conversation cleanly."""
+        llm = MagicMock(spec=_BootstrapLLM)
+        llm.complete.return_value = (
+            "",
+            [
+                {
+                    "id": "tc_fin",
+                    "type": "function",
+                    "function": {
+                        "name": "finish",
+                        "arguments": '{"summary": "All configured."}',
+                    },
+                }
+            ],
+            "tool_calls",
+        )
+
+        from turnstone.bootstrap import _run_conversation
+
+        # Should return without needing user input
+        _run_conversation(llm, tmp_path)
+        assert llm.complete.call_count == 1
+
+
+# ---------------------------------------------------------------------------
+# Interactive startup tests
+# ---------------------------------------------------------------------------
+
+
+class TestProviderDefaults:
+    def test_openai_default_model(self) -> None:
+        from turnstone.bootstrap import _DEFAULT_MODELS
+
+        assert _DEFAULT_MODELS["openai"] == "gpt-5.4"
+
+    def test_anthropic_default_model(self) -> None:
+        from turnstone.bootstrap import _DEFAULT_MODELS
+
+        assert _DEFAULT_MODELS["anthropic"] == "claude-sonnet-4-6"
+
+
+class TestSelectProvider:
+    def test_openai_selection(self) -> None:
+        """Selecting '1' should set up OpenAI."""
+        mock_client = MagicMock()
+        with (
+            patch("builtins.input", side_effect=["1", ""]),
+            patch("getpass.getpass", return_value="sk-test"),
+            patch("openai.OpenAI", return_value=mock_client),
+        ):
+            from turnstone.bootstrap import _select_provider
+
+            provider, client, model = _select_provider()
+        assert provider == "openai"
+        assert model == "gpt-5.4"
+
+    def test_local_selection(self) -> None:
+        """Selecting '3' should set up local/vLLM."""
+        mock_client = MagicMock()
+        # Ensure OPENAI_API_KEY is not in env so we hit the getpass path
+        env = {k: v for k, v in os.environ.items() if k != "OPENAI_API_KEY"}
+        with (
+            patch.dict("os.environ", env, clear=True),
+            patch("builtins.input", side_effect=["3", "http://localhost:8000/v1", "my-model"]),
+            patch("getpass.getpass", return_value="none"),
+            patch("openai.OpenAI", return_value=mock_client),
+        ):
+            from turnstone.bootstrap import _select_provider
+
+            provider, client, model = _select_provider()
+        assert provider == "openai"
+        assert model == "my-model"
+
+
+# ---------------------------------------------------------------------------
+# System prompt and tools sanity checks
+# ---------------------------------------------------------------------------
+
+
+class TestConstants:
+    def test_system_prompt_not_empty(self) -> None:
+        assert len(SYSTEM_PROMPT) > 500
+
+    def test_system_prompt_mentions_turnstone(self) -> None:
+        assert "Turnstone" in SYSTEM_PROMPT
+
+    def test_all_tools_have_required_fields(self) -> None:
+        for tool in TOOLS:
+            assert tool["type"] == "function"
+            func = tool["function"]
+            assert "name" in func
+            assert "description" in func
+            assert "parameters" in func
+            assert func["parameters"]["type"] == "object"
+
+    def test_tool_count(self) -> None:
+        assert len(TOOLS) == 7
+
+    def test_all_tools_have_implementations(self) -> None:
+        from turnstone.bootstrap import TOOL_FUNCTIONS
+
+        for tool in TOOLS:
+            name = tool["function"]["name"]
+            assert name in TOOL_FUNCTIONS, f"Missing implementation for tool: {name}"

tests/test_bridge_events.py

@@ -0,0 +1,69 @@
+"""Tests for bridge event publishing — TurnCompleteEvent on idle transitions."""
+
+from unittest.mock import MagicMock, patch
+
+from turnstone.mq.bridge import Bridge
+from turnstone.mq.protocol import StateChangeEvent, TurnCompleteEvent
+
+
+def _make_bridge():
+    """Create a Bridge with a mock broker (no Redis or HTTP needed)."""
+    broker = MagicMock()
+    bridge = Bridge(server_url="http://localhost:8080", broker=broker, node_id="test-node")
+    return bridge
+
+
+class TestIdleTurnComplete:
+    """TurnCompleteEvent should be emitted on every idle transition."""
+
+    def test_idle_emits_turn_complete_with_correlation_id(self):
+        """Bridge-initiated turn: TurnCompleteEvent has the correlation_id."""
+        bridge = _make_bridge()
+        bridge._active_sends["ws-1"] = "cid-abc"
+
+        published = []
+        with patch.object(
+            bridge, "_publish_ws", side_effect=lambda ws, ev: published.append((ws, ev))
+        ):
+            bridge._handle_global_event({"type": "ws_state", "ws_id": "ws-1", "state": "idle"})
+
+        turn_completes = [(ws, ev) for ws, ev in published if isinstance(ev, TurnCompleteEvent)]
+        assert len(turn_completes) == 1
+        ws, ev = turn_completes[0]
+        assert ws == "ws-1"
+        assert ev.correlation_id == "cid-abc"
+        # correlation_id should be removed from _active_sends
+        assert "ws-1" not in bridge._active_sends
+
+    def test_idle_emits_turn_complete_without_correlation_id(self):
+        """Server-UI-initiated turn: TurnCompleteEvent has empty correlation_id."""
+        bridge = _make_bridge()
+        # No entry in _active_sends for this workstream
+
+        published = []
+        with patch.object(
+            bridge, "_publish_ws", side_effect=lambda ws, ev: published.append((ws, ev))
+        ):
+            bridge._handle_global_event({"type": "ws_state", "ws_id": "ws-2", "state": "idle"})
+
+        turn_completes = [(ws, ev) for ws, ev in published if isinstance(ev, TurnCompleteEvent)]
+        assert len(turn_completes) == 1
+        ws, ev = turn_completes[0]
+        assert ws == "ws-2"
+        assert ev.correlation_id == ""
+
+    def test_non_idle_state_does_not_emit_turn_complete(self):
+        """Non-idle state transitions should emit StateChangeEvent but not TurnCompleteEvent."""
+        bridge = _make_bridge()
+
+        published = []
+        with patch.object(
+            bridge, "_publish_ws", side_effect=lambda ws, ev: published.append((ws, ev))
+        ):
+            bridge._handle_global_event({"type": "ws_state", "ws_id": "ws-3", "state": "thinking"})
+
+        state_changes = [ev for _, ev in published if isinstance(ev, StateChangeEvent)]
+        turn_completes = [ev for _, ev in published if isinstance(ev, TurnCompleteEvent)]
+        assert len(state_changes) == 1
+        assert state_changes[0].state == "thinking"
+        assert len(turn_completes) == 0

tests/test_cancel.py

@@ -0,0 +1,406 @@
+"""Tests for generation cancellation (cooperative cancel via threading.Event)."""
+
+import threading
+import time
+from dataclasses import dataclass, field
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from turnstone.core.session import ChatSession, GenerationCancelled
+
+
+class NullUI:
+    """UI adapter that records state changes and discards other output."""
+
+    def __init__(self):
+        self.states = []
+        self.infos = []
+        self.stream_ends = 0
+
+    def on_thinking_start(self):
+        pass
+
+    def on_thinking_stop(self):
+        pass
+
+    def on_reasoning_token(self, text):
+        pass
+
+    def on_content_token(self, text):
+        pass
+
+    def on_stream_end(self):
+        self.stream_ends += 1
+
+    def approve_tools(self, items):
+        return True, None
+
+    def on_tool_result(self, call_id, name, output):
+        pass
+
+    def on_tool_output_chunk(self, call_id, chunk):
+        pass
+
+    def on_status(self, usage, context_window, effort):
+        pass
+
+    def on_plan_review(self, content):
+        return ""
+
+    def on_info(self, message):
+        self.infos.append(message)
+
+    def on_error(self, message):
+        pass
+
+    def on_state_change(self, state):
+        self.states.append(state)
+
+    def on_rename(self, name):
+        pass
+
+
+def _make_session(ui=None, **kwargs):
+    """Helper to construct a ChatSession with minimal setup."""
+    defaults = dict(
+        client=MagicMock(),
+        model="test-model",
+        ui=ui or NullUI(),
+        instructions=None,
+        temperature=0.5,
+        max_tokens=4096,
+        tool_timeout=30,
+    )
+    defaults.update(kwargs)
+    return ChatSession(**defaults)
+
+
+class TestCancelEvent:
+    """Basic cancel event mechanics."""
+
+    def test_cancel_sets_event(self, tmp_db):
+        session = _make_session()
+        assert not session._cancel_event.is_set()
+        session.cancel()
+        assert session._cancel_event.is_set()
+
+    def test_check_cancelled_raises_when_set(self, tmp_db):
+        session = _make_session()
+        session.cancel()
+        with pytest.raises(GenerationCancelled):
+            session._check_cancelled()
+
+    def test_check_cancelled_noop_when_clear(self, tmp_db):
+        session = _make_session()
+        session._check_cancelled()  # Should not raise
+
+    def test_cancel_is_idempotent(self, tmp_db):
+        session = _make_session()
+        session.cancel()
+        session.cancel()  # Double call is harmless
+        assert session._cancel_event.is_set()
+
+    def test_cancel_event_cleared_on_send_start(self, tmp_db):
+        """send() clears a stale cancel flag before starting."""
+        ui = NullUI()
+        session = _make_session(ui=ui)
+        session.cancel()  # Set stale flag
+
+        @dataclass
+        class FakeChunk:
+            content_delta: str = ""
+            reasoning_delta: str = ""
+            tool_call_deltas: list = field(default_factory=list)
+            usage: None = None
+            finish_reason: str = "stop"
+            info_delta: str = ""
+            provider_blocks: list = field(default_factory=list)
+
+        fake_stream = iter([FakeChunk(content_delta="Hello", finish_reason="stop")])
+
+        with (
+            patch.object(session, "_create_stream_with_retry", return_value=fake_stream),
+            patch.object(session, "_full_messages", return_value=[]),
+        ):
+            session.send("test")
+
+        # Should complete normally — cancel flag was cleared
+        assert "idle" in ui.states
+
+
+class TestCancelDuringStreaming:
+    """Cancel while _stream_response is iterating chunks."""
+
+    def test_preserves_partial_content(self, tmp_db):
+        """Partial content already streamed should be preserved in messages."""
+        ui = NullUI()
+        session = _make_session(ui=ui)
+
+        @dataclass
+        class FakeChunk:
+            content_delta: str = ""
+            reasoning_delta: str = ""
+            tool_call_deltas: list = field(default_factory=list)
+            usage: None = None
+            finish_reason: str = ""
+            info_delta: str = ""
+            provider_blocks: list = field(default_factory=list)
+
+        def cancelling_stream():
+            """Yield a few chunks then cancel."""
+            yield FakeChunk(content_delta="Hello ")
+            yield FakeChunk(content_delta="world")
+            session.cancel()
+            yield FakeChunk(content_delta=" — this should not appear")
+
+        with (
+            patch.object(session, "_create_stream_with_retry", return_value=cancelling_stream()),
+            patch.object(session, "_full_messages", return_value=[]),
+        ):
+            session.send("test")
+
+        # Session should be idle (not error)
+        assert ui.states[-1] == "idle"
+        # Check that "[Generation cancelled]" was emitted
+        assert any("cancelled" in i.lower() for i in ui.infos)
+        # The partial content should be preserved as an assistant message
+        assistant_msgs = [m for m in session.messages if m["role"] == "assistant"]
+        assert len(assistant_msgs) == 1
+        assert assistant_msgs[0]["content"] == "Hello world"
+        # No tool_calls in the partial message
+        assert "tool_calls" not in assistant_msgs[0]
+
+
+class TestCancelDuringToolExecution:
+    """Cancel while tools are being executed."""
+
+    def test_rollback_incomplete_tool_results(self, tmp_db):
+        """When cancelled during tool execution, incomplete results are rolled back."""
+        ui = NullUI()
+        session = _make_session(ui=ui)
+
+        @dataclass
+        class FakeChunk:
+            content_delta: str = ""
+            reasoning_delta: str = ""
+            tool_call_deltas: list = field(default_factory=list)
+            usage: None = None
+            finish_reason: str = ""
+            info_delta: str = ""
+            provider_blocks: list = field(default_factory=list)
+
+        @dataclass
+        class FakeToolDelta:
+            index: int = 0
+            id: str = ""
+            name: str = ""
+            arguments_delta: str = ""
+
+        # First call: return content with a tool call
+        def stream_with_tool():
+            yield FakeChunk(
+                tool_call_deltas=[FakeToolDelta(index=0, id="tc_1", name="bash")],
+                finish_reason="",
+            )
+            yield FakeChunk(
+                tool_call_deltas=[FakeToolDelta(index=0, arguments_delta='{"command":"echo hi"}')],
+                finish_reason="tool_calls",
+            )
+
+        call_count = 0
+
+        def fake_create_stream(msgs):
+            nonlocal call_count
+            call_count += 1
+            if call_count == 1:
+                return stream_with_tool()
+            # Should not be called a second time since cancel happens before phase 3
+            raise AssertionError("Should not stream again after cancel")
+
+        def cancel_before_execute(tool_calls):
+            """Simulate cancel happening before tool execution."""
+            session.cancel()
+            raise GenerationCancelled()
+
+        with (
+            patch.object(session, "_create_stream_with_retry", side_effect=fake_create_stream),
+            patch.object(session, "_full_messages", return_value=[]),
+            patch.object(session, "_execute_tools", side_effect=cancel_before_execute),
+        ):
+            session.send("run something")
+
+        # Session should be idle
+        assert ui.states[-1] == "idle"
+        # No tool result messages should remain (rolled back)
+        roles = [m["role"] for m in session.messages]
+        assert "tool" not in roles
+        # The assistant message with tool_calls should also be rolled back
+        for m in session.messages:
+            if m["role"] == "assistant":
+                assert "tool_calls" not in m or not m["tool_calls"]
+
+
+class TestCancelWhenIdle:
+    """Cancelling when no generation is active is harmless."""
+
+    def test_cancel_when_idle_is_noop(self, tmp_db):
+        session = _make_session()
+        session.cancel()
+        # Next send should work normally (cancel cleared at start)
+
+        @dataclass
+        class FakeChunk:
+            content_delta: str = ""
+            reasoning_delta: str = ""
+            tool_call_deltas: list = field(default_factory=list)
+            usage: None = None
+            finish_reason: str = "stop"
+            info_delta: str = ""
+            provider_blocks: list = field(default_factory=list)
+
+        fake_stream = iter([FakeChunk(content_delta="ok", finish_reason="stop")])
+        with (
+            patch.object(session, "_create_stream_with_retry", return_value=fake_stream),
+            patch.object(session, "_full_messages", return_value=[]),
+        ):
+            session.send("hello")
+
+        # Should complete normally
+        assistant_msgs = [m for m in session.messages if m["role"] == "assistant"]
+        assert len(assistant_msgs) == 1
+        assert assistant_msgs[0]["content"] == "ok"
+
+
+class TestCancelThreadSafety:
+    """Cancel from a different thread while generation is running."""
+
+    def test_cancel_from_another_thread(self, tmp_db):
+        ui = NullUI()
+        session = _make_session(ui=ui)
+
+        @dataclass
+        class FakeChunk:
+            content_delta: str = ""
+            reasoning_delta: str = ""
+            tool_call_deltas: list = field(default_factory=list)
+            usage: None = None
+            finish_reason: str = ""
+            info_delta: str = ""
+            provider_blocks: list = field(default_factory=list)
+
+        barrier = threading.Event()
+
+        def slow_stream():
+            yield FakeChunk(content_delta="Start")
+            barrier.set()  # Signal that streaming has started
+            time.sleep(2)  # Simulate slow streaming
+            yield FakeChunk(content_delta=" end", finish_reason="stop")
+
+        with (
+            patch.object(session, "_create_stream_with_retry", return_value=slow_stream()),
+            patch.object(session, "_full_messages", return_value=[]),
+        ):
+            # Run send() in a thread
+            error = []
+
+            def run():
+                try:
+                    session.send("test")
+                except Exception as e:
+                    error.append(e)
+
+            t = threading.Thread(target=run)
+            t.start()
+            barrier.wait(timeout=5)
+            # Cancel from main thread
+            session.cancel()
+            t.join(timeout=5)
+
+        assert not error
+        assert ui.states[-1] == "idle"
+        assert any("cancelled" in i.lower() for i in ui.infos)
+
+
+class TestGenerationCancelledException:
+    """GenerationCancelled is a BaseException, not Exception."""
+
+    def test_is_base_exception(self):
+        assert issubclass(GenerationCancelled, BaseException)
+
+    def test_not_caught_by_except_exception(self):
+        """Verify GenerationCancelled is NOT caught by except Exception."""
+        with pytest.raises(GenerationCancelled):
+            try:
+                raise GenerationCancelled()
+            except Exception:
+                pytest.fail("GenerationCancelled was caught by except Exception")
+
+
+class TestStreamFlushBeforeToolCalls:
+    """Content pending buffer must be flushed before tool call processing."""
+
+    def test_pending_content_flushed_before_tool_calls(self, tmp_db):
+        """All content tokens arrive via on_content_token before tool calls."""
+        events: list[tuple[str, ...]] = []
+
+        class TrackingUI(NullUI):
+            def on_content_token(self, text):
+                events.append(("content", text))
+
+            def on_stream_end(self):
+                events.append(("stream_end",))
+                super().on_stream_end()
+
+        ui = TrackingUI()
+        session = _make_session(ui=ui)
+
+        @dataclass
+        class FakeChunk:
+            content_delta: str = ""
+            reasoning_delta: str = ""
+            tool_call_deltas: list = field(default_factory=list)
+            usage: None = None
+            finish_reason: str = ""
+            info_delta: str = ""
+            provider_blocks: list = field(default_factory=list)
+
+        @dataclass
+        class FakeToolDelta:
+            index: int = 0
+            id: str = ""
+            name: str = ""
+            arguments_delta: str = ""
+
+        def stream_content_then_tool():
+            # Content long enough to leave chars in pending buffer
+            # (_MAX_TAG_LEN = 13, so _drain_pending retains last 13 chars)
+            yield FakeChunk(content_delta="Hello world, this is a test message")
+            yield FakeChunk(
+                tool_call_deltas=[FakeToolDelta(index=0, id="tc_1", name="bash")],
+            )
+            yield FakeChunk(
+                tool_call_deltas=[FakeToolDelta(index=0, arguments_delta='{"command":"echo hi"}')],
+                finish_reason="tool_calls",
+            )
+
+        with (
+            patch.object(
+                session,
+                "_create_stream_with_retry",
+                return_value=stream_content_then_tool(),
+            ),
+            patch.object(session, "_full_messages", return_value=[]),
+            # Prevent real tool execution (e.g., bash) during this test.
+            patch.object(session, "_execute_tools", return_value=([], None)),
+        ):
+            session.send("test")
+
+        # All content should have been emitted
+        total = "".join(e[1] for e in events if e[0] == "content")
+        assert total == "Hello world, this is a test message"
+
+        # No content events after stream_end
+        stream_end_idx = next(i for i, e in enumerate(events) if e[0] == "stream_end")
+        late_content = [e for e in events[stream_end_idx + 1 :] if e[0] == "content"]
+        assert late_content == [], f"Content after stream_end: {late_content}"

tests/test_channel_discord.py

@@ -312,6 +312,59 @@ class TestParseFooter:
 # ---------------------------------------------------------------------------
 
 
+class TestWsEventFinalization:
+    """TurnCompleteEvent should finalize streaming messages in the Discord bot."""
+
+    def test_turn_complete_finalizes_streaming(self):
+        """ContentEvent + TurnCompleteEvent(correlation_id='') finalizes the message."""
+        from turnstone.channels.discord.bot import TurnstoneBot
+        from turnstone.mq.protocol import ContentEvent, TurnCompleteEvent
+
+        bot = MagicMock(spec=TurnstoneBot)
+        bot.config = MagicMock()
+        bot.config.max_message_length = 2000
+        bot.config.streaming_edit_interval = 1.5
+        bot.config.auto_approve = False
+        bot.config.auto_approve_tools = []
+        bot._streaming = {}
+
+        # Use the real _on_ws_event method
+        bot._on_ws_event = TurnstoneBot._on_ws_event.__get__(bot, TurnstoneBot)
+
+        thread = AsyncMock()
+
+        # Feed content event
+        content_raw = ContentEvent(ws_id="ws-1", text="Hello world").to_json()
+        _run(bot._on_ws_event("ws-1", thread, content_raw))
+
+        # StreamingMessage should exist
+        assert "ws-1" in bot._streaming
+
+        # Feed turn complete with empty correlation_id (server-UI-initiated)
+        complete_raw = TurnCompleteEvent(ws_id="ws-1", correlation_id="").to_json()
+        _run(bot._on_ws_event("ws-1", thread, complete_raw))
+
+        # StreamingMessage should be removed and finalized
+        assert "ws-1" not in bot._streaming
+
+    def test_turn_complete_no_streaming_is_noop(self):
+        """TurnCompleteEvent without prior content should not error."""
+        from turnstone.channels.discord.bot import TurnstoneBot
+        from turnstone.mq.protocol import TurnCompleteEvent
+
+        bot = MagicMock(spec=TurnstoneBot)
+        bot._streaming = {}
+        bot._on_ws_event = TurnstoneBot._on_ws_event.__get__(bot, TurnstoneBot)
+
+        thread = AsyncMock()
+
+        complete_raw = TurnCompleteEvent(ws_id="ws-1", correlation_id="").to_json()
+        _run(bot._on_ws_event("ws-1", thread, complete_raw))
+
+        # No error, no streaming message
+        assert "ws-1" not in bot._streaming
+
+
 class TestChannelCLI:
     """Tests for the channel CLI entry point."""
 

tests/test_console.py

@@ -1,5 +1,6 @@
 """Tests for turnstone.console — collector and HTTP server."""
 
+import asyncio
 import json
 import queue
 from unittest.mock import MagicMock
@@ -201,6 +202,68 @@ class TestCollectorPolling:
         # Should not raise
         c._apply_poll("unknown", _dashboard_response(), {})
 
+    def test_apply_poll_emits_ws_created_for_new_workstream(self):
+        c = _make_collector()
+        c._nodes["node-a"] = NodeSnapshot(node_id="node-a", server_url="http://a:8080")
+        q: queue.Queue[dict] = queue.Queue()
+        c.register_listener(q)
+
+        dashboard = _dashboard_response(
+            workstreams=[{"id": "ws1", "name": "new-task", "state": "idle"}]
+        )
+        c._apply_poll("node-a", dashboard, {})
+
+        event = q.get_nowait()
+        assert event["type"] == "ws_created"
+        assert event["ws_id"] == "ws1"
+        assert event["name"] == "new-task"
+        assert event["node_id"] == "node-a"
+
+    def test_apply_poll_emits_ws_closed_for_removed_workstream(self):
+        c = _make_collector()
+        c._nodes["node-a"] = NodeSnapshot(
+            node_id="node-a",
+            server_url="http://a:8080",
+            workstreams={"ws1": {"id": "ws1", "name": "old", "state": "idle"}},
+        )
+        q: queue.Queue[dict] = queue.Queue()
+        c.register_listener(q)
+
+        c._apply_poll("node-a", _dashboard_response(), {})
+
+        event = q.get_nowait()
+        assert event["type"] == "ws_closed"
+        assert event["ws_id"] == "ws1"
+
+    def test_apply_poll_no_events_when_unchanged(self):
+        c = _make_collector()
+        c._nodes["node-a"] = NodeSnapshot(
+            node_id="node-a",
+            server_url="http://a:8080",
+            workstreams={"ws1": {"id": "ws1", "name": "same", "state": "idle"}},
+        )
+        q: queue.Queue[dict] = queue.Queue()
+        c.register_listener(q)
+
+        dashboard = _dashboard_response(
+            workstreams=[{"id": "ws1", "name": "same", "state": "running"}]
+        )
+        c._apply_poll("node-a", dashboard, {})
+
+        assert q.empty()
+
+    def test_apply_poll_skips_empty_id_workstream(self):
+        c = _make_collector()
+        c._nodes["node-a"] = NodeSnapshot(node_id="node-a", server_url="http://a:8080")
+        q: queue.Queue[dict] = queue.Queue()
+        c.register_listener(q)
+
+        dashboard = _dashboard_response(workstreams=[{"name": "no-id", "state": "idle"}])
+        c._apply_poll("node-a", dashboard, {})
+
+        assert q.empty()
+        assert len(c._nodes["node-a"].workstreams) == 0
+
 
 class TestCollectorEvents:
     """Real-time event handling from cluster channel."""
@@ -445,6 +508,44 @@ class TestCollectorQueries:
     def test_get_node_detail_not_found(self, populated_collector):
         assert populated_collector.get_node_detail("nonexistent") is None
 
+    def test_get_snapshot_empty(self):
+        c = _make_collector()
+        snap = c.get_snapshot()
+        assert snap["nodes"] == []
+        assert snap["overview"]["nodes"] == 0
+        assert snap["overview"]["workstreams"] == 0
+        assert snap["overview"]["states"]["running"] == 0
+        assert "timestamp" in snap
+
+    def test_get_snapshot_with_nodes(self, populated_collector):
+        snap = populated_collector.get_snapshot()
+        assert len(snap["nodes"]) == 2
+        assert snap["overview"]["nodes"] == 2
+        assert snap["overview"]["workstreams"] == 3
+        assert snap["overview"]["states"]["running"] == 1
+        assert snap["overview"]["states"]["attention"] == 1
+        assert snap["overview"]["states"]["idle"] == 1
+        assert snap["overview"]["aggregate"]["total_tokens"] == 17000
+        assert snap["timestamp"] > 0
+        # Each node should embed its workstreams
+        node_ids = {n["node_id"] for n in snap["nodes"]}
+        assert node_ids == {"node-a", "node-b"}
+        for n in snap["nodes"]:
+            if n["node_id"] == "node-a":
+                assert len(n["workstreams"]) == 2
+            elif n["node_id"] == "node-b":
+                assert len(n["workstreams"]) == 1
+
+    def test_get_snapshot_consistency(self, populated_collector):
+        """Snapshot overview should match get_overview()."""
+        snap = populated_collector.get_snapshot()
+        overview = populated_collector.get_overview()
+        assert snap["overview"]["nodes"] == overview["nodes"]
+        assert snap["overview"]["workstreams"] == overview["workstreams"]
+        assert snap["overview"]["states"] == overview["states"]
+        assert snap["overview"]["aggregate"] == overview["aggregate"]
+        assert snap["overview"]["version_drift"] == overview["version_drift"]
+
 
 # ---------------------------------------------------------------------------
 # ClusterStateEvent protocol tests
@@ -535,6 +636,31 @@ class TestConsoleHTTPEndpoints:
             "workstreams": [],
             "aggregate": {},
         }
+        collector.get_snapshot.return_value = {
+            "nodes": [
+                {
+                    "node_id": "node-a",
+                    "server_url": "http://a:8080",
+                    "max_ws": 10,
+                    "reachable": True,
+                    "version": "0.5.0",
+                    "health": {},
+                    "aggregate": {"total_tokens": 50000, "total_tool_calls": 200},
+                    "workstreams": [
+                        {"id": "ws1", "name": "test", "state": "running", "node": "node-a"},
+                    ],
+                },
+            ],
+            "overview": {
+                "nodes": 3,
+                "workstreams": 15,
+                "states": {"running": 5, "thinking": 2, "attention": 1, "idle": 6, "error": 1},
+                "aggregate": {"total_tokens": 50000, "total_tool_calls": 200},
+                "version_drift": False,
+                "versions": ["0.5.0"],
+            },
+            "timestamp": 1234567890.0,
+        }
         return collector
 
     @pytest.fixture()
@@ -614,6 +740,16 @@ class TestConsoleHTTPEndpoints:
         assert status == 404
         assert "error" in data
 
+    def test_get_snapshot(self, client, mock_collector):
+        status, data = self._get(client, "/v1/api/cluster/snapshot")
+        assert status == 200
+        assert len(data["nodes"]) == 1
+        assert data["nodes"][0]["node_id"] == "node-a"
+        assert data["overview"]["nodes"] == 3
+        assert data["overview"]["workstreams"] == 15
+        assert data["timestamp"] == 1234567890.0
+        mock_collector.get_snapshot.assert_called_once()
+
     def test_health_endpoint(self, client, mock_collector):
         status, data = self._get(client, "/health")
         assert status == 200
@@ -1299,3 +1435,243 @@ class TestProxySharedStatic:
         resp = client.get("/node/unknown/shared/base.css")
         assert resp.status_code == 404
         client.close()
+
+
+# ---------------------------------------------------------------------------
+# SSE proxy — raw byte passthrough
+# ---------------------------------------------------------------------------
+
+
+class TestSSEProxy:
+    """Verify _proxy_sse forwards raw bytes including ping comments."""
+
+    def test_proxy_sse_preserves_pings_and_events(self):
+        """SSE proxy should forward ping comments and events verbatim."""
+        from turnstone.console.server import _proxy_sse
+
+        # Simulate an upstream SSE response with a ping comment and a real event
+        sse_payload = b': ping - 2026-03-08T12:00:00Z\n\nevent: message\ndata: {"type": "test"}\n\n'
+
+        class FakeResponse:
+            status_code = 200
+            headers = {"content-type": "text/event-stream"}
+
+            async def aiter_bytes(self):
+                yield sse_payload
+
+            async def aclose(self):
+                pass
+
+            async def __aenter__(self):
+                return self
+
+            async def __aexit__(self, *args):
+                pass
+
+        class FakeClient:
+            def stream(self, method, url, **kwargs):
+                return FakeResponse()
+
+        class FakeRequest:
+            class url:  # noqa: N801
+                query = "ws_id=test123"
+
+            class app:  # noqa: N801
+                class state:  # noqa: N801
+                    proxy_sse_client = FakeClient()
+                    proxy_auth_token = ""
+
+            headers = {}
+
+            async def is_disconnected(self):
+                return False
+
+        async def _run():
+            response = await _proxy_sse(
+                FakeRequest(), "http://fake:8080", "events", api_prefix="v1/api"
+            )
+            assert response.media_type == "text/event-stream"
+            # Collect the streamed bytes
+            chunks: list[bytes] = []
+            async for chunk in response.body_iterator:
+                chunks.append(chunk if isinstance(chunk, bytes) else chunk.encode())
+            body = b"".join(chunks)
+            # Ping comment must be preserved (not filtered)
+            assert b": ping" in body
+            # Real event must be preserved
+            assert b"event: message" in body
+            assert b'"type": "test"' in body
+
+        asyncio.run(_run())
+
+    def test_proxy_sse_upstream_error_status(self):
+        """Non-200 upstream status should yield an error event."""
+
+        from turnstone.console.server import _proxy_sse
+
+        class FakeResponse:
+            status_code = 502
+
+            async def aiter_bytes(self):
+                return
+                yield  # make it an async generator
+
+            async def aclose(self):
+                pass
+
+            async def __aenter__(self):
+                return self
+
+            async def __aexit__(self, *args):
+                pass
+
+        class FakeClient:
+            def stream(self, method, url, **kwargs):
+                return FakeResponse()
+
+        class FakeRequest:
+            class url:  # noqa: N801
+                query = ""
+
+            class app:  # noqa: N801
+                class state:  # noqa: N801
+                    proxy_sse_client = FakeClient()
+                    proxy_auth_token = ""
+
+            headers = {}
+
+            async def is_disconnected(self):
+                return False
+
+        async def _run():
+            response = await _proxy_sse(FakeRequest(), "http://fake:8080", "events")
+            chunks: list[bytes] = []
+            async for chunk in response.body_iterator:
+                chunks.append(chunk if isinstance(chunk, bytes) else chunk.encode())
+            body = b"".join(chunks)
+            assert b"event: error" in body
+            assert b"502" in body
+
+        asyncio.run(_run())
+
+    def test_proxy_sse_disconnect_handling(self):
+        """Proxy should stop when browser disconnects."""
+
+        from turnstone.console.server import _proxy_sse
+
+        class FakeResponse:
+            status_code = 200
+
+            async def aiter_bytes(self):
+                yield b"data: chunk1\n\n"
+                yield b"data: chunk2\n\n"  # should not be reached
+                yield b"data: chunk3\n\n"
+
+            async def aclose(self):
+                pass
+
+            async def __aenter__(self):
+                return self
+
+            async def __aexit__(self, *args):
+                pass
+
+        class FakeClient:
+            def stream(self, method, url, **kwargs):
+                return FakeResponse()
+
+        call_count = 0
+
+        class FakeRequest:
+            class url:  # noqa: N801
+                query = ""
+
+            class app:  # noqa: N801
+                class state:  # noqa: N801
+                    proxy_sse_client = FakeClient()
+                    proxy_auth_token = ""
+
+            headers = {}
+
+            async def is_disconnected(self):
+                nonlocal call_count
+                call_count += 1
+                return call_count > 1  # disconnect after first chunk
+
+        async def _run():
+            response = await _proxy_sse(FakeRequest(), "http://fake:8080", "events")
+            chunks: list[bytes] = []
+            async for chunk in response.body_iterator:
+                chunks.append(chunk if isinstance(chunk, bytes) else chunk.encode())
+            body = b"".join(chunks)
+            assert b"chunk1" in body
+            # Should have stopped before chunk3
+            assert b"chunk3" not in body
+
+        asyncio.run(_run())
+
+
+# ---------------------------------------------------------------------------
+# Collector — MCP aggregation in get_overview()
+# ---------------------------------------------------------------------------
+
+
+class TestCollectorMCPAggregation:
+    """Verify MCP server/resource/prompt aggregation in overview and snapshot."""
+
+    def test_overview_mcp_aggregation(self):
+        """Two nodes with MCP data produce correct sums in the overview."""
+        c = _make_collector()
+        c._nodes["node-a"] = NodeSnapshot(
+            node_id="node-a",
+            server_url="http://a:8080",
+            health={"mcp": {"servers": 2, "resources": 5, "prompts": 3}},
+        )
+        c._nodes["node-b"] = NodeSnapshot(
+            node_id="node-b",
+            server_url="http://b:8080",
+            health={"mcp": {"servers": 1, "resources": 4, "prompts": 2}},
+        )
+
+        overview = c.get_overview()
+        assert overview["mcp_servers"] == 3
+        assert overview["mcp_resources"] == 9
+        assert overview["mcp_prompts"] == 5
+
+    def test_overview_mcp_absent_when_zero(self):
+        """Nodes without MCP data produce no mcp_servers key in the overview."""
+        c = _make_collector()
+        c._nodes["node-a"] = NodeSnapshot(
+            node_id="node-a",
+            server_url="http://a:8080",
+            health={"status": "ok"},
+        )
+        c._nodes["node-b"] = NodeSnapshot(
+            node_id="node-b",
+            server_url="http://b:8080",
+            health={},
+        )
+
+        overview = c.get_overview()
+        assert "mcp_servers" not in overview
+        assert "mcp_resources" not in overview
+        assert "mcp_prompts" not in overview
+
+    def test_overview_mcp_mixed_nodes(self):
+        """One node with MCP, one without — only the MCP node contributes."""
+        c = _make_collector()
+        c._nodes["node-a"] = NodeSnapshot(
+            node_id="node-a",
+            server_url="http://a:8080",
+            health={"mcp": {"servers": 3, "resources": 10, "prompts": 7}},
+        )
+        c._nodes["node-b"] = NodeSnapshot(
+            node_id="node-b",
+            server_url="http://b:8080",
+            health={"status": "ok"},
+        )
+
+        overview = c.get_overview()
+        assert overview["mcp_servers"] == 3
+        assert overview["mcp_resources"] == 10
+        assert overview["mcp_prompts"] == 7

tests/test_governance_endpoints.py

@@ -0,0 +1,761 @@
+"""Tests for governance admin API endpoints (roles, orgs, policies, templates, usage, audit)."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import pytest
+from starlette.applications import Starlette
+from starlette.middleware import Middleware
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.routing import Mount, Route
+from starlette.testclient import TestClient
+
+if TYPE_CHECKING:
+    from starlette.requests import Request
+    from starlette.responses import Response
+
+from turnstone.console.server import (
+    admin_assign_role,
+    admin_audit,
+    admin_create_policy,
+    admin_create_role,
+    admin_create_template,
+    admin_delete_policy,
+    admin_delete_role,
+    admin_delete_template,
+    admin_delete_user,
+    admin_get_org,
+    admin_list_orgs,
+    admin_list_policies,
+    admin_list_roles,
+    admin_list_templates,
+    admin_list_user_roles,
+    admin_unassign_role,
+    admin_update_org,
+    admin_update_policy,
+    admin_update_role,
+    admin_update_template,
+    admin_usage,
+)
+from turnstone.core.auth import AuthResult
+from turnstone.core.storage._sqlite import SQLiteBackend
+
+# ---------------------------------------------------------------------------
+# Auth bypass middleware — injects a full-access AuthResult on every request.
+# ---------------------------------------------------------------------------
+
+
+class _InjectAuthMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next: Any) -> Response:
+        request.state.auth_result = AuthResult(
+            user_id="test-admin",
+            scopes=frozenset({"approve"}),
+            token_source="config",
+            permissions=frozenset(
+                {
+                    "read",
+                    "write",
+                    "approve",
+                    "admin.roles",
+                    "admin.users",
+                    "admin.orgs",
+                    "admin.policies",
+                    "admin.templates",
+                    "admin.usage",
+                    "admin.audit",
+                    "admin.schedules",
+                    "admin.watches",
+                    "tools.approve",
+                    "workstreams.create",
+                    "workstreams.close",
+                }
+            ),
+        )
+        return await call_next(request)
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def storage(tmp_path):
+    """Fresh SQLite backend for each test, seeded with test users."""
+    backend = SQLiteBackend(str(tmp_path / "test.db"))
+    # Seed users required by role assignment tests
+    backend.create_user("test-admin", "testadmin", "Test Admin", "hash")
+    backend.create_user("user-1", "user1", "User One", "hash")
+    return backend
+
+
+@pytest.fixture
+def client(storage):
+    """TestClient with storage and auth bypassed."""
+    app = Starlette(
+        routes=[
+            Mount(
+                "/v1",
+                routes=[
+                    # Roles
+                    Route("/api/admin/roles", admin_list_roles),
+                    Route("/api/admin/roles", admin_create_role, methods=["POST"]),
+                    Route("/api/admin/roles/{role_id}", admin_update_role, methods=["PUT"]),
+                    Route("/api/admin/roles/{role_id}", admin_delete_role, methods=["DELETE"]),
+                    # Users
+                    Route(
+                        "/api/admin/users/{user_id}",
+                        admin_delete_user,
+                        methods=["DELETE"],
+                    ),
+                    # User-role assignments
+                    Route("/api/admin/users/{user_id}/roles", admin_list_user_roles),
+                    Route(
+                        "/api/admin/users/{user_id}/roles",
+                        admin_assign_role,
+                        methods=["POST"],
+                    ),
+                    Route(
+                        "/api/admin/users/{user_id}/roles/{role_id}",
+                        admin_unassign_role,
+                        methods=["DELETE"],
+                    ),
+                    # Orgs
+                    Route("/api/admin/orgs", admin_list_orgs),
+                    Route("/api/admin/orgs/{org_id}", admin_get_org),
+                    Route("/api/admin/orgs/{org_id}", admin_update_org, methods=["PUT"]),
+                    # Policies
+                    Route("/api/admin/policies", admin_list_policies),
+                    Route("/api/admin/policies", admin_create_policy, methods=["POST"]),
+                    Route(
+                        "/api/admin/policies/{policy_id}",
+                        admin_update_policy,
+                        methods=["PUT"],
+                    ),
+                    Route(
+                        "/api/admin/policies/{policy_id}",
+                        admin_delete_policy,
+                        methods=["DELETE"],
+                    ),
+                    # Templates
+                    Route("/api/admin/templates", admin_list_templates),
+                    Route("/api/admin/templates", admin_create_template, methods=["POST"]),
+                    Route(
+                        "/api/admin/templates/{template_id}",
+                        admin_update_template,
+                        methods=["PUT"],
+                    ),
+                    Route(
+                        "/api/admin/templates/{template_id}",
+                        admin_delete_template,
+                        methods=["DELETE"],
+                    ),
+                    # Usage & Audit
+                    Route("/api/admin/usage", admin_usage),
+                    Route("/api/admin/audit", admin_audit),
+                ],
+            ),
+        ],
+        middleware=[Middleware(_InjectAuthMiddleware)],
+    )
+    app.state.auth_storage = storage
+    return TestClient(app)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _role_payload(**overrides: Any) -> dict[str, Any]:
+    defaults: dict[str, Any] = {
+        "name": "analyst",
+        "display_name": "Data Analyst",
+        "permissions": "read,write",
+    }
+    defaults.update(overrides)
+    return defaults
+
+
+def _policy_payload(**overrides: Any) -> dict[str, Any]:
+    defaults: dict[str, Any] = {
+        "name": "Allow bash",
+        "tool_pattern": "bash_*",
+        "action": "allow",
+        "priority": 10,
+    }
+    defaults.update(overrides)
+    return defaults
+
+
+def _template_payload(**overrides: Any) -> dict[str, Any]:
+    defaults: dict[str, Any] = {
+        "name": "Greeting",
+        "content": "Hello {{user}}, how can I help?",
+        "category": "system",
+    }
+    defaults.update(overrides)
+    return defaults
+
+
+# ---------------------------------------------------------------------------
+# Tests — Roles
+# ---------------------------------------------------------------------------
+
+
+class TestRoles:
+    def test_list_empty(self, client):
+        resp = client.get("/v1/api/admin/roles")
+        assert resp.status_code == 200
+        assert resp.json()["roles"] == []
+
+    def test_create_role(self, client):
+        resp = client.post("/v1/api/admin/roles", json=_role_payload())
+        assert resp.status_code == 200
+        role = resp.json()
+        assert role["name"] == "analyst"
+        assert role["display_name"] == "Data Analyst"
+        assert role["permissions"] == "read,write"
+        assert role["builtin"] is False
+        assert "role_id" in role
+        assert "created" in role
+
+    def test_create_role_missing_name(self, client):
+        resp = client.post("/v1/api/admin/roles", json=_role_payload(name=""))
+        assert resp.status_code == 400
+        assert "name" in resp.json()["error"].lower()
+
+    def test_create_role_invalid_name(self, client):
+        resp = client.post("/v1/api/admin/roles", json=_role_payload(name="bad name!@#"))
+        assert resp.status_code == 400
+        assert "name" in resp.json()["error"].lower()
+
+    def test_create_role_default_display_name(self, client):
+        resp = client.post(
+            "/v1/api/admin/roles",
+            json={"name": "ops", "permissions": ""},
+        )
+        assert resp.status_code == 200
+        role = resp.json()
+        # display_name defaults to name when not provided
+        assert role["display_name"] == "ops"
+
+    def test_list_after_create(self, client):
+        client.post("/v1/api/admin/roles", json=_role_payload())
+        resp = client.get("/v1/api/admin/roles")
+        assert resp.status_code == 200
+        roles = resp.json()["roles"]
+        assert len(roles) == 1
+        assert roles[0]["name"] == "analyst"
+
+    def test_update_role(self, client):
+        create_resp = client.post("/v1/api/admin/roles", json=_role_payload())
+        role_id = create_resp.json()["role_id"]
+
+        resp = client.put(
+            f"/v1/api/admin/roles/{role_id}",
+            json={"display_name": "Senior Analyst", "permissions": "read,write,approve"},
+        )
+        assert resp.status_code == 200
+        role = resp.json()
+        assert role["display_name"] == "Senior Analyst"
+        assert role["permissions"] == "read,write,approve"
+
+    def test_update_nonexistent_role(self, client):
+        resp = client.put(
+            "/v1/api/admin/roles/nonexistent",
+            json={"display_name": "Nope"},
+        )
+        assert resp.status_code == 404
+
+    def test_update_builtin_role_rejected(self, client, storage):
+        # Seed a builtin role directly via storage
+        storage.create_role(
+            role_id="builtin-admin",
+            name="admin",
+            display_name="Administrator",
+            permissions="*",
+            builtin=True,
+        )
+        resp = client.put(
+            "/v1/api/admin/roles/builtin-admin",
+            json={"display_name": "Hacked"},
+        )
+        assert resp.status_code == 400
+        assert "builtin" in resp.json()["error"].lower()
+
+    def test_delete_role(self, client):
+        create_resp = client.post("/v1/api/admin/roles", json=_role_payload())
+        role_id = create_resp.json()["role_id"]
+
+        resp = client.delete(f"/v1/api/admin/roles/{role_id}")
+        assert resp.status_code == 200
+        assert resp.json()["status"] == "ok"
+
+        # Verify gone from listing
+        list_resp = client.get("/v1/api/admin/roles")
+        assert list_resp.json()["roles"] == []
+
+    def test_delete_nonexistent_role(self, client):
+        resp = client.delete("/v1/api/admin/roles/nonexistent")
+        assert resp.status_code == 404
+
+    def test_delete_builtin_role_rejected(self, client, storage):
+        storage.create_role(
+            role_id="builtin-viewer",
+            name="viewer",
+            display_name="Viewer",
+            permissions="read",
+            builtin=True,
+        )
+        resp = client.delete("/v1/api/admin/roles/builtin-viewer")
+        assert resp.status_code == 400
+        assert "builtin" in resp.json()["error"].lower()
+
+
+# ---------------------------------------------------------------------------
+# Tests — Role assignments
+# ---------------------------------------------------------------------------
+
+
+class TestRoleAssignments:
+    def test_list_user_roles_empty(self, client):
+        resp = client.get("/v1/api/admin/users/user-1/roles")
+        assert resp.status_code == 200
+        assert resp.json()["roles"] == []
+
+    def test_assign_role(self, client):
+        create_resp = client.post("/v1/api/admin/roles", json=_role_payload())
+        role_id = create_resp.json()["role_id"]
+
+        resp = client.post(
+            "/v1/api/admin/users/user-1/roles",
+            json={"role_id": role_id},
+        )
+        assert resp.status_code == 200
+        assert resp.json()["status"] == "ok"
+
+        # Verify listed
+        list_resp = client.get("/v1/api/admin/users/user-1/roles")
+        roles = list_resp.json()["roles"]
+        assert len(roles) >= 1
+
+    def test_assign_role_missing_role_id(self, client):
+        resp = client.post(
+            "/v1/api/admin/users/user-1/roles",
+            json={},
+        )
+        assert resp.status_code == 400
+        assert "role_id" in resp.json()["error"].lower()
+
+    def test_unassign_role(self, client):
+        create_resp = client.post("/v1/api/admin/roles", json=_role_payload())
+        role_id = create_resp.json()["role_id"]
+
+        # Assign first
+        client.post(
+            "/v1/api/admin/users/user-1/roles",
+            json={"role_id": role_id},
+        )
+
+        # Now unassign
+        resp = client.delete(f"/v1/api/admin/users/user-1/roles/{role_id}")
+        assert resp.status_code == 200
+        assert resp.json()["status"] == "ok"
+
+        # Verify removed
+        list_resp = client.get("/v1/api/admin/users/user-1/roles")
+        assert list_resp.json()["roles"] == []
+
+    def test_unassign_nonexistent(self, client):
+        resp = client.delete("/v1/api/admin/users/user-1/roles/nonexistent")
+        assert resp.status_code == 404
+
+
+# ---------------------------------------------------------------------------
+# Tests — Orgs
+# ---------------------------------------------------------------------------
+
+
+class TestOrgs:
+    def test_list_empty(self, client):
+        resp = client.get("/v1/api/admin/orgs")
+        assert resp.status_code == 200
+        assert resp.json()["orgs"] == []
+
+    def test_get_org(self, client, storage):
+        storage.create_org(
+            org_id="org-1",
+            name="acme",
+            display_name="Acme Corp",
+            settings='{"theme": "dark"}',
+        )
+        resp = client.get("/v1/api/admin/orgs/org-1")
+        assert resp.status_code == 200
+        org = resp.json()
+        assert org["org_id"] == "org-1"
+        assert org["name"] == "acme"
+        assert org["display_name"] == "Acme Corp"
+
+    def test_get_org_not_found(self, client):
+        resp = client.get("/v1/api/admin/orgs/nonexistent")
+        assert resp.status_code == 404
+
+    def test_update_org(self, client, storage):
+        storage.create_org(org_id="org-1", name="acme", display_name="Acme Corp")
+
+        resp = client.put(
+            "/v1/api/admin/orgs/org-1",
+            json={"display_name": "Acme Inc.", "settings": '{"theme": "light"}'},
+        )
+        assert resp.status_code == 200
+        org = resp.json()
+        assert org["display_name"] == "Acme Inc."
+        assert org["settings"] == '{"theme": "light"}'
+
+    def test_update_org_not_found(self, client):
+        resp = client.put(
+            "/v1/api/admin/orgs/nonexistent",
+            json={"display_name": "Nope"},
+        )
+        assert resp.status_code == 404
+
+
+# ---------------------------------------------------------------------------
+# Tests — Tool policies
+# ---------------------------------------------------------------------------
+
+
+class TestPolicies:
+    def test_list_empty(self, client):
+        resp = client.get("/v1/api/admin/policies")
+        assert resp.status_code == 200
+        assert resp.json()["policies"] == []
+
+    def test_create_policy(self, client):
+        resp = client.post("/v1/api/admin/policies", json=_policy_payload())
+        assert resp.status_code == 200
+        policy = resp.json()
+        assert policy["name"] == "Allow bash"
+        assert policy["tool_pattern"] == "bash_*"
+        assert policy["action"] == "allow"
+        assert policy["priority"] == 10
+        assert "policy_id" in policy
+        assert "created" in policy
+
+    def test_create_policy_missing_name(self, client):
+        resp = client.post("/v1/api/admin/policies", json=_policy_payload(name=""))
+        assert resp.status_code == 400
+        assert "name" in resp.json()["error"].lower()
+
+    def test_create_policy_missing_tool_pattern(self, client):
+        resp = client.post(
+            "/v1/api/admin/policies",
+            json=_policy_payload(tool_pattern=""),
+        )
+        assert resp.status_code == 400
+        assert "tool_pattern" in resp.json()["error"].lower()
+
+    def test_create_policy_invalid_action(self, client):
+        resp = client.post(
+            "/v1/api/admin/policies",
+            json=_policy_payload(action="yolo"),
+        )
+        assert resp.status_code == 400
+        assert "action" in resp.json()["error"].lower()
+
+    def test_list_after_create(self, client):
+        client.post("/v1/api/admin/policies", json=_policy_payload())
+        resp = client.get("/v1/api/admin/policies")
+        assert resp.status_code == 200
+        policies = resp.json()["policies"]
+        assert len(policies) == 1
+        assert policies[0]["name"] == "Allow bash"
+
+    def test_update_policy(self, client):
+        create_resp = client.post("/v1/api/admin/policies", json=_policy_payload())
+        policy_id = create_resp.json()["policy_id"]
+
+        resp = client.put(
+            f"/v1/api/admin/policies/{policy_id}",
+            json={"name": "Deny bash", "action": "deny", "priority": 20},
+        )
+        assert resp.status_code == 200
+        policy = resp.json()
+        assert policy["name"] == "Deny bash"
+        assert policy["action"] == "deny"
+        assert policy["priority"] == 20
+
+    def test_update_policy_invalid_action(self, client):
+        create_resp = client.post("/v1/api/admin/policies", json=_policy_payload())
+        policy_id = create_resp.json()["policy_id"]
+
+        resp = client.put(
+            f"/v1/api/admin/policies/{policy_id}",
+            json={"action": "nope"},
+        )
+        assert resp.status_code == 400
+        assert "action" in resp.json()["error"].lower()
+
+    def test_update_policy_not_found(self, client):
+        resp = client.put(
+            "/v1/api/admin/policies/nonexistent",
+            json={"name": "Nope"},
+        )
+        assert resp.status_code == 404
+
+    def test_delete_policy(self, client):
+        create_resp = client.post("/v1/api/admin/policies", json=_policy_payload())
+        policy_id = create_resp.json()["policy_id"]
+
+        resp = client.delete(f"/v1/api/admin/policies/{policy_id}")
+        assert resp.status_code == 200
+        assert resp.json()["status"] == "ok"
+
+        # Verify gone
+        list_resp = client.get("/v1/api/admin/policies")
+        assert list_resp.json()["policies"] == []
+
+    def test_delete_policy_not_found(self, client):
+        resp = client.delete("/v1/api/admin/policies/nonexistent")
+        assert resp.status_code == 404
+
+
+# ---------------------------------------------------------------------------
+# Tests — Prompt templates
+# ---------------------------------------------------------------------------
+
+
+class TestTemplates:
+    def test_list_empty(self, client):
+        resp = client.get("/v1/api/admin/templates")
+        assert resp.status_code == 200
+        assert resp.json()["templates"] == []
+
+    def test_create_template(self, client):
+        resp = client.post("/v1/api/admin/templates", json=_template_payload())
+        assert resp.status_code == 200
+        tmpl = resp.json()
+        assert tmpl["name"] == "Greeting"
+        assert "{{user}}" in tmpl["content"]
+        assert tmpl["category"] == "system"
+        assert "template_id" in tmpl
+        assert "created" in tmpl
+
+    def test_create_template_missing_name(self, client):
+        resp = client.post(
+            "/v1/api/admin/templates",
+            json=_template_payload(name=""),
+        )
+        assert resp.status_code == 400
+        assert "name" in resp.json()["error"].lower()
+
+    def test_create_template_missing_content(self, client):
+        resp = client.post(
+            "/v1/api/admin/templates",
+            json=_template_payload(content=""),
+        )
+        assert resp.status_code == 400
+        assert "content" in resp.json()["error"].lower()
+
+    def test_list_after_create(self, client):
+        client.post("/v1/api/admin/templates", json=_template_payload())
+        resp = client.get("/v1/api/admin/templates")
+        assert resp.status_code == 200
+        templates = resp.json()["templates"]
+        assert len(templates) == 1
+        assert templates[0]["name"] == "Greeting"
+
+    def test_update_template(self, client):
+        create_resp = client.post("/v1/api/admin/templates", json=_template_payload())
+        template_id = create_resp.json()["template_id"]
+
+        resp = client.put(
+            f"/v1/api/admin/templates/{template_id}",
+            json={"name": "Welcome", "content": "Welcome, {{user}}!", "is_default": True},
+        )
+        assert resp.status_code == 200
+        tmpl = resp.json()
+        assert tmpl["name"] == "Welcome"
+        assert tmpl["content"] == "Welcome, {{user}}!"
+        assert tmpl["is_default"] is True
+
+    def test_update_template_not_found(self, client):
+        resp = client.put(
+            "/v1/api/admin/templates/nonexistent",
+            json={"name": "Nope"},
+        )
+        assert resp.status_code == 404
+
+    def test_delete_template(self, client):
+        create_resp = client.post("/v1/api/admin/templates", json=_template_payload())
+        template_id = create_resp.json()["template_id"]
+
+        resp = client.delete(f"/v1/api/admin/templates/{template_id}")
+        assert resp.status_code == 200
+        assert resp.json()["status"] == "ok"
+
+        # Verify gone
+        list_resp = client.get("/v1/api/admin/templates")
+        assert list_resp.json()["templates"] == []
+
+    def test_delete_template_not_found(self, client):
+        resp = client.delete("/v1/api/admin/templates/nonexistent")
+        assert resp.status_code == 404
+
+
+# ---------------------------------------------------------------------------
+# Tests — Usage
+# ---------------------------------------------------------------------------
+
+
+class TestUsage:
+    def test_usage_defaults(self, client):
+        """Query usage with no params — should return summary and breakdown."""
+        resp = client.get("/v1/api/admin/usage")
+        assert resp.status_code == 200
+        data = resp.json()
+        assert "summary" in data
+        assert "breakdown" in data
+        # Summary is a list with at least one row
+        assert isinstance(data["summary"], list)
+        assert len(data["summary"]) >= 1
+        # All-zeros when no data
+        assert data["summary"][0]["prompt_tokens"] == 0
+
+    def test_usage_with_data(self, client, storage):
+        """Seed usage events and verify they appear in the query."""
+        storage.record_usage_event(
+            event_id="evt-1",
+            user_id="user-1",
+            model="gpt-5",
+            prompt_tokens=100,
+            completion_tokens=50,
+            tool_calls_count=2,
+        )
+        storage.record_usage_event(
+            event_id="evt-2",
+            user_id="user-1",
+            model="gpt-5",
+            prompt_tokens=200,
+            completion_tokens=75,
+            tool_calls_count=1,
+        )
+        resp = client.get("/v1/api/admin/usage")
+        assert resp.status_code == 200
+        summary = resp.json()["summary"]
+        assert summary[0]["prompt_tokens"] == 300
+        assert summary[0]["completion_tokens"] == 125
+        assert summary[0]["tool_calls_count"] == 3
+
+    def test_usage_with_filters(self, client, storage):
+        storage.record_usage_event(
+            event_id="evt-f1",
+            user_id="user-a",
+            model="gpt-5",
+            prompt_tokens=100,
+            completion_tokens=10,
+        )
+        storage.record_usage_event(
+            event_id="evt-f2",
+            user_id="user-b",
+            model="claude-4",
+            prompt_tokens=200,
+            completion_tokens=20,
+        )
+        resp = client.get("/v1/api/admin/usage?user_id=user-a")
+        assert resp.status_code == 200
+        summary = resp.json()["summary"]
+        assert summary[0]["prompt_tokens"] == 100
+
+        resp2 = client.get("/v1/api/admin/usage?model=claude-4")
+        assert resp2.status_code == 200
+        summary2 = resp2.json()["summary"]
+        assert summary2[0]["prompt_tokens"] == 200
+
+
+# ---------------------------------------------------------------------------
+# Tests — Audit
+# ---------------------------------------------------------------------------
+
+
+class TestAudit:
+    def test_audit_empty(self, client):
+        resp = client.get("/v1/api/admin/audit")
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["events"] == []
+        assert data["total"] == 0
+
+    def test_audit_populated_by_mutations(self, client):
+        """Creating a role should produce an audit event."""
+        client.post("/v1/api/admin/roles", json=_role_payload())
+
+        resp = client.get("/v1/api/admin/audit")
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["total"] >= 1
+        actions = [e["action"] for e in data["events"]]
+        assert "role.create" in actions
+
+    def test_audit_filter_by_action(self, client):
+        # Create a role and a policy to produce different audit actions
+        client.post("/v1/api/admin/roles", json=_role_payload())
+        client.post("/v1/api/admin/policies", json=_policy_payload())
+
+        resp = client.get("/v1/api/admin/audit?action=policy.create")
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["total"] >= 1
+        assert all(e["action"] == "policy.create" for e in data["events"])
+
+    def test_audit_filter_by_user_id(self, client):
+        client.post("/v1/api/admin/roles", json=_role_payload())
+
+        resp = client.get("/v1/api/admin/audit?user_id=test-admin")
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["total"] >= 1
+        assert all(e["user_id"] == "test-admin" for e in data["events"])
+
+    def test_audit_pagination(self, client):
+        # Create several resources to produce multiple audit events
+        for i in range(5):
+            client.post(
+                "/v1/api/admin/roles",
+                json=_role_payload(name=f"role-{i}"),
+            )
+
+        resp = client.get("/v1/api/admin/audit?limit=2&offset=0")
+        assert resp.status_code == 200
+        data = resp.json()
+        assert len(data["events"]) == 2
+        assert data["total"] >= 5
+
+        resp2 = client.get("/v1/api/admin/audit?limit=2&offset=2")
+        assert resp2.status_code == 200
+        data2 = resp2.json()
+        assert len(data2["events"]) == 2
+        # The two pages should not overlap
+        ids_page1 = {e["event_id"] for e in data["events"]}
+        ids_page2 = {e["event_id"] for e in data2["events"]}
+        assert ids_page1.isdisjoint(ids_page2)
+
+
+# ---------------------------------------------------------------------------
+# Tests — User self-deletion guard
+# ---------------------------------------------------------------------------
+
+
+class TestUserSelfDeletion:
+    def test_cannot_delete_self(self, client):
+        """Admin should not be able to delete their own account."""
+        resp = client.delete("/v1/api/admin/users/test-admin")
+        assert resp.status_code == 400
+        assert "own account" in resp.json()["error"].lower()
+
+    def test_can_delete_other_user(self, client):
+        resp = client.delete("/v1/api/admin/users/user-1")
+        assert resp.status_code == 200
+        assert resp.json()["status"] == "ok"

tests/test_governance_storage.py

@@ -0,0 +1,808 @@
+"""Tests for governance storage operations (SQLite backend).
+
+Covers RBAC roles, organizations, tool policies, prompt templates,
+usage events, and audit events.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+import pytest
+import sqlalchemy as sa
+
+from turnstone.core.storage._sqlite import SQLiteBackend
+
+
+@pytest.fixture()
+def db(tmp_path):
+    """Create a fresh SQLite backend for each test."""
+    return SQLiteBackend(str(tmp_path / "test.db"))
+
+
+# ---------------------------------------------------------------------------
+# Roles
+# ---------------------------------------------------------------------------
+
+
+class TestRoleCRUD:
+    def test_create_role(self, db):
+        db.create_role("r1", "editor", "Editor", "read,write", builtin=False, org_id="")
+        role = db.get_role("r1")
+        assert role is not None
+        assert role["role_id"] == "r1"
+        assert role["name"] == "editor"
+        assert role["display_name"] == "Editor"
+        assert role["permissions"] == "read,write"
+        assert role["builtin"] is False
+        assert role["org_id"] == ""
+        assert "created" in role
+        assert "updated" in role
+
+    def test_create_role_idempotent(self, db):
+        db.create_role("r1", "editor", "Editor", "read,write", builtin=False, org_id="")
+        # Second insert with same role_id should be silently ignored.
+        db.create_role("r1", "editor2", "Editor 2", "read", builtin=True, org_id="org1")
+        role = db.get_role("r1")
+        assert role is not None
+        # Original values preserved.
+        assert role["name"] == "editor"
+        assert role["display_name"] == "Editor"
+
+    def test_get_role_by_name(self, db):
+        db.create_role("r1", "editor", "Editor", "read,write", builtin=False, org_id="")
+        role = db.get_role_by_name("editor")
+        assert role is not None
+        assert role["role_id"] == "r1"
+
+    def test_get_role_by_name_nonexistent(self, db):
+        assert db.get_role_by_name("nope") is None
+
+    def test_list_roles(self, db):
+        db.create_role("r2", "beta", "Beta Role", "read", builtin=False, org_id="")
+        db.create_role("r1", "alpha", "Alpha Role", "write", builtin=False, org_id="")
+        roles = db.list_roles()
+        assert len(roles) == 2
+        # Ordered by name ascending.
+        assert roles[0]["name"] == "alpha"
+        assert roles[1]["name"] == "beta"
+
+    def test_list_roles_filter_org(self, db):
+        db.create_role("r1", "role_a", "A", "read", builtin=False, org_id="org1")
+        db.create_role("r2", "role_b", "B", "read", builtin=False, org_id="org2")
+        db.create_role("r3", "role_c", "C", "read", builtin=False, org_id="org1")
+        result = db.list_roles(org_id="org1")
+        assert len(result) == 2
+        assert {r["role_id"] for r in result} == {"r1", "r3"}
+
+    def test_update_role(self, db):
+        db.create_role("r1", "editor", "Editor", "read,write", builtin=False, org_id="")
+        ok = db.update_role("r1", permissions="read,write,approve", display_name="Senior Editor")
+        assert ok is True
+        role = db.get_role("r1")
+        assert role is not None
+        assert role["permissions"] == "read,write,approve"
+        assert role["display_name"] == "Senior Editor"
+
+    def test_update_role_nonexistent(self, db):
+        assert db.update_role("missing", permissions="read") is False
+
+    def test_delete_role(self, db):
+        db.create_role("r1", "editor", "Editor", "read", builtin=False, org_id="")
+        db.create_user("u1", "alice", "Alice", "$2b$hash")
+        db.assign_role("u1", "r1")
+        # Verify assignment exists.
+        assert len(db.list_user_roles("u1")) == 1
+        ok = db.delete_role("r1")
+        assert ok is True
+        assert db.get_role("r1") is None
+        # Cascade: user_roles for this role should be gone.
+        assert len(db.list_user_roles("u1")) == 0
+
+    def test_delete_role_nonexistent(self, db):
+        assert db.delete_role("missing") is False
+
+    def test_assign_role(self, db):
+        db.create_role("r1", "editor", "Editor", "read,write", builtin=False, org_id="")
+        db.create_user("u1", "alice", "Alice", "$2b$hash")
+        db.assign_role("u1", "r1", assigned_by="admin")
+        roles = db.list_user_roles("u1")
+        assert len(roles) == 1
+        assert roles[0]["role_id"] == "r1"
+        assert roles[0]["assigned_by"] == "admin"
+
+    def test_assign_role_idempotent(self, db):
+        db.create_role("r1", "editor", "Editor", "read,write", builtin=False, org_id="")
+        db.create_user("u1", "alice", "Alice", "$2b$hash")
+        db.assign_role("u1", "r1")
+        # Second assign should not raise.
+        db.assign_role("u1", "r1")
+        roles = db.list_user_roles("u1")
+        assert len(roles) == 1
+
+    def test_unassign_role(self, db):
+        db.create_role("r1", "editor", "Editor", "read,write", builtin=False, org_id="")
+        db.create_user("u1", "alice", "Alice", "$2b$hash")
+        db.assign_role("u1", "r1")
+        ok = db.unassign_role("u1", "r1")
+        assert ok is True
+        assert len(db.list_user_roles("u1")) == 0
+
+    def test_unassign_role_nonexistent(self, db):
+        assert db.unassign_role("u1", "r1") is False
+
+    def test_list_user_roles(self, db):
+        db.create_role("r1", "editor", "Editor", "read,write", builtin=False, org_id="")
+        db.create_role("r2", "viewer", "Viewer", "read", builtin=True, org_id="")
+        db.create_user("u1", "alice", "Alice", "$2b$hash")
+        db.assign_role("u1", "r1", assigned_by="admin")
+        db.assign_role("u1", "r2", assigned_by="system")
+        roles = db.list_user_roles("u1")
+        assert len(roles) == 2
+        # Each entry should have joined role fields plus assignment metadata.
+        for r in roles:
+            assert "role_id" in r
+            assert "name" in r
+            assert "permissions" in r
+            assert "assigned_by" in r
+            assert "assignment_created" in r
+
+    def test_get_user_permissions(self, db):
+        db.create_role("r1", "editor", "Editor", "read,write", builtin=False, org_id="")
+        db.create_role("r2", "approver", "Approver", "approve,read", builtin=False, org_id="")
+        db.create_user("u1", "alice", "Alice", "$2b$hash")
+        db.assign_role("u1", "r1")
+        db.assign_role("u1", "r2")
+        perms = db.get_user_permissions("u1")
+        assert perms == {"read", "write", "approve"}
+
+    def test_get_user_permissions_no_roles(self, db):
+        db.create_user("u1", "alice", "Alice", "$2b$hash")
+        assert db.get_user_permissions("u1") == set()
+
+
+# ---------------------------------------------------------------------------
+# Organizations
+# ---------------------------------------------------------------------------
+
+
+class TestOrgCRUD:
+    def test_create_org(self, db):
+        db.create_org("org1", "acme", "Acme Corp", '{"plan":"pro"}')
+        org = db.get_org("org1")
+        assert org is not None
+        assert org["org_id"] == "org1"
+        assert org["name"] == "acme"
+        assert org["display_name"] == "Acme Corp"
+        assert org["settings"] == '{"plan":"pro"}'
+        assert "created" in org
+        assert "updated" in org
+
+    def test_get_org_nonexistent(self, db):
+        assert db.get_org("nope") is None
+
+    def test_create_org_idempotent(self, db):
+        db.create_org("org1", "acme", "Acme Corp")
+        db.create_org("org1", "acme2", "Acme 2")
+        org = db.get_org("org1")
+        assert org is not None
+        assert org["name"] == "acme"
+
+    def test_list_orgs(self, db):
+        db.create_org("o2", "beta", "Beta Inc")
+        db.create_org("o1", "alpha", "Alpha LLC")
+        orgs = db.list_orgs()
+        assert len(orgs) == 2
+        # Ordered by name ascending.
+        assert orgs[0]["name"] == "alpha"
+        assert orgs[1]["name"] == "beta"
+
+    def test_update_org(self, db):
+        db.create_org("org1", "acme", "Acme Corp")
+        ok = db.update_org(
+            "org1", display_name="Acme Corp Global", settings='{"plan":"enterprise"}'
+        )
+        assert ok is True
+        org = db.get_org("org1")
+        assert org is not None
+        assert org["display_name"] == "Acme Corp Global"
+        assert org["settings"] == '{"plan":"enterprise"}'
+
+    def test_update_org_nonexistent(self, db):
+        assert db.update_org("missing", display_name="X") is False
+
+
+# ---------------------------------------------------------------------------
+# Tool Policies
+# ---------------------------------------------------------------------------
+
+
+class TestToolPolicyCRUD:
+    def test_create_tool_policy(self, db):
+        db.create_tool_policy(
+            "p1",
+            "deny-bash",
+            "bash*",
+            "deny",
+            priority=100,
+            org_id="org1",
+            enabled=True,
+            created_by="admin",
+        )
+        pol = db.get_tool_policy("p1")
+        assert pol is not None
+        assert pol["policy_id"] == "p1"
+        assert pol["name"] == "deny-bash"
+        assert pol["tool_pattern"] == "bash*"
+        assert pol["action"] == "deny"
+        assert pol["priority"] == 100
+        assert pol["org_id"] == "org1"
+        assert pol["enabled"] is True
+        assert pol["created_by"] == "admin"
+
+    def test_get_tool_policy_nonexistent(self, db):
+        assert db.get_tool_policy("missing") is None
+
+    def test_list_tool_policies_ordered_by_priority(self, db):
+        db.create_tool_policy("p1", "low", "*", "allow", priority=10)
+        db.create_tool_policy("p2", "high", "*", "deny", priority=100)
+        db.create_tool_policy("p3", "mid", "*", "ask", priority=50)
+        policies = db.list_tool_policies()
+        assert len(policies) == 3
+        # DESC priority order.
+        assert policies[0]["priority"] == 100
+        assert policies[1]["priority"] == 50
+        assert policies[2]["priority"] == 10
+
+    def test_update_tool_policy(self, db):
+        db.create_tool_policy("p1", "deny-bash", "bash*", "deny", priority=100)
+        ok = db.update_tool_policy("p1", action="allow", priority=50)
+        assert ok is True
+        pol = db.get_tool_policy("p1")
+        assert pol is not None
+        assert pol["action"] == "allow"
+        assert pol["priority"] == 50
+
+    def test_update_tool_policy_nonexistent(self, db):
+        assert db.update_tool_policy("missing", action="deny") is False
+
+    def test_delete_tool_policy(self, db):
+        db.create_tool_policy("p1", "deny-bash", "bash*", "deny", priority=100)
+        ok = db.delete_tool_policy("p1")
+        assert ok is True
+        assert db.get_tool_policy("p1") is None
+
+    def test_delete_tool_policy_nonexistent(self, db):
+        assert db.delete_tool_policy("missing") is False
+
+    def test_enabled_as_bool(self, db):
+        db.create_tool_policy("p1", "on", "*", "allow", priority=0, enabled=True)
+        db.create_tool_policy("p2", "off", "*", "deny", priority=0, enabled=False)
+        p1 = db.get_tool_policy("p1")
+        p2 = db.get_tool_policy("p2")
+        assert p1 is not None
+        assert p2 is not None
+        assert p1["enabled"] is True
+        assert isinstance(p1["enabled"], bool)
+        assert p2["enabled"] is False
+        assert isinstance(p2["enabled"], bool)
+
+    def test_list_policies_filter_org(self, db):
+        db.create_tool_policy("p1", "a", "*", "allow", priority=0, org_id="org1")
+        db.create_tool_policy("p2", "b", "*", "deny", priority=0, org_id="org2")
+        db.create_tool_policy("p3", "c", "*", "ask", priority=0, org_id="org1")
+        result = db.list_tool_policies(org_id="org1")
+        assert len(result) == 2
+        assert {r["policy_id"] for r in result} == {"p1", "p3"}
+
+
+# ---------------------------------------------------------------------------
+# Prompt Templates
+# ---------------------------------------------------------------------------
+
+
+class TestPromptTemplateCRUD:
+    def test_create_prompt_template(self, db):
+        db.create_prompt_template(
+            "t1",
+            "greeting",
+            "general",
+            "Hello {{name}}!",
+            variables='["name"]',
+            is_default=True,
+            org_id="org1",
+            created_by="admin",
+        )
+        tpl = db.get_prompt_template("t1")
+        assert tpl is not None
+        assert tpl["template_id"] == "t1"
+        assert tpl["name"] == "greeting"
+        assert tpl["category"] == "general"
+        assert tpl["content"] == "Hello {{name}}!"
+        assert tpl["variables"] == '["name"]'
+        assert tpl["is_default"] is True
+        assert tpl["org_id"] == "org1"
+        assert tpl["created_by"] == "admin"
+
+    def test_get_prompt_template_nonexistent(self, db):
+        assert db.get_prompt_template("missing") is None
+
+    def test_list_prompt_templates_ordered_by_name(self, db):
+        db.create_prompt_template("t2", "beta", "general", "B")
+        db.create_prompt_template("t1", "alpha", "general", "A")
+        templates = db.list_prompt_templates()
+        assert len(templates) == 2
+        assert templates[0]["name"] == "alpha"
+        assert templates[1]["name"] == "beta"
+
+    def test_list_prompt_templates_filter_org(self, db):
+        db.create_prompt_template("t1", "a", "general", "A", org_id="org1")
+        db.create_prompt_template("t2", "b", "general", "B", org_id="org2")
+        result = db.list_prompt_templates(org_id="org1")
+        assert len(result) == 1
+        assert result[0]["template_id"] == "t1"
+
+    def test_update_prompt_template(self, db):
+        db.create_prompt_template("t1", "greeting", "general", "Hello!")
+        ok = db.update_prompt_template("t1", content="Hi there!", category="custom")
+        assert ok is True
+        tpl = db.get_prompt_template("t1")
+        assert tpl is not None
+        assert tpl["content"] == "Hi there!"
+        assert tpl["category"] == "custom"
+
+    def test_update_prompt_template_nonexistent(self, db):
+        assert db.update_prompt_template("missing", content="x") is False
+
+    def test_delete_prompt_template(self, db):
+        db.create_prompt_template("t1", "greeting", "general", "Hello!")
+        ok = db.delete_prompt_template("t1")
+        assert ok is True
+        assert db.get_prompt_template("t1") is None
+
+    def test_delete_prompt_template_nonexistent(self, db):
+        assert db.delete_prompt_template("missing") is False
+
+    def test_is_default_as_bool(self, db):
+        db.create_prompt_template("t1", "default_one", "general", "D", is_default=True)
+        db.create_prompt_template("t2", "not_default", "general", "N", is_default=False)
+        t1 = db.get_prompt_template("t1")
+        t2 = db.get_prompt_template("t2")
+        assert t1 is not None
+        assert t2 is not None
+        assert t1["is_default"] is True
+        assert isinstance(t1["is_default"], bool)
+        assert t2["is_default"] is False
+        assert isinstance(t2["is_default"], bool)
+
+    def test_create_with_mcp_origin(self, db):
+        db.create_prompt_template(
+            "t1",
+            "mcp__srv__prompt",
+            "mcp",
+            "content",
+            variables="[]",
+            is_default=False,
+            org_id="",
+            created_by="",
+            origin="mcp",
+            mcp_server="srv",
+            readonly=True,
+        )
+        tpl = db.get_prompt_template("t1")
+        assert tpl is not None
+        assert tpl["origin"] == "mcp"
+        assert tpl["mcp_server"] == "srv"
+        assert tpl["readonly"] is True
+        assert isinstance(tpl["readonly"], bool)
+
+    def test_default_origin_values(self, db):
+        db.create_prompt_template("t1", "basic", "general", "Hello")
+        tpl = db.get_prompt_template("t1")
+        assert tpl is not None
+        assert tpl["origin"] == "manual"
+        assert tpl["mcp_server"] == ""
+        assert tpl["readonly"] is False
+
+    def test_get_prompt_template_by_name(self, db):
+        db.create_prompt_template("t1", "greeting", "general", "Hello!")
+        tpl = db.get_prompt_template_by_name("greeting")
+        assert tpl is not None
+        assert tpl["template_id"] == "t1"
+        assert tpl["name"] == "greeting"
+
+    def test_get_prompt_template_by_name_nonexistent(self, db):
+        assert db.get_prompt_template_by_name("nope") is None
+
+    def test_list_default_templates(self, db):
+        db.create_prompt_template("t1", "alpha", "general", "A", is_default=True)
+        db.create_prompt_template("t2", "beta", "general", "B", is_default=False)
+        db.create_prompt_template("t3", "gamma", "general", "C", is_default=True)
+        result = db.list_default_templates()
+        assert len(result) == 2
+        assert result[0]["name"] == "alpha"
+        assert result[1]["name"] == "gamma"
+
+    def test_list_default_templates_empty(self, db):
+        db.create_prompt_template("t1", "alpha", "general", "A", is_default=False)
+        assert db.list_default_templates() == []
+
+    def test_list_prompt_templates_by_origin(self, db):
+        db.create_prompt_template("t1", "manual_one", "general", "A", origin="manual")
+        db.create_prompt_template("t2", "mcp_one", "mcp", "B", origin="mcp", mcp_server="srv1")
+        db.create_prompt_template("t3", "mcp_two", "mcp", "C", origin="mcp", mcp_server="srv2")
+        result = db.list_prompt_templates_by_origin("mcp")
+        assert len(result) == 2
+        names = [r["name"] for r in result]
+        assert "mcp_one" in names
+        assert "mcp_two" in names
+
+
+# ---------------------------------------------------------------------------
+# Usage Events
+# ---------------------------------------------------------------------------
+
+
+class TestUsageEvents:
+    def test_record_usage_event(self, db):
+        db.record_usage_event(
+            "ev1",
+            user_id="u1",
+            ws_id="ws1",
+            node_id="n1",
+            model="gpt-5",
+            prompt_tokens=100,
+            completion_tokens=50,
+            tool_calls_count=2,
+        )
+        # Verify via query_usage (no group_by returns summary).
+        result = db.query_usage(since="2000-01-01T00:00:00")
+        assert len(result) == 1
+        assert result[0]["prompt_tokens"] == 100
+        assert result[0]["completion_tokens"] == 50
+        assert result[0]["tool_calls_count"] == 2
+
+    def test_query_usage_summary(self, db):
+        db.record_usage_event("ev1", model="gpt-5", prompt_tokens=100, completion_tokens=50)
+        db.record_usage_event("ev2", model="gpt-5", prompt_tokens=200, completion_tokens=75)
+        result = db.query_usage(since="2000-01-01T00:00:00")
+        assert len(result) == 1
+        assert result[0]["prompt_tokens"] == 300
+        assert result[0]["completion_tokens"] == 125
+
+    def test_query_usage_by_day(self, db):
+        # Insert events with known timestamps by directly inserting rows.
+        from turnstone.core.storage._schema import usage_events
+
+        with db._engine.connect() as conn:
+            conn.execute(
+                sa.insert(usage_events),
+                [
+                    {
+                        "event_id": "e1",
+                        "timestamp": "2026-03-01T10:00:00",
+                        "user_id": "",
+                        "ws_id": "",
+                        "node_id": "",
+                        "model": "gpt-5",
+                        "prompt_tokens": 100,
+                        "completion_tokens": 50,
+                        "tool_calls_count": 0,
+                        "created": "2026-03-01T10:00:00",
+                    },
+                    {
+                        "event_id": "e2",
+                        "timestamp": "2026-03-01T14:00:00",
+                        "user_id": "",
+                        "ws_id": "",
+                        "node_id": "",
+                        "model": "gpt-5",
+                        "prompt_tokens": 50,
+                        "completion_tokens": 25,
+                        "tool_calls_count": 0,
+                        "created": "2026-03-01T14:00:00",
+                    },
+                    {
+                        "event_id": "e3",
+                        "timestamp": "2026-03-02T08:00:00",
+                        "user_id": "",
+                        "ws_id": "",
+                        "node_id": "",
+                        "model": "gpt-5",
+                        "prompt_tokens": 200,
+                        "completion_tokens": 100,
+                        "tool_calls_count": 0,
+                        "created": "2026-03-02T08:00:00",
+                    },
+                ],
+            )
+            conn.commit()
+
+        result = db.query_usage(since="2026-03-01T00:00:00", group_by="day")
+        assert len(result) == 2
+        assert result[0]["key"] == "2026-03-01"
+        assert result[0]["prompt_tokens"] == 150
+        assert result[1]["key"] == "2026-03-02"
+        assert result[1]["prompt_tokens"] == 200
+
+    def test_query_usage_by_model(self, db):
+        from turnstone.core.storage._schema import usage_events
+
+        with db._engine.connect() as conn:
+            conn.execute(
+                sa.insert(usage_events),
+                [
+                    {
+                        "event_id": "e1",
+                        "timestamp": "2026-03-01T10:00:00",
+                        "user_id": "",
+                        "ws_id": "",
+                        "node_id": "",
+                        "model": "gpt-5",
+                        "prompt_tokens": 100,
+                        "completion_tokens": 50,
+                        "tool_calls_count": 0,
+                        "created": "2026-03-01T10:00:00",
+                    },
+                    {
+                        "event_id": "e2",
+                        "timestamp": "2026-03-01T10:00:00",
+                        "user_id": "",
+                        "ws_id": "",
+                        "node_id": "",
+                        "model": "claude-4",
+                        "prompt_tokens": 200,
+                        "completion_tokens": 100,
+                        "tool_calls_count": 1,
+                        "created": "2026-03-01T10:00:00",
+                    },
+                ],
+            )
+            conn.commit()
+
+        result = db.query_usage(since="2026-03-01T00:00:00", group_by="model")
+        assert len(result) == 2
+        keys = [r["key"] for r in result]
+        assert "gpt-5" in keys
+        assert "claude-4" in keys
+
+    def test_query_usage_by_user(self, db):
+        from turnstone.core.storage._schema import usage_events
+
+        with db._engine.connect() as conn:
+            conn.execute(
+                sa.insert(usage_events),
+                [
+                    {
+                        "event_id": "e1",
+                        "timestamp": "2026-03-01T10:00:00",
+                        "user_id": "u1",
+                        "ws_id": "",
+                        "node_id": "",
+                        "model": "",
+                        "prompt_tokens": 100,
+                        "completion_tokens": 50,
+                        "tool_calls_count": 0,
+                        "created": "2026-03-01T10:00:00",
+                    },
+                    {
+                        "event_id": "e2",
+                        "timestamp": "2026-03-01T10:00:00",
+                        "user_id": "u2",
+                        "ws_id": "",
+                        "node_id": "",
+                        "model": "",
+                        "prompt_tokens": 300,
+                        "completion_tokens": 150,
+                        "tool_calls_count": 2,
+                        "created": "2026-03-01T10:00:00",
+                    },
+                ],
+            )
+            conn.commit()
+
+        result = db.query_usage(since="2026-03-01T00:00:00", group_by="user")
+        assert len(result) == 2
+        by_key = {r["key"]: r for r in result}
+        assert by_key["u1"]["prompt_tokens"] == 100
+        assert by_key["u2"]["prompt_tokens"] == 300
+
+    def test_query_usage_filter_model(self, db):
+        from turnstone.core.storage._schema import usage_events
+
+        with db._engine.connect() as conn:
+            conn.execute(
+                sa.insert(usage_events),
+                [
+                    {
+                        "event_id": "e1",
+                        "timestamp": "2026-03-01T10:00:00",
+                        "user_id": "",
+                        "ws_id": "",
+                        "node_id": "",
+                        "model": "gpt-5",
+                        "prompt_tokens": 100,
+                        "completion_tokens": 50,
+                        "tool_calls_count": 0,
+                        "created": "2026-03-01T10:00:00",
+                    },
+                    {
+                        "event_id": "e2",
+                        "timestamp": "2026-03-01T10:00:00",
+                        "user_id": "",
+                        "ws_id": "",
+                        "node_id": "",
+                        "model": "claude-4",
+                        "prompt_tokens": 200,
+                        "completion_tokens": 100,
+                        "tool_calls_count": 0,
+                        "created": "2026-03-01T10:00:00",
+                    },
+                ],
+            )
+            conn.commit()
+
+        result = db.query_usage(since="2026-03-01T00:00:00", model="gpt-5")
+        assert len(result) == 1
+        assert result[0]["prompt_tokens"] == 100
+
+    def test_prune_usage_events(self, db):
+        from turnstone.core.storage._schema import usage_events
+
+        old_ts = "2020-01-01T00:00:00"
+        now_ts = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%S")
+        with db._engine.connect() as conn:
+            conn.execute(
+                sa.insert(usage_events),
+                [
+                    {
+                        "event_id": "old",
+                        "timestamp": old_ts,
+                        "user_id": "",
+                        "ws_id": "",
+                        "node_id": "",
+                        "model": "",
+                        "prompt_tokens": 10,
+                        "completion_tokens": 5,
+                        "tool_calls_count": 0,
+                        "created": old_ts,
+                    },
+                    {
+                        "event_id": "new",
+                        "timestamp": now_ts,
+                        "user_id": "",
+                        "ws_id": "",
+                        "node_id": "",
+                        "model": "",
+                        "prompt_tokens": 20,
+                        "completion_tokens": 10,
+                        "tool_calls_count": 0,
+                        "created": now_ts,
+                    },
+                ],
+            )
+            conn.commit()
+
+        pruned = db.prune_usage_events(retention_days=30)
+        assert pruned == 1
+        # Only the recent event should remain.
+        result = db.query_usage(since="2000-01-01T00:00:00")
+        assert result[0]["prompt_tokens"] == 20
+
+
+# ---------------------------------------------------------------------------
+# Audit Events
+# ---------------------------------------------------------------------------
+
+
+class TestAuditEvents:
+    def test_record_audit_event(self, db):
+        db.record_audit_event(
+            "a1",
+            user_id="u1",
+            action="role.create",
+            resource_type="role",
+            resource_id="r1",
+            detail='{"name":"editor"}',
+            ip_address="127.0.0.1",
+        )
+        events = db.list_audit_events()
+        assert len(events) == 1
+        ev = events[0]
+        assert ev["event_id"] == "a1"
+        assert ev["user_id"] == "u1"
+        assert ev["action"] == "role.create"
+        assert ev["resource_type"] == "role"
+        assert ev["resource_id"] == "r1"
+        assert ev["detail"] == '{"name":"editor"}'
+        assert ev["ip_address"] == "127.0.0.1"
+
+    def test_list_audit_events(self, db):
+        db.record_audit_event("a1", action="login")
+        db.record_audit_event("a2", action="logout")
+        events = db.list_audit_events()
+        assert len(events) == 2
+        # Ordered by timestamp DESC — most recent first.
+        # Both created in quick succession with same-second granularity,
+        # but the order should still be deterministic (DESC).
+        assert {e["event_id"] for e in events} == {"a1", "a2"}
+
+    def test_list_audit_events_filter_action(self, db):
+        db.record_audit_event("a1", action="login")
+        db.record_audit_event("a2", action="logout")
+        db.record_audit_event("a3", action="login")
+        events = db.list_audit_events(action="login")
+        assert len(events) == 2
+        assert all(e["action"] == "login" for e in events)
+
+    def test_list_audit_events_filter_user(self, db):
+        db.record_audit_event("a1", user_id="u1", action="login")
+        db.record_audit_event("a2", user_id="u2", action="login")
+        events = db.list_audit_events(user_id="u1")
+        assert len(events) == 1
+        assert events[0]["user_id"] == "u1"
+
+    def test_list_audit_events_pagination(self, db):
+        for i in range(5):
+            db.record_audit_event(f"a{i}", action="test")
+        page1 = db.list_audit_events(limit=2, offset=0)
+        page2 = db.list_audit_events(limit=2, offset=2)
+        page3 = db.list_audit_events(limit=2, offset=4)
+        assert len(page1) == 2
+        assert len(page2) == 2
+        assert len(page3) == 1
+        # No overlap.
+        ids = [e["event_id"] for e in page1 + page2 + page3]
+        assert len(set(ids)) == 5
+
+    def test_count_audit_events(self, db):
+        db.record_audit_event("a1", action="login")
+        db.record_audit_event("a2", action="logout")
+        db.record_audit_event("a3", action="login")
+        assert db.count_audit_events() == 3
+        assert db.count_audit_events(action="login") == 2
+        assert db.count_audit_events(action="logout") == 1
+
+    def test_count_audit_events_filter_user(self, db):
+        db.record_audit_event("a1", user_id="u1", action="login")
+        db.record_audit_event("a2", user_id="u2", action="login")
+        assert db.count_audit_events(user_id="u1") == 1
+
+    def test_prune_audit_events(self, db):
+        from turnstone.core.storage._schema import audit_events
+
+        old_ts = "2020-01-01T00:00:00"
+        now_ts = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%S")
+        with db._engine.connect() as conn:
+            conn.execute(
+                sa.insert(audit_events),
+                [
+                    {
+                        "event_id": "old",
+                        "timestamp": old_ts,
+                        "user_id": "",
+                        "action": "test",
+                        "resource_type": "",
+                        "resource_id": "",
+                        "detail": "{}",
+                        "ip_address": "",
+                        "created": old_ts,
+                    },
+                    {
+                        "event_id": "new",
+                        "timestamp": now_ts,
+                        "user_id": "",
+                        "action": "test",
+                        "resource_type": "",
+                        "resource_id": "",
+                        "detail": "{}",
+                        "ip_address": "",
+                        "created": now_ts,
+                    },
+                ],
+            )
+            conn.commit()
+
+        pruned = db.prune_audit_events(retention_days=30)
+        assert pruned == 1
+        assert db.count_audit_events() == 1

tests/test_mcp_client.py

@@ -2,10 +2,11 @@
 
 from __future__ import annotations
 
+import asyncio
 import json
 from contextlib import AsyncExitStack
 from typing import Any
-from unittest.mock import MagicMock, patch
+from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
 
@@ -50,6 +51,83 @@ def _fake_openai_tool(name: str = "mcp__test__search") -> dict[str, Any]:
     }
 
 
+def _fake_mcp_resource(
+    uri: str = "file:///README.md",
+    name: str = "readme",
+    description: str = "Project readme",
+    mime_type: str = "text/plain",
+) -> MagicMock:
+    """Create a mock MCP Resource object matching the SDK's Resource type."""
+    res = MagicMock()
+    res.uri = uri
+    res.name = name
+    res.description = description
+    res.mimeType = mime_type
+    return res
+
+
+def _fake_resource_dict(
+    uri: str = "file:///README.md",
+    name: str = "readme",
+    description: str = "Project readme",
+    mime_type: str = "text/plain",
+    server: str = "test",
+) -> dict[str, Any]:
+    """Create a fake resource dict as stored in per-server state."""
+    return {
+        "uri": uri,
+        "name": name,
+        "description": description,
+        "mimeType": mime_type,
+        "server": server,
+    }
+
+
+def _fake_mcp_prompt(
+    name: str = "code_review",
+    description: str = "Generate a code review",
+    arguments: list[dict[str, Any]] | None = None,
+) -> MagicMock:
+    """Create a mock MCP Prompt object matching the SDK's Prompt type."""
+    prompt = MagicMock()
+    prompt.name = name
+    prompt.description = description
+    if arguments is None:
+        arg = MagicMock()
+        arg.name = "language"
+        arg.description = "Programming language"
+        arg.required = True
+        prompt.arguments = [arg]
+    else:
+        mock_args = []
+        for a in arguments:
+            arg = MagicMock()
+            arg.name = a["name"]
+            arg.description = a.get("description", "")
+            arg.required = a.get("required", False)
+            mock_args.append(arg)
+        prompt.arguments = mock_args
+    return prompt
+
+
+def _fake_prompt_dict(
+    name: str = "mcp__test__code_review",
+    original_name: str = "code_review",
+    server: str = "test",
+    description: str = "Generate a code review",
+) -> dict[str, Any]:
+    """Create a fake prompt dict as stored in per-server state."""
+    return {
+        "name": name,
+        "original_name": original_name,
+        "server": server,
+        "description": description,
+        "arguments": [
+            {"name": "language", "description": "Programming language", "required": True}
+        ],
+    }
+
+
 # ---------------------------------------------------------------------------
 # Schema conversion
 # ---------------------------------------------------------------------------
@@ -411,3 +489,882 @@ class TestCreateMcpClient:
 
             result = create_mcp_client()
             assert result is None
+
+
+# ---------------------------------------------------------------------------
+# Tool refresh — _rebuild_tools, _refresh_server, listeners
+# ---------------------------------------------------------------------------
+
+
+class TestRebuildTools:
+    def test_rebuild_from_per_server(self):
+        mgr = MCPClientManager({})
+        mgr._per_server_tools = {
+            "github": [_fake_openai_tool("mcp__github__search")],
+            "slack": [_fake_openai_tool("mcp__slack__send")],
+        }
+        mgr._rebuild_tools()
+        assert len(mgr._tools) == 2
+        names = {t["function"]["name"] for t in mgr._tools}
+        assert names == {"mcp__github__search", "mcp__slack__send"}
+        assert mgr._tool_map["mcp__github__search"] == ("github", "search")
+        assert mgr._tool_map["mcp__slack__send"] == ("slack", "send")
+
+    def test_rebuild_copy_on_write(self):
+        mgr = MCPClientManager({})
+        mgr._per_server_tools = {"a": [_fake_openai_tool("mcp__a__x")]}
+        mgr._rebuild_tools()
+        old_tools = mgr._tools
+        old_map = mgr._tool_map
+        mgr._per_server_tools["b"] = [_fake_openai_tool("mcp__b__y")]
+        mgr._rebuild_tools()
+        assert mgr._tools is not old_tools
+        assert mgr._tool_map is not old_map
+
+    def test_rebuild_empty(self):
+        mgr = MCPClientManager({})
+        mgr._per_server_tools = {}
+        mgr._rebuild_tools()
+        assert mgr._tools == []
+        assert mgr._tool_map == {}
+
+
+class TestRefreshServer:
+    @staticmethod
+    def _add_empty_resource_prompt_mocks(
+        mgr: MCPClientManager, server_name: str, mock_session: MagicMock
+    ) -> None:
+        """Add empty list_resources/list_prompts mocks so _refresh_server works."""
+        mgr._supports_resources[server_name] = True
+        mgr._supports_prompts[server_name] = True
+        empty_res = MagicMock()
+        empty_res.resources = []
+        mock_session.list_resources = AsyncMock(return_value=empty_res)
+        empty_tmpl = MagicMock()
+        empty_tmpl.resourceTemplates = []
+        mock_session.list_resource_templates = AsyncMock(return_value=empty_tmpl)
+        empty_prompts = MagicMock()
+        empty_prompts.prompts = []
+        mock_session.list_prompts = AsyncMock(return_value=empty_prompts)
+
+    def test_refresh_detects_added_tools(self):
+        async def _run() -> None:
+            mgr = MCPClientManager({})
+            mock_session = MagicMock()
+            mock_result = MagicMock()
+            mock_result.tools = [
+                _fake_mcp_tool("search"),
+                _fake_mcp_tool("create"),  # new tool
+            ]
+            mock_session.list_tools = AsyncMock(return_value=mock_result)
+            self._add_empty_resource_prompt_mocks(mgr, "github", mock_session)
+            mgr._sessions["github"] = mock_session
+            mgr._per_server_tools["github"] = [_fake_openai_tool("mcp__github__search")]
+            mgr._rebuild_tools()
+
+            added, removed = await mgr._refresh_server("github")
+            assert "mcp__github__create" in added
+            assert removed == []
+            assert len(mgr._tools) == 2
+
+        asyncio.run(_run())
+
+    def test_refresh_detects_removed_tools(self):
+        async def _run() -> None:
+            mgr = MCPClientManager({})
+            mock_session = MagicMock()
+            mock_result = MagicMock()
+            mock_result.tools = []  # all tools removed
+            mock_session.list_tools = AsyncMock(return_value=mock_result)
+            self._add_empty_resource_prompt_mocks(mgr, "github", mock_session)
+            mgr._sessions["github"] = mock_session
+            mgr._per_server_tools["github"] = [_fake_openai_tool("mcp__github__search")]
+            mgr._rebuild_tools()
+
+            added, removed = await mgr._refresh_server("github")
+            assert added == []
+            assert "mcp__github__search" in removed
+            assert mgr._tools == []
+
+        asyncio.run(_run())
+
+    def test_refresh_no_changes(self):
+        async def _run() -> None:
+            mgr = MCPClientManager({})
+            mock_session = MagicMock()
+            mock_result = MagicMock()
+            mock_result.tools = [_fake_mcp_tool("search")]
+            mock_session.list_tools = AsyncMock(return_value=mock_result)
+            self._add_empty_resource_prompt_mocks(mgr, "github", mock_session)
+            mgr._sessions["github"] = mock_session
+            mgr._per_server_tools["github"] = [_fake_openai_tool("mcp__github__search")]
+            mgr._rebuild_tools()
+
+            added, removed = await mgr._refresh_server("github")
+            assert added == []
+            assert removed == []
+
+        asyncio.run(_run())
+
+    def test_refresh_disconnected_raises(self):
+        async def _run() -> None:
+            mgr = MCPClientManager({})
+            with pytest.raises(RuntimeError, match="not connected"):
+                await mgr._refresh_server_tools("ghost")
+
+        asyncio.run(_run())
+
+
+class TestListeners:
+    def test_add_and_notify(self):
+        mgr = MCPClientManager({})
+        calls: list[int] = []
+        mgr.add_listener(lambda: calls.append(1))
+        mgr._per_server_tools = {"a": [_fake_openai_tool("mcp__a__x")]}
+        mgr._rebuild_tools()
+        assert len(calls) == 1
+
+    def test_remove_listener(self):
+        mgr = MCPClientManager({})
+        calls: list[int] = []
+        cb = lambda: calls.append(1)  # noqa: E731
+        mgr.add_listener(cb)
+        mgr.remove_listener(cb)
+        mgr._rebuild_tools()
+        assert calls == []
+
+    def test_remove_nonexistent_listener(self):
+        mgr = MCPClientManager({})
+        mgr.remove_listener(lambda: None)  # should not raise
+
+    def test_listener_error_does_not_propagate(self):
+        mgr = MCPClientManager({})
+        mgr.add_listener(lambda: 1 / 0)  # will raise ZeroDivisionError
+        mgr._rebuild_tools()  # should not raise
+
+
+class TestServerNames:
+    def test_server_names_property(self):
+        mgr = MCPClientManager({"github": {}, "slack": {}})
+        assert sorted(mgr.server_names) == ["github", "slack"]
+
+    def test_server_names_empty(self):
+        mgr = MCPClientManager({})
+        assert mgr.server_names == []
+
+
+# ---------------------------------------------------------------------------
+# Session integration — tool refresh propagation
+# ---------------------------------------------------------------------------
+
+
+class TestSessionRefresh:
+    @pytest.fixture()
+    def tmp_db(self, tmp_path):
+        from turnstone.core.storage import init_storage, reset_storage
+
+        reset_storage()
+        init_storage("sqlite", path=str(tmp_path / "test.db"), run_migrations=False)
+        yield
+        reset_storage()
+
+    def _make_session(self, mcp_client=None, **kwargs):
+        from turnstone.core.session import ChatSession
+
+        defaults: dict[str, Any] = dict(
+            client=MagicMock(),
+            model="test-model",
+            ui=MagicMock(),
+            instructions=None,
+            temperature=0.5,
+            max_tokens=4096,
+            tool_timeout=30,
+            mcp_client=mcp_client,
+        )
+        defaults.update(kwargs)
+        return ChatSession(**defaults)
+
+    def test_listener_registered_on_init(self, tmp_db):
+        mock_mcp = MagicMock()
+        mock_mcp.get_tools.return_value = []
+        session = self._make_session(mcp_client=mock_mcp)
+        mock_mcp.add_listener.assert_called_once()
+        assert session._mcp_refresh_cb is not None
+
+    def test_no_listener_without_mcp(self, tmp_db):
+        session = self._make_session(mcp_client=None)
+        assert session._mcp_refresh_cb is None
+
+    def test_close_removes_listener(self, tmp_db):
+        mock_mcp = MagicMock()
+        mock_mcp.get_tools.return_value = []
+        session = self._make_session(mcp_client=mock_mcp)
+        session.close()
+        mock_mcp.remove_listener.assert_called_once()
+        assert session._mcp_refresh_cb is None
+
+    def test_close_idempotent(self, tmp_db):
+        mock_mcp = MagicMock()
+        mock_mcp.get_tools.return_value = []
+        session = self._make_session(mcp_client=mock_mcp)
+        session.close()
+        session.close()  # should not raise
+        assert mock_mcp.remove_listener.call_count == 1
+
+    def test_on_mcp_tools_changed_rebuilds_tools(self, tmp_db):
+        mock_mcp = MagicMock()
+        mock_mcp.get_tools.return_value = [_fake_openai_tool("mcp__test__a")]
+        session = self._make_session(mcp_client=mock_mcp)
+        initial_count = len(session._tools)
+
+        # Simulate a tool refresh — MCP now has 2 tools
+        mock_mcp.get_tools.return_value = [
+            _fake_openai_tool("mcp__test__a"),
+            _fake_openai_tool("mcp__test__b"),
+        ]
+        session._on_mcp_tools_changed()
+        assert len(session._tools) == initial_count + 1
+
+    def test_tool_search_preserved_across_refresh(self, tmp_db):
+        # Create enough MCP tools to trigger tool search
+        mcp_tools = [_fake_openai_tool(f"mcp__srv__tool{i}") for i in range(25)]
+        mock_mcp = MagicMock()
+        mock_mcp.get_tools.return_value = mcp_tools
+        session = self._make_session(
+            mcp_client=mock_mcp,
+            tool_search="auto",
+            tool_search_threshold=20,
+        )
+        assert session._tool_search is not None
+
+        # Expand a tool
+        session._tool_search.expand_visible(["mcp__srv__tool0"])
+        assert "mcp__srv__tool0" in session._tool_search.get_expanded_names()
+
+        # Refresh with same tools
+        session._on_mcp_tools_changed()
+        assert session._tool_search is not None
+        assert "mcp__srv__tool0" in session._tool_search.get_expanded_names()
+
+    def test_tool_search_prunes_removed_from_expanded(self, tmp_db):
+        mcp_tools = [_fake_openai_tool(f"mcp__srv__tool{i}") for i in range(25)]
+        mock_mcp = MagicMock()
+        mock_mcp.get_tools.return_value = mcp_tools
+        session = self._make_session(
+            mcp_client=mock_mcp,
+            tool_search="auto",
+            tool_search_threshold=20,
+        )
+        session._tool_search.expand_visible(["mcp__srv__tool0"])
+
+        # Refresh with tool0 removed
+        new_tools = [_fake_openai_tool(f"mcp__srv__tool{i}") for i in range(1, 25)]
+        mock_mcp.get_tools.return_value = new_tools
+        session._on_mcp_tools_changed()
+        # tool0 was removed, so it should no longer be in expanded
+        expanded = session._tool_search.get_expanded_names()
+        assert "mcp__srv__tool0" not in expanded
+
+    def test_mcp_refresh_command(self, tmp_db):
+        mock_mcp = MagicMock()
+        mock_mcp.get_tools.return_value = [_fake_openai_tool()]
+        mock_mcp.server_names = ["test"]
+        mock_mcp.refresh_sync.return_value = {"test": (["mcp__test__new"], [])}
+        session = self._make_session(mcp_client=mock_mcp)
+
+        session.handle_command("/mcp refresh")
+        mock_mcp.refresh_sync.assert_called_once_with(None)
+        session.ui.on_info.assert_called()
+
+    def test_mcp_refresh_specific_server(self, tmp_db):
+        mock_mcp = MagicMock()
+        mock_mcp.get_tools.return_value = [_fake_openai_tool()]
+        mock_mcp.server_names = ["github", "slack"]
+        mock_mcp.refresh_sync.return_value = {"github": ([], [])}
+        session = self._make_session(mcp_client=mock_mcp)
+
+        session.handle_command("/mcp refresh github")
+        mock_mcp.refresh_sync.assert_called_once_with("github")
+
+    def test_mcp_refresh_unknown_server(self, tmp_db):
+        mock_mcp = MagicMock()
+        mock_mcp.get_tools.return_value = [_fake_openai_tool()]
+        mock_mcp.server_names = ["github"]
+        session = self._make_session(mcp_client=mock_mcp)
+
+        session.handle_command("/mcp refresh nonexistent")
+        session.ui.on_error.assert_called_once()
+        assert "Unknown MCP server" in session.ui.on_error.call_args[0][0]
+
+    def test_mcp_refresh_error_handling(self, tmp_db):
+        mock_mcp = MagicMock()
+        mock_mcp.get_tools.return_value = [_fake_openai_tool()]
+        mock_mcp.server_names = ["test"]
+        mock_mcp.refresh_sync.side_effect = TimeoutError("timed out")
+        session = self._make_session(mcp_client=mock_mcp)
+
+        session.handle_command("/mcp refresh")
+        session.ui.on_error.assert_called_once()
+        assert "MCP refresh failed" in session.ui.on_error.call_args[0][0]
+
+
+# ---------------------------------------------------------------------------
+# MCP Resources
+# ---------------------------------------------------------------------------
+
+
+class TestMCPResources:
+    def test_resource_discovery(self):
+        """Mock list_resources() returning 2 resources, verify get_resources()."""
+        mgr = MCPClientManager({})
+        mgr._per_server_resources = {
+            "fs": [
+                _fake_resource_dict("file:///a.txt", "a", "File A", "text/plain", "fs"),
+                _fake_resource_dict("file:///b.txt", "b", "File B", "text/plain", "fs"),
+            ],
+        }
+        mgr._rebuild_resources()
+        resources = mgr.get_resources()
+        assert len(resources) == 2
+        uris = {r["uri"] for r in resources}
+        assert uris == {"file:///a.txt", "file:///b.txt"}
+        assert all(r["server"] == "fs" for r in resources)
+
+    def test_rebuild_resources_copy_on_write(self):
+        """Verify mutation safety — get_resources() returns independent copy."""
+        mgr = MCPClientManager({})
+        mgr._per_server_resources = {
+            "a": [_fake_resource_dict("file:///x", "x", "", "", "a")],
+        }
+        mgr._rebuild_resources()
+        old_resources = mgr._resources
+        old_map = mgr._resource_map
+        mgr._per_server_resources["b"] = [_fake_resource_dict("file:///y", "y", "", "", "b")]
+        mgr._rebuild_resources()
+        assert mgr._resources is not old_resources
+        assert mgr._resource_map is not old_map
+
+    def test_get_resources_returns_copy(self):
+        mgr = MCPClientManager({})
+        mgr._per_server_resources = {
+            "a": [_fake_resource_dict("file:///x", "x", "", "", "a")],
+        }
+        mgr._rebuild_resources()
+        resources = mgr.get_resources()
+        assert len(resources) == 1
+        resources.clear()
+        assert len(mgr.get_resources()) == 1
+
+    def test_read_resource_sync(self):
+        """Mock session.read_resource(), verify text extraction."""
+        mgr = MCPClientManager({})
+        mgr._resource_map = {"file:///readme": ("fs", "file:///readme")}
+        mock_session = MagicMock()
+        mgr._sessions["fs"] = mock_session
+        mgr._loop = asyncio.new_event_loop()
+
+        # Mock the read_resource result
+        text_content = MagicMock(spec=["text"])
+        text_content.text = "Hello, world!"
+        mock_result = MagicMock()
+        mock_result.contents = [text_content]
+        mock_session.read_resource = AsyncMock(return_value=mock_result)
+
+        thread = None
+        try:
+            thread = __import__("threading").Thread(target=mgr._loop.run_forever, daemon=True)
+            thread.start()
+            output = mgr.read_resource_sync("file:///readme", timeout=5)
+            assert output == "Hello, world!"
+            mock_session.read_resource.assert_awaited_once_with("file:///readme")
+        finally:
+            mgr._loop.call_soon_threadsafe(mgr._loop.stop)
+            if thread:
+                thread.join(timeout=5)
+            mgr._loop.close()
+
+    def test_read_resource_sync_blob(self):
+        """Verify base64 blob extraction."""
+        mgr = MCPClientManager({})
+        mgr._resource_map = {"file:///img.png": ("fs", "file:///img.png")}
+        mock_session = MagicMock()
+        mgr._sessions["fs"] = mock_session
+        mgr._loop = asyncio.new_event_loop()
+
+        blob_content = MagicMock(spec=["blob"])
+        blob_content.blob = "aGVsbG8="
+        mock_result = MagicMock()
+        mock_result.contents = [blob_content]
+        mock_session.read_resource = AsyncMock(return_value=mock_result)
+
+        thread = None
+        try:
+            thread = __import__("threading").Thread(target=mgr._loop.run_forever, daemon=True)
+            thread.start()
+            output = mgr.read_resource_sync("file:///img.png", timeout=5)
+            assert output == "aGVsbG8="
+        finally:
+            mgr._loop.call_soon_threadsafe(mgr._loop.stop)
+            if thread:
+                thread.join(timeout=5)
+            mgr._loop.close()
+
+    def test_read_resource_sync_unknown_uri(self):
+        mgr = MCPClientManager({})
+        with pytest.raises(ValueError, match="Unknown MCP resource"):
+            mgr.read_resource_sync("file:///nonexistent")
+
+    def test_read_resource_sync_disconnected(self):
+        mgr = MCPClientManager({})
+        mgr._resource_map = {"file:///x": ("dead", "file:///x")}
+        with pytest.raises(RuntimeError, match="not connected"):
+            mgr.read_resource_sync("file:///x")
+
+    def test_read_resource_sync_timeout(self):
+        """Verify timeout handling."""
+        mgr = MCPClientManager({})
+        mgr._resource_map = {"file:///x": ("fs", "file:///x")}
+        mock_session = MagicMock()
+        mgr._sessions["fs"] = mock_session
+        mgr._loop = asyncio.new_event_loop()
+
+        async def _slow_read(_uri: str) -> None:
+            await asyncio.sleep(10)
+
+        mock_session.read_resource = _slow_read
+
+        thread = None
+        try:
+            thread = __import__("threading").Thread(target=mgr._loop.run_forever, daemon=True)
+            thread.start()
+            with pytest.raises(TimeoutError):
+                mgr.read_resource_sync("file:///x", timeout=1)
+        finally:
+            mgr._loop.call_soon_threadsafe(mgr._loop.stop)
+            if thread:
+                thread.join(timeout=5)
+            mgr._loop.close()
+
+    def test_resource_listener_notification(self):
+        """Verify callback fires on rebuild."""
+        mgr = MCPClientManager({})
+        calls: list[int] = []
+        mgr.add_resource_listener(lambda: calls.append(1))
+        mgr._per_server_resources = {"a": [_fake_resource_dict()]}
+        mgr._rebuild_resources()
+        assert len(calls) == 1
+
+    def test_resource_listener_remove(self):
+        mgr = MCPClientManager({})
+        calls: list[int] = []
+        cb = lambda: calls.append(1)  # noqa: E731
+        mgr.add_resource_listener(cb)
+        mgr.remove_resource_listener(cb)
+        mgr._rebuild_resources()
+        assert calls == []
+
+    def test_resource_listener_error_does_not_propagate(self):
+        mgr = MCPClientManager({})
+        mgr.add_resource_listener(lambda: 1 / 0)
+        mgr._rebuild_resources()  # should not raise
+
+    def test_resource_refresh_on_notification(self):
+        """Mock notification, verify re-fetch of resources."""
+
+        async def _run() -> None:
+            mgr = MCPClientManager({})
+            mock_session = MagicMock()
+            mgr._sessions["fs"] = mock_session
+            mgr._supports_resources["fs"] = True
+
+            # Initial state
+            mgr._per_server_resources["fs"] = [
+                _fake_resource_dict("file:///old", server="fs"),
+            ]
+            mgr._rebuild_resources()
+            assert len(mgr.get_resources()) == 1
+
+            # Mock the re-fetch returning a new resource
+            new_res = _fake_mcp_resource("file:///new", "new")
+            mock_res_result = MagicMock()
+            mock_res_result.resources = [new_res]
+            mock_session.list_resources = AsyncMock(return_value=mock_res_result)
+            mock_tmpl_result = MagicMock()
+            mock_tmpl_result.resourceTemplates = []
+            mock_session.list_resource_templates = AsyncMock(return_value=mock_tmpl_result)
+
+            await mgr._refresh_server_resources("fs")
+            resources = mgr.get_resources()
+            assert len(resources) == 1
+            assert resources[0]["uri"] == "file:///new"
+
+        asyncio.run(_run())
+
+    def test_rebuild_resources_empty(self):
+        mgr = MCPClientManager({})
+        mgr._per_server_resources = {}
+        mgr._rebuild_resources()
+        assert mgr._resources == []
+        assert mgr._resource_map == {}
+
+    def test_rebuild_resources_multi_server(self):
+        mgr = MCPClientManager({})
+        mgr._per_server_resources = {
+            "fs": [_fake_resource_dict("file:///a", server="fs")],
+            "db": [_fake_resource_dict("db://table", name="table", server="db")],
+        }
+        mgr._rebuild_resources()
+        assert len(mgr._resources) == 2
+        assert mgr._resource_map["file:///a"] == ("fs", "file:///a")
+        assert mgr._resource_map["db://table"] == ("db", "db://table")
+
+    def test_template_prefix_matching(self):
+        """Expanded URI matches template by prefix."""
+        mgr = MCPClientManager({})
+        mgr._per_server_resources = {
+            "db": [
+                {
+                    "uri": "db://tables/{table}/rows/{id}",
+                    "name": "row",
+                    "description": "A row",
+                    "mimeType": "application/json",
+                    "server": "db",
+                    "template": True,
+                },
+            ],
+        }
+        mgr._rebuild_resources()
+        # Template should not be in resource_map
+        assert "db://tables/{table}/rows/{id}" not in mgr._resource_map
+        # But prefix matching should find it
+        result = mgr._match_template("db://tables/users/rows/1")
+        assert result is not None
+        server, template_uri = result
+        assert server == "db"
+        assert template_uri == "db://tables/{table}/rows/{id}"
+
+    def test_template_longest_prefix_wins(self):
+        """When two templates have overlapping prefixes, the longer one wins."""
+        mgr = MCPClientManager({})
+        # Use templates with genuinely different prefix lengths:
+        # "db://data/" (6 chars after scheme) vs "db://data/tables/" (13 chars after scheme)
+        mgr._per_server_resources = {
+            "short": [
+                {
+                    "uri": "db://data/{collection}",
+                    "name": "collection",
+                    "description": "",
+                    "mimeType": "",
+                    "server": "short",
+                    "template": True,
+                },
+            ],
+            "long": [
+                {
+                    "uri": "db://data/tables/{table}",
+                    "name": "table",
+                    "description": "",
+                    "mimeType": "",
+                    "server": "long",
+                    "template": True,
+                },
+            ],
+        }
+        mgr._rebuild_resources()
+        # "db://data/tables/users" matches both prefixes ("db://data/" and
+        # "db://data/tables/") — the longer one should win
+        result = mgr._match_template("db://data/tables/users")
+        assert result is not None
+        server, template_uri = result
+        assert server == "long"
+        assert template_uri == "db://data/tables/{table}"
+        # URI that only matches the short prefix
+        result2 = mgr._match_template("db://data/views/active")
+        assert result2 is not None
+        assert result2[0] == "short"
+
+    def test_template_no_match_raises(self):
+        """Completely unrelated URI still raises ValueError."""
+        mgr = MCPClientManager({})
+        mgr._per_server_resources = {
+            "db": [
+                {
+                    "uri": "db://tables/{table}",
+                    "name": "table",
+                    "description": "",
+                    "mimeType": "",
+                    "server": "db",
+                    "template": True,
+                },
+            ],
+        }
+        mgr._rebuild_resources()
+        assert mgr._match_template("file:///something") is None
+        with pytest.raises(ValueError, match="Unknown MCP resource"):
+            mgr.read_resource_sync("file:///something")
+
+    def test_read_resource_sync_with_template_uri(self):
+        """End-to-end: template discovered, expanded URI dispatched to correct server."""
+        mgr = MCPClientManager({})
+        mgr._per_server_resources = {
+            "db": [
+                {
+                    "uri": "db://tables/{table}/rows/{id}",
+                    "name": "row",
+                    "description": "A row",
+                    "mimeType": "application/json",
+                    "server": "db",
+                    "template": True,
+                },
+            ],
+        }
+        mgr._rebuild_resources()
+
+        mock_session = MagicMock()
+        mgr._sessions["db"] = mock_session
+        mgr._loop = asyncio.new_event_loop()
+
+        text_content = MagicMock(spec=["text"])
+        text_content.text = '{"name": "Alice"}'
+        mock_result = MagicMock()
+        mock_result.contents = [text_content]
+        mock_session.read_resource = AsyncMock(return_value=mock_result)
+
+        thread = None
+        try:
+            thread = __import__("threading").Thread(target=mgr._loop.run_forever, daemon=True)
+            thread.start()
+            output = mgr.read_resource_sync("db://tables/users/rows/1", timeout=5)
+            assert output == '{"name": "Alice"}'
+            mock_session.read_resource.assert_awaited_once_with("db://tables/users/rows/1")
+        finally:
+            mgr._loop.call_soon_threadsafe(mgr._loop.stop)
+            if thread:
+                thread.join(timeout=5)
+            mgr._loop.close()
+
+
+# ---------------------------------------------------------------------------
+# MCP Prompts
+# ---------------------------------------------------------------------------
+
+
+class TestMCPPrompts:
+    def test_prompt_discovery(self):
+        """Mock list_prompts(), verify get_prompts() with correct prefixed names."""
+        mgr = MCPClientManager({})
+        mgr._per_server_prompts = {
+            "tmpl": [
+                _fake_prompt_dict("mcp__tmpl__code_review", "code_review", "tmpl"),
+                _fake_prompt_dict("mcp__tmpl__summarize", "summarize", "tmpl"),
+            ],
+        }
+        mgr._rebuild_prompts()
+        prompts = mgr.get_prompts()
+        assert len(prompts) == 2
+        names = {p["name"] for p in prompts}
+        assert names == {"mcp__tmpl__code_review", "mcp__tmpl__summarize"}
+        # Verify map entries
+        assert mgr._prompt_map["mcp__tmpl__code_review"] == ("tmpl", "code_review")
+        assert mgr._prompt_map["mcp__tmpl__summarize"] == ("tmpl", "summarize")
+
+    def test_rebuild_prompts_copy_on_write(self):
+        """Verify mutation safety."""
+        mgr = MCPClientManager({})
+        mgr._per_server_prompts = {
+            "a": [_fake_prompt_dict("mcp__a__p1", "p1", "a")],
+        }
+        mgr._rebuild_prompts()
+        old_prompts = mgr._prompts
+        old_map = mgr._prompt_map
+        mgr._per_server_prompts["b"] = [_fake_prompt_dict("mcp__b__p2", "p2", "b")]
+        mgr._rebuild_prompts()
+        assert mgr._prompts is not old_prompts
+        assert mgr._prompt_map is not old_map
+
+    def test_get_prompts_returns_copy(self):
+        mgr = MCPClientManager({})
+        mgr._per_server_prompts = {
+            "a": [_fake_prompt_dict("mcp__a__p1", "p1", "a")],
+        }
+        mgr._rebuild_prompts()
+        prompts = mgr.get_prompts()
+        assert len(prompts) == 1
+        prompts.clear()
+        assert len(mgr.get_prompts()) == 1
+
+    def test_get_prompt_sync(self):
+        """Mock session.get_prompt(), verify message conversion."""
+        mgr = MCPClientManager({})
+        mgr._prompt_map = {"mcp__tmpl__review": ("tmpl", "review")}
+        mock_session = MagicMock()
+        mgr._sessions["tmpl"] = mock_session
+        mgr._loop = asyncio.new_event_loop()
+
+        # Build mock PromptMessage
+        msg1 = MagicMock()
+        msg1.role = "user"
+        msg1.content = MagicMock()
+        msg1.content.text = "Review this code"
+        msg2 = MagicMock()
+        msg2.role = "assistant"
+        msg2.content = MagicMock()
+        msg2.content.text = "Looks good!"
+        mock_result = MagicMock()
+        mock_result.messages = [msg1, msg2]
+        mock_session.get_prompt = AsyncMock(return_value=mock_result)
+
+        thread = None
+        try:
+            thread = __import__("threading").Thread(target=mgr._loop.run_forever, daemon=True)
+            thread.start()
+            messages = mgr.get_prompt_sync(
+                "mcp__tmpl__review", arguments={"language": "python"}, timeout=5
+            )
+            assert len(messages) == 2
+            assert messages[0] == {"role": "user", "content": "Review this code"}
+            assert messages[1] == {"role": "assistant", "content": "Looks good!"}
+            mock_session.get_prompt.assert_awaited_once_with(
+                "review", arguments={"language": "python"}
+            )
+        finally:
+            mgr._loop.call_soon_threadsafe(mgr._loop.stop)
+            if thread:
+                thread.join(timeout=5)
+            mgr._loop.close()
+
+    def test_get_prompt_sync_unknown(self):
+        mgr = MCPClientManager({})
+        with pytest.raises(ValueError, match="Unknown MCP prompt"):
+            mgr.get_prompt_sync("mcp__no__such")
+
+    def test_get_prompt_sync_disconnected(self):
+        mgr = MCPClientManager({})
+        mgr._prompt_map = {"mcp__dead__p": ("dead", "p")}
+        with pytest.raises(RuntimeError, match="not connected"):
+            mgr.get_prompt_sync("mcp__dead__p")
+
+    def test_get_prompt_sync_timeout(self):
+        """Verify timeout handling."""
+        mgr = MCPClientManager({})
+        mgr._prompt_map = {"mcp__tmpl__slow": ("tmpl", "slow")}
+        mock_session = MagicMock()
+        mgr._sessions["tmpl"] = mock_session
+        mgr._loop = asyncio.new_event_loop()
+
+        async def _slow_prompt(_name: str, *, arguments: dict[str, str] | None = None) -> None:
+            await asyncio.sleep(10)
+
+        mock_session.get_prompt = _slow_prompt
+
+        thread = None
+        try:
+            thread = __import__("threading").Thread(target=mgr._loop.run_forever, daemon=True)
+            thread.start()
+            with pytest.raises(TimeoutError):
+                mgr.get_prompt_sync("mcp__tmpl__slow", timeout=1)
+        finally:
+            mgr._loop.call_soon_threadsafe(mgr._loop.stop)
+            if thread:
+                thread.join(timeout=5)
+            mgr._loop.close()
+
+    def test_prompt_listener_notification(self):
+        """Verify callback fires on rebuild."""
+        mgr = MCPClientManager({})
+        calls: list[int] = []
+        mgr.add_prompt_listener(lambda: calls.append(1))
+        mgr._per_server_prompts = {"a": [_fake_prompt_dict()]}
+        mgr._rebuild_prompts()
+        assert len(calls) == 1
+
+    def test_prompt_listener_remove(self):
+        mgr = MCPClientManager({})
+        calls: list[int] = []
+        cb = lambda: calls.append(1)  # noqa: E731
+        mgr.add_prompt_listener(cb)
+        mgr.remove_prompt_listener(cb)
+        mgr._rebuild_prompts()
+        assert calls == []
+
+    def test_prompt_listener_error_does_not_propagate(self):
+        mgr = MCPClientManager({})
+        mgr.add_prompt_listener(lambda: 1 / 0)
+        mgr._rebuild_prompts()  # should not raise
+
+    def test_is_mcp_prompt(self):
+        """Verify name lookup."""
+        mgr = MCPClientManager({})
+        mgr._prompt_map["mcp__tmpl__review"] = ("tmpl", "review")
+        assert mgr.is_mcp_prompt("mcp__tmpl__review") is True
+        assert mgr.is_mcp_prompt("nonexistent") is False
+
+    def test_prompt_refresh_on_notification(self):
+        """Mock notification, verify re-fetch of prompts."""
+
+        async def _run() -> None:
+            mgr = MCPClientManager({})
+            mock_session = MagicMock()
+            mgr._sessions["tmpl"] = mock_session
+            mgr._supports_prompts["tmpl"] = True
+
+            # Initial state
+            mgr._per_server_prompts["tmpl"] = [
+                _fake_prompt_dict("mcp__tmpl__old", "old", "tmpl"),
+            ]
+            mgr._rebuild_prompts()
+            assert len(mgr.get_prompts()) == 1
+
+            # Mock re-fetch returning a new prompt
+            new_prompt = _fake_mcp_prompt("new_prompt", "A new prompt")
+            mock_prompt_result = MagicMock()
+            mock_prompt_result.prompts = [new_prompt]
+            mock_session.list_prompts = AsyncMock(return_value=mock_prompt_result)
+
+            await mgr._refresh_server_prompts("tmpl")
+            prompts = mgr.get_prompts()
+            assert len(prompts) == 1
+            assert prompts[0]["name"] == "mcp__tmpl__new_prompt"
+            assert prompts[0]["original_name"] == "new_prompt"
+
+        asyncio.run(_run())
+
+    def test_rebuild_prompts_empty(self):
+        mgr = MCPClientManager({})
+        mgr._per_server_prompts = {}
+        mgr._rebuild_prompts()
+        assert mgr._prompts == []
+        assert mgr._prompt_map == {}
+
+    def test_rebuild_prompts_multi_server(self):
+        mgr = MCPClientManager({})
+        mgr._per_server_prompts = {
+            "a": [_fake_prompt_dict("mcp__a__p1", "p1", "a")],
+            "b": [_fake_prompt_dict("mcp__b__p2", "p2", "b")],
+        }
+        mgr._rebuild_prompts()
+        assert len(mgr._prompts) == 2
+        assert mgr._prompt_map["mcp__a__p1"] == ("a", "p1")
+        assert mgr._prompt_map["mcp__b__p2"] == ("b", "p2")
+
+
+# ---------------------------------------------------------------------------
+# Shutdown cleans up new state
+# ---------------------------------------------------------------------------
+
+
+class TestShutdownCleanup:
+    def test_shutdown_clears_resources_and_prompts(self):
+        mgr = MCPClientManager({})
+        mgr._per_server_resources = {"a": [_fake_resource_dict()]}
+        mgr._rebuild_resources()
+        mgr._per_server_prompts = {"a": [_fake_prompt_dict()]}
+        mgr._rebuild_prompts()
+        assert mgr.get_resources() != []
+        assert mgr.get_prompts() != []
+
+        mgr.shutdown()
+        assert mgr.get_resources() == []
+        assert mgr.get_prompts() == []
+        assert mgr._resource_map == {}
+        assert mgr._prompt_map == {}

tests/test_mcp_integration.py

@@ -0,0 +1,397 @@
+"""Integration tests for MCPClientManager data flow.
+
+Uses real storage (SQLite) and real MCPClientManager state manipulation,
+but mock MCP sessions instead of wire-protocol connections. This validates
+the full data pipeline: per-server data -> rebuild -> merged state ->
+query methods -> storage sync -> shutdown cleanup.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from turnstone.core.mcp_client import MCPClientManager
+from turnstone.core.storage._sqlite import SQLiteBackend
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_resource(
+    uri: str, name: str, server: str, description: str = "", mime: str = "text/plain"
+) -> dict[str, Any]:
+    return {
+        "uri": uri,
+        "name": name,
+        "description": description,
+        "mimeType": mime,
+        "server": server,
+    }
+
+
+def _make_prompt(
+    prefixed_name: str,
+    original_name: str,
+    server: str,
+    description: str = "",
+    arguments: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    return {
+        "name": prefixed_name,
+        "original_name": original_name,
+        "server": server,
+        "description": description,
+        "arguments": arguments or [],
+    }
+
+
+def _make_mock_session(
+    read_resource_result: Any = None,
+    get_prompt_result: Any = None,
+) -> AsyncMock:
+    """Build a mock ClientSession with configurable async return values."""
+    session = AsyncMock()
+
+    if read_resource_result is not None:
+        session.read_resource.return_value = read_resource_result
+    else:
+        # Default: single text content
+        content_item = MagicMock()
+        content_item.text = "resource content"
+        result = MagicMock()
+        result.contents = [content_item]
+        session.read_resource.return_value = result
+
+    if get_prompt_result is not None:
+        session.get_prompt.return_value = get_prompt_result
+    else:
+        msg = MagicMock()
+        msg.role = "user"
+        msg.content = MagicMock()
+        msg.content.text = "Hello, World!"
+        result = MagicMock()
+        result.messages = [msg]
+        session.get_prompt.return_value = result
+
+    return session
+
+
+# ---------------------------------------------------------------------------
+# Integration test class
+# ---------------------------------------------------------------------------
+
+
+class TestFullLifecycleResourcesPrompts:
+    """Integration test exercising real code paths with real SQLite storage
+    but mock MCP sessions.
+
+    Validates the complete data flow: per-server data population, rebuild
+    merging, query methods, resource/prompt dispatch through asyncio, storage
+    sync, and shutdown cleanup.
+    """
+
+    @pytest.fixture()
+    def mgr(self) -> MCPClientManager:
+        """Create an MCPClientManager with no server configs (no start())."""
+        return MCPClientManager({})
+
+    @pytest.fixture()
+    def db(self, tmp_path) -> SQLiteBackend:
+        """Create a fresh SQLite backend for each test."""
+        backend = SQLiteBackend(str(tmp_path / "test.db"))
+        yield backend
+        backend.close()
+
+    def test_rebuild_resources_produces_merged_state(self, mgr: MCPClientManager) -> None:
+        """_rebuild_resources merges per-server resources into a unified list."""
+        mgr._per_server_resources["alpha"] = [
+            _make_resource("file:///a.txt", "a", "alpha"),
+            _make_resource("file:///b.txt", "b", "alpha"),
+        ]
+        mgr._per_server_resources["beta"] = [
+            _make_resource("file:///c.txt", "c", "beta"),
+        ]
+
+        mgr._rebuild_resources()
+
+        resources = mgr.get_resources()
+        assert len(resources) == 3
+        uris = {r["uri"] for r in resources}
+        assert uris == {"file:///a.txt", "file:///b.txt", "file:///c.txt"}
+        # resource_map should have entries for all non-template resources
+        assert "file:///a.txt" in mgr._resource_map
+        assert "file:///c.txt" in mgr._resource_map
+        assert mgr.resource_count == 3
+
+    def test_rebuild_prompts_produces_merged_state(self, mgr: MCPClientManager) -> None:
+        """_rebuild_prompts merges per-server prompts into a unified list."""
+        mgr._per_server_prompts["alpha"] = [
+            _make_prompt("mcp__alpha__greet", "greet", "alpha", "Say hello"),
+        ]
+        mgr._per_server_prompts["beta"] = [
+            _make_prompt("mcp__beta__summarize", "summarize", "beta", "Summarize text"),
+            _make_prompt("mcp__beta__translate", "translate", "beta", "Translate text"),
+        ]
+
+        mgr._rebuild_prompts()
+
+        prompts = mgr.get_prompts()
+        assert len(prompts) == 3
+        names = {p["name"] for p in prompts}
+        assert names == {"mcp__alpha__greet", "mcp__beta__summarize", "mcp__beta__translate"}
+        # prompt_map should map prefixed -> (server, original)
+        assert mgr._prompt_map["mcp__alpha__greet"] == ("alpha", "greet")
+        assert mgr._prompt_map["mcp__beta__summarize"] == ("beta", "summarize")
+        assert mgr.prompt_count == 3
+        assert mgr.is_mcp_prompt("mcp__alpha__greet") is True
+        assert mgr.is_mcp_prompt("nonexistent") is False
+
+    def test_read_resource_sync_dispatches_correctly(self, mgr: MCPClientManager) -> None:
+        """read_resource_sync dispatches to the correct session via a real asyncio loop."""
+        # Set up a real event loop in a thread (simulating start())
+        loop = asyncio.new_event_loop()
+        import threading
+
+        thread = threading.Thread(target=loop.run_forever, daemon=True)
+        thread.start()
+        mgr._loop = loop
+
+        try:
+            # Populate session and resource map
+            session = _make_mock_session()
+            mgr._sessions["alpha"] = session
+            mgr._per_server_resources["alpha"] = [
+                _make_resource("file:///readme.md", "readme", "alpha"),
+            ]
+            mgr._rebuild_resources()
+
+            result = mgr.read_resource_sync("file:///readme.md", timeout=5)
+            assert result == "resource content"
+            session.read_resource.assert_awaited_once_with("file:///readme.md")
+        finally:
+            loop.call_soon_threadsafe(loop.stop)
+            thread.join(timeout=5)
+            loop.close()
+
+    def test_read_resource_sync_unknown_uri_raises(self, mgr: MCPClientManager) -> None:
+        """read_resource_sync raises ValueError for an unknown URI."""
+        with pytest.raises(ValueError, match="Unknown MCP resource"):
+            mgr.read_resource_sync("file:///nonexistent")
+
+    def test_read_resource_via_template(self, mgr: MCPClientManager) -> None:
+        """Expanded template URI dispatched to correct server via real asyncio loop."""
+        loop = asyncio.new_event_loop()
+        import threading
+
+        thread = threading.Thread(target=loop.run_forever, daemon=True)
+        thread.start()
+        mgr._loop = loop
+
+        try:
+            session = _make_mock_session()
+            mgr._sessions["alpha"] = session
+            # Register a template resource (no concrete resources)
+            mgr._per_server_resources["alpha"] = [
+                {
+                    "uri": "db://tables/{table}/rows/{id}",
+                    "name": "row",
+                    "description": "Fetch a row",
+                    "mimeType": "application/json",
+                    "server": "alpha",
+                    "template": True,
+                },
+            ]
+            mgr._rebuild_resources()
+
+            # Template should not be in _resource_map
+            assert "db://tables/{table}/rows/{id}" not in mgr._resource_map
+            # But expanded URI should resolve via prefix matching
+            result = mgr.read_resource_sync("db://tables/users/rows/42", timeout=5)
+            assert result == "resource content"
+            session.read_resource.assert_awaited_once_with("db://tables/users/rows/42")
+        finally:
+            loop.call_soon_threadsafe(loop.stop)
+            thread.join(timeout=5)
+            loop.close()
+
+    def test_get_prompt_sync_dispatches_correctly(self, mgr: MCPClientManager) -> None:
+        """get_prompt_sync dispatches to the correct session via a real asyncio loop."""
+        loop = asyncio.new_event_loop()
+        import threading
+
+        thread = threading.Thread(target=loop.run_forever, daemon=True)
+        thread.start()
+        mgr._loop = loop
+
+        try:
+            session = _make_mock_session()
+            mgr._sessions["alpha"] = session
+            mgr._per_server_prompts["alpha"] = [
+                _make_prompt("mcp__alpha__greet", "greet", "alpha", "Say hello"),
+            ]
+            mgr._rebuild_prompts()
+
+            messages = mgr.get_prompt_sync(
+                "mcp__alpha__greet", arguments={"name": "World"}, timeout=5
+            )
+            assert len(messages) == 1
+            assert messages[0]["role"] == "user"
+            assert messages[0]["content"] == "Hello, World!"
+            session.get_prompt.assert_awaited_once_with("greet", arguments={"name": "World"})
+        finally:
+            loop.call_soon_threadsafe(loop.stop)
+            thread.join(timeout=5)
+            loop.close()
+
+    def test_get_prompt_sync_unknown_name_raises(self, mgr: MCPClientManager) -> None:
+        """get_prompt_sync raises ValueError for an unknown prompt name."""
+        with pytest.raises(ValueError, match="Unknown MCP prompt"):
+            mgr.get_prompt_sync("mcp__nosrv__nope")
+
+    def test_sync_prompts_to_storage_creates_templates(
+        self, mgr: MCPClientManager, db: SQLiteBackend
+    ) -> None:
+        """sync_prompts_to_storage creates governance templates in real SQLite."""
+        mgr.set_storage(db)
+        mgr._prompts = [
+            _make_prompt(
+                "mcp__alpha__greet",
+                "greet",
+                "alpha",
+                "Say hello",
+                [{"name": "user", "description": "Who to greet", "required": True}],
+            ),
+            _make_prompt(
+                "mcp__beta__summarize",
+                "summarize",
+                "beta",
+                "Summarize text",
+            ),
+        ]
+        # Mark connected so set_storage triggers sync
+        mgr._connected.set()
+        # Re-set storage to trigger auto-sync
+        mgr.set_storage(db)
+
+        templates = db.list_prompt_templates()
+        assert len(templates) == 2
+        names = {t["name"] for t in templates}
+        assert names == {"mcp__alpha__greet", "mcp__beta__summarize"}
+
+        # Verify details on first template
+        tpl = db.get_prompt_template_by_name("mcp__alpha__greet")
+        assert tpl is not None
+        assert tpl["origin"] == "mcp"
+        assert tpl["mcp_server"] == "alpha"
+        assert tpl["readonly"] is True
+        assert tpl["category"] == "mcp"
+        assert "user" in tpl["variables"]
+
+    def test_sync_prompts_removes_stale_templates(
+        self, mgr: MCPClientManager, db: SQLiteBackend
+    ) -> None:
+        """sync_prompts_to_storage removes templates whose MCP prompts are gone."""
+        mgr.set_storage(db)
+
+        # Create an initial template via sync
+        mgr._prompts = [
+            _make_prompt("mcp__alpha__old", "old", "alpha", "Old prompt"),
+        ]
+        mgr.sync_prompts_to_storage()
+        assert len(db.list_prompt_templates()) == 1
+
+        # Now the prompt is gone
+        mgr._prompts = []
+        result = mgr.sync_prompts_to_storage()
+        assert result["removed"] == ["mcp__alpha__old"]
+        assert len(db.list_prompt_templates()) == 0
+
+    def test_shutdown_clears_all_state(self, mgr: MCPClientManager) -> None:
+        """shutdown() clears sessions, tools, resources, prompts, and listeners."""
+        # Populate state
+        mgr._sessions["alpha"] = MagicMock()
+        mgr._per_server_tools["alpha"] = [
+            {
+                "type": "function",
+                "function": {
+                    "name": "mcp__alpha__search",
+                    "description": "Search",
+                    "parameters": {},
+                },
+            }
+        ]
+        mgr._rebuild_tools()
+        mgr._per_server_resources["alpha"] = [
+            _make_resource("file:///a.txt", "a", "alpha"),
+            {
+                "uri": "db://tables/{table}",
+                "name": "table",
+                "description": "",
+                "mimeType": "",
+                "server": "alpha",
+                "template": True,
+            },
+        ]
+        mgr._rebuild_resources()
+        mgr._per_server_prompts["alpha"] = [
+            _make_prompt("mcp__alpha__greet", "greet", "alpha"),
+        ]
+        mgr._rebuild_prompts()
+        mgr._listeners.append(lambda: None)
+        mgr._resource_listeners.append(lambda: None)
+        mgr._prompt_listeners.append(lambda: None)
+
+        # Verify populated
+        assert len(mgr._sessions) == 1
+        assert len(mgr._tools) == 1
+        assert len(mgr._resources) == 2  # 1 concrete + 1 template
+        assert len(mgr._template_prefixes) == 1
+        assert len(mgr._prompts) == 1
+
+        mgr.shutdown()
+
+        assert len(mgr._sessions) == 0
+        assert len(mgr._tools) == 0
+        assert len(mgr._tool_map) == 0
+        assert len(mgr._resources) == 0
+        assert len(mgr._resource_map) == 0
+        assert len(mgr._template_prefixes) == 0
+        assert len(mgr._prompts) == 0
+        assert len(mgr._prompt_map) == 0
+        assert len(mgr._listeners) == 0
+        assert len(mgr._resource_listeners) == 0
+        assert len(mgr._prompt_listeners) == 0
+
+    def test_listener_notifications_fire_on_rebuild(self, mgr: MCPClientManager) -> None:
+        """Rebuild methods fire the appropriate listener callbacks."""
+        tool_fired = []
+        resource_fired = []
+        prompt_fired = []
+        mgr.add_listener(lambda: tool_fired.append(1))
+        mgr.add_resource_listener(lambda: resource_fired.append(1))
+        mgr.add_prompt_listener(lambda: prompt_fired.append(1))
+
+        mgr._per_server_tools["alpha"] = []
+        mgr._rebuild_tools()
+        assert len(tool_fired) == 1
+
+        mgr._per_server_resources["alpha"] = [
+            _make_resource("file:///x.txt", "x", "alpha"),
+        ]
+        mgr._rebuild_resources()
+        assert len(resource_fired) == 1
+
+        mgr._per_server_prompts["alpha"] = [
+            _make_prompt("mcp__alpha__p1", "p1", "alpha"),
+        ]
+        mgr._rebuild_prompts()
+        assert len(prompt_fired) == 1
+
+        # Tool and resource listeners should not have been fired again
+        assert len(tool_fired) == 1
+        assert len(resource_fired) == 1

tests/test_mcp_prompt_sync.py

@@ -0,0 +1,272 @@
+"""Tests for MCP prompt → governance template sync and readonly API guards."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock
+
+import pytest
+
+from turnstone.core.mcp_client import MCPClientManager
+
+
+@pytest.fixture()
+def mgr() -> MCPClientManager:
+    """Create an MCPClientManager with no real servers (no start())."""
+    return MCPClientManager({})
+
+
+def _make_storage() -> MagicMock:
+    """Create a mock storage backend with prompt template methods."""
+    storage = MagicMock()
+    storage.get_prompt_template_by_name.return_value = None
+    storage.list_prompt_templates_by_origin.return_value = []
+    storage.create_prompt_template.return_value = None
+    storage.update_prompt_template.return_value = True
+    storage.delete_prompt_template.return_value = True
+    return storage
+
+
+class TestSyncPromptsToStorage:
+    def test_sync_no_storage(self, mgr: MCPClientManager) -> None:
+        """Without storage set, sync returns empty stats."""
+        result = mgr.sync_prompts_to_storage()
+        assert result == {"added": [], "removed": [], "skipped": []}
+
+    def test_sync_creates_mcp_templates(self, mgr: MCPClientManager) -> None:
+        """New MCP prompts are created as templates."""
+        storage = _make_storage()
+        mgr.set_storage(storage)
+
+        # Populate internal prompts list directly
+        mgr._prompts = [
+            {
+                "name": "mcp__test__greeting",
+                "original_name": "greeting",
+                "server": "test",
+                "description": "Say hello",
+                "arguments": [
+                    {"name": "name", "description": "Who to greet", "required": True},
+                ],
+            },
+        ]
+
+        result = mgr.sync_prompts_to_storage()
+
+        assert result["added"] == ["mcp__test__greeting"]
+        assert result["removed"] == []
+        assert result["skipped"] == []
+        storage.create_prompt_template.assert_called_once()
+        call_kwargs = storage.create_prompt_template.call_args
+        assert call_kwargs[1]["name"] == "mcp__test__greeting"
+        assert call_kwargs[1]["origin"] == "mcp"
+        assert call_kwargs[1]["mcp_server"] == "test"
+        assert call_kwargs[1]["readonly"] is True
+        assert call_kwargs[1]["category"] == "mcp"
+        assert '"name"' in call_kwargs[1]["variables"]
+
+    def test_sync_skips_manual_overrides(self, mgr: MCPClientManager) -> None:
+        """A manual template with the same name is not overwritten."""
+        storage = _make_storage()
+        storage.get_prompt_template_by_name.return_value = {
+            "template_id": "existing-id",
+            "name": "mcp__test__greeting",
+            "origin": "manual",
+            "readonly": False,
+        }
+        mgr.set_storage(storage)
+
+        mgr._prompts = [
+            {
+                "name": "mcp__test__greeting",
+                "original_name": "greeting",
+                "server": "test",
+                "description": "Say hello",
+                "arguments": [],
+            },
+        ]
+
+        result = mgr.sync_prompts_to_storage()
+
+        assert result["skipped"] == ["mcp__test__greeting"]
+        assert result["added"] == []
+        storage.create_prompt_template.assert_not_called()
+        storage.update_prompt_template.assert_not_called()
+
+    def test_sync_updates_existing_mcp_template(self, mgr: MCPClientManager) -> None:
+        """An existing MCP template gets its content/variables updated."""
+        storage = _make_storage()
+        storage.get_prompt_template_by_name.return_value = {
+            "template_id": "existing-id",
+            "name": "mcp__test__greeting",
+            "origin": "mcp",
+            "mcp_server": "test",
+            "readonly": True,
+        }
+        mgr.set_storage(storage)
+
+        mgr._prompts = [
+            {
+                "name": "mcp__test__greeting",
+                "original_name": "greeting",
+                "server": "test",
+                "description": "Updated description",
+                "arguments": [
+                    {"name": "user", "description": "The user", "required": False},
+                ],
+            },
+        ]
+
+        result = mgr.sync_prompts_to_storage()
+
+        assert result["added"] == []
+        assert result["skipped"] == []
+        storage.create_prompt_template.assert_not_called()
+        storage.update_prompt_template.assert_called_once()
+        call_args = storage.update_prompt_template.call_args
+        assert call_args[0][0] == "existing-id"
+        assert "Updated description" in call_args[1]["content"]
+        assert "user" in call_args[1]["variables"]
+        # Security: is_default must be reset to prevent compromised MCP server
+        # from injecting content into a previously admin-promoted default
+        assert call_args[1]["is_default"] is False
+
+    def test_sync_resets_is_default_on_promoted_template(self, mgr: MCPClientManager) -> None:
+        """An MCP template promoted to default by admin gets is_default reset on sync."""
+        storage = _make_storage()
+        storage.get_prompt_template_by_name.return_value = {
+            "template_id": "promoted-id",
+            "name": "mcp__test__greeting",
+            "origin": "mcp",
+            "mcp_server": "test",
+            "readonly": True,
+            "is_default": True,  # admin toggled this
+        }
+        mgr.set_storage(storage)
+
+        mgr._prompts = [
+            {
+                "name": "mcp__test__greeting",
+                "original_name": "greeting",
+                "server": "test",
+                "description": "Potentially compromised content",
+                "arguments": [],
+            },
+        ]
+
+        mgr.sync_prompts_to_storage()
+
+        call_args = storage.update_prompt_template.call_args
+        assert call_args[1]["is_default"] is False
+
+    def test_sync_removes_deleted_prompts(self, mgr: MCPClientManager) -> None:
+        """MCP templates in storage with no matching prompt are deleted."""
+        storage = _make_storage()
+        storage.list_prompt_templates_by_origin.return_value = [
+            {
+                "template_id": "old-id",
+                "name": "mcp__test__old_prompt",
+                "origin": "mcp",
+                "mcp_server": "test",
+            },
+        ]
+        mgr.set_storage(storage)
+        mgr._prompts = []  # No prompts at all
+
+        result = mgr.sync_prompts_to_storage()
+
+        assert result["removed"] == ["mcp__test__old_prompt"]
+        storage.delete_prompt_template.assert_called_once_with("old-id")
+
+
+class TestSetStorageAutoSync:
+    """set_storage() triggers an immediate sync when servers are already connected."""
+
+    def test_set_storage_syncs_when_connected(self, mgr) -> None:
+        storage = _make_storage()
+        mgr._prompts = [
+            {
+                "name": "mcp__srv__p1",
+                "original_name": "p1",
+                "server": "srv",
+                "description": "A prompt",
+                "arguments": [],
+            }
+        ]
+        mgr._connected.set()
+
+        mgr.set_storage(storage)
+
+        # Should have called create_prompt_template for the discovered prompt
+        storage.create_prompt_template.assert_called_once()
+        call_kwargs = storage.create_prompt_template.call_args
+        assert call_kwargs[1]["name"] == "mcp__srv__p1"
+        assert call_kwargs[1]["origin"] == "mcp"
+
+    def test_set_storage_no_sync_when_not_connected(self, mgr) -> None:
+        storage = _make_storage()
+        mgr._prompts = [
+            {
+                "name": "mcp__srv__p1",
+                "original_name": "p1",
+                "server": "srv",
+                "description": "A prompt",
+                "arguments": [],
+            }
+        ]
+        # _connected is NOT set
+
+        mgr.set_storage(storage)
+
+        # Should not have synced
+        storage.create_prompt_template.assert_not_called()
+
+
+class TestReadonlyAPIGuards:
+    """Test that the console server API guards reject edits to readonly templates."""
+
+    @pytest.fixture()
+    def db(self, tmp_path):
+        """Create a fresh SQLite backend for each test."""
+        from turnstone.core.storage._sqlite import SQLiteBackend
+
+        return SQLiteBackend(str(tmp_path / "test.db"))
+
+    def test_readonly_guard_update(self, db) -> None:
+        """Readonly templates cannot be updated via storage guard logic."""
+        db.create_prompt_template(
+            "t1",
+            "mcp__srv__prompt",
+            "mcp",
+            "content",
+            variables="[]",
+            is_default=False,
+            org_id="",
+            created_by="",
+            origin="mcp",
+            mcp_server="srv",
+            readonly=True,
+        )
+        tpl = db.get_prompt_template("t1")
+        assert tpl is not None
+        assert tpl["readonly"] is True
+        # Simulate API guard check
+        assert tpl.get("readonly") is True
+
+    def test_readonly_guard_delete(self, db) -> None:
+        """Readonly templates are flagged for API-level rejection."""
+        db.create_prompt_template(
+            "t1",
+            "mcp__srv__prompt",
+            "mcp",
+            "content",
+            variables="[]",
+            is_default=False,
+            org_id="",
+            created_by="",
+            origin="mcp",
+            mcp_server="srv",
+            readonly=True,
+        )
+        existing = db.get_prompt_template("t1")
+        assert existing is not None
+        assert existing.get("readonly") is True

tests/test_model_registry.py

@@ -534,7 +534,7 @@ class TestWorkstreamModelParam:
             nonlocal captured_alias
             captured_alias = model_alias
             mock_session = MagicMock()
-            mock_session.session_id = "test123"
+            mock_session.ws_id = "test123"
             return mock_session
 
         mgr = WorkstreamManager(factory)
@@ -548,7 +548,7 @@ class TestWorkstreamModelParam:
             nonlocal captured_alias
             captured_alias = model_alias
             mock_session = MagicMock()
-            mock_session.session_id = "test123"
+            mock_session.ws_id = "test123"
             return mock_session
 
         from turnstone.core.workstream import WorkstreamManager

tests/test_notify_tool.py

@@ -14,7 +14,7 @@ def _make_session() -> ChatSession:
     from unittest.mock import patch
 
     with (
-        patch("turnstone.core.session.register_session"),
+        patch("turnstone.core.memory.register_workstream"),
         patch("turnstone.core.session.save_message"),
     ):
         from turnstone.core.session import ChatSession

tests/test_openapi.py

@@ -27,7 +27,7 @@ class TestServerSpec:
         expected = {
             "/v1/api/workstreams",
             "/v1/api/dashboard",
-            "/v1/api/sessions",
+            "/v1/api/workstreams/saved",
             "/v1/api/send",
             "/v1/api/approve",
             "/v1/api/plan",

tests/test_prompt_templates_runtime.py

@@ -0,0 +1,393 @@
+"""Tests for prompt template runtime wiring into ChatSession."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock
+
+from turnstone.core.session import ChatSession, _render_template
+
+
+class NullUI:
+    """UI adapter that discards all output."""
+
+    def on_thinking_start(self):
+        pass
+
+    def on_thinking_stop(self):
+        pass
+
+    def on_reasoning_token(self, text):
+        pass
+
+    def on_content_token(self, text):
+        pass
+
+    def on_stream_end(self):
+        pass
+
+    def approve_tools(self, items):
+        return True, None
+
+    def on_tool_result(self, call_id, name, output):
+        pass
+
+    def on_tool_output_chunk(self, call_id, chunk):
+        pass
+
+    def on_status(self, usage, context_window, effort):
+        pass
+
+    def on_plan_review(self, content):
+        return ""
+
+    def on_info(self, message):
+        pass
+
+    def on_error(self, message):
+        pass
+
+    def on_state_change(self, state):
+        pass
+
+    def on_rename(self, name):
+        pass
+
+
+def _make_session(**kwargs):
+    defaults = dict(
+        client=MagicMock(),
+        model="test-model",
+        ui=NullUI(),
+        instructions=None,
+        temperature=0.5,
+        max_tokens=4096,
+        tool_timeout=30,
+    )
+    defaults.update(kwargs)
+    return ChatSession(**defaults)
+
+
+def _sys_content(session: ChatSession) -> str:
+    """Extract the system message content."""
+    msgs = [m for m in session.system_messages if m["role"] == "system"]
+    assert msgs
+    return msgs[0]["content"]
+
+
+def _create_template(db, template_id, name, content, is_default=False, **kwargs):
+    """Helper to create a prompt template in storage."""
+    db.create_prompt_template(
+        template_id=template_id,
+        name=name,
+        category=kwargs.get("category", "general"),
+        content=content,
+        variables=kwargs.get("variables", "[]"),
+        is_default=is_default,
+        org_id=kwargs.get("org_id", ""),
+        created_by=kwargs.get("created_by", "test"),
+        origin=kwargs.get("origin", "manual"),
+        mcp_server=kwargs.get("mcp_server", ""),
+        readonly=kwargs.get("readonly", False),
+    )
+
+
+# ---------------------------------------------------------------------------
+# _render_template unit tests
+# ---------------------------------------------------------------------------
+
+
+class TestRenderTemplate:
+    def test_basic_substitution(self):
+        result = _render_template("Hello {{name}}", {"name": "world"})
+        assert result == "Hello world"
+
+    def test_multiple_variables(self):
+        result = _render_template(
+            "Model: {{model}}, WS: {{ws_id}}", {"model": "gpt-5", "ws_id": "abc123"}
+        )
+        assert result == "Model: gpt-5, WS: abc123"
+
+    def test_unresolvable_variable_kept(self):
+        result = _render_template("Hello {{unknown}}", {"model": "gpt-5"})
+        assert result == "Hello {{unknown}}"
+
+    def test_empty_context(self):
+        result = _render_template("No vars here", {})
+        assert result == "No vars here"
+
+    def test_duplicate_placeholder(self):
+        result = _render_template("{{x}} and {{x}}", {"x": "val"})
+        assert result == "val and val"
+
+    def test_no_cross_variable_injection(self):
+        # If model contains {{ws_id}}, it must NOT be expanded
+        result = _render_template("Model: {{model}}", {"model": "{{ws_id}}", "ws_id": "secret"})
+        assert result == "Model: {{ws_id}}"
+        assert "secret" not in result
+
+
+# ---------------------------------------------------------------------------
+# Default templates in system message
+# ---------------------------------------------------------------------------
+
+
+class TestDefaultTemplates:
+    def test_default_templates_in_system_message(self, tmp_db):
+        from turnstone.core.storage import get_storage
+
+        db = get_storage()
+        _create_template(db, "t1", "alpha", "You are a helpful assistant.", is_default=True)
+        _create_template(db, "t2", "beta", "Always be concise.", is_default=True)
+
+        session = _make_session()
+        content = _sys_content(session)
+        assert "You are a helpful assistant." in content
+        assert "Always be concise." in content
+
+    def test_default_templates_ordered_by_name(self, tmp_db):
+        from turnstone.core.storage import get_storage
+
+        db = get_storage()
+        _create_template(db, "t2", "b-template", "SECOND", is_default=True)
+        _create_template(db, "t1", "a-template", "FIRST", is_default=True)
+
+        session = _make_session()
+        content = _sys_content(session)
+        first_pos = content.index("FIRST")
+        second_pos = content.index("SECOND")
+        assert first_pos < second_pos
+
+    def test_no_default_templates(self, tmp_db):
+        from turnstone.core.storage import get_storage
+
+        db = get_storage()
+        _create_template(db, "t1", "alpha", "Not default.", is_default=False)
+
+        session = _make_session()
+        content = _sys_content(session)
+        assert "Not default." not in content
+
+    def test_templates_before_instructions(self, tmp_db):
+        from turnstone.core.storage import get_storage
+
+        db = get_storage()
+        _create_template(db, "t1", "tpl", "TEMPLATE_CONTENT", is_default=True)
+
+        session = _make_session(instructions="USER_INSTRUCTIONS")
+        content = _sys_content(session)
+        tpl_pos = content.index("TEMPLATE_CONTENT")
+        instr_pos = content.index("USER_INSTRUCTIONS")
+        assert tpl_pos < instr_pos
+
+
+# ---------------------------------------------------------------------------
+# Explicit template selection
+# ---------------------------------------------------------------------------
+
+
+class TestExplicitTemplate:
+    def test_explicit_template_replaces_defaults(self, tmp_db):
+        from turnstone.core.storage import get_storage
+
+        db = get_storage()
+        _create_template(db, "t1", "default-tpl", "DEFAULT_CONTENT", is_default=True)
+        _create_template(db, "t2", "specific-tpl", "SPECIFIC_CONTENT", is_default=False)
+
+        session = _make_session(template="specific-tpl")
+        content = _sys_content(session)
+        assert "SPECIFIC_CONTENT" in content
+        assert "DEFAULT_CONTENT" not in content
+
+    def test_explicit_template_not_found(self, tmp_db):
+        session = _make_session(template="nonexistent")
+        content = _sys_content(session)
+        # Graceful degradation — no template content injected
+        assert "nonexistent" not in content
+
+
+# ---------------------------------------------------------------------------
+# Variable substitution in templates
+# ---------------------------------------------------------------------------
+
+
+class TestTemplateVariables:
+    def test_model_and_ws_id_substituted(self, tmp_db):
+        from turnstone.core.storage import get_storage
+
+        db = get_storage()
+        _create_template(db, "t1", "vars-tpl", "Model: {{model}}, WS: {{ws_id}}", is_default=True)
+
+        session = _make_session()
+        content = _sys_content(session)
+        assert "Model: test-model" in content
+        assert f"WS: {session.ws_id}" in content
+
+    def test_node_id_substituted(self, tmp_db):
+        from turnstone.core.storage import get_storage
+
+        db = get_storage()
+        _create_template(db, "t1", "node-tpl", "Node: {{node_id}}", is_default=True)
+
+        session = _make_session(node_id="node-42")
+        content = _sys_content(session)
+        assert "Node: node-42" in content
+
+    def test_unknown_variable_preserved(self, tmp_db):
+        from turnstone.core.storage import get_storage
+
+        db = get_storage()
+        _create_template(db, "t1", "unknown-tpl", "Val: {{unknown_var}}", is_default=True)
+
+        session = _make_session()
+        content = _sys_content(session)
+        assert "Val: {{unknown_var}}" in content
+
+
+# ---------------------------------------------------------------------------
+# Template persistence and resume
+# ---------------------------------------------------------------------------
+
+
+class TestTemplatePersistence:
+    def test_template_persisted_in_config(self, tmp_db):
+        from turnstone.core.memory import load_workstream_config
+        from turnstone.core.storage import get_storage
+
+        db = get_storage()
+        _create_template(db, "t1", "my-tpl", "TPL_CONTENT", is_default=False)
+
+        session = _make_session(template="my-tpl")
+        config = load_workstream_config(session.ws_id)
+        assert config["template"] == "my-tpl"
+
+    def test_template_restored_on_resume(self, tmp_db):
+        from turnstone.core.memory import save_message
+        from turnstone.core.storage import get_storage
+
+        db = get_storage()
+        _create_template(db, "t1", "my-tpl", "PERSISTED_TEMPLATE", is_default=False)
+
+        # Create session with template, save a message so resume has history
+        session1 = _make_session(template="my-tpl")
+        ws_id = session1.ws_id
+        save_message(ws_id, "user", "hello")
+
+        # New session without template, then resume
+        session2 = _make_session()
+        assert session2._template_name is None
+        resumed = session2.resume(ws_id)
+        assert resumed
+        assert session2._template_name == "my-tpl"
+        content = _sys_content(session2)
+        assert "PERSISTED_TEMPLATE" in content
+
+    def test_empty_template_config_means_defaults(self, tmp_db):
+        from turnstone.core.memory import load_workstream_config
+
+        session = _make_session()
+        config = load_workstream_config(session.ws_id)
+        assert config["template"] == ""
+
+
+# ---------------------------------------------------------------------------
+# /template slash command
+# ---------------------------------------------------------------------------
+
+
+class TestTemplateSlashCommand:
+    def test_template_set(self, tmp_db):
+        from turnstone.core.storage import get_storage
+
+        db = get_storage()
+        _create_template(db, "t1", "my-tpl", "SLASH_TEMPLATE", is_default=False)
+
+        session = _make_session()
+        content_before = _sys_content(session)
+        assert "SLASH_TEMPLATE" not in content_before
+
+        session.handle_command("/template my-tpl")
+        assert session._template_name == "my-tpl"
+        content_after = _sys_content(session)
+        assert "SLASH_TEMPLATE" in content_after
+
+    def test_template_clear(self, tmp_db):
+        from turnstone.core.storage import get_storage
+
+        db = get_storage()
+        _create_template(db, "t1", "my-tpl", "EXPLICIT_TEMPLATE", is_default=False)
+        _create_template(db, "t2", "default-tpl", "DEFAULT_TEMPLATE", is_default=True)
+
+        session = _make_session(template="my-tpl")
+        assert "EXPLICIT_TEMPLATE" in _sys_content(session)
+        assert "DEFAULT_TEMPLATE" not in _sys_content(session)
+
+        session.handle_command("/template clear")
+        assert session._template_name is None
+        assert "DEFAULT_TEMPLATE" in _sys_content(session)
+        assert "EXPLICIT_TEMPLATE" not in _sys_content(session)
+
+    def test_template_not_found(self, tmp_db):
+        ui = NullUI()
+        ui.on_error = MagicMock()
+        session = _make_session(ui=ui)
+        session.handle_command("/template nonexistent")
+        ui.on_error.assert_called_once()
+        assert "not found" in ui.on_error.call_args[0][0].lower()
+
+    def test_template_show_current(self, tmp_db):
+        from turnstone.core.storage import get_storage
+
+        db = get_storage()
+        _create_template(db, "t1", "my-tpl", "content", is_default=False)
+
+        ui = NullUI()
+        ui.on_info = MagicMock()
+        session = _make_session(ui=ui, template="my-tpl")
+        session.handle_command("/template")
+        ui.on_info.assert_called_once()
+        assert "my-tpl" in ui.on_info.call_args[0][0]
+
+
+# ---------------------------------------------------------------------------
+# MCP-origin templates
+# ---------------------------------------------------------------------------
+
+
+class TestMCPTemplates:
+    def test_mcp_readonly_template_as_default(self, tmp_db):
+        from turnstone.core.storage import get_storage
+
+        db = get_storage()
+        _create_template(
+            db,
+            "t1",
+            "mcp__server__prompt",
+            "MCP_CONTENT",
+            is_default=True,
+            origin="mcp",
+            mcp_server="server",
+            readonly=True,
+        )
+
+        session = _make_session()
+        content = _sys_content(session)
+        assert "MCP_CONTENT" in content
+
+    def test_mcp_template_selectable_explicitly(self, tmp_db):
+        from turnstone.core.storage import get_storage
+
+        db = get_storage()
+        _create_template(
+            db,
+            "t1",
+            "mcp__server__code",
+            "MCP_EXPLICIT",
+            is_default=False,
+            origin="mcp",
+            mcp_server="server",
+            readonly=True,
+        )
+
+        session = _make_session(template="mcp__server__code")
+        content = _sys_content(session)
+        assert "MCP_EXPLICIT" in content

tests/test_protocol.py

@@ -8,6 +8,7 @@ from turnstone.mq.protocol import (
     AckEvent,
     ApprovalRequestEvent,
     ApproveMessage,
+    CancelMessage,
     CloseWorkstreamMessage,
     CommandMessage,
     ContentEvent,
@@ -68,6 +69,7 @@ INBOUND_TYPES = [
     (ListWorkstreamsMessage, {}),
     (HealthMessage, {}),
     (ListNodesMessage, {}),
+    (CancelMessage, {"ws_id": "abc"}),
 ]
 
 
@@ -207,6 +209,20 @@ def test_create_workstream_target_node():
     assert restored.name == "debug-ws"
 
 
+def test_create_workstream_template_field():
+    msg = CreateWorkstreamMessage(name="ws", template="code-review")
+    assert msg.template == "code-review"
+    raw = msg.to_json()
+    restored = InboundMessage.from_json(raw)
+    assert isinstance(restored, CreateWorkstreamMessage)
+    assert restored.template == "code-review"
+
+
+def test_create_workstream_template_default_empty():
+    msg = CreateWorkstreamMessage(name="ws")
+    assert msg.template == ""
+
+
 def test_list_nodes_round_trip():
     msg = ListNodesMessage()
     raw = msg.to_json()

tests/test_providers.py

@@ -1933,3 +1933,254 @@ class TestAnthropicProviderBlocks:
         assert blocks[1]["input"] == {"query": "test"}  # parsed from accumulated JSON
         assert blocks[2]["type"] == "web_search_tool_result"
         assert blocks[2]["encrypted_content"] == "enc_data"
+
+
+# ---------------------------------------------------------------------------
+# Tool search tests
+# ---------------------------------------------------------------------------
+
+
+class TestAnthropicToolSearch:
+    """Test Anthropic provider tool search injection."""
+
+    @pytest.fixture()
+    def provider(self):
+        from turnstone.core.providers._anthropic import AnthropicProvider
+
+        return AnthropicProvider()
+
+    def test_tool_search_capability_flag(self, provider):
+        caps = provider.get_capabilities("claude-opus-4-6-20260101")
+        assert caps.supports_tool_search is True
+
+    def test_tool_search_not_supported_on_haiku(self, provider):
+        caps = provider.get_capabilities("claude-haiku-4-5-20251001")
+        assert caps.supports_tool_search is False
+
+    def test_inject_tool_search_marks_deferred(self, provider):
+        caps = provider.get_capabilities("claude-opus-4-6-20260101")
+        tools = [
+            {"name": "bash", "description": "Run commands", "input_schema": {}},
+            {
+                "name": "mcp__github__create_issue",
+                "description": "Create issue",
+                "input_schema": {},
+            },
+        ]
+        deferred = frozenset(["mcp__github__create_issue"])
+        result = provider._inject_tool_search(tools, caps, deferred)
+        # bash should not be deferred
+        assert result[0].get("defer_loading") is None or result[0].get("defer_loading") is False
+        # MCP tool should be deferred
+        assert result[1]["defer_loading"] is True
+        # Search tool should be appended
+        assert result[-1]["type"] == "tool_search_tool_bm25_20251119"
+        assert result[-1]["name"] == "tool_search"
+
+    def test_inject_tool_search_no_op_without_deferred(self, provider):
+        caps = provider.get_capabilities("claude-opus-4-6-20260101")
+        tools = [{"name": "bash", "description": "Run commands", "input_schema": {}}]
+        result = provider._inject_tool_search(tools, caps, None)
+        assert result == tools
+
+    def test_inject_tool_search_no_op_on_unsupported_model(self, provider):
+        caps = provider.get_capabilities("claude-haiku-4-5-20251001")
+        tools = [{"name": "bash", "description": "Run commands", "input_schema": {}}]
+        deferred = frozenset(["some_tool"])
+        result = provider._inject_tool_search(tools, caps, deferred)
+        assert result == tools
+
+
+class TestOpenAIToolSearch:
+    """Test OpenAI provider tool search injection."""
+
+    @pytest.fixture()
+    def provider(self):
+        return OpenAIProvider()
+
+    def test_tool_search_capability_on_gpt54(self, provider):
+        caps = provider.get_capabilities("gpt-5.4")
+        assert caps.supports_tool_search is True
+
+    def test_tool_search_not_supported_on_gpt5(self, provider):
+        caps = provider.get_capabilities("gpt-5")
+        assert caps.supports_tool_search is False
+
+    def test_apply_tool_search_marks_deferred(self, provider):
+        caps = provider.get_capabilities("gpt-5.4")
+        tools = [
+            {"type": "function", "function": {"name": "bash", "description": "Run commands"}},
+            {
+                "type": "function",
+                "function": {"name": "mcp__slack__send", "description": "Send message"},
+            },
+        ]
+        deferred = frozenset(["mcp__slack__send"])
+        result = provider._apply_tool_search(caps, tools, deferred)
+        assert result is not None
+        # bash not deferred
+        assert result[0].get("defer_loading") is None or result[0].get("defer_loading") is False
+        # slack tool deferred
+        assert result[1]["defer_loading"] is True
+
+    def test_apply_tool_search_no_op_without_deferred(self, provider):
+        caps = provider.get_capabilities("gpt-5.4")
+        tools = [
+            {"type": "function", "function": {"name": "bash", "description": "Run commands"}},
+        ]
+        result = provider._apply_tool_search(caps, tools, None)
+        assert result == tools
+
+    def test_apply_tool_search_no_op_on_unsupported_model(self, provider):
+        caps = provider.get_capabilities("gpt-5")
+        tools = [
+            {"type": "function", "function": {"name": "bash", "description": "Run commands"}},
+        ]
+        deferred = frozenset(["some_tool"])
+        result = provider._apply_tool_search(caps, tools, deferred)
+        assert result == tools
+
+
+class TestModelCapabilitiesToolSearch:
+    """Test supports_tool_search defaults and values."""
+
+    def test_default_is_false(self):
+        from turnstone.core.providers._protocol import ModelCapabilities
+
+        caps = ModelCapabilities()
+        assert caps.supports_tool_search is False
+
+
+# ---------------------------------------------------------------------------
+# Vision support
+# ---------------------------------------------------------------------------
+
+
+class TestVisionCapabilities:
+    """Test supports_vision flag across providers."""
+
+    def test_default_is_false(self) -> None:
+        from turnstone.core.providers._protocol import ModelCapabilities
+
+        caps = ModelCapabilities()
+        assert caps.supports_vision is False
+
+    def test_openai_commercial_supports_vision(self) -> None:
+        provider = OpenAIProvider()
+        for model in ("gpt-5", "gpt-5-mini", "gpt-5.4", "o3", "o4-mini"):
+            caps = provider.get_capabilities(model)
+            assert caps.supports_vision is True, f"{model} should support vision"
+
+    def test_openai_default_no_vision(self) -> None:
+        """Unknown models (local servers) default to no vision."""
+        provider = OpenAIProvider()
+        caps = provider.get_capabilities("some-local-model")
+        assert caps.supports_vision is False
+
+    def test_anthropic_supports_vision(self) -> None:
+        from turnstone.core.providers._anthropic import AnthropicProvider
+
+        provider = AnthropicProvider()
+        for model in ("claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5"):
+            caps = provider.get_capabilities(model)
+            assert caps.supports_vision is True, f"{model} should support vision"
+
+    def test_anthropic_default_supports_vision(self) -> None:
+        """Anthropic default (unknown Claude model) supports vision."""
+        from turnstone.core.providers._anthropic import AnthropicProvider
+
+        provider = AnthropicProvider()
+        caps = provider.get_capabilities("claude-unknown-9")
+        assert caps.supports_vision is True
+
+
+class TestAnthropicVisionConversion:
+    """Test image content conversion in _convert_messages."""
+
+    def setup_method(self) -> None:
+        from turnstone.core.providers._anthropic import AnthropicProvider
+
+        self.provider = AnthropicProvider()
+
+    def test_tool_result_with_image_content(self) -> None:
+        """Tool result with list content converts image_url to Anthropic image."""
+        messages = [
+            {"role": "user", "content": "Read this image"},
+            {
+                "role": "assistant",
+                "content": "",
+                "tool_calls": [
+                    {
+                        "id": "call_1",
+                        "function": {"name": "read_file", "arguments": '{"path": "img.png"}'},
+                    }
+                ],
+            },
+            {
+                "role": "tool",
+                "tool_call_id": "call_1",
+                "content": [
+                    {"type": "text", "text": "Image file: img.png (1024 bytes)"},
+                    {
+                        "type": "image_url",
+                        "image_url": {"url": "data:image/png;base64,iVBORw0KGgo="},
+                    },
+                ],
+            },
+        ]
+        _, converted = self.provider._convert_messages(messages)
+        # Tool result should be in a user message
+        tool_user_msg = converted[2]
+        assert tool_user_msg["role"] == "user"
+        tool_result = tool_user_msg["content"][0]
+        assert tool_result["type"] == "tool_result"
+        assert tool_result["tool_use_id"] == "call_1"
+        # Content should be a list with converted image block
+        content = tool_result["content"]
+        assert isinstance(content, list)
+        assert content[0] == {"type": "text", "text": "Image file: img.png (1024 bytes)"}
+        assert content[1]["type"] == "image"
+        assert content[1]["source"]["type"] == "base64"
+        assert content[1]["source"]["media_type"] == "image/png"
+        assert content[1]["source"]["data"] == "iVBORw0KGgo="
+
+    def test_tool_result_with_string_content_unchanged(self) -> None:
+        """Tool result with plain string content is unchanged."""
+        messages = [
+            {"role": "user", "content": "Read file"},
+            {
+                "role": "assistant",
+                "content": "",
+                "tool_calls": [
+                    {
+                        "id": "call_2",
+                        "function": {"name": "read_file", "arguments": '{"path": "f.py"}'},
+                    }
+                ],
+            },
+            {
+                "role": "tool",
+                "tool_call_id": "call_2",
+                "content": "   1\tprint('hello')",
+            },
+        ]
+        _, converted = self.provider._convert_messages(messages)
+        tool_result = converted[2]["content"][0]
+        assert tool_result["content"] == "   1\tprint('hello')"
+
+    def test_convert_content_parts_static_method(self) -> None:
+        """_convert_content_parts handles both image_url and text."""
+        from turnstone.core.providers._anthropic import AnthropicProvider
+
+        parts = [
+            {"type": "text", "text": "description"},
+            {
+                "type": "image_url",
+                "image_url": {"url": "data:image/jpeg;base64,/9j/4AAQ"},
+            },
+        ]
+        result = AnthropicProvider._convert_content_parts(parts)
+        assert result[0] == {"type": "text", "text": "description"}
+        assert result[1]["type"] == "image"
+        assert result[1]["source"]["media_type"] == "image/jpeg"
+        assert result[1]["source"]["data"] == "/9j/4AAQ"

tests/test_resume_flow.py

@@ -1,6 +1,6 @@
 """Tests for the atomic workstream resumption flow.
 
-Covers CreateWorkstreamMessage resume_session field, SessionResumedEvent,
+Covers CreateWorkstreamMessage resume_ws field, WorkstreamResumedEvent,
 WorkstreamCreatedEvent resumed fields, and server endpoint handling.
 """
 
@@ -10,8 +10,8 @@ import json
 
 from turnstone.mq.protocol import (
     CreateWorkstreamMessage,
-    SessionResumedEvent,
     WorkstreamCreatedEvent,
+    WorkstreamResumedEvent,
 )
 
 # ---------------------------------------------------------------------------
@@ -20,93 +20,78 @@ from turnstone.mq.protocol import (
 
 
 class TestCreateWorkstreamMessageResumeField:
-    def test_resume_session_defaults_empty(self) -> None:
+    def test_resume_ws_defaults_empty(self) -> None:
         msg = CreateWorkstreamMessage(name="test")
-        assert msg.resume_session == ""
+        assert msg.resume_ws == ""
 
-    def test_resume_session_set(self) -> None:
-        msg = CreateWorkstreamMessage(name="test", resume_session="sess-abc")
-        assert msg.resume_session == "sess-abc"
+    def test_resume_ws_set(self) -> None:
+        msg = CreateWorkstreamMessage(name="test", resume_ws="ws-abc")
+        assert msg.resume_ws == "ws-abc"
 
-    def test_resume_session_serializes(self) -> None:
-        msg = CreateWorkstreamMessage(resume_session="sess-xyz")
+    def test_resume_ws_serializes(self) -> None:
+        msg = CreateWorkstreamMessage(resume_ws="ws-xyz")
         data = json.loads(msg.to_json())
-        assert data["resume_session"] == "sess-xyz"
+        assert data["resume_ws"] == "ws-xyz"
 
-    def test_resume_session_deserializes(self) -> None:
-        msg = CreateWorkstreamMessage(resume_session="sess-123")
+    def test_resume_ws_deserializes(self) -> None:
+        msg = CreateWorkstreamMessage(resume_ws="ws-123")
         raw = msg.to_json()
         from turnstone.mq.protocol import InboundMessage
 
         restored = InboundMessage.from_json(raw)
-        assert getattr(restored, "resume_session", "") == "sess-123"
+        assert getattr(restored, "resume_ws", "") == "ws-123"
 
 
 class TestWorkstreamCreatedEventResumeFields:
     def test_default_not_resumed(self) -> None:
         event = WorkstreamCreatedEvent(ws_id="ws-1", name="test")
         assert event.resumed is False
-        assert event.session_id == ""
         assert event.message_count == 0
 
     def test_resumed_fields(self) -> None:
-        event = WorkstreamCreatedEvent(
-            ws_id="ws-1", name="test", resumed=True, session_id="s-1", message_count=42
-        )
+        event = WorkstreamCreatedEvent(ws_id="ws-1", name="test", resumed=True, message_count=42)
         assert event.resumed is True
-        assert event.session_id == "s-1"
         assert event.message_count == 42
 
     def test_serializes_resumed_fields(self) -> None:
-        event = WorkstreamCreatedEvent(
-            ws_id="ws-1", resumed=True, session_id="s-1", message_count=10
-        )
+        event = WorkstreamCreatedEvent(ws_id="ws-1", resumed=True, message_count=10)
         data = json.loads(event.to_json())
         assert data["resumed"] is True
-        assert data["session_id"] == "s-1"
         assert data["message_count"] == 10
 
     def test_deserializes_resumed_fields(self) -> None:
-        event = WorkstreamCreatedEvent(
-            ws_id="ws-1", resumed=True, session_id="s-1", message_count=5
-        )
+        event = WorkstreamCreatedEvent(ws_id="ws-1", resumed=True, message_count=5)
         from turnstone.mq.protocol import OutboundEvent
 
         restored = OutboundEvent.from_json(event.to_json())
         assert isinstance(restored, WorkstreamCreatedEvent)
         assert restored.resumed is True
-        assert restored.session_id == "s-1"
         assert restored.message_count == 5
 
 
-class TestSessionResumedEvent:
+class TestWorkstreamResumedEvent:
     def test_defaults(self) -> None:
-        event = SessionResumedEvent(ws_id="ws-1")
-        assert event.type == "session_resumed"
-        assert event.session_id == ""
+        event = WorkstreamResumedEvent(ws_id="ws-1")
+        assert event.type == "ws_resumed"
         assert event.message_count == 0
         assert event.name == ""
 
     def test_with_values(self) -> None:
-        event = SessionResumedEvent(
-            ws_id="ws-1", session_id="s-abc", message_count=25, name="My Chat"
-        )
-        assert event.session_id == "s-abc"
+        event = WorkstreamResumedEvent(ws_id="ws-1", message_count=25, name="My Chat")
         assert event.message_count == 25
         assert event.name == "My Chat"
 
     def test_round_trip(self) -> None:
-        event = SessionResumedEvent(ws_id="ws-1", session_id="s-abc", message_count=10, name="Chat")
+        event = WorkstreamResumedEvent(ws_id="ws-1", message_count=10, name="Chat")
         from turnstone.mq.protocol import OutboundEvent
 
         restored = OutboundEvent.from_json(event.to_json())
-        assert isinstance(restored, SessionResumedEvent)
-        assert restored.session_id == "s-abc"
+        assert isinstance(restored, WorkstreamResumedEvent)
         assert restored.message_count == 10
         assert restored.name == "Chat"
 
     def test_registered_in_outbound_registry(self) -> None:
         from turnstone.mq.protocol import _OUTBOUND_REGISTRY
 
-        assert "session_resumed" in _OUTBOUND_REGISTRY
-        assert _OUTBOUND_REGISTRY["session_resumed"] is SessionResumedEvent
+        assert "ws_resumed" in _OUTBOUND_REGISTRY
+        assert _OUTBOUND_REGISTRY["ws_resumed"] is WorkstreamResumedEvent

tests/test_schedule_api.py

@@ -2,11 +2,19 @@
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING, Any
+
 import pytest
 from starlette.applications import Starlette
+from starlette.middleware import Middleware
+from starlette.middleware.base import BaseHTTPMiddleware
 from starlette.routing import Mount, Route
 from starlette.testclient import TestClient
 
+if TYPE_CHECKING:
+    from starlette.requests import Request
+    from starlette.responses import Response
+
 from turnstone.console.server import (
     admin_create_schedule,
     admin_delete_schedule,
@@ -15,9 +23,21 @@ from turnstone.console.server import (
     admin_list_schedules,
     admin_update_schedule,
 )
+from turnstone.core.auth import AuthResult
 from turnstone.core.storage._sqlite import SQLiteBackend
 
 
+class _InjectAuthMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next: Any) -> Response:
+        request.state.auth_result = AuthResult(
+            user_id="test-admin",
+            scopes=frozenset({"approve"}),
+            token_source="config",
+            permissions=frozenset({"admin.schedules"}),
+        )
+        return await call_next(request)
+
+
 @pytest.fixture
 def storage(tmp_path):
     """Fresh SQLite backend for each test."""
@@ -52,6 +72,7 @@ def client(storage):
                 ],
             ),
         ],
+        middleware=[Middleware(_InjectAuthMiddleware)],
     )
     app.state.auth_storage = storage
     return TestClient(app)

tests/test_sdk_events.py

@@ -1,6 +1,7 @@
 """Tests for turnstone.sdk.events — SSE event deserialization."""
 
 from turnstone.sdk.events import (
+    ApprovalResolvedEvent,
     ApproveRequestEvent,
     BusyErrorEvent,
     ClearUiEvent,
@@ -92,6 +93,15 @@ def test_approve_request_event():
     assert len(e.items) == 1
 
 
+def test_approval_resolved_event():
+    e = ServerEvent.from_dict(
+        {"type": "approval_resolved", "approved": False, "feedback": "Approval timed out"}
+    )
+    assert isinstance(e, ApprovalResolvedEvent)
+    assert e.approved is False
+    assert e.feedback == "Approval timed out"
+
+
 def test_tool_result_event():
     e = ServerEvent.from_dict(
         {"type": "tool_result", "call_id": "c1", "name": "search", "output": "found it"}

tests/test_sdk_server.py

@@ -148,19 +148,19 @@ async def test_command():
 
 
 # ---------------------------------------------------------------------------
-# Sessions
+# History
 # ---------------------------------------------------------------------------
 
 
 @pytest.mark.anyio
-async def test_list_sessions():
+async def test_list_saved_workstreams():
     transport = _mock_transport(
         {
-            "GET /v1/api/sessions": _json_response(
+            "GET /v1/api/workstreams/saved": _json_response(
                 {
-                    "sessions": [
+                    "workstreams": [
                         {
-                            "session_id": "s1",
+                            "ws_id": "s1",
                             "title": "test",
                             "created": "2024-01-01",
                             "updated": "2024-01-02",
@@ -173,8 +173,8 @@ async def test_list_sessions():
     )
     async with httpx.AsyncClient(transport=transport, base_url="http://test") as hc:
         client = AsyncTurnstoneServer(httpx_client=hc)
-        resp = await client.list_sessions()
-        assert len(resp.sessions) == 1
+        resp = await client.list_saved_workstreams()
+        assert len(resp.workstreams) == 1
 
 
 # ---------------------------------------------------------------------------

tests/test_server_live.py

@@ -609,7 +609,7 @@ class TestServerHealthMetrics:
         mock_ui._ws_context_ratio = 0.0
 
         mock_session = MagicMock()
-        mock_session.session_id = "test-session-id"
+        mock_session.ws_id = "test-session-id"
 
         mock_ws = MagicMock()
         mock_ws.id = "test-ws"
@@ -785,7 +785,7 @@ class TestServerRateLimiting:
         mock_ui._ws_context_ratio = 0.0
 
         mock_session = MagicMock()
-        mock_session.session_id = "test-session-id"
+        mock_session.ws_id = "test-session-id"
 
         mock_ws = MagicMock()
         mock_ws.id = "test-ws"

tests/test_session.py

@@ -1,9 +1,10 @@
 """Tests for turnstone.core.session — ChatSession construction."""
 
+import base64
 import json
 from unittest.mock import MagicMock, patch
 
-from turnstone.core.session import ChatSession
+from turnstone.core.session import _IMAGE_EXTENSIONS, _IMAGE_SIZE_CAP, ChatSession
 
 
 class NullUI:
@@ -143,12 +144,21 @@ class TestChatSessionConstruction:
 class TestPlanExec:
     """Tests for _exec_plan: unique session-scoped plan file and existing-plan injection."""
 
-    def _run_plan(self, session, prompt, agent_return="# Plan\n\nDo the thing."):
+    _VALID_PLAN = (
+        "## Goal\n\nDo the thing.\n\n"
+        "## Current State\n\nFile foo.py has bar().\n\n"
+        "## Plan\n\n1. Edit foo.py line 10.\n\n"
+        "## Risks\n\nNone."
+    )
+
+    def _run_plan(self, session, prompt, agent_return=None):
         """Invoke _exec_plan with _run_agent patched to avoid LLM calls.
 
         Returns (call_id_returned, content_returned, captured_messages) where
         captured_messages is the agent_messages list passed to _run_agent.
         """
+        if agent_return is None:
+            agent_return = self._VALID_PLAN
         captured = {}
 
         def fake_run_agent(messages, **kwargs):
@@ -161,12 +171,12 @@ class TestPlanExec:
 
         return call_id, content, captured.get("messages", [])
 
-    def test_plan_file_uses_session_id(self, tmp_db, tmp_path, monkeypatch):
-        """Plan file is named .plan-<session_id>.md, not .plan.md."""
+    def test_plan_file_uses_ws_id(self, tmp_db, tmp_path, monkeypatch):
+        """Plan file is named .plan-<ws_id>.md, not .plan.md."""
         monkeypatch.chdir(tmp_path)
         session = _make_session()
         self._run_plan(session, "add feature")
-        expected = tmp_path / f".plan-{session._session_id}.md"
+        expected = tmp_path / f".plan-{session._ws_id}.md"
         assert expected.exists(), f"Expected {expected} to be created"
         assert not (tmp_path / ".plan.md").exists()
 
@@ -174,17 +184,16 @@ class TestPlanExec:
         """Written plan file contains the agent's output verbatim."""
         monkeypatch.chdir(tmp_path)
         session = _make_session()
-        plan_content = "## Goal\n\nAdd a new endpoint."
-        self._run_plan(session, "add endpoint", agent_return=plan_content)
-        plan_file = tmp_path / f".plan-{session._session_id}.md"
-        assert plan_file.read_text() == plan_content
+        self._run_plan(session, "add endpoint")
+        plan_file = tmp_path / f".plan-{session._ws_id}.md"
+        assert plan_file.read_text() == self._VALID_PLAN
 
     def test_two_sessions_produce_different_files(self, tmp_db, tmp_path, monkeypatch):
         """Two ChatSession instances never collide on the same plan file."""
         monkeypatch.chdir(tmp_path)
         s1 = _make_session()
         s2 = _make_session()
-        assert s1._session_id != s2._session_id
+        assert s1._ws_id != s2._ws_id
         self._run_plan(s1, "feature A")
         self._run_plan(s2, "feature B")
         files = list(tmp_path.glob(".plan-*.md"))
@@ -202,8 +211,8 @@ class TestPlanExec:
                         "id": tc_id,
                         "type": "function",
                         "function": {
-                            "name": "plan",
-                            "arguments": json.dumps({"prompt": prior_prompt}),
+                            "name": "create_plan",
+                            "arguments": json.dumps({"goal": prior_prompt}),
                         },
                     }
                 ],
@@ -238,7 +247,7 @@ class TestPlanExec:
             m for m in messages if m["role"] == "assistant" and m.get("tool_calls")
         ]
         assert len(assistant_with_tc) == 1
-        assert assistant_with_tc[0]["tool_calls"][0]["function"]["name"] == "plan"
+        assert assistant_with_tc[0]["tool_calls"][0]["function"]["name"] == "create_plan"
 
         # The real tool result is forwarded with its original content
         tool_msgs = [m for m in messages if m["role"] == "tool"]
@@ -261,7 +270,440 @@ class TestPlanExec:
         """_exec_plan returns (call_id, agent_output)."""
         monkeypatch.chdir(tmp_path)
         session = _make_session()
-        agent_output = "## Goal\n\nBuild it."
-        call_id, content, _ = self._run_plan(session, "do stuff", agent_return=agent_output)
+        call_id, content, _ = self._run_plan(session, "do stuff")
         assert call_id == "test-call-1"
-        assert content == agent_output
+        assert content == self._VALID_PLAN
+
+    def test_exec_plan_retries_on_garbage(self, tmp_db, tmp_path, monkeypatch):
+        """When _run_agent returns garbage, _exec_plan retries once."""
+        monkeypatch.chdir(tmp_path)
+        session = _make_session()
+        good_plan = (
+            "## Goal\n\nAdd feature X.\n\n"
+            "## Current State\n\nFile foo.py has bar().\n\n"
+            "## Plan\n\n1. Edit foo.py:bar()\n\n"
+            "## Risks\n\nNone."
+        )
+        call_count = 0
+
+        def fake_run_agent(messages, **kwargs):
+            nonlocal call_count
+            call_count += 1
+            if call_count == 1:
+                return "Sure, do the thing."
+            return good_plan
+
+        item = {"call_id": "c1", "prompt": "add feature X"}
+        with patch.object(session, "_run_agent", side_effect=fake_run_agent):
+            _, content = session._exec_plan(item)
+
+        assert call_count == 2
+        assert "## Goal" in content
+
+    def test_exec_plan_warning_on_double_failure(self, tmp_db, tmp_path, monkeypatch):
+        """When both attempts produce garbage, content gets a warning prefix."""
+        monkeypatch.chdir(tmp_path)
+        session = _make_session()
+
+        def fake_run_agent(messages, **kwargs):
+            return "nope"
+
+        item = {"call_id": "c1", "prompt": "add feature X"}
+        with patch.object(session, "_run_agent", side_effect=fake_run_agent):
+            _, content = session._exec_plan(item)
+
+        assert content.startswith("[Warning:")
+
+    def test_retry_continues_agent_conversation(self, tmp_db, tmp_path, monkeypatch):
+        """Retry appends coaching to the same agent_messages list."""
+        monkeypatch.chdir(tmp_path)
+        session = _make_session()
+        captured_messages: list[list] = []
+
+        def fake_run_agent(messages, **kwargs):
+            captured_messages.append(list(messages))
+            if len(captured_messages) == 1:
+                return "garbage"
+            return (
+                "## Goal\n\nDone.\n\n## Current State\n\nx\n\n## Plan\n\n1. x\n\n## Risks\n\nNone."
+            )
+
+        item = {"call_id": "c1", "prompt": "add feature X"}
+        with patch.object(session, "_run_agent", side_effect=fake_run_agent):
+            session._exec_plan(item)
+
+        assert len(captured_messages) == 2
+        # Second call should have more messages (coaching appended)
+        assert len(captured_messages[1]) > len(captured_messages[0])
+        # Last user message in second call is the coaching message
+        assert "did not follow" in captured_messages[1][-1]["content"]
+
+
+# ---------------------------------------------------------------------------
+# Plan validation
+# ---------------------------------------------------------------------------
+
+
+class TestPlanValidation:
+    """Tests for ChatSession._validate_plan quality gate."""
+
+    GOOD_PLAN = (
+        "## Goal\n\nAdd authentication to the API.\n\n"
+        "## Current State\n\nFile server.py:45 has no auth middleware.\n\n"
+        "## Plan\n\n1. Add AuthMiddleware to server.py.\n"
+        "2. Create auth.py with JWT verification.\n\n"
+        "## Risks\n\nToken expiry handling may need tuning."
+    )
+
+    def test_valid_plan_passes(self):
+        valid, issues = ChatSession._validate_plan(self.GOOD_PLAN, "add auth")
+        assert valid
+        assert issues == []
+
+    def test_too_short_fails(self):
+        valid, issues = ChatSession._validate_plan("Do the thing.", "do stuff")
+        assert not valid
+        assert any("too short" in i for i in issues)
+
+    def test_no_sections_fails(self):
+        content = "A" * 150  # long enough but no sections
+        valid, issues = ChatSession._validate_plan(content, "build it")
+        assert not valid
+        assert any("missing plan sections" in i for i in issues)
+
+    def test_echo_detection(self):
+        goal = "deliver a simpsons quote from a specific episode"
+        content = "Deliver a Simpsons quote from a specific episode"
+        valid, issues = ChatSession._validate_plan(content, goal)
+        assert not valid
+        assert any("echo" in i for i in issues)
+
+    def test_refusal_detection(self):
+        content = "I cannot create a plan for this task because " + "x" * 100
+        valid, issues = ChatSession._validate_plan(content, "do stuff")
+        assert not valid
+        assert any("refusal" in i for i in issues)
+
+    def test_partial_sections_passes(self):
+        """2 out of 4 sections is enough to pass."""
+        content = (
+            "## Goal\n\nFix the bug in parsing.\n\n"
+            "## Plan\n\n1. Edit parser.py line 42.\n"
+            "2. Add boundary check.\n"
+            "This is enough detail to proceed with confidence."
+        )
+        valid, issues = ChatSession._validate_plan(content, "fix bug")
+        assert valid
+
+    def test_one_section_fails(self):
+        """Only 1 out of 4 sections is not enough."""
+        content = (
+            "## Goal\n\nFix the bug.\n\n"
+            "We should probably edit parser.py and add some checks "
+            "to the boundary handling code path for safety."
+        )
+        valid, issues = ChatSession._validate_plan(content, "fix bug")
+        assert not valid
+        assert any("missing plan sections" in i for i in issues)
+
+
+# ---------------------------------------------------------------------------
+# Plan refinement loop
+# ---------------------------------------------------------------------------
+
+
+class TestPlanRefinement:
+    """Tests for the iterative plan refinement loop in _execute_tools."""
+
+    GOOD_PLAN = TestPlanValidation.GOOD_PLAN
+
+    def test_feedback_triggers_refinement(self, tmp_db, tmp_path, monkeypatch):
+        """User feedback causes _refine_plan to run, then approval exits."""
+        monkeypatch.chdir(tmp_path)
+        session = _make_session()
+        refine_called = []
+
+        review_responses = iter(["add error handling", ""])
+        session.ui = MagicMock(spec_set=NullUI)
+        session.ui.on_plan_review.side_effect = lambda c: next(review_responses)
+        session.ui.on_info = MagicMock()
+        session.ui.on_state_change = MagicMock()
+
+        revised = self.GOOD_PLAN + "\n\n3. Add error handling."
+
+        def fake_refine(content, goal, feedback):
+            refine_called.append(feedback)
+            return revised
+
+        with patch.object(session, "_refine_plan", side_effect=fake_refine):
+            items = [
+                {
+                    "func_name": "create_plan",
+                    "call_id": "c1",
+                    "prompt": "add auth",
+                }
+            ]
+            results = [("c1", self.GOOD_PLAN)]
+            # Manually invoke the post-plan gate portion of _execute_tools.
+            # We test the loop by calling the gate code directly.
+            session.auto_approve = False
+
+            original_goal = items[0].get("prompt", "")
+            output = results[0][1]
+            refinement_round = 0
+            while refinement_round < session._MAX_PLAN_REFINEMENTS:
+                resp = session.ui.on_plan_review(output)
+                if resp.lower() in ("n", "no", "reject"):
+                    break
+                elif resp:
+                    output = session._refine_plan(output, original_goal, resp)
+                    refinement_round += 1
+                else:
+                    break
+
+        assert len(refine_called) == 1
+        assert refine_called[0] == "add error handling"
+        assert "error handling" in output
+
+    def test_reject_skips_refinement(self, tmp_db, tmp_path, monkeypatch):
+        """Rejection exits immediately without calling _refine_plan."""
+        monkeypatch.chdir(tmp_path)
+        session = _make_session()
+        session.ui = MagicMock(spec_set=NullUI)
+        session.ui.on_plan_review.return_value = "reject"
+
+        with patch.object(session, "_refine_plan") as mock_refine:
+            output = self.GOOD_PLAN
+            resp = session.ui.on_plan_review(output)
+            if resp.lower() in ("n", "no", "reject"):
+                output += "\n\n---\nUser REJECTED"
+            elif resp:
+                output = session._refine_plan(output, "g", resp)
+
+        mock_refine.assert_not_called()
+        assert "REJECTED" in output
+
+    def test_approve_skips_refinement(self, tmp_db, tmp_path, monkeypatch):
+        """Empty response (enter) approves without refinement."""
+        monkeypatch.chdir(tmp_path)
+        session = _make_session()
+        session.ui = MagicMock(spec_set=NullUI)
+        session.ui.on_plan_review.return_value = ""
+
+        with patch.object(session, "_refine_plan") as mock_refine:
+            output = self.GOOD_PLAN
+            resp = session.ui.on_plan_review(output)
+            if resp.lower() in ("n", "no", "reject"):
+                output += "\n\n---\nUser REJECTED"
+            elif resp:
+                output = session._refine_plan(output, "g", resp)
+
+        mock_refine.assert_not_called()
+        assert "REJECTED" not in output
+
+    def test_max_refinement_rounds(self, tmp_db, tmp_path, monkeypatch):
+        """Loop stops after _MAX_PLAN_REFINEMENTS rounds with a final review."""
+        monkeypatch.chdir(tmp_path)
+        session = _make_session()
+        session.ui = MagicMock(spec_set=NullUI)
+        session.ui.on_plan_review.return_value = "more detail please"
+        session.ui.on_info = MagicMock()
+
+        refine_count = 0
+
+        def fake_refine(content, goal, feedback):
+            nonlocal refine_count
+            refine_count += 1
+            return content + f"\n(revision {refine_count})"
+
+        with patch.object(session, "_refine_plan", side_effect=fake_refine):
+            output = self.GOOD_PLAN
+            original_goal = "add auth"
+            refinement_round = 0
+            while True:
+                resp = session.ui.on_plan_review(output)
+                if (
+                    resp.lower() in ("n", "no", "reject")
+                    or not resp
+                    or refinement_round >= session._MAX_PLAN_REFINEMENTS
+                ):
+                    break
+                output = session._refine_plan(output, original_goal, resp)
+                refinement_round += 1
+
+        assert refine_count == session._MAX_PLAN_REFINEMENTS
+        # User gets one extra review call after max rounds (the final prompt)
+        assert session.ui.on_plan_review.call_count == session._MAX_PLAN_REFINEMENTS + 1
+
+    def test_refine_plan_message_structure(self, tmp_db, tmp_path, monkeypatch):
+        """_refine_plan passes system + prior plan + feedback to _run_agent."""
+        monkeypatch.chdir(tmp_path)
+        session = _make_session()
+        captured = {}
+
+        def fake_run_agent(messages, **kwargs):
+            captured["messages"] = list(messages)
+            return self.GOOD_PLAN
+
+        with patch.object(session, "_run_agent", side_effect=fake_run_agent):
+            session._refine_plan(self.GOOD_PLAN, "add auth", "add tests too")
+
+        msgs = captured["messages"]
+        assert msgs[0]["role"] == "system"
+        assert msgs[1]["role"] == "assistant"
+        assert msgs[1]["tool_calls"][0]["function"]["name"] == "create_plan"
+        assert msgs[2]["role"] == "tool"
+        assert msgs[2]["content"] == self.GOOD_PLAN
+        assert msgs[3]["role"] == "user"
+        assert "add tests too" in msgs[3]["content"]
+
+
+# ---------------------------------------------------------------------------
+# Vision / image support
+# ---------------------------------------------------------------------------
+
+
+class TestImageExtensions:
+    """Test _IMAGE_EXTENSIONS constant and detection logic."""
+
+    def test_common_image_extensions(self):
+        for ext in (".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp", ".tiff", ".tif", ".ico"):
+            assert ext in _IMAGE_EXTENSIONS, f"{ext} should be in _IMAGE_EXTENSIONS"
+
+    def test_svg_excluded(self):
+        assert ".svg" not in _IMAGE_EXTENSIONS
+
+    def test_text_extensions_excluded(self):
+        for ext in (".py", ".txt", ".json", ".md", ".rs", ".go"):
+            assert ext not in _IMAGE_EXTENSIONS
+
+
+class TestExecReadImage:
+    """Test _exec_read_image method."""
+
+    def _make_png(self, path: str, size: int = 100) -> None:
+        """Write a minimal valid-ish PNG header to a file."""
+        # 8-byte PNG signature + enough bytes to reach target size
+        header = b"\x89PNG\r\n\x1a\n"
+        with open(path, "wb") as f:
+            f.write(header + b"\x00" * max(0, size - len(header)))
+
+    def test_image_returns_content_parts(self, tmp_db, tmp_path):
+        """read_file on a PNG with vision support returns content parts."""
+        img = tmp_path / "test.png"
+        self._make_png(str(img))
+
+        session = _make_session()
+        # Mock provider to report vision support
+        mock_caps = MagicMock()
+        mock_caps.supports_vision = True
+        session._provider.get_capabilities = MagicMock(return_value=mock_caps)
+
+        item = {"call_id": "c1", "path": str(img), "offset": None, "limit": None}
+        call_id, output = session._exec_read_file(item)
+
+        assert call_id == "c1"
+        assert isinstance(output, list)
+        assert len(output) == 2
+        assert output[0]["type"] == "text"
+        assert "test.png" in output[0]["text"]
+        assert output[1]["type"] == "image_url"
+        url = output[1]["image_url"]["url"]
+        assert url.startswith("data:image/png;base64,")
+        # Verify base64 round-trip
+        b64part = url.split(",", 1)[1]
+        decoded = base64.b64decode(b64part)
+        assert decoded == img.read_bytes()
+
+    def test_no_vision_returns_text(self, tmp_db, tmp_path):
+        """read_file on image with non-vision model returns text description."""
+        img = tmp_path / "photo.jpg"
+        self._make_png(str(img), size=2048)
+
+        session = _make_session()
+        mock_caps = MagicMock()
+        mock_caps.supports_vision = False
+        session._provider.get_capabilities = MagicMock(return_value=mock_caps)
+
+        item = {"call_id": "c2", "path": str(img), "offset": None, "limit": None}
+        call_id, output = session._exec_read_file(item)
+
+        assert call_id == "c2"
+        assert isinstance(output, str)
+        assert "does not support vision" in output
+        assert "photo.jpg" in output
+
+    def test_oversized_image_returns_error(self, tmp_db, tmp_path):
+        """Images exceeding _IMAGE_SIZE_CAP return an error string."""
+        img = tmp_path / "huge.png"
+        # Write slightly over the cap
+        with open(img, "wb") as f:
+            f.write(b"\x89PNG\r\n\x1a\n" + b"\x00" * _IMAGE_SIZE_CAP)
+
+        session = _make_session()
+        mock_caps = MagicMock()
+        mock_caps.supports_vision = True
+        session._provider.get_capabilities = MagicMock(return_value=mock_caps)
+
+        item = {"call_id": "c3", "path": str(img), "offset": None, "limit": None}
+        call_id, output = session._exec_read_file(item)
+
+        assert call_id == "c3"
+        assert isinstance(output, str)
+        assert "exceeds" in output
+
+    def test_missing_image_returns_error(self, tmp_db, tmp_path):
+        """read_file on non-existent image returns error."""
+        session = _make_session()
+        mock_caps = MagicMock()
+        mock_caps.supports_vision = True
+        session._provider.get_capabilities = MagicMock(return_value=mock_caps)
+
+        item = {"call_id": "c4", "path": str(tmp_path / "nope.png"), "offset": None, "limit": None}
+        call_id, output = session._exec_read_file(item)
+        assert isinstance(output, str)
+        assert "not found" in output
+
+    def test_svg_read_as_text(self, tmp_db, tmp_path):
+        """SVG files are read as text, not as images."""
+        svg = tmp_path / "icon.svg"
+        svg.write_text('<svg xmlns="http://www.w3.org/2000/svg"><circle r="10"/></svg>')
+
+        session = _make_session()
+        item = {"call_id": "c5", "path": str(svg), "offset": None, "limit": None}
+        call_id, output = session._exec_read_file(item)
+        assert isinstance(output, str)
+        assert "<svg" in output  # Read as text
+
+
+class TestGetCapabilitiesOverride:
+    """Test _get_capabilities with config.toml overrides."""
+
+    def test_config_override_applies(self, tmp_db):
+        """capabilities dict from ModelConfig is merged onto provider caps."""
+        from turnstone.core.model_registry import ModelConfig, ModelRegistry
+        from turnstone.core.providers._protocol import ModelCapabilities
+
+        cfg = ModelConfig(
+            alias="qwen-vl",
+            base_url="http://localhost:8000/v1",
+            api_key="dummy",
+            model="qwen-3.5-vl",
+            capabilities={"supports_vision": True},
+        )
+        registry = ModelRegistry(
+            models={"qwen-vl": cfg},
+            default="qwen-vl",
+        )
+        session = _make_session(registry=registry, model_alias="qwen-vl")
+        # Ensure provider returns a real ModelCapabilities (not MagicMock)
+        session._provider.get_capabilities = MagicMock(return_value=ModelCapabilities())
+        caps = session._get_capabilities()
+        assert caps.supports_vision is True
+
+    def test_no_override_uses_provider_default(self, tmp_db):
+        """Without config override, provider defaults are used."""
+        session = _make_session()
+        caps = session._get_capabilities()
+        # Default OpenAI provider for unknown model → no vision
+        assert caps.supports_vision is False

tests/test_sessions.py

@@ -1,155 +1,155 @@
-"""Tests for session persistence and resume functionality."""
+"""Tests for workstream persistence and resume functionality."""
 
 from unittest.mock import MagicMock
 
 import sqlalchemy as sa
 
 from turnstone.core.memory import (
-    delete_session,
-    list_sessions,
-    load_session_config,
-    load_session_messages,
-    prune_sessions,
-    register_session,
-    resolve_session,
+    delete_workstream,
+    list_workstreams_with_history,
+    load_messages,
+    load_workstream_config,
+    prune_workstreams,
+    register_workstream,
+    resolve_workstream,
     save_message,
-    save_session_config,
-    set_session_alias,
-    update_session_title,
+    save_workstream_config,
+    set_workstream_alias,
+    update_workstream_title,
 )
 from turnstone.core.session import ChatSession
 from turnstone.core.storage import get_storage
 
-# ── Session registration ──────────────────────────────────────────────
+# ── Workstream registration ───────────────────────────────────────────
 
 
-class TestRegisterSession:
+class TestRegisterWorkstream:
     def test_register_creates_row(self, tmp_db):
-        register_session("abc123")
-        # Session exists in DB (resolve works) even without messages
-        assert resolve_session("abc123") == "abc123"
+        register_workstream("abc123")
+        # Workstream exists in DB (resolve works) even without messages
+        assert resolve_workstream("abc123") == "abc123"
 
     def test_register_with_title(self, tmp_db):
-        register_session("abc123", title="My Session")
+        register_workstream("abc123", name="My Workstream")
         save_message("abc123", "user", "hello")
-        rows = list_sessions()
-        assert rows[0][2] == "My Session"  # title
+        rows = list_workstreams_with_history()
+        assert rows[0][2] is None  # title column (name is separate)
 
     def test_register_idempotent(self, tmp_db):
-        register_session("abc123", title="First")
-        register_session("abc123", title="Second")  # should be ignored
+        register_workstream("abc123")
+        update_workstream_title("abc123", "First")
+        register_workstream("abc123")  # should be ignored
+        update_workstream_title("abc123", "First")  # title is set via update
         save_message("abc123", "user", "hello")
-        rows = list_sessions()
+        rows = list_workstreams_with_history()
         assert len(rows) == 1
-        assert rows[0][2] == "First"  # original title preserved
+        assert rows[0][2] == "First"  # title preserved
 
     def test_update_title(self, tmp_db):
-        register_session("abc123")
-        update_session_title("abc123", "New Title")
+        register_workstream("abc123")
+        update_workstream_title("abc123", "New Title")
         save_message("abc123", "user", "hello")
-        rows = list_sessions()
+        rows = list_workstreams_with_history()
         assert rows[0][2] == "New Title"
 
 
-# ── Session alias ─────────────────────────────────────────────────────
+# ── Workstream alias ──────────────────────────────────────────────────
 
 
-class TestSessionAlias:
+class TestWorkstreamAlias:
     def test_set_alias(self, tmp_db):
-        register_session("abc123")
-        assert set_session_alias("abc123", "my-session") is True
+        register_workstream("abc123")
+        assert set_workstream_alias("abc123", "my-session") is True
         save_message("abc123", "user", "hello")
-        rows = list_sessions()
+        rows = list_workstreams_with_history()
         assert rows[0][1] == "my-session"  # alias
 
     def test_alias_conflict(self, tmp_db):
-        register_session("abc123")
-        register_session("def456")
-        set_session_alias("abc123", "taken")
-        assert set_session_alias("def456", "taken") is False
+        register_workstream("abc123")
+        register_workstream("def456")
+        set_workstream_alias("abc123", "taken")
+        assert set_workstream_alias("def456", "taken") is False
 
-    def test_alias_same_session_ok(self, tmp_db):
-        register_session("abc123")
-        set_session_alias("abc123", "mine")
-        assert set_session_alias("abc123", "mine") is True  # no-op, same session
+    def test_alias_same_workstream_ok(self, tmp_db):
+        register_workstream("abc123")
+        set_workstream_alias("abc123", "mine")
+        assert set_workstream_alias("abc123", "mine") is True  # no-op, same workstream
 
 
-# ── Session resolution ────────────────────────────────────────────────
+# ── Workstream resolution ─────────────────────────────────────────────
 
 
-class TestResolveSession:
+class TestResolveWorkstream:
     def test_resolve_by_alias(self, tmp_db):
-        register_session("abc123")
-        set_session_alias("abc123", "my-alias")
-        assert resolve_session("my-alias") == "abc123"
+        register_workstream("abc123")
+        set_workstream_alias("abc123", "my-alias")
+        assert resolve_workstream("my-alias") == "abc123"
 
     def test_resolve_by_exact_id(self, tmp_db):
-        register_session("abc123def456")
-        assert resolve_session("abc123def456") == "abc123def456"
+        register_workstream("abc123def456")
+        assert resolve_workstream("abc123def456") == "abc123def456"
 
     def test_resolve_by_prefix(self, tmp_db):
-        register_session("abc123def456")
-        assert resolve_session("abc123") == "abc123def456"
+        register_workstream("abc123def456")
+        assert resolve_workstream("abc123") == "abc123def456"
 
     def test_resolve_prefix_ambiguous(self, tmp_db):
-        register_session("abc123aaaaaa")
-        register_session("abc123bbbbbb")
+        register_workstream("abc123aaaaaa")
+        register_workstream("abc123bbbbbb")
         # Ambiguous prefix should return None
-        assert resolve_session("abc123") is None
+        assert resolve_workstream("abc123") is None
 
     def test_resolve_not_found(self, tmp_db):
-        assert resolve_session("nonexistent") is None
-
-    def test_resolve_legacy_session(self, tmp_db):
-        """Sessions that exist only in conversations (pre-migration) should auto-register."""
-        save_message("legacy123456", "user", "old message")
-        result = resolve_session("legacy123456")
-        assert result == "legacy123456"
-        # Should now appear in sessions list
-        rows = list_sessions()
-        assert any(r[0] == "legacy123456" for r in rows)
+        assert resolve_workstream("nonexistent") is None
 
 
-# ── List sessions ─────────────────────────────────────────────────────
+# ── List workstreams with history ──────────────────────────────────────
 
 
-class TestListSessions:
+class TestListWorkstreamsWithHistory:
     def test_empty(self, tmp_db):
-        assert list_sessions() == []
+        assert list_workstreams_with_history() == []
 
     def test_ordered_by_updated(self, tmp_db):
-        register_session("first")
+        register_workstream("first")
         save_message("first", "user", "hello")
-        register_session("second")
+        # Force an older timestamp so ordering is deterministic
+        engine = get_storage()._engine  # noqa: SLF001
+        with engine.connect() as conn:
+            conn.execute(
+                sa.text("UPDATE workstreams SET updated = '2020-01-01' WHERE ws_id = 'first'")
+            )
+            conn.commit()
+        register_workstream("second")
         save_message("second", "user", "hello")
         # second is more recent
-        rows = list_sessions()
+        rows = list_workstreams_with_history()
         assert rows[0][0] == "second"
         assert rows[1][0] == "first"
 
     def test_includes_message_count(self, tmp_db):
-        register_session("sess1")
+        register_workstream("sess1")
         save_message("sess1", "user", "hello")
         save_message("sess1", "assistant", "hi")
-        rows = list_sessions()
+        rows = list_workstreams_with_history()
         assert rows[0][5] == 2  # msg_count
 
     def test_respects_limit(self, tmp_db):
         for i in range(5):
-            register_session(f"sess{i}")
+            register_workstream(f"sess{i}")
             save_message(f"sess{i}", "user", "hello")
-        rows = list_sessions(limit=3)
+        rows = list_workstreams_with_history(limit=3)
         assert len(rows) == 3
 
 
-# ── Load session messages ─────────────────────────────────────────────
+# ── Load messages ─────────────────────────────────────────────────────
 
 
-class TestLoadSessionMessages:
+class TestLoadMessages:
     def test_simple_user_assistant(self, tmp_db):
         save_message("s1", "user", "hello")
         save_message("s1", "assistant", "hi there")
-        msgs = load_session_messages("s1")
+        msgs = load_messages("s1")
         assert len(msgs) == 2
         assert msgs[0] == {"role": "user", "content": "hello"}
         assert msgs[1] == {"role": "assistant", "content": "hi there"}
@@ -159,7 +159,7 @@ class TestLoadSessionMessages:
         save_message("s1", "assistant", "Let me check.")
         save_message("s1", "tool_call", None, "bash", '{"command":"ls"}', tool_call_id="call_abc")
         save_message("s1", "tool_result", "file1.txt\nfile2.txt", "bash", tool_call_id="call_abc")
-        msgs = load_session_messages("s1")
+        msgs = load_messages("s1")
         assert len(msgs) == 3  # user, assistant+tool_calls, tool
         # Assistant should have content merged with tool_calls
         assert msgs[1]["role"] == "assistant"
@@ -177,7 +177,7 @@ class TestLoadSessionMessages:
         save_message("s1", "user", "do stuff")
         save_message("s1", "tool_call", None, "bash", '{"command":"ls"}')
         save_message("s1", "tool_result", "output", "bash")
-        msgs = load_session_messages("s1")
+        msgs = load_messages("s1")
         assert len(msgs) == 3
         # Synthetic IDs should match
         tc_id = msgs[1]["tool_calls"][0]["id"]
@@ -189,36 +189,36 @@ class TestLoadSessionMessages:
         save_message("s1", "tool_call", None, "search", '{"query":"b"}', tool_call_id="call_2")
         save_message("s1", "tool_result", "result a", "search", tool_call_id="call_1")
         save_message("s1", "tool_result", "result b", "search", tool_call_id="call_2")
-        msgs = load_session_messages("s1")
+        msgs = load_messages("s1")
         assert len(msgs) == 4  # user, assistant+2 tool_calls, 2 tool results
         assert len(msgs[1]["tool_calls"]) == 2
         assert msgs[2]["tool_call_id"] == "call_1"
         assert msgs[3]["tool_call_id"] == "call_2"
 
-    def test_empty_session(self, tmp_db):
-        assert load_session_messages("nonexistent") == []
+    def test_empty_workstream(self, tmp_db):
+        assert load_messages("nonexistent") == []
 
     def test_orphaned_tool_result_skipped(self, tmp_db):
         save_message("s1", "user", "hello")
         save_message("s1", "tool_result", "orphan", "bash")
-        msgs = load_session_messages("s1")
+        msgs = load_messages("s1")
         assert len(msgs) == 1  # only the user message
 
 
-# ── Delete session ────────────────────────────────────────────────────
+# ── Delete workstream ─────────────────────────────────────────────────
 
 
-class TestDeleteSession:
-    def test_delete_removes_session_and_messages(self, tmp_db):
-        register_session("abc123")
+class TestDeleteWorkstream:
+    def test_delete_removes_workstream_and_messages(self, tmp_db):
+        register_workstream("abc123")
         save_message("abc123", "user", "hello")
         save_message("abc123", "assistant", "hi")
-        assert delete_session("abc123") is True
-        assert list_sessions() == []
-        assert load_session_messages("abc123") == []
+        assert delete_workstream("abc123") is True
+        assert list_workstreams_with_history() == []
+        assert load_messages("abc123") == []
 
     def test_delete_nonexistent(self, tmp_db):
-        assert delete_session("nonexistent") is True  # no-op, still returns True
+        assert delete_workstream("nonexistent") is False
 
 
 # ── save_message with tool_call_id ────────────────────────────────────
@@ -230,7 +230,7 @@ class TestSaveMessageToolCallId:
         engine = get_storage()._engine  # noqa: SLF001
         with engine.connect() as conn:
             row = conn.execute(
-                sa.text("SELECT tool_call_id FROM conversations WHERE session_id = 's1'")
+                sa.text("SELECT tool_call_id FROM conversations WHERE ws_id = 's1'")
             ).fetchone()
             assert row[0] == "call_xyz"
 
@@ -239,20 +239,20 @@ class TestSaveMessageToolCallId:
         engine = get_storage()._engine  # noqa: SLF001
         with engine.connect() as conn:
             row = conn.execute(
-                sa.text("SELECT tool_call_id FROM conversations WHERE session_id = 's1'")
+                sa.text("SELECT tool_call_id FROM conversations WHERE ws_id = 's1'")
             ).fetchone()
             assert row[0] is None
 
 
-# ── Sessions table creation ───────────────────────────────────────────
+# ── Workstreams table creation ────────────────────────────────────────
 
 
-class TestSessionsTable:
-    def test_sessions_table_exists(self, tmp_db):
+class TestWorkstreamsTable:
+    def test_workstreams_table_exists(self, tmp_db):
         engine = get_storage()._engine  # noqa: SLF001
         with engine.connect() as conn:
             rows = conn.execute(
-                sa.text("SELECT name FROM sqlite_master WHERE type='table' AND name='sessions'")
+                sa.text("SELECT name FROM sqlite_master WHERE type='table' AND name='workstreams'")
             ).fetchall()
             assert len(rows) == 1
 
@@ -263,15 +263,15 @@ class TestSessionsTable:
             conn.execute(sa.text("SELECT tool_call_id FROM conversations LIMIT 0"))
 
 
-# ── ChatSession.resume_session ────────────────────────────────────────
+# ── ChatSession.resume ────────────────────────────────────────────────
 
 
-class TestResumeSession:
+class TestResumeWorkstream:
     def test_resume_loads_messages(self, tmp_db, mock_openai_client):
-        # Set up a session with messages in DB
-        register_session("old_sess_123")
-        save_message("old_sess_123", "user", "hello world")
-        save_message("old_sess_123", "assistant", "hi there")
+        # Set up a workstream with messages in DB
+        register_workstream("old_ws_123")
+        save_message("old_ws_123", "user", "hello world")
+        save_message("old_ws_123", "assistant", "hi there")
 
         # Create a new session and resume
         session = ChatSession(
@@ -283,12 +283,12 @@ class TestResumeSession:
             max_tokens=1000,
             tool_timeout=10,
         )
-        original_id = session._session_id
-        assert original_id != "old_sess_123"
+        original_id = session._ws_id
+        assert original_id != "old_ws_123"
 
-        result = session.resume_session("old_sess_123")
+        result = session.resume("old_ws_123")
         assert result is True
-        assert session._session_id == "old_sess_123"
+        assert session._ws_id == "old_ws_123"
         assert len(session.messages) == 2
         assert session.messages[0]["content"] == "hello world"
         assert session._title_generated is True
@@ -303,9 +303,9 @@ class TestResumeSession:
             max_tokens=1000,
             tool_timeout=10,
         )
-        assert session.resume_session("nonexistent") is False
+        assert session.resume("nonexistent") is False
 
-    def test_session_registered_on_init(self, tmp_db, mock_openai_client):
+    def test_workstream_not_registered_until_message(self, tmp_db, mock_openai_client):
         session = ChatSession(
             client=mock_openai_client,
             model="test-model",
@@ -315,20 +315,19 @@ class TestResumeSession:
             max_tokens=1000,
             tool_timeout=10,
         )
-        # Session is registered in DB (resolvable) even before any messages
-        assert resolve_session(session._session_id) == session._session_id
-        # But does not appear in list_sessions until a message is saved
-        assert not any(r[0] == session._session_id for r in list_sessions())
+        # Workstream is not auto-registered on init — only on /new or server creation
+        assert resolve_workstream(session._ws_id) is None
+        assert not any(r[0] == session._ws_id for r in list_workstreams_with_history())
 
 
-# ── save_message updates sessions.updated ─────────────────────────────
+# ── save_message updates workstreams.updated ──────────────────────────
 
 
-class TestSaveMessageUpdatesSession:
+class TestSaveMessageUpdatesWorkstream:
     def test_updated_timestamp_bumped(self, tmp_db):
-        register_session("s1")
+        register_workstream("s1")
         save_message("s1", "user", "first")
-        rows = list_sessions()
+        rows = list_workstreams_with_history()
         _original_updated = rows[0][4]
 
         import time
@@ -336,18 +335,18 @@ class TestSaveMessageUpdatesSession:
         time.sleep(0.01)  # ensure different timestamp
         save_message("s1", "user", "hello")
 
-        rows = list_sessions()
+        rows = list_workstreams_with_history()
         new_updated = rows[0][4]
         # updated should be same or later (sqlite datetime resolution is seconds,
         # so they may be equal in fast tests — just verify no error)
         assert new_updated is not None
 
 
-# ── Interrupted session repair ───────────────────────────────────────
+# ── Interrupted workstream repair ─────────────────────────────────────
 
 
-class TestInterruptedSessionRepair:
-    """load_session_messages() should strip trailing incomplete tool call turns."""
+class TestInterruptedWorkstreamRepair:
+    """load_messages() should strip trailing incomplete tool call turns."""
 
     def test_complete_tool_turn_preserved(self, tmp_db):
         """2 tool_calls + 2 tool_results = complete, no stripping."""
@@ -356,7 +355,7 @@ class TestInterruptedSessionRepair:
         save_message("s1", "tool_call", None, "bash", '{"command":"pwd"}', "call_2")
         save_message("s1", "tool_result", "file.txt", tool_call_id="call_1")
         save_message("s1", "tool_result", "/home", tool_call_id="call_2")
-        msgs = load_session_messages("s1")
+        msgs = load_messages("s1")
         assert len(msgs) == 4  # user + assistant(2 calls) + 2 tool results
 
     def test_partial_tool_results_stripped(self, tmp_db):
@@ -365,7 +364,7 @@ class TestInterruptedSessionRepair:
         save_message("s1", "tool_call", None, "bash", '{"command":"ls"}', "call_1")
         save_message("s1", "tool_call", None, "bash", '{"command":"pwd"}', "call_2")
         save_message("s1", "tool_result", "file.txt", tool_call_id="call_1")
-        msgs = load_session_messages("s1")
+        msgs = load_messages("s1")
         assert len(msgs) == 1  # only user message remains
         assert msgs[0]["role"] == "user"
 
@@ -375,7 +374,7 @@ class TestInterruptedSessionRepair:
         save_message("s1", "assistant", "Let me check")
         save_message("s1", "tool_call", None, "bash", '{"command":"ls"}', "call_1")
         save_message("s1", "tool_call", None, "bash", '{"command":"pwd"}', "call_2")
-        msgs = load_session_messages("s1")
+        msgs = load_messages("s1")
         # assistant with content was merged into tool_call assistant, so stripped
         assert len(msgs) == 1
         assert msgs[0]["role"] == "user"
@@ -386,42 +385,42 @@ class TestInterruptedSessionRepair:
         save_message("s1", "assistant", "response")
         save_message("s1", "user", "second")
         save_message("s1", "tool_call", None, "bash", '{"command":"ls"}', "call_1")
-        msgs = load_session_messages("s1")
+        msgs = load_messages("s1")
         assert len(msgs) == 3  # user + assistant + user (incomplete turn stripped)
         assert msgs[0]["role"] == "user"
         assert msgs[1]["role"] == "assistant"
         assert msgs[2]["role"] == "user"
 
 
-# ── Session config persistence ───────────────────────────────────────
+# ── Workstream config persistence ─────────────────────────────────────
 
 
-class TestSessionConfig:
+class TestWorkstreamConfig:
     def test_save_load_roundtrip(self, tmp_db):
         config = {"temperature": "0.3", "reasoning_effort": "high", "creative_mode": "False"}
-        save_session_config("s1", config)
-        loaded = load_session_config("s1")
+        save_workstream_config("s1", config)
+        loaded = load_workstream_config("s1")
         assert loaded == config
 
     def test_update_existing_key(self, tmp_db):
-        save_session_config("s1", {"temperature": "0.3"})
-        save_session_config("s1", {"temperature": "0.7"})
-        loaded = load_session_config("s1")
+        save_workstream_config("s1", {"temperature": "0.3"})
+        save_workstream_config("s1", {"temperature": "0.7"})
+        loaded = load_workstream_config("s1")
         assert loaded["temperature"] == "0.7"
 
-    def test_missing_session_returns_empty(self, tmp_db):
-        loaded = load_session_config("nonexistent")
+    def test_missing_workstream_returns_empty(self, tmp_db):
+        loaded = load_workstream_config("nonexistent")
         assert loaded == {}
 
-    def test_delete_session_removes_config(self, tmp_db):
-        register_session("s1")
+    def test_delete_workstream_removes_config(self, tmp_db):
+        register_workstream("s1")
         save_message("s1", "user", "hi")
-        save_session_config("s1", {"temperature": "0.5"})
-        delete_session("s1")
-        assert load_session_config("s1") == {}
+        save_workstream_config("s1", {"temperature": "0.5"})
+        delete_workstream("s1")
+        assert load_workstream_config("s1") == {}
 
     def test_resume_restores_config(self, tmp_db):
-        """ChatSession.resume_session() should restore persisted config."""
+        """ChatSession.resume() should restore persisted config."""
         client = MagicMock()
         client.models.list.return_value.data = [MagicMock(id="test-model")]
         ui = MagicMock()
@@ -430,11 +429,11 @@ class TestSessionConfig:
         ui.on_state_change = MagicMock()
         ui.on_rename = MagicMock()
 
-        # Create a session with specific config
-        register_session("orig")
+        # Create a workstream with specific config
+        register_workstream("orig")
         save_message("orig", "user", "hello")
         save_message("orig", "assistant", "hi there")
-        save_session_config(
+        save_workstream_config(
             "orig",
             {
                 "temperature": "0.3",
@@ -456,7 +455,7 @@ class TestSessionConfig:
             tool_timeout=30,
         )
         assert session.temperature == 0.7  # default
-        result = session.resume_session("orig")
+        result = session.resume("orig")
         assert result is True
         assert session.temperature == 0.3
         assert session.reasoning_effort == "high"
@@ -465,84 +464,84 @@ class TestSessionConfig:
         assert session.creative_mode is True
 
 
-# ── Prune sessions ───────────────────────────────────────────────────
+# ── Prune workstreams ─────────────────────────────────────────────────
 
 
-class TestPruneSessions:
+class TestPruneWorkstreams:
     def test_orphan_removed(self, tmp_db):
-        """Session registered with no messages should be pruned."""
-        register_session("orphan")
-        orphans, stale = prune_sessions()
+        """Workstream registered with no messages should be pruned."""
+        register_workstream("orphan")
+        orphans, stale = prune_workstreams()
         assert orphans == 1
-        assert list_sessions() == []
+        assert list_workstreams_with_history() == []
 
-    def test_session_with_messages_kept(self, tmp_db):
-        """Session with messages should not be pruned."""
-        register_session("active")
+    def test_workstream_with_messages_kept(self, tmp_db):
+        """Workstream with messages should not be pruned."""
+        register_workstream("active")
         save_message("active", "user", "hello")
-        orphans, _stale = prune_sessions()
+        orphans, _stale = prune_workstreams()
         assert orphans == 0
-        assert len(list_sessions()) == 1
+        assert len(list_workstreams_with_history()) == 1
 
     def test_stale_unnamed_removed(self, tmp_db):
-        """Old unnamed session should be pruned by retention policy."""
-        register_session("old1")
+        """Old unnamed workstream should be pruned by retention policy."""
+        register_workstream("old1")
         save_message("old1", "user", "ancient message")
         # Force the updated timestamp to the past so it looks stale
         engine = get_storage()._engine  # noqa: SLF001
         with engine.connect() as conn:
             conn.execute(
-                sa.text("UPDATE sessions SET updated = '2020-01-01' WHERE session_id = 'old1'")
+                sa.text("UPDATE workstreams SET updated = '2020-01-01' WHERE ws_id = 'old1'")
             )
             conn.commit()
-        _orphans, stale = prune_sessions(retention_days=30)
+        _orphans, stale = prune_workstreams(retention_days=30)
         assert stale == 1
 
-    def test_named_session_preserved(self, tmp_db):
-        """Session with alias should be kept regardless of age."""
-        register_session("old2")
-        set_session_alias("old2", "important")
+    def test_named_workstream_preserved(self, tmp_db):
+        """Workstream with alias should be kept regardless of age."""
+        register_workstream("old2")
+        set_workstream_alias("old2", "important")
         save_message("old2", "user", "old but named")
         # Force old timestamp
         engine = get_storage()._engine  # noqa: SLF001
         with engine.connect() as conn:
             conn.execute(
-                sa.text("UPDATE sessions SET updated = '2020-01-01' WHERE session_id = 'old2'")
+                sa.text("UPDATE workstreams SET updated = '2020-01-01' WHERE ws_id = 'old2'")
             )
             conn.commit()
-        _orphans, stale = prune_sessions(retention_days=30)
+        _orphans, stale = prune_workstreams(retention_days=30)
         assert stale == 0
-        assert len(list_sessions()) == 1
+        assert len(list_workstreams_with_history()) == 1
 
     def test_fresh_unnamed_preserved(self, tmp_db):
-        """Recent unnamed session should not be pruned."""
-        register_session("fresh")
+        """Recent unnamed workstream should not be pruned."""
+        register_workstream("fresh")
         save_message("fresh", "user", "just now")
-        _orphans, stale = prune_sessions(retention_days=30)
+        _orphans, stale = prune_workstreams(retention_days=30)
         assert stale == 0
-        assert len(list_sessions()) == 1
+        assert len(list_workstreams_with_history()) == 1
 
-    def test_prune_removes_session_config(self, tmp_db):
-        """Pruning orphan/stale sessions should also remove their config rows."""
-        register_session("orphan_cfg")
-        save_session_config("orphan_cfg", {"temperature": "0.5"})
+    def test_prune_removes_workstream_config(self, tmp_db):
+        """Pruning orphan/stale workstreams should also remove their config rows."""
+        register_workstream("orphan_cfg")
+        save_workstream_config("orphan_cfg", {"temperature": "0.5"})
 
-        register_session("stale_cfg")
+        register_workstream("stale_cfg")
         save_message("stale_cfg", "user", "old")
-        save_session_config("stale_cfg", {"temperature": "0.9"})
+        save_workstream_config("stale_cfg", {"temperature": "0.9"})
         engine = get_storage()._engine  # noqa: SLF001
         with engine.connect() as conn:
             conn.execute(
-                sa.text("UPDATE sessions SET updated = '2020-01-01' WHERE session_id = 'stale_cfg'")
+                sa.text("UPDATE workstreams SET updated = '2020-01-01' WHERE ws_id = 'stale_cfg'")
             )
             conn.commit()
 
         # Both should have config before prune
-        assert load_session_config("orphan_cfg") == {"temperature": "0.5"}
-        assert load_session_config("stale_cfg") == {"temperature": "0.9"}
+        assert load_workstream_config("orphan_cfg") == {"temperature": "0.5"}
+        assert load_workstream_config("stale_cfg") == {"temperature": "0.9"}
 
-        prune_sessions(retention_days=30)
+        prune_workstreams(retention_days=30)
 
         # Config rows should be cleaned up
-        assert load_session_config("orphan_cfg") == {}
-        assert load_session_config("stale_cfg") == {}
+        assert load_workstream_config("orphan_cfg") == {}
+        assert load_workstream_config("stale_cfg") == {}

tests/test_storage_sqlite.py

@@ -14,28 +14,28 @@ def backend(tmp_path):
     reset_storage()
 
 
-# -- Session operations --------------------------------------------------------
+# -- Workstream registration ---------------------------------------------------
 
 
-class TestRegisterSession:
-    def test_register_creates_session(self, backend):
-        backend.register_session("s1", title="Test")
-        name = backend.get_session_name("s1")
+class TestRegisterWorkstream:
+    def test_register_creates_workstream(self, backend):
+        backend.register_workstream("s1", title="Test")
+        name = backend.get_workstream_display_name("s1")
         assert name == "Test"
 
     def test_register_idempotent(self, backend):
-        backend.register_session("s1", title="First")
-        backend.register_session("s1", title="Second")
-        name = backend.get_session_name("s1")
+        backend.register_workstream("s1", title="First")
+        backend.register_workstream("s1", title="Second")
+        name = backend.get_workstream_display_name("s1")
         assert name == "First"  # INSERT OR IGNORE preserves first
 
 
 class TestSaveAndLoadMessages:
     def test_roundtrip(self, backend):
-        backend.register_session("s1")
+        backend.register_workstream("s1")
         backend.save_message("s1", "user", "hello")
         backend.save_message("s1", "assistant", "world")
-        msgs = backend.load_session_messages("s1")
+        msgs = backend.load_messages("s1")
         assert len(msgs) == 2
         assert msgs[0]["role"] == "user"
         assert msgs[0]["content"] == "hello"
@@ -43,12 +43,12 @@ class TestSaveAndLoadMessages:
         assert msgs[1]["content"] == "world"
 
     def test_tool_call_grouping(self, backend):
-        backend.register_session("s1")
+        backend.register_workstream("s1")
         backend.save_message("s1", "user", "do something")
         backend.save_message("s1", "tool_call", None, "bash", '{"cmd":"ls"}', tool_call_id="c1")
         backend.save_message("s1", "tool_result", "file.txt", tool_call_id="c1")
         backend.save_message("s1", "assistant", "done")
-        msgs = backend.load_session_messages("s1")
+        msgs = backend.load_messages("s1")
         assert len(msgs) == 4
         assert msgs[1]["role"] == "assistant"
         assert len(msgs[1]["tool_calls"]) == 1
@@ -57,136 +57,136 @@ class TestSaveAndLoadMessages:
         assert msgs[2]["content"] == "file.txt"
 
     def test_incomplete_turn_repair(self, backend):
-        backend.register_session("s1")
+        backend.register_workstream("s1")
         backend.save_message("s1", "user", "do something")
         backend.save_message("s1", "tool_call", None, "bash", '{"cmd":"ls"}', tool_call_id="c1")
         backend.save_message("s1", "tool_call", None, "read", '{"path":"a"}', tool_call_id="c2")
         # Only 1 result for 2 calls — incomplete turn
         backend.save_message("s1", "tool_result", "ok", tool_call_id="c1")
-        msgs = backend.load_session_messages("s1")
+        msgs = backend.load_messages("s1")
         # Incomplete turn should be stripped
         assert len(msgs) == 1  # only the user message remains
 
     def test_provider_data_preserved(self, backend):
         import json
 
-        backend.register_session("s1")
+        backend.register_workstream("s1")
         pd = json.dumps({"encrypted": True})
         backend.save_message("s1", "assistant", "hi", provider_data=pd)
-        msgs = backend.load_session_messages("s1")
+        msgs = backend.load_messages("s1")
         assert msgs[0].get("_provider_content") == {"encrypted": True}
 
-    def test_empty_session_returns_empty(self, backend):
-        assert backend.load_session_messages("nonexistent") == []
+    def test_empty_workstream_returns_empty(self, backend):
+        assert backend.load_messages("nonexistent") == []
 
 
-class TestListSessions:
-    def test_lists_sessions_with_messages(self, backend):
-        backend.register_session("s1")
+class TestListWorkstreamsWithHistory:
+    def test_lists_workstreams_with_messages(self, backend):
+        backend.register_workstream("s1")
         backend.save_message("s1", "user", "hi")
-        backend.register_session("s2")  # no messages
-        rows = backend.list_sessions()
+        backend.register_workstream("s2")  # no messages
+        rows = backend.list_workstreams_with_history()
         assert len(rows) == 1
         assert rows[0][0] == "s1"
 
     def test_respects_limit(self, backend):
         for i in range(5):
             sid = f"s{i}"
-            backend.register_session(sid)
+            backend.register_workstream(sid)
             backend.save_message(sid, "user", f"msg {i}")
-        rows = backend.list_sessions(limit=3)
+        rows = backend.list_workstreams_with_history(limit=3)
         assert len(rows) == 3
 
 
-class TestDeleteSession:
+class TestDeleteWorkstream:
     def test_deletes_all_data(self, backend):
-        backend.register_session("s1")
+        backend.register_workstream("s1")
         backend.save_message("s1", "user", "hi")
-        backend.save_session_config("s1", {"temp": "0.5"})
-        assert backend.delete_session("s1")
-        assert backend.load_session_messages("s1") == []
-        assert backend.load_session_config("s1") == {}
-        assert backend.get_session_name("s1") is None
+        backend.save_workstream_config("s1", {"temp": "0.5"})
+        assert backend.delete_workstream("s1")
+        assert backend.load_messages("s1") == []
+        assert backend.load_workstream_config("s1") == {}
+        assert backend.get_workstream_display_name("s1") is None
 
 
-class TestPruneSessions:
+class TestPruneWorkstreams:
     def test_orphan_removed(self, backend):
-        backend.register_session("orphan")
-        orphans, stale = backend.prune_sessions()
+        backend.register_workstream("orphan")
+        orphans, stale = backend.prune_workstreams()
         assert orphans == 1
 
     def test_stale_removed(self, backend):
         import sqlalchemy as sa
 
-        backend.register_session("old")
+        backend.register_workstream("old")
         backend.save_message("old", "user", "hi")
         # Force old timestamp
         with backend._engine.connect() as conn:
             conn.execute(
-                sa.text("UPDATE sessions SET updated = '2020-01-01' WHERE session_id = 'old'")
+                sa.text("UPDATE workstreams SET updated = '2020-01-01' WHERE ws_id = 'old'")
             )
             conn.commit()
-        _, stale = backend.prune_sessions(retention_days=30)
+        _, stale = backend.prune_workstreams(retention_days=30)
         assert stale == 1
 
 
-class TestResolveSession:
+class TestResolveWorkstream:
     def test_exact_alias(self, backend):
-        backend.register_session("s1")
-        backend.set_session_alias("s1", "myalias")
-        assert backend.resolve_session("myalias") == "s1"
+        backend.register_workstream("s1")
+        backend.set_workstream_alias("s1", "myalias")
+        assert backend.resolve_workstream("myalias") == "s1"
 
     def test_exact_id(self, backend):
-        backend.register_session("abc-123-def")
-        assert backend.resolve_session("abc-123-def") == "abc-123-def"
+        backend.register_workstream("abc-123-def")
+        assert backend.resolve_workstream("abc-123-def") == "abc-123-def"
 
     def test_prefix_match(self, backend):
-        backend.register_session("abc-123-def")
-        assert backend.resolve_session("abc") == "abc-123-def"
+        backend.register_workstream("abc-123-def")
+        assert backend.resolve_workstream("abc") == "abc-123-def"
 
     def test_not_found(self, backend):
-        assert backend.resolve_session("nonexistent") is None
+        assert backend.resolve_workstream("nonexistent") is None
 
 
-# -- Session config ------------------------------------------------------------
+# -- Workstream config ---------------------------------------------------------
 
 
-class TestSessionConfig:
+class TestWorkstreamConfig:
     def test_roundtrip(self, backend):
-        backend.register_session("s1")
-        backend.save_session_config("s1", {"temperature": "0.7", "effort": "high"})
-        cfg = backend.load_session_config("s1")
+        backend.register_workstream("s1")
+        backend.save_workstream_config("s1", {"temperature": "0.7", "effort": "high"})
+        cfg = backend.load_workstream_config("s1")
         assert cfg == {"temperature": "0.7", "effort": "high"}
 
     def test_empty_config(self, backend):
-        assert backend.load_session_config("nonexistent") == {}
+        assert backend.load_workstream_config("nonexistent") == {}
 
 
-# -- Session metadata ----------------------------------------------------------
+# -- Workstream metadata ------------------------------------------------------
 
 
-class TestSessionMetadata:
+class TestWorkstreamMetadata:
     def test_alias(self, backend):
-        backend.register_session("s1")
-        assert backend.set_session_alias("s1", "my-session")
-        assert backend.get_session_name("s1") == "my-session"
+        backend.register_workstream("s1")
+        assert backend.set_workstream_alias("s1", "my-session")
+        assert backend.get_workstream_display_name("s1") == "my-session"
 
     def test_alias_conflict(self, backend):
-        backend.register_session("s1")
-        backend.register_session("s2")
-        backend.set_session_alias("s1", "taken")
-        assert not backend.set_session_alias("s2", "taken")
+        backend.register_workstream("s1")
+        backend.register_workstream("s2")
+        backend.set_workstream_alias("s1", "taken")
+        assert not backend.set_workstream_alias("s2", "taken")
 
     def test_title(self, backend):
-        backend.register_session("s1")
-        backend.update_session_title("s1", "My Title")
-        assert backend.get_session_name("s1") == "My Title"
+        backend.register_workstream("s1")
+        backend.update_workstream_title("s1", "My Title")
+        assert backend.get_workstream_display_name("s1") == "My Title"
 
     def test_alias_preferred_over_title(self, backend):
-        backend.register_session("s1")
-        backend.update_session_title("s1", "Title")
-        backend.set_session_alias("s1", "Alias")
-        assert backend.get_session_name("s1") == "Alias"
+        backend.register_workstream("s1")
+        backend.update_workstream_title("s1", "Title")
+        backend.set_workstream_alias("s1", "Alias")
+        assert backend.get_workstream_display_name("s1") == "Alias"
 
 
 # -- Key-value store -----------------------------------------------------------
@@ -234,7 +234,7 @@ class TestKVStore:
 
 class TestSearch:
     def test_search_history(self, backend):
-        backend.register_session("s1")
+        backend.register_workstream("s1")
         backend.save_message("s1", "user", "hello world")
         backend.save_message("s1", "user", "goodbye world")
         results = backend.search_history("hello")
@@ -242,7 +242,7 @@ class TestSearch:
         assert any("hello" in str(r[3]) for r in results)
 
     def test_search_recent(self, backend):
-        backend.register_session("s1")
+        backend.register_workstream("s1")
         backend.save_message("s1", "user", "msg1")
         backend.save_message("s1", "user", "msg2")
         results = backend.search_history_recent(limit=1)
@@ -293,15 +293,14 @@ class TestWorkstreams:
         assert len(rows) == 1
         assert rows[0][0] == "ws1"
 
-    def test_session_with_ws_id(self, backend):
+    def test_workstream_with_messages_in_history(self, backend):
         backend.register_workstream("ws1", node_id="node-a")
-        backend.register_session("s1", node_id="node-a", ws_id="ws1")
-        backend.save_message("s1", "user", "hello")
-        rows = backend.list_sessions()
+        backend.save_message("ws1", "user", "hello")
+        rows = backend.list_workstreams_with_history()
         assert len(rows) == 1
-        # Columns: sid, alias, title, created, updated, count, node_id, ws_id
+        # Columns: ws_id, alias, title, created, updated, count, node_id
+        assert rows[0][0] == "ws1"
         assert rows[0][6] == "node-a"
-        assert rows[0][7] == "ws1"
 
 
 # -- Lifecycle -----------------------------------------------------------------

tests/test_tool_policy.py

@@ -0,0 +1,167 @@
+"""Tests for turnstone.core.policy."""
+
+import pytest
+
+from turnstone.core.policy import evaluate_tool_policies_batch, evaluate_tool_policy
+from turnstone.core.storage._sqlite import SQLiteBackend
+
+
+@pytest.fixture
+def storage(tmp_path):
+    path = str(tmp_path / "test.db")
+    backend = SQLiteBackend(path)
+    yield backend
+    backend.close()
+
+
+def test_no_policies_returns_none(storage):
+    result = evaluate_tool_policy(storage, "bash")
+    assert result is None
+
+
+def test_exact_match_allow(storage):
+    storage.create_tool_policy("p1", "allow-read", "read_file", "allow", 0)
+    assert evaluate_tool_policy(storage, "read_file") == "allow"
+    assert evaluate_tool_policy(storage, "write_file") is None
+
+
+def test_glob_match_deny(storage):
+    storage.create_tool_policy("p1", "block-bash", "bash*", "deny", 0)
+    assert evaluate_tool_policy(storage, "bash") == "deny"
+    assert evaluate_tool_policy(storage, "bash_exec") == "deny"
+    assert evaluate_tool_policy(storage, "read_file") is None
+
+
+def test_wildcard_match(storage):
+    storage.create_tool_policy("p1", "ask-all", "*", "ask", 0)
+    assert evaluate_tool_policy(storage, "anything") == "ask"
+
+
+def test_priority_ordering(storage):
+    # Higher priority wins
+    storage.create_tool_policy("p1", "allow-all", "*", "allow", 0)
+    storage.create_tool_policy("p2", "deny-bash", "bash*", "deny", 100)
+    assert evaluate_tool_policy(storage, "bash") == "deny"  # p2 matches first (higher priority)
+    assert evaluate_tool_policy(storage, "read_file") == "allow"  # p1 matches
+
+
+def test_disabled_policy_skipped(storage):
+    storage.create_tool_policy("p1", "block-bash", "bash*", "deny", 100, enabled=False)
+    storage.create_tool_policy("p2", "allow-all", "*", "allow", 0)
+    assert evaluate_tool_policy(storage, "bash") == "allow"  # p1 disabled, falls through to p2
+
+
+def test_batch_evaluation(storage):
+    storage.create_tool_policy("p1", "block-bash", "bash*", "deny", 100)
+    storage.create_tool_policy("p2", "allow-read", "read_*", "allow", 50)
+    results = evaluate_tool_policies_batch(storage, ["bash", "read_file", "write_file"])
+    assert results["bash"] == "deny"
+    assert results["read_file"] == "allow"
+    assert results["write_file"] is None
+
+
+def test_storage_failure_returns_none():
+    """Graceful degradation on storage failure."""
+
+    class BrokenStorage:
+        def list_tool_policies(self, org_id=""):
+            raise RuntimeError("boom")
+
+    assert evaluate_tool_policy(BrokenStorage(), "bash") is None
+
+
+def test_batch_storage_failure():
+    class BrokenStorage:
+        def list_tool_policies(self, org_id=""):
+            raise RuntimeError("boom")
+
+    results = evaluate_tool_policies_batch(BrokenStorage(), ["a", "b"])
+    assert results == {"a": None, "b": None}
+
+
+def test_first_match_wins(storage):
+    # Two policies match, first by priority wins
+    storage.create_tool_policy("p1", "deny-bash", "bash*", "deny", 100)
+    storage.create_tool_policy("p2", "allow-bash", "bash*", "allow", 50)
+    assert evaluate_tool_policy(storage, "bash_exec") == "deny"
+
+
+# ---------------------------------------------------------------------------
+# MCP resource and prompt policy patterns
+# ---------------------------------------------------------------------------
+
+
+def test_mcp_resource_wildcard_deny(storage):
+    """Deny all MCP resource reads via glob pattern."""
+    storage.create_tool_policy("p1", "block-resources", "mcp_resource__*", "deny", 100)
+    assert evaluate_tool_policy(storage, "mcp_resource__file:///secret.txt") == "deny"
+    assert evaluate_tool_policy(storage, "mcp_resource__db://users") == "deny"
+    assert evaluate_tool_policy(storage, "read_file") is None  # unrelated tool
+
+
+def test_mcp_resource_per_server_pattern(storage):
+    """Allow resources from a specific server, deny others."""
+    storage.create_tool_policy("p1", "block-all-resources", "mcp_resource__*", "deny", 50)
+    storage.create_tool_policy("p2", "allow-docs", "mcp_resource__file:///docs/*", "allow", 100)
+    assert evaluate_tool_policy(storage, "mcp_resource__file:///docs/readme.md") == "allow"
+    assert evaluate_tool_policy(storage, "mcp_resource__file:///etc/passwd") == "deny"
+
+
+def test_mcp_prompt_wildcard_ask(storage):
+    """Require approval for all MCP prompt invocations."""
+    storage.create_tool_policy("p1", "ask-prompts", "mcp__*", "ask", 100)
+    assert evaluate_tool_policy(storage, "mcp__github__code_review") == "ask"
+    assert evaluate_tool_policy(storage, "mcp__templates__greeting") == "ask"
+    assert evaluate_tool_policy(storage, "bash") is None
+
+
+def test_mcp_prompt_per_server_allow(storage):
+    """Auto-approve prompts from a trusted server."""
+    storage.create_tool_policy("p1", "ask-all-mcp", "mcp__*", "ask", 50)
+    storage.create_tool_policy("p2", "allow-trusted", "mcp__trusted__*", "allow", 100)
+    assert evaluate_tool_policy(storage, "mcp__trusted__greeting") == "allow"
+    assert evaluate_tool_policy(storage, "mcp__untrusted__evil") == "ask"
+
+
+def test_mcp_batch_mixed(storage):
+    """Batch evaluation with mixed MCP and built-in tools."""
+    storage.create_tool_policy("p1", "block-resources", "mcp_resource__*", "deny", 100)
+    storage.create_tool_policy("p2", "allow-prompts", "mcp__trusted__*", "allow", 100)
+    results = evaluate_tool_policies_batch(
+        storage,
+        ["mcp_resource__file:///x", "mcp__trusted__greeting", "bash", "mcp__other__y"],
+    )
+    assert results["mcp_resource__file:///x"] == "deny"
+    assert results["mcp__trusted__greeting"] == "allow"
+    assert results["bash"] is None
+    assert results["mcp__other__y"] is None
+
+
+def test_normalize_resource_uri_prevents_traversal():
+    """URI normalization resolves .. segments to prevent policy traversal bypass."""
+    from turnstone.core.session import ChatSession
+
+    # Normal URI unchanged
+    assert ChatSession._normalize_resource_uri("file:///docs/readme.md") == "file:///docs/readme.md"
+    # Traversal resolved
+    assert ChatSession._normalize_resource_uri("file:///docs/../etc/passwd") == "file:///etc/passwd"
+    # Double traversal
+    assert ChatSession._normalize_resource_uri("file:///a/b/../../c") == "file:///c"
+    # Non-file scheme (netloc preserved, path normalized)
+    assert ChatSession._normalize_resource_uri("db://host/tables/../secrets") == "db://host/secrets"
+    # Percent-encoded traversal decoded before normalization
+    assert (
+        ChatSession._normalize_resource_uri("file:///docs/%2e%2e/etc/passwd")
+        == "file:///etc/passwd"
+    )
+    # Mixed percent-encoded and literal traversal
+    assert ChatSession._normalize_resource_uri("file:///a/%2e%2e/b/../c") == "file:///c"
+
+
+def test_mcp_tool_granular_policy(storage):
+    """MCP tool calls use their prefixed func_name for granular policy matching."""
+    storage.create_tool_policy("p1", "ask-all-mcp", "mcp__*", "ask", 50)
+    storage.create_tool_policy("p2", "allow-github", "mcp__github__*", "allow", 100)
+    # MCP tools now use func_name as approval_label
+    assert evaluate_tool_policy(storage, "mcp__github__search") == "allow"
+    assert evaluate_tool_policy(storage, "mcp__untrusted__exec") == "ask"

tests/test_tool_search.py

@@ -0,0 +1,254 @@
+"""Tests for turnstone.core.tool_search — BM25 index and tool search manager."""
+
+from __future__ import annotations
+
+import pytest
+
+from turnstone.core.tool_search import (
+    BM25Index,
+    ToolSearchManager,
+    _mcp_server_summary,
+    _tokenize,
+    _tool_name,
+)
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_tool(name: str, description: str = "") -> dict:
+    """Create a minimal OpenAI-format tool dict for testing."""
+    return {
+        "type": "function",
+        "function": {
+            "name": name,
+            "description": description or f"Tool {name}",
+            "parameters": {"type": "object", "properties": {}},
+        },
+    }
+
+
+# ---------------------------------------------------------------------------
+# BM25Index tests
+# ---------------------------------------------------------------------------
+
+
+class TestTokenize:
+    def test_basic_split(self):
+        assert _tokenize("hello world") == ["hello", "world"]
+
+    def test_underscore_split(self):
+        assert _tokenize("create_issue") == ["create", "issue"]
+
+    def test_mixed_delimiters(self):
+        assert _tokenize("mcp__github__create-issue") == ["mcp", "github", "create", "issue"]
+
+    def test_empty_string(self):
+        assert _tokenize("") == []
+
+    def test_lowercased(self):
+        assert _tokenize("GitHub Create") == ["github", "create"]
+
+
+class TestBM25Index:
+    def test_empty_corpus(self):
+        idx = BM25Index([])
+        assert idx.search("test") == []
+
+    def test_empty_query(self):
+        idx = BM25Index(["hello world", "foo bar"])
+        assert idx.search("") == []
+
+    def test_single_document(self):
+        idx = BM25Index(["create github issue"])
+        assert idx.search("github") == [0]
+
+    def test_ranking_order(self):
+        docs = [
+            "list_repos List all repositories",
+            "create_issue Create a new GitHub issue",
+            "get_issue Get details of a GitHub issue",
+        ]
+        idx = BM25Index(docs)
+        results = idx.search("github issue")
+        # Both issue-related docs should rank above list_repos
+        assert 1 in results[:2]
+        assert 2 in results[:2]
+
+    def test_top_k_limit(self):
+        docs = [f"tool_{i} description {i}" for i in range(20)]
+        idx = BM25Index(docs)
+        results = idx.search("tool description", k=3)
+        assert len(results) <= 3
+
+    def test_no_match(self):
+        idx = BM25Index(["alpha beta gamma"])
+        assert idx.search("zzzzz") == []
+
+    def test_exact_name_match_ranks_high(self):
+        docs = [
+            "send_email Send an email message",
+            "send_slack Send a Slack message",
+            "read_email Read email inbox",
+        ]
+        idx = BM25Index(docs)
+        results = idx.search("send email")
+        assert results[0] == 0  # send_email should rank first
+
+
+# ---------------------------------------------------------------------------
+# ToolSearchManager tests
+# ---------------------------------------------------------------------------
+
+
+class TestToolSearchManager:
+    @pytest.fixture()
+    def builtin_tools(self):
+        return [
+            _make_tool("bash", "Execute shell commands"),
+            _make_tool("read_file", "Read a file"),
+            _make_tool("edit_file", "Edit a file"),
+        ]
+
+    @pytest.fixture()
+    def mcp_tools(self):
+        return [
+            _make_tool("mcp__github__create_issue", "Create a new GitHub issue"),
+            _make_tool("mcp__github__list_issues", "List GitHub issues"),
+            _make_tool("mcp__github__get_repo", "Get repository details"),
+            _make_tool("mcp__slack__send_message", "Send a Slack message"),
+            _make_tool("mcp__slack__list_channels", "List Slack channels"),
+            _make_tool("mcp__jira__create_ticket", "Create a Jira ticket"),
+        ]
+
+    @pytest.fixture()
+    def manager(self, builtin_tools, mcp_tools):
+        all_tools = builtin_tools + mcp_tools
+        return ToolSearchManager(
+            all_tools,
+            always_on_names={"bash", "read_file", "edit_file"},
+            threshold=5,
+            max_results=3,
+        )
+
+    def test_should_activate_above_threshold(self, manager):
+        assert manager.should_activate()
+
+    def test_should_not_activate_below_threshold(self, builtin_tools):
+        mgr = ToolSearchManager(builtin_tools, always_on_names={"bash", "read_file", "edit_file"})
+        assert not mgr.should_activate()
+
+    def test_visible_tools_initially_builtin_only(self, manager):
+        visible = manager.get_visible_tools()
+        names = {_tool_name(t) for t in visible}
+        assert names == {"bash", "read_file", "edit_file"}
+
+    def test_deferred_tools_excludes_builtin(self, manager):
+        deferred = manager.get_deferred_tools()
+        names = {_tool_name(t) for t in deferred}
+        assert "bash" not in names
+        assert "mcp__github__create_issue" in names
+
+    def test_search_returns_relevant_tools(self, manager):
+        results = manager.search("github issue")
+        names = {_tool_name(t) for t in results}
+        assert "mcp__github__create_issue" in names or "mcp__github__list_issues" in names
+
+    def test_search_respects_max_results(self, manager):
+        results = manager.search("tool")
+        assert len(results) <= 3
+
+    def test_search_excludes_already_expanded(self, manager):
+        # Expand a github tool, then search for github — expanded tool should not appear
+        manager.expand_visible(["mcp__github__create_issue"])
+        results = manager.search("github issue")
+        names = {_tool_name(t) for t in results}
+        assert "mcp__github__create_issue" not in names
+
+    def test_expand_visible_adds_tools(self, manager):
+        manager.expand_visible(["mcp__github__create_issue"])
+        visible = manager.get_visible_tools()
+        names = {_tool_name(t) for t in visible}
+        assert "mcp__github__create_issue" in names
+
+    def test_expand_visible_returns_newly_added(self, manager):
+        added = manager.expand_visible(["mcp__github__create_issue", "mcp__slack__send_message"])
+        assert len(added) == 2
+        names = {_tool_name(t) for t in added}
+        assert names == {"mcp__github__create_issue", "mcp__slack__send_message"}
+
+    def test_expand_visible_idempotent(self, manager):
+        manager.expand_visible(["mcp__github__create_issue"])
+        added = manager.expand_visible(["mcp__github__create_issue"])
+        assert added == []
+
+    def test_expand_visible_ignores_unknown(self, manager):
+        added = manager.expand_visible(["nonexistent_tool"])
+        assert added == []
+
+    def test_get_expanded_names_empty(self, manager):
+        assert manager.get_expanded_names() == []
+
+    def test_get_expanded_names_after_expand(self, manager):
+        manager.expand_visible(["mcp__github__create_issue", "mcp__slack__send_message"])
+        names = manager.get_expanded_names()
+        assert names == ["mcp__github__create_issue", "mcp__slack__send_message"]
+
+    def test_deferred_excludes_expanded(self, manager):
+        manager.expand_visible(["mcp__github__create_issue"])
+        deferred = manager.get_deferred_tools()
+        names = {_tool_name(t) for t in deferred}
+        assert "mcp__github__create_issue" not in names
+
+    def test_get_all_tools_returns_everything(self, manager, builtin_tools, mcp_tools):
+        assert len(manager.get_all_tools()) == len(builtin_tools) + len(mcp_tools)
+
+    def test_search_tool_definition_format(self, manager):
+        defn = manager.get_search_tool_definition()
+        assert defn["type"] == "function"
+        fn = defn["function"]
+        assert fn["name"] == "tool_search"
+        assert "query" in fn["parameters"]["properties"]
+        assert "query" in fn["parameters"]["required"]
+
+    def test_search_tool_description_has_server_hint(self, manager):
+        defn = manager.get_search_tool_definition()
+        desc = defn["function"]["description"]
+        assert "github" in desc
+        assert "slack" in desc
+        assert "jira" in desc
+
+    def test_format_search_results_empty(self, manager):
+        text = manager.format_search_results([])
+        assert "No matching tools found" in text
+
+    def test_format_search_results_with_tools(self, manager, mcp_tools):
+        text = manager.format_search_results(mcp_tools[:2])
+        assert "Found 2" in text
+        assert "mcp__github__create_issue" in text
+
+
+# ---------------------------------------------------------------------------
+# Helper function tests
+# ---------------------------------------------------------------------------
+
+
+class TestMCPServerSummary:
+    def test_groups_by_server(self):
+        tools = [
+            _make_tool("mcp__github__a"),
+            _make_tool("mcp__github__b"),
+            _make_tool("mcp__slack__c"),
+        ]
+        summary = _mcp_server_summary(tools)
+        assert "github (2 tools)" in summary
+        assert "slack (1 tool)" in summary
+
+    def test_non_mcp_tools_counted_as_other(self):
+        tools = [_make_tool("custom_tool")]
+        summary = _mcp_server_summary(tools)
+        assert "other (1 tool)" in summary
+
+    def test_empty_list(self):
+        assert _mcp_server_summary([]) == ""

tests/test_tools_schema.py

@@ -72,16 +72,24 @@ class TestToolsMetadata:
     """Validate the metadata extracted from JSON files."""
 
     def test_tool_count(self):
-        assert len(TOOLS) == 15
+        assert len(TOOLS) == 18
 
     def test_agent_tools_count(self):
-        assert len(AGENT_TOOLS) == 7
+        assert len(AGENT_TOOLS) == 9
 
     def test_task_agent_tools_count(self):
-        assert len(TASK_AGENT_TOOLS) == 10
+        assert len(TASK_AGENT_TOOLS) == 12
 
     def test_auto_approve_sets_match(self):
-        expected = {"read_file", "search", "math", "man", "web_fetch", "web_search", "notify"}
+        expected = {
+            "read_file",
+            "search",
+            "math",
+            "man",
+            "web_fetch",
+            "web_search",
+            "notify",
+        }
         assert expected == AGENT_AUTO_TOOLS
         assert expected == TASK_AUTO_TOOLS
 
@@ -97,11 +105,14 @@ class TestToolsMetadata:
             "web_fetch": "url",
             "web_search": "query",
             "task": "prompt",
-            "plan": "prompt",
+            "create_plan": "goal",
             "remember": "key",
             "recall": "query",
             "forget": "key",
             "notify": "message",
+            "watch": "command",
+            "read_resource": "uri",
+            "use_prompt": "name",
         }
         assert expected == PRIMARY_KEY_MAP
 

tests/test_user_storage.py

@@ -65,6 +65,14 @@ class TestUserCRUD:
         db.delete_user("u1")
         assert len(db.list_api_tokens("u1")) == 0
 
+    def test_delete_cascades_user_roles(self, db):
+        db.create_user("u1", "admin", "Admin", "$2b$hash")
+        db.create_role("r1", "editor", "Editor", "read,write", builtin=False, org_id="")
+        db.assign_role("u1", "r1")
+        assert len(db.list_user_roles("u1")) == 1
+        db.delete_user("u1")
+        assert len(db.list_user_roles("u1")) == 0
+
 
 class TestApiTokenCRUD:
     def test_create_and_lookup_by_hash(self, db):
@@ -127,21 +135,7 @@ class TestApiTokenCRUD:
         assert "expires" not in tok
 
 
-class TestSessionWorkstreamUserId:
-    def test_register_session_with_user_id(self, db):
-        db.register_session("s1", user_id="u1")
-        # Verify via raw SQL that user_id is stored
-        import sqlalchemy as sa
-
-        from turnstone.core.storage._schema import sessions
-
-        with db._engine.connect() as conn:
-            row = conn.execute(
-                sa.select(sessions.c.user_id).where(sessions.c.session_id == "s1")
-            ).fetchone()
-            assert row is not None
-            assert row[0] == "u1"
-
+class TestWorkstreamUserId:
     def test_register_workstream_with_user_id(self, db):
         db.register_workstream("ws1", user_id="u1")
         import sqlalchemy as sa
@@ -155,15 +149,15 @@ class TestSessionWorkstreamUserId:
             assert row is not None
             assert row[0] == "u1"
 
-    def test_register_session_without_user_id(self, db):
-        db.register_session("s1")
+    def test_register_workstream_without_user_id(self, db):
+        db.register_workstream("ws1")
         import sqlalchemy as sa
 
-        from turnstone.core.storage._schema import sessions
+        from turnstone.core.storage._schema import workstreams
 
         with db._engine.connect() as conn:
             row = conn.execute(
-                sa.select(sessions.c.user_id).where(sessions.c.session_id == "s1")
+                sa.select(workstreams.c.user_id).where(workstreams.c.ws_id == "ws1")
             ).fetchone()
             assert row is not None
             assert row[0] is None

tests/test_watch.py

@@ -0,0 +1,487 @@
+"""Tests for the watch module — duration parsing, condition evaluation, WatchRunner."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from unittest.mock import MagicMock
+
+import pytest
+
+from turnstone.core.watch import (
+    WatchRunner,
+    evaluate_condition,
+    format_interval,
+    format_watch_message,
+    parse_duration,
+    validate_condition,
+)
+
+# ---------------------------------------------------------------------------
+# parse_duration
+# ---------------------------------------------------------------------------
+
+
+class TestParseDuration:
+    def test_seconds(self):
+        assert parse_duration("30s") == 30.0
+
+    def test_minutes(self):
+        assert parse_duration("5m") == 300.0
+
+    def test_hours(self):
+        assert parse_duration("1h") == 3600.0
+
+    def test_compound(self):
+        assert parse_duration("2h30m") == 9000.0
+
+    def test_bare_number(self):
+        assert parse_duration("90") == 90.0
+
+    def test_bare_float(self):
+        assert parse_duration("10.5") == 10.5
+
+    def test_whitespace(self):
+        assert parse_duration("  5m  ") == 300.0
+
+    def test_case_insensitive(self):
+        assert parse_duration("1H30M") == 5400.0
+
+    def test_empty_raises(self):
+        with pytest.raises(ValueError, match="empty"):
+            parse_duration("")
+
+    def test_invalid_raises(self):
+        with pytest.raises(ValueError, match="invalid duration"):
+            parse_duration("abc")
+
+    def test_negative_raises(self):
+        with pytest.raises(ValueError, match="positive"):
+            parse_duration("-5")
+
+    def test_zero_raises(self):
+        with pytest.raises(ValueError, match="positive"):
+            parse_duration("0")
+
+    def test_zero_duration_raises(self):
+        with pytest.raises(ValueError, match="positive"):
+            parse_duration("0s")
+
+
+# ---------------------------------------------------------------------------
+# validate_condition
+# ---------------------------------------------------------------------------
+
+
+class TestValidateCondition:
+    def test_valid_expression(self):
+        assert validate_condition('data["state"] == "MERGED"') is None
+
+    def test_valid_simple(self):
+        assert validate_condition('"error" in output') is None
+
+    def test_valid_compound(self):
+        assert validate_condition('changed and "ready" in output.lower()') is None
+
+    def test_syntax_error(self):
+        result = validate_condition("if True:")
+        assert result is not None
+        assert "syntax" in result.lower()
+
+    def test_incomplete_expression(self):
+        result = validate_condition("==")
+        assert result is not None
+
+
+# ---------------------------------------------------------------------------
+# evaluate_condition
+# ---------------------------------------------------------------------------
+
+
+class TestEvaluateCondition:
+    def test_none_first_poll_no_fire(self):
+        """With stop_on=None, first poll (prev_output=None) should not fire."""
+        fired, reason = evaluate_condition(None, "hello", 0, None)
+        assert not fired
+
+    def test_none_change_detected(self):
+        fired, reason = evaluate_condition(None, "world", 0, "hello")
+        assert fired
+        assert "changed" in reason
+
+    def test_none_no_change(self):
+        fired, reason = evaluate_condition(None, "same", 0, "same")
+        assert not fired
+
+    def test_string_match(self):
+        fired, reason = evaluate_condition('"error" in output', "has error here", 0, None)
+        assert fired
+
+    def test_string_no_match(self):
+        fired, reason = evaluate_condition('"error" in output', "all good", 0, None)
+        assert not fired
+
+    def test_exit_code(self):
+        fired, reason = evaluate_condition("exit_code != 0", "fail", 1, None)
+        assert fired
+
+    def test_exit_code_zero(self):
+        fired, reason = evaluate_condition("exit_code != 0", "ok", 0, None)
+        assert not fired
+
+    def test_json_data(self):
+        output = '{"state": "MERGED"}'
+        fired, reason = evaluate_condition('data["state"] == "MERGED"', output, 0, None)
+        assert fired
+
+    def test_json_data_no_match(self):
+        output = '{"state": "OPEN"}'
+        fired, reason = evaluate_condition('data["state"] == "MERGED"', output, 0, None)
+        assert not fired
+
+    def test_json_data_none_for_non_json(self):
+        """Non-JSON output should have data=None."""
+        fired, reason = evaluate_condition("data is None", "plain text", 0, None)
+        assert fired
+
+    def test_changed_variable(self):
+        fired, reason = evaluate_condition("changed", "new", 0, "old")
+        assert fired
+
+    def test_changed_false(self):
+        fired, reason = evaluate_condition("changed", "same", 0, "same")
+        assert not fired
+
+    def test_compound_condition(self):
+        fired, reason = evaluate_condition(
+            'changed and "ready" in output.lower()',
+            "System Ready",
+            0,
+            "System Starting",
+        )
+        assert fired
+
+    def test_invalid_expression_no_crash(self):
+        fired, reason = evaluate_condition("1/0", "hello", 0, None)
+        assert not fired
+        assert "error" in reason.lower()
+
+    def test_no_import_builtin(self):
+        """__import__ should not be accessible."""
+        fired, reason = evaluate_condition("__import__('os')", "hello", 0, None)
+        assert not fired
+        assert "error" in reason.lower()
+
+    def test_no_open_builtin(self):
+        fired, reason = evaluate_condition("open('/etc/passwd')", "hello", 0, None)
+        assert not fired
+        assert "error" in reason.lower()
+
+    def test_no_exec_builtin(self):
+        fired, reason = evaluate_condition("exec('print(1)')", "hello", 0, None)
+        assert not fired
+        assert "error" in reason.lower()
+
+    def test_no_eval_builtin(self):
+        fired, reason = evaluate_condition("eval('1+1')", "hello", 0, None)
+        assert not fired
+        assert "error" in reason.lower()
+
+    def test_no_compile_builtin(self):
+        fired, reason = evaluate_condition("compile('1','','eval')", "hello", 0, None)
+        assert not fired
+        assert "error" in reason.lower()
+
+    def test_safe_len(self):
+        fired, reason = evaluate_condition("len(output) > 0", "hello", 0, None)
+        assert fired
+
+    def test_safe_sorted(self):
+        fired, reason = evaluate_condition("sorted([3,1,2]) == [1,2,3]", "x", 0, None)
+        assert fired
+
+    def test_data_get_method(self):
+        output = '{"mergedAt": "2024-01-15"}'
+        fired, reason = evaluate_condition('data.get("mergedAt") is not None', output, 0, None)
+        assert fired
+
+    def test_prev_output_available(self):
+        fired, reason = evaluate_condition(
+            "prev_output is not None and output != prev_output",
+            "new",
+            0,
+            "old",
+        )
+        assert fired
+
+
+# ---------------------------------------------------------------------------
+# format_interval
+# ---------------------------------------------------------------------------
+
+
+class TestFormatInterval:
+    def test_seconds(self):
+        assert format_interval(30) == "30s"
+
+    def test_exactly_60(self):
+        assert format_interval(60) == "1m"
+
+    def test_minutes(self):
+        assert format_interval(300) == "5m"
+
+    def test_exactly_3600(self):
+        assert format_interval(3600) == "1h"
+
+    def test_hours_and_minutes(self):
+        assert format_interval(5400) == "1h30m"
+
+    def test_hours_only(self):
+        assert format_interval(7200) == "2h"
+
+    def test_large_value(self):
+        assert format_interval(86400) == "24h"
+
+
+# ---------------------------------------------------------------------------
+# format_watch_message
+# ---------------------------------------------------------------------------
+
+
+class TestFormatWatchMessage:
+    def test_basic(self):
+        msg = format_watch_message(
+            name="pr-review",
+            command="gh pr view --json state",
+            output='{"state": "MERGED"}',
+            poll_count=5,
+            max_polls=100,
+            elapsed_secs=1500,
+            stop_on='data["state"] == "MERGED"',
+            is_final=True,
+            reason='condition met: data["state"] == "MERGED"',
+        )
+        assert "pr-review" in msg
+        assert "poll #5/100" in msg
+        assert "25m" in msg
+        assert "gh pr view --json state" in msg
+        assert "MERGED" in msg
+        assert "auto-cancelled" in msg.lower()
+        # Model should see the condition it was waiting for
+        assert "condition:" in msg.lower()
+
+    def test_non_final(self):
+        msg = format_watch_message(
+            name="deploy",
+            command="curl -s http://localhost/health",
+            output="ok",
+            poll_count=3,
+            max_polls=50,
+            elapsed_secs=90,
+            stop_on=None,
+            is_final=False,
+            reason="",
+        )
+        assert "deploy" in msg
+        assert "auto-cancelled" not in msg.lower()
+        # Change-detection mode should be indicated
+        assert "output change" in msg.lower()
+
+    def test_max_polls_final(self):
+        msg = format_watch_message(
+            name="test",
+            command="echo hello",
+            output="hello",
+            poll_count=100,
+            max_polls=100,
+            elapsed_secs=6000,
+            stop_on=None,
+            is_final=True,
+            reason="",
+        )
+        assert "max polls" in msg.lower()
+
+
+# ---------------------------------------------------------------------------
+# WatchRunner
+# ---------------------------------------------------------------------------
+
+
+class TestWatchRunner:
+    def _make_runner(self, storage=None, **kwargs):
+        if storage is None:
+            storage = MagicMock()
+            storage.list_due_watches.return_value = []
+        return WatchRunner(
+            storage=storage,
+            node_id="test-node",
+            check_interval=0.1,
+            tool_timeout=5,
+            **kwargs,
+        )
+
+    def test_start_stop(self):
+        runner = self._make_runner()
+        runner.start()
+        assert runner._thread is not None
+        assert runner._thread.is_alive()
+        runner.stop()
+        assert runner._thread is None
+
+    def test_tick_calls_list_due(self):
+        storage = MagicMock()
+        storage.list_due_watches.return_value = []
+        runner = self._make_runner(storage=storage)
+        runner._tick()
+        storage.list_due_watches.assert_called_once()
+
+    def test_poll_watch_runs_command(self):
+        storage = MagicMock()
+        storage.update_watch.return_value = True
+        runner = self._make_runner(storage=storage)
+        dispatch_fn = MagicMock()
+        runner.set_dispatch_fn("ws-1", dispatch_fn)
+
+        watch_row = {
+            "watch_id": "abc123",
+            "ws_id": "ws-1",
+            "name": "test-watch",
+            "command": "echo hello",
+            "stop_on": '"hello" in output',
+            "max_polls": 100,
+            "poll_count": 0,
+            "last_output": None,
+            "interval_secs": 60,
+            "created": datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%S"),
+        }
+        runner._poll_watch(watch_row)
+
+        # Should update the watch in storage
+        storage.update_watch.assert_called_once()
+        call_kwargs = storage.update_watch.call_args
+        assert call_kwargs[0][0] == "abc123"  # watch_id
+        assert call_kwargs[1]["poll_count"] == 1
+        # Condition should fire (output contains "hello")
+        assert call_kwargs[1]["active"] is False  # deactivated
+        # Should dispatch result
+        dispatch_fn.assert_called_once()
+
+    def test_poll_watch_no_fire_on_first_change_detection(self):
+        storage = MagicMock()
+        storage.update_watch.return_value = True
+        runner = self._make_runner(storage=storage)
+        dispatch_fn = MagicMock()
+        runner.set_dispatch_fn("ws-1", dispatch_fn)
+
+        watch_row = {
+            "watch_id": "abc123",
+            "ws_id": "ws-1",
+            "name": "test-watch",
+            "command": "echo hello",
+            "stop_on": None,  # change detection
+            "max_polls": 100,
+            "poll_count": 0,
+            "last_output": None,  # first poll
+            "interval_secs": 60,
+            "created": datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%S"),
+        }
+        runner._poll_watch(watch_row)
+
+        # First poll with change detection should not fire
+        dispatch_fn.assert_not_called()
+        call_kwargs = storage.update_watch.call_args
+        # Watch should remain active
+        assert "active" not in call_kwargs[1] or call_kwargs[1].get("active") is not False
+
+    def test_max_polls_deactivates(self):
+        storage = MagicMock()
+        storage.update_watch.return_value = True
+        runner = self._make_runner(storage=storage)
+        dispatch_fn = MagicMock()
+        runner.set_dispatch_fn("ws-1", dispatch_fn)
+
+        watch_row = {
+            "watch_id": "abc123",
+            "ws_id": "ws-1",
+            "name": "test-watch",
+            "command": "echo hello",
+            "stop_on": '"never" in output',  # won't fire
+            "max_polls": 5,
+            "poll_count": 4,  # next is #5 = max
+            "last_output": "hello\n",
+            "interval_secs": 60,
+            "created": datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%S"),
+        }
+        runner._poll_watch(watch_row)
+
+        call_kwargs = storage.update_watch.call_args
+        assert call_kwargs[1]["active"] is False
+        assert call_kwargs[1]["poll_count"] == 5
+        dispatch_fn.assert_called_once()
+
+    def test_blocked_command_deactivates(self):
+        storage = MagicMock()
+        storage.update_watch.return_value = True
+        runner = self._make_runner(storage=storage)
+
+        watch_row = {
+            "watch_id": "abc123",
+            "ws_id": "ws-1",
+            "name": "test-watch",
+            "command": "rm -rf /",
+            "stop_on": None,
+            "max_polls": 100,
+            "poll_count": 0,
+            "last_output": None,
+            "interval_secs": 60,
+            "created": datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%S"),
+        }
+        runner._poll_watch(watch_row)
+
+        storage.update_watch.assert_called_once()
+        call_kwargs = storage.update_watch.call_args
+        assert call_kwargs[0][0] == "abc123"
+        assert call_kwargs[1]["active"] is False
+
+    def test_dispatch_fn_registry(self):
+        runner = self._make_runner()
+        fn1 = MagicMock()
+        fn2 = MagicMock()
+
+        runner.set_dispatch_fn("ws-1", fn1)
+        runner.set_dispatch_fn("ws-2", fn2)
+
+        runner._dispatch_result("ws-1", "msg1")
+        fn1.assert_called_once_with("msg1")
+        fn2.assert_not_called()
+
+        runner.remove_dispatch_fn("ws-1")
+        # After removal, dispatch should try restore_fn
+        runner._dispatch_result("ws-1", "msg2")
+        fn1.assert_called_once()  # still just the one call
+
+    def test_restore_fn_called_for_evicted(self):
+        restored_fn = MagicMock()
+        restore_fn = MagicMock(return_value=restored_fn)
+        runner = self._make_runner(restore_fn=restore_fn)
+
+        runner._dispatch_result("ws-evicted", "hello")
+        restore_fn.assert_called_once_with("ws-evicted")
+        restored_fn.assert_called_once_with("hello")
+
+    def test_run_command_success(self):
+        runner = self._make_runner()
+        output, code = runner._run_command("echo hello")
+        assert "hello" in output
+        assert code == 0
+
+    def test_run_command_failure(self):
+        runner = self._make_runner()
+        output, code = runner._run_command("exit 42")
+        assert code == 42
+
+    def test_run_command_timeout(self):
+        runner = self._make_runner()
+        runner._tool_timeout = 1
+        output, code = runner._run_command("sleep 30")
+        assert "timed out" in output.lower()
+        assert code == -1

tests/test_watch_storage.py

@@ -0,0 +1,130 @@
+"""Tests for watches storage CRUD."""
+
+from __future__ import annotations
+
+import pytest
+
+from turnstone.core.storage._sqlite import SQLiteBackend
+
+
+@pytest.fixture
+def db(tmp_path):
+    """Fresh SQLite backend for each test."""
+    return SQLiteBackend(str(tmp_path / "test.db"))
+
+
+def _make_watch_kwargs(**overrides):
+    """Build default kwargs for create_watch."""
+    defaults = {
+        "watch_id": "watch_001",
+        "ws_id": "ws-abc",
+        "node_id": "node-1",
+        "name": "pr-review",
+        "command": "gh pr view --json state",
+        "interval_secs": 300.0,
+        "stop_on": 'data["state"] == "MERGED"',
+        "max_polls": 100,
+        "created_by": "model",
+        "next_poll": "2099-01-01T00:05:00",
+    }
+    defaults.update(overrides)
+    return defaults
+
+
+class TestWatchCRUD:
+    def test_create_and_get(self, db):
+        db.create_watch(**_make_watch_kwargs())
+        w = db.get_watch("watch_001")
+        assert w is not None
+        assert w["name"] == "pr-review"
+        assert w["command"] == "gh pr view --json state"
+        assert w["interval_secs"] == 300.0
+        assert w["active"] == 1
+        assert w["poll_count"] == 0
+
+    def test_get_nonexistent(self, db):
+        assert db.get_watch("nope") is None
+
+    def test_create_idempotent(self, db):
+        db.create_watch(**_make_watch_kwargs())
+        db.create_watch(**_make_watch_kwargs())  # OR IGNORE
+        assert db.get_watch("watch_001") is not None
+
+    def test_update(self, db):
+        db.create_watch(**_make_watch_kwargs())
+        updated = db.update_watch(
+            "watch_001",
+            poll_count=5,
+            last_output="hello",
+            last_exit_code=0,
+        )
+        assert updated is True
+        w = db.get_watch("watch_001")
+        assert w["poll_count"] == 5
+        assert w["last_output"] == "hello"
+        assert w["last_exit_code"] == 0
+
+    def test_update_nonexistent(self, db):
+        assert db.update_watch("nope", poll_count=1) is False
+
+    def test_update_active_flag(self, db):
+        db.create_watch(**_make_watch_kwargs())
+        db.update_watch("watch_001", active=False)
+        w = db.get_watch("watch_001")
+        assert w["active"] == 0
+
+    def test_delete(self, db):
+        db.create_watch(**_make_watch_kwargs())
+        assert db.delete_watch("watch_001") is True
+        assert db.get_watch("watch_001") is None
+
+    def test_delete_nonexistent(self, db):
+        assert db.delete_watch("nope") is False
+
+
+class TestWatchListQueries:
+    def test_list_for_ws(self, db):
+        db.create_watch(**_make_watch_kwargs(watch_id="w1", ws_id="ws-1", name="a"))
+        db.create_watch(**_make_watch_kwargs(watch_id="w2", ws_id="ws-1", name="b"))
+        db.create_watch(**_make_watch_kwargs(watch_id="w3", ws_id="ws-2", name="c"))
+
+        ws1 = db.list_watches_for_ws("ws-1")
+        assert len(ws1) == 2
+        assert {w["name"] for w in ws1} == {"a", "b"}
+
+    def test_list_for_ws_excludes_inactive(self, db):
+        db.create_watch(**_make_watch_kwargs(watch_id="w1", ws_id="ws-1"))
+        db.update_watch("w1", active=False)
+        assert db.list_watches_for_ws("ws-1") == []
+
+    def test_list_for_node(self, db):
+        db.create_watch(**_make_watch_kwargs(watch_id="w1", node_id="n1"))
+        db.create_watch(**_make_watch_kwargs(watch_id="w2", node_id="n1"))
+        db.create_watch(**_make_watch_kwargs(watch_id="w3", node_id="n2"))
+
+        n1 = db.list_watches_for_node("n1")
+        assert len(n1) == 2
+
+    def test_list_due(self, db):
+        # Due
+        db.create_watch(**_make_watch_kwargs(watch_id="w1", next_poll="2020-01-01T00:00:00"))
+        # Not due (far future)
+        db.create_watch(**_make_watch_kwargs(watch_id="w2", next_poll="2099-01-01T00:00:00"))
+        # Due but inactive
+        db.create_watch(**_make_watch_kwargs(watch_id="w3", next_poll="2020-01-01T00:00:00"))
+        db.update_watch("w3", active=False)
+
+        due = db.list_due_watches("2025-01-01T00:00:00")
+        assert len(due) == 1
+        assert due[0]["watch_id"] == "w1"
+
+    def test_delete_for_ws(self, db):
+        db.create_watch(**_make_watch_kwargs(watch_id="w1", ws_id="ws-1"))
+        db.create_watch(**_make_watch_kwargs(watch_id="w2", ws_id="ws-1"))
+        db.create_watch(**_make_watch_kwargs(watch_id="w3", ws_id="ws-2"))
+
+        count = db.delete_watches_for_ws("ws-1")
+        assert count == 2
+        assert db.get_watch("w1") is None
+        assert db.get_watch("w2") is None
+        assert db.get_watch("w3") is not None

tests/test_workstream.py

@@ -665,6 +665,31 @@ class TestWebUI:
         assert ui._approval_result == (True, "looks good")
         t.join()
 
+    def test_resolve_approval_emits_event(self):
+        """resolve_approval should enqueue an approval_resolved SSE event."""
+        from turnstone.server import WebUI
+
+        ui = WebUI(ws_id="test-emit")
+        listener = ui._register_listener()
+
+        # Drain any init events
+        while not listener.empty():
+            listener.get_nowait()
+
+        ui.resolve_approval(False, "Approval timed out")
+
+        # Collect events from the listener
+        events = []
+        while not listener.empty():
+            events.append(listener.get_nowait())
+
+        ui._unregister_listener(listener)
+
+        resolved = [e for e in events if e.get("type") == "approval_resolved"]
+        assert len(resolved) == 1
+        assert resolved[0]["approved"] is False
+        assert resolved[0]["feedback"] == "Approval timed out"
+
     def test_resolve_plan(self):
         from turnstone.server import WebUI
 
@@ -683,6 +708,117 @@ class TestWebUI:
         t.join()
 
 
+# ---------------------------------------------------------------------------
+# WebUI SSE fan-out
+# ---------------------------------------------------------------------------
+
+
+class TestWebUIFanOut:
+    """Verify per-client SSE fan-out on WebUI._enqueue / _register_listener."""
+
+    def test_enqueue_no_listeners(self):
+        """Events silently dropped when no listeners are registered."""
+        from turnstone.server import WebUI
+
+        ui = WebUI(ws_id="test")
+        ui._enqueue({"type": "content", "text": "hello"})  # should not raise
+
+    def test_enqueue_single_listener(self):
+        """Single listener receives the event."""
+        from turnstone.server import WebUI
+
+        ui = WebUI(ws_id="test")
+        q = ui._register_listener()
+        ui._enqueue({"type": "content", "text": "hello"})
+        assert q.get_nowait() == {"type": "content", "text": "hello"}
+
+    def test_enqueue_multiple_listeners(self):
+        """All registered listeners receive an identical copy."""
+        from turnstone.server import WebUI
+
+        ui = WebUI(ws_id="test")
+        q1 = ui._register_listener()
+        q2 = ui._register_listener()
+        q3 = ui._register_listener()
+
+        event = {"type": "content", "text": "world"}
+        ui._enqueue(event)
+
+        assert q1.get_nowait() == event
+        assert q2.get_nowait() == event
+        assert q3.get_nowait() == event
+
+    def test_unregister_stops_delivery(self):
+        """After unregister, the queue receives no further events."""
+        import queue as queue_mod
+
+        from turnstone.server import WebUI
+
+        ui = WebUI(ws_id="test")
+        q = ui._register_listener()
+        ui._unregister_listener(q)
+        ui._enqueue({"type": "content", "text": "gone"})
+
+        with pytest.raises(queue_mod.Empty):
+            q.get_nowait()
+
+    def test_slow_consumer_does_not_block(self):
+        """A full queue doesn't block the producer or starve other listeners."""
+        from turnstone.server import WebUI
+
+        ui = WebUI(ws_id="test")
+        slow = ui._register_listener()
+        fast = ui._register_listener()
+
+        # Fill only the slow consumer's queue directly to capacity
+        for i in range(500):
+            slow.put_nowait({"type": "content", "text": f"fill-{i}"})
+
+        assert slow.qsize() == 500
+        assert fast.qsize() == 0
+
+        # Enqueue via fan-out — slow drops (full), fast receives
+        event = {"type": "content", "text": "overflow"}
+        ui._enqueue(event)
+        assert slow.qsize() == 500  # still full, overflow dropped
+        assert fast.qsize() == 1
+        assert fast.get_nowait() == event
+
+    def test_unregister_idempotent(self):
+        """Double unregister does not raise."""
+
+        from turnstone.server import WebUI
+
+        ui = WebUI(ws_id="test")
+        q = ui._register_listener()
+        ui._unregister_listener(q)
+        ui._unregister_listener(q)  # should not raise
+
+    def test_concurrent_enqueue_and_register(self):
+        """Concurrent register/unregister and enqueue should not crash."""
+        from turnstone.server import WebUI
+
+        ui = WebUI(ws_id="test")
+        stop = threading.Event()
+
+        def register_loop():
+            while not stop.is_set():
+                q = ui._register_listener()
+                ui._unregister_listener(q)
+
+        def enqueue_loop():
+            for i in range(500):
+                ui._enqueue({"type": "content", "text": f"tok-{i}"})
+
+        t1 = threading.Thread(target=register_loop)
+        t2 = threading.Thread(target=enqueue_loop)
+        t1.start()
+        t2.start()
+        t2.join()
+        stop.set()
+        t1.join()
+
+
 # ---------------------------------------------------------------------------
 # Integration: WorkstreamManager + session state transitions
 # ---------------------------------------------------------------------------

turnstone/__init__.py

@@ -1,3 +1,3 @@
 """turnstone - Multi-node AI orchestration platform with tool use, agent routing, and cluster simulation."""
 
-__version__ = "0.4.2"
+__version__ = "0.5.5"

turnstone/api/console_schemas.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+from typing import Any
+
 from pydantic import BaseModel, Field
 
 # ---------------------------------------------------------------------------
@@ -48,7 +50,7 @@ class ClusterNodeInfo(BaseModel):
     total_tokens: int = 0
     started: float = 0.0
     reachable: bool = True
-    health: dict[str, str] = Field(default_factory=dict)
+    health: dict[str, Any] = Field(default_factory=dict)
     version: str = ""
 
 
@@ -91,12 +93,34 @@ class ClusterWorkstreamsResponse(BaseModel):
 class NodeDetailResponse(BaseModel):
     node_id: str
     server_url: str = ""
-    health: dict[str, str] = Field(default_factory=dict)
+    health: dict[str, Any] = Field(default_factory=dict)
     workstreams: list[ClusterWorkstreamInfo] = []
     aggregate: dict[str, int] = Field(default_factory=dict)
     reachable: bool = True
 
 
+# ---------------------------------------------------------------------------
+# Cluster snapshot
+# ---------------------------------------------------------------------------
+
+
+class ClusterSnapshotNode(BaseModel):
+    node_id: str
+    server_url: str = ""
+    max_ws: int = 10
+    reachable: bool = True
+    version: str = ""
+    health: dict[str, Any] = Field(default_factory=dict)
+    aggregate: dict[str, int] = Field(default_factory=dict)
+    workstreams: list[ClusterWorkstreamInfo] = []
+
+
+class ClusterSnapshotResponse(BaseModel):
+    nodes: list[ClusterSnapshotNode]
+    overview: ClusterOverviewResponse
+    timestamp: float = 0.0
+
+
 # ---------------------------------------------------------------------------
 # Workstream creation
 # ---------------------------------------------------------------------------
@@ -112,6 +136,9 @@ class ConsoleCreateWsRequest(BaseModel):
     initial_message: str = Field(
         default="", description="Optional first message sent after creation"
     )
+    template: str = Field(
+        default="", description="Prompt template name (replaces default templates)"
+    )
 
 
 class ConsoleCreateWsResponse(BaseModel):
@@ -132,3 +159,219 @@ class ConsoleHealthResponse(BaseModel):
     workstreams: int = 0
     version_drift: bool = False
     versions: list[str] = []
+
+
+# ---------------------------------------------------------------------------
+# Governance: Roles
+# ---------------------------------------------------------------------------
+
+
+class RoleInfo(BaseModel):
+    role_id: str
+    name: str
+    display_name: str
+    permissions: str
+    builtin: bool
+    org_id: str
+    created: str
+    updated: str
+
+
+class CreateRoleRequest(BaseModel):
+    name: str
+    display_name: str = ""
+    permissions: str = "read"
+
+
+class UpdateRoleRequest(BaseModel):
+    display_name: str | None = None
+    permissions: str | None = None
+
+
+class ListRolesResponse(BaseModel):
+    roles: list[RoleInfo]
+
+
+class AssignRoleRequest(BaseModel):
+    role_id: str
+
+
+class UserRoleInfo(BaseModel):
+    role_id: str
+    name: str
+    display_name: str
+    permissions: str
+    builtin: bool
+    org_id: str
+    created: str
+    updated: str
+    assigned_by: str
+    assignment_created: str
+
+
+class ListUserRolesResponse(BaseModel):
+    roles: list[UserRoleInfo]
+
+
+# ---------------------------------------------------------------------------
+# Governance: Orgs
+# ---------------------------------------------------------------------------
+
+
+class OrgInfo(BaseModel):
+    org_id: str
+    name: str
+    display_name: str
+    settings: str
+    created: str
+    updated: str
+
+
+class UpdateOrgRequest(BaseModel):
+    display_name: str | None = None
+    settings: str | None = None
+
+
+class ListOrgsResponse(BaseModel):
+    orgs: list[OrgInfo]
+
+
+# ---------------------------------------------------------------------------
+# Governance: Tool Policies
+# ---------------------------------------------------------------------------
+
+
+class ToolPolicyInfo(BaseModel):
+    policy_id: str
+    name: str
+    tool_pattern: str
+    action: str
+    priority: int
+    org_id: str
+    enabled: bool
+    created_by: str
+    created: str
+    updated: str
+
+
+class CreateToolPolicyRequest(BaseModel):
+    name: str
+    tool_pattern: str
+    action: str  # allow, deny, ask
+    priority: int = 0
+    org_id: str = ""
+    enabled: bool = True
+
+
+class UpdateToolPolicyRequest(BaseModel):
+    name: str | None = None
+    tool_pattern: str | None = None
+    action: str | None = None
+    priority: int | None = None
+    enabled: bool | None = None
+
+
+class ListToolPoliciesResponse(BaseModel):
+    policies: list[ToolPolicyInfo]
+
+
+# ---------------------------------------------------------------------------
+# Governance: Prompt Templates
+# ---------------------------------------------------------------------------
+
+
+class PromptTemplateInfo(BaseModel):
+    template_id: str
+    name: str
+    category: str
+    content: str
+    variables: str
+    is_default: bool
+    org_id: str
+    created_by: str
+    origin: str = "manual"
+    mcp_server: str = ""
+    readonly: bool = False
+    created: str
+    updated: str
+
+
+class CreatePromptTemplateRequest(BaseModel):
+    name: str
+    content: str
+    category: str = "general"
+    variables: str = "[]"
+    is_default: bool = False
+    org_id: str = ""
+
+
+class UpdatePromptTemplateRequest(BaseModel):
+    name: str | None = None
+    content: str | None = None
+    category: str | None = None
+    variables: str | None = None
+    is_default: bool | None = None
+
+
+class ListPromptTemplatesResponse(BaseModel):
+    templates: list[PromptTemplateInfo]
+
+
+# ---------------------------------------------------------------------------
+# Governance: Usage
+# ---------------------------------------------------------------------------
+
+
+class UsageBreakdownItem(BaseModel):
+    key: str = ""
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    tool_calls_count: int = 0
+
+
+class UsageResponse(BaseModel):
+    summary: list[UsageBreakdownItem]
+    breakdown: list[UsageBreakdownItem]
+
+
+# ---------------------------------------------------------------------------
+# Governance: Audit
+# ---------------------------------------------------------------------------
+
+
+class AuditEventInfo(BaseModel):
+    event_id: str
+    timestamp: str
+    user_id: str
+    action: str
+    resource_type: str
+    resource_id: str
+    detail: str
+    ip_address: str
+    created: str
+
+
+class ListAuditEventsResponse(BaseModel):
+    events: list[AuditEventInfo]
+
+
+# ---------------------------------------------------------------------------
+# Channels
+# ---------------------------------------------------------------------------
+
+
+class ChannelUserInfo(BaseModel):
+    channel_type: str
+    channel_user_id: str
+    user_id: str
+    created: str
+
+
+class ListChannelUsersResponse(BaseModel):
+    channels: list[ChannelUserInfo]
+
+
+class CreateChannelUserRequest(BaseModel):
+    channel_type: str = Field(..., description="Channel type (e.g. discord, slack)")
+    channel_user_id: str = Field(..., description="External channel user identifier")
+    total: int

turnstone/api/console_spec.py

@@ -8,13 +8,39 @@ if TYPE_CHECKING:
     from pydantic import BaseModel
 
 from turnstone.api.console_schemas import (
+    AssignRoleRequest,
+    AuditEventInfo,
+    ChannelUserInfo,
     ClusterNodesResponse,
     ClusterOverviewResponse,
+    ClusterSnapshotResponse,
     ClusterWorkstreamsResponse,
     ConsoleCreateWsRequest,
     ConsoleCreateWsResponse,
     ConsoleHealthResponse,
+    CreateChannelUserRequest,
+    CreatePromptTemplateRequest,
+    CreateRoleRequest,
+    CreateToolPolicyRequest,
+    ListAuditEventsResponse,
+    ListChannelUsersResponse,
+    ListOrgsResponse,
+    ListPromptTemplatesResponse,
+    ListRolesResponse,
+    ListToolPoliciesResponse,
+    ListUserRolesResponse,
     NodeDetailResponse,
+    OrgInfo,
+    PromptTemplateInfo,
+    RoleInfo,
+    ToolPolicyInfo,
+    UpdateOrgRequest,
+    UpdatePromptTemplateRequest,
+    UpdateRoleRequest,
+    UpdateToolPolicyRequest,
+    UsageBreakdownItem,
+    UsageResponse,
+    UserRoleInfo,
 )
 from turnstone.api.openapi import EndpointSpec, QueryParam, build_openapi
 from turnstone.api.schemas import (
@@ -97,14 +123,23 @@ CONSOLE_ENDPOINTS: list[EndpointSpec] = [
         error_codes=[400, 404, 503],
         tags=["Cluster"],
     ),
+    EndpointSpec(
+        "/v1/api/cluster/snapshot",
+        "GET",
+        "Full cluster state snapshot",
+        description="Returns the complete cluster state: all nodes with their workstreams "
+        "and overview aggregates. Used for initial load and reconnection.",
+        response_model=ClusterSnapshotResponse,
+        tags=["Cluster"],
+    ),
     # --- Streaming ---
     EndpointSpec(
         "/v1/api/cluster/events",
         "GET",
         "Cluster SSE event stream",
         description="Server-Sent Events stream for real-time cluster updates. "
-        "Returns text/event-stream with node_joined, node_lost, cluster_state, "
-        "ws_created, ws_closed, ws_rename events.",
+        "First event is a 'snapshot' with full cluster state, followed by "
+        "node_joined, node_lost, cluster_state, ws_created, ws_closed, ws_rename events.",
         tags=["Streaming"],
     ),
     # --- Auth ---
@@ -187,6 +222,31 @@ CONSOLE_ENDPOINTS: list[EndpointSpec] = [
         error_codes=[404],
         tags=["Admin"],
     ),
+    # --- Channels ---
+    EndpointSpec(
+        "/v1/api/admin/users/{user_id}/channels",
+        "GET",
+        "List channel links for a user",
+        response_model=ListChannelUsersResponse,
+        tags=["Admin"],
+    ),
+    EndpointSpec(
+        "/v1/api/admin/users/{user_id}/channels",
+        "POST",
+        "Link a channel account to a user",
+        request_model=CreateChannelUserRequest,
+        response_model=ChannelUserInfo,
+        error_codes=[400, 404, 409],
+        tags=["Admin"],
+    ),
+    EndpointSpec(
+        "/v1/api/admin/channels/{channel_type}/{channel_user_id}",
+        "DELETE",
+        "Unlink a channel account",
+        response_model=StatusResponse,
+        error_codes=[404],
+        tags=["Admin"],
+    ),
     # --- Schedules ---
     EndpointSpec(
         "/v1/api/admin/schedules",
@@ -242,6 +302,191 @@ CONSOLE_ENDPOINTS: list[EndpointSpec] = [
         error_codes=[404],
         tags=["Schedules"],
     ),
+    # --- Governance: Roles ---
+    EndpointSpec(
+        "/v1/api/admin/roles",
+        "GET",
+        "List all roles",
+        response_model=ListRolesResponse,
+        tags=["Admin"],
+    ),
+    EndpointSpec(
+        "/v1/api/admin/roles",
+        "POST",
+        "Create a custom role",
+        request_model=CreateRoleRequest,
+        response_model=RoleInfo,
+        error_codes=[400],
+        tags=["Admin"],
+    ),
+    EndpointSpec(
+        "/v1/api/admin/roles/{role_id}",
+        "PUT",
+        "Update a role",
+        request_model=UpdateRoleRequest,
+        response_model=RoleInfo,
+        error_codes=[400, 404],
+        tags=["Admin"],
+    ),
+    EndpointSpec(
+        "/v1/api/admin/roles/{role_id}",
+        "DELETE",
+        "Delete a custom role",
+        response_model=StatusResponse,
+        error_codes=[400, 404],
+        tags=["Admin"],
+    ),
+    EndpointSpec(
+        "/v1/api/admin/users/{user_id}/roles",
+        "GET",
+        "List roles assigned to a user",
+        response_model=ListUserRolesResponse,
+        tags=["Admin"],
+    ),
+    EndpointSpec(
+        "/v1/api/admin/users/{user_id}/roles",
+        "POST",
+        "Assign a role to a user",
+        request_model=AssignRoleRequest,
+        response_model=StatusResponse,
+        error_codes=[400, 404],
+        tags=["Admin"],
+    ),
+    EndpointSpec(
+        "/v1/api/admin/users/{user_id}/roles/{role_id}",
+        "DELETE",
+        "Unassign a role from a user",
+        response_model=StatusResponse,
+        error_codes=[404],
+        tags=["Admin"],
+    ),
+    # --- Governance: Orgs ---
+    EndpointSpec(
+        "/v1/api/admin/orgs",
+        "GET",
+        "List organizations",
+        response_model=ListOrgsResponse,
+        tags=["Admin"],
+    ),
+    EndpointSpec(
+        "/v1/api/admin/orgs/{org_id}",
+        "GET",
+        "Get organization details",
+        response_model=OrgInfo,
+        error_codes=[404],
+        tags=["Admin"],
+    ),
+    EndpointSpec(
+        "/v1/api/admin/orgs/{org_id}",
+        "PUT",
+        "Update organization settings",
+        request_model=UpdateOrgRequest,
+        response_model=OrgInfo,
+        error_codes=[404],
+        tags=["Admin"],
+    ),
+    # --- Governance: Tool Policies ---
+    EndpointSpec(
+        "/v1/api/admin/policies",
+        "GET",
+        "List tool policies",
+        response_model=ListToolPoliciesResponse,
+        tags=["Admin"],
+    ),
+    EndpointSpec(
+        "/v1/api/admin/policies",
+        "POST",
+        "Create a tool policy",
+        request_model=CreateToolPolicyRequest,
+        response_model=ToolPolicyInfo,
+        error_codes=[400],
+        tags=["Admin"],
+    ),
+    EndpointSpec(
+        "/v1/api/admin/policies/{policy_id}",
+        "PUT",
+        "Update a tool policy",
+        request_model=UpdateToolPolicyRequest,
+        response_model=ToolPolicyInfo,
+        error_codes=[404],
+        tags=["Admin"],
+    ),
+    EndpointSpec(
+        "/v1/api/admin/policies/{policy_id}",
+        "DELETE",
+        "Delete a tool policy",
+        response_model=StatusResponse,
+        error_codes=[404],
+        tags=["Admin"],
+    ),
+    # --- Governance: Prompt Templates ---
+    EndpointSpec(
+        "/v1/api/admin/templates",
+        "GET",
+        "List prompt templates",
+        response_model=ListPromptTemplatesResponse,
+        tags=["Admin"],
+    ),
+    EndpointSpec(
+        "/v1/api/admin/templates",
+        "POST",
+        "Create a prompt template",
+        request_model=CreatePromptTemplateRequest,
+        response_model=PromptTemplateInfo,
+        error_codes=[400],
+        tags=["Admin"],
+    ),
+    EndpointSpec(
+        "/v1/api/admin/templates/{template_id}",
+        "PUT",
+        "Update a prompt template",
+        request_model=UpdatePromptTemplateRequest,
+        response_model=PromptTemplateInfo,
+        error_codes=[404],
+        tags=["Admin"],
+    ),
+    EndpointSpec(
+        "/v1/api/admin/templates/{template_id}",
+        "DELETE",
+        "Delete a prompt template",
+        response_model=StatusResponse,
+        error_codes=[404],
+        tags=["Admin"],
+    ),
+    # --- Governance: Usage & Audit ---
+    EndpointSpec(
+        "/v1/api/admin/usage",
+        "GET",
+        "Aggregated usage data",
+        response_model=UsageResponse,
+        query_params=[
+            QueryParam("since", "Start timestamp (ISO8601, defaults to last 7 days)"),
+            QueryParam("until", "End timestamp (ISO8601)"),
+            QueryParam("user_id", "Filter by user"),
+            QueryParam("model", "Filter by model"),
+            QueryParam(
+                "group_by",
+                "Group results",
+                enum=["day", "hour", "model", "user"],
+            ),
+        ],
+        tags=["Admin"],
+    ),
+    EndpointSpec(
+        "/v1/api/admin/audit",
+        "GET",
+        "Paginated audit events",
+        response_model=ListAuditEventsResponse,
+        query_params=[
+            QueryParam("action", "Filter by action type"),
+            QueryParam("user_id", "Filter by user"),
+            QueryParam("since", "Start timestamp (ISO8601)"),
+            QueryParam("until", "End timestamp (ISO8601)"),
+            QueryParam("limit", "Page size", schema_type="integer", default=50),
+            QueryParam("offset", "Pagination offset", schema_type="integer", default=0),
+        ],
+        tags=["Admin"],
+    ),
     # --- Observability ---
     EndpointSpec(
         "/health",
@@ -266,10 +511,14 @@ _ALL_MODELS: list[type[BaseModel]] = [
     CreateTokenRequest,
     CreateTokenResponse,
     ListTokensResponse,
+    ChannelUserInfo,
+    CreateChannelUserRequest,
+    ListChannelUsersResponse,
     ClusterOverviewResponse,
     ClusterNodesResponse,
     ClusterWorkstreamsResponse,
     NodeDetailResponse,
+    ClusterSnapshotResponse,
     ConsoleCreateWsRequest,
     ConsoleCreateWsResponse,
     ConsoleHealthResponse,
@@ -278,6 +527,28 @@ _ALL_MODELS: list[type[BaseModel]] = [
     ScheduleInfo,
     ListSchedulesResponse,
     ListScheduleRunsResponse,
+    RoleInfo,
+    CreateRoleRequest,
+    UpdateRoleRequest,
+    ListRolesResponse,
+    AssignRoleRequest,
+    UserRoleInfo,
+    ListUserRolesResponse,
+    OrgInfo,
+    UpdateOrgRequest,
+    ListOrgsResponse,
+    ToolPolicyInfo,
+    CreateToolPolicyRequest,
+    UpdateToolPolicyRequest,
+    ListToolPoliciesResponse,
+    PromptTemplateInfo,
+    CreatePromptTemplateRequest,
+    UpdatePromptTemplateRequest,
+    ListPromptTemplatesResponse,
+    UsageBreakdownItem,
+    UsageResponse,
+    AuditEventInfo,
+    ListAuditEventsResponse,
 ]
 
 

turnstone/api/schemas.py

@@ -175,6 +175,7 @@ class CreateScheduleRequest(BaseModel):
     initial_message: str = Field(description="Message sent to the new workstream")
     auto_approve: bool = Field(default=False)
     auto_approve_tools: list[str] = Field(default_factory=list)
+    template: str = Field(default="", description="Prompt template name")
     enabled: bool = Field(default=True)
 
 
@@ -191,6 +192,7 @@ class UpdateScheduleRequest(BaseModel):
     initial_message: str | None = None
     auto_approve: bool | None = None
     auto_approve_tools: list[str] | None = None
+    template: str | None = None
     enabled: bool | None = None
 
 
@@ -208,6 +210,7 @@ class ScheduleInfo(BaseModel):
     initial_message: str
     auto_approve: bool = False
     auto_approve_tools: list[str] = Field(default_factory=list)
+    template: str = ""
     enabled: bool = True
     created_by: str = ""
     last_run: str | None = None

turnstone/api/server_schemas.py

@@ -35,22 +35,30 @@ class CommandRequest(BaseModel):
     ws_id: str = Field(description="Target workstream ID")
 
 
+class CancelRequest(BaseModel):
+    ws_id: str = Field(description="Target workstream ID")
+
+
 class CreateWorkstreamRequest(BaseModel):
     name: str = Field(default="", description="Workstream display name (auto-generated if empty)")
     model: str = Field(default="", description="Model alias from registry")
     auto_approve: bool = Field(default=False, description="Auto-approve all tool calls")
-    resume_session: str = Field(
+    resume_ws: str = Field(
         default="",
-        description="Session ID to resume atomically during creation (empty = fresh start)",
+        description="Workstream ID to resume atomically during creation (empty = fresh start)",
+    )
+    template: str = Field(
+        default="", description="Prompt template name (replaces default templates)"
     )
 
 
 class CreateWorkstreamResponse(BaseModel):
     ws_id: str = Field(description="Unique ID of the new workstream")
     name: str = Field(description="Assigned workstream name")
-    resumed: bool = Field(default=False, description="Whether a previous session was resumed")
-    session_id: str = Field(default="", description="Resolved session ID (set when resumed)")
-    message_count: int = Field(default=0, description="Number of messages in the resumed session")
+    resumed: bool = Field(default=False, description="Whether a previous workstream was resumed")
+    message_count: int = Field(
+        default=0, description="Number of messages in the resumed workstream"
+    )
 
 
 class CloseWorkstreamRequest(BaseModel):
@@ -66,7 +74,6 @@ class WorkstreamInfo(BaseModel):
     id: str
     name: str
     state: str
-    session_id: str | None = None
 
 
 class ListWorkstreamsResponse(BaseModel):
@@ -77,7 +84,6 @@ class DashboardWorkstream(BaseModel):
     id: str
     name: str
     state: str
-    session_id: str | None = None
     title: str = ""
     tokens: int = 0
     context_ratio: float = 0.0
@@ -104,12 +110,12 @@ class DashboardResponse(BaseModel):
 
 
 # ---------------------------------------------------------------------------
-# Sessions
+# Saved workstreams
 # ---------------------------------------------------------------------------
 
 
-class SessionInfo(BaseModel):
-    session_id: str
+class SavedWorkstreamInfo(BaseModel):
+    ws_id: str
     alias: str | None = None
     title: str | None = None
     created: str
@@ -117,8 +123,8 @@ class SessionInfo(BaseModel):
     message_count: int
 
 
-class ListSessionsResponse(BaseModel):
-    sessions: list[SessionInfo]
+class ListSavedWorkstreamsResponse(BaseModel):
+    workstreams: list[SavedWorkstreamInfo]
 
 
 # ---------------------------------------------------------------------------
@@ -140,6 +146,12 @@ class WorkstreamCounts(BaseModel):
     error: int = 0
 
 
+class McpStatus(BaseModel):
+    servers: int = 0
+    resources: int = 0
+    prompts: int = 0
+
+
 class HealthResponse(BaseModel):
     status: str = Field(examples=["ok", "degraded"])
     version: str = ""
@@ -147,3 +159,4 @@ class HealthResponse(BaseModel):
     model: str = ""
     workstreams: WorkstreamCounts = WorkstreamCounts()
     backend: BackendStatus | None = None
+    mcp: McpStatus | None = None

turnstone/api/server_spec.py

@@ -19,13 +19,14 @@ from turnstone.api.schemas import (
 )
 from turnstone.api.server_schemas import (
     ApproveRequest,
+    CancelRequest,
     CloseWorkstreamRequest,
     CommandRequest,
     CreateWorkstreamRequest,
     CreateWorkstreamResponse,
     DashboardResponse,
     HealthResponse,
-    ListSessionsResponse,
+    ListSavedWorkstreamsResponse,
     ListWorkstreamsResponse,
     PlanFeedbackRequest,
     SendRequest,
@@ -103,6 +104,15 @@ SERVER_ENDPOINTS: list[EndpointSpec] = [
         error_codes=[400, 404],
         tags=["Chat"],
     ),
+    EndpointSpec(
+        "/v1/api/cancel",
+        "POST",
+        "Cancel the active generation in a workstream",
+        request_model=CancelRequest,
+        response_model=StatusResponse,
+        error_codes=[400, 404],
+        tags=["Chat"],
+    ),
     # --- Streaming ---
     EndpointSpec(
         "/v1/api/events",
@@ -122,13 +132,13 @@ SERVER_ENDPOINTS: list[EndpointSpec] = [
         "across all workstreams. Returns text/event-stream.",
         tags=["Streaming"],
     ),
-    # --- Sessions ---
+    # --- Saved workstreams ---
     EndpointSpec(
-        "/v1/api/sessions",
+        "/v1/api/workstreams/saved",
         "GET",
-        "List saved sessions",
-        response_model=ListSessionsResponse,
-        tags=["Sessions"],
+        "List saved workstreams",
+        response_model=ListSavedWorkstreamsResponse,
+        tags=["Workstreams"],
     ),
     # --- Auth ---
     EndpointSpec(
@@ -186,12 +196,13 @@ _ALL_MODELS: list[type[BaseModel]] = [
     ApproveRequest,
     PlanFeedbackRequest,
     CommandRequest,
+    CancelRequest,
     CreateWorkstreamRequest,
     CreateWorkstreamResponse,
     CloseWorkstreamRequest,
     ListWorkstreamsResponse,
     DashboardResponse,
-    ListSessionsResponse,
+    ListSavedWorkstreamsResponse,
     HealthResponse,
 ]
 

turnstone/channels/_config.py

@@ -21,3 +21,4 @@ class ChannelConfig:
     model: str = ""
     auto_approve: bool = False
     auto_approve_tools: list[str] = field(default_factory=list)
+    template: str = ""