chore: bump version to 1.5.0a4

* fix(server): trusted-team workstream visibility on listing endpoints

The per-user filter on /v1/api/workstreams, /v1/api/dashboard, and
/v1/api/workstreams/saved (PR #375's _visible_workstreams helper) was
written for a multi-tenant SaaS threat model that doesn't match how
turnstone gets deployed.  In a self-hosted, trusted-team install the
filter created friction without preventing the relevant threats — and
hid the auto-created name="default" startup workstream from every
web user, leaving fresh installs staring at a blank dashboard.

Listing endpoints now return the cluster-wide set to any authenticated
caller.  Per-workstream MUTATIONS (/send, /close, /open, /title,
/delete, /refresh-title) keep their independent ownership checks — the
cross-tenant guards from PR #375 stay in force on those handlers (see
TestCrossTenant{Delete,Approve,Close,Title,Open}).  Listing only
exposes metadata (name, state, kind, message_count); message history
still requires the per-workstream gate on /history.

Resuming a saved workstream still goes through /open's owner check, so
the metadata-leak surface ends at "you can see workstream X exists" —
not at any actionable cross-user capability.

The console collector's service-scope is now load-bearing only for the
SSE event stream gate (/v1/api/events/global); kept anyway as belt-
and-braces.

If turnstone is ever deployed as a true multi-tenant SaaS, the right
boundary is a real ``tenant_id`` column with row-level filtering at
the storage layer, not the empty-user_id heuristic this used to apply.

Tests updated to assert the new contract: listing returns all owners;
mutation gates unchanged.

* fix(server): repair test mocks + tighten docstrings on listing endpoints

- tests/test_auth.py: TestServerAuth + TestServerLogin mocks now set
  kind / parent_ws_id / user_id explicitly so /v1/api/workstreams JSON-
  serializes them.  Bare MagicMock attributes return another MagicMock
  that fails json.dumps and surfaces as 500.

- turnstone/server.py: list_saved_workstreams docstring corrected to
  describe what the endpoint actually returns (summary metadata, not
  history) and to spell out that ownerless persisted rows are claimable
  by any authenticated caller via /open — consistent with the trusted-
  team model the listing endpoints assume.  Same callout added next
  to the open_workstream ownership-gate block.  Comments throughout
  rewritten to be timeless (no "previously" / PR-number references).

- tests/test_server_authz.py: TestSaved... docstring matches the actual
  /open behavior for orphan rows (claimable by any authenticated
  caller, not a separate admin path).

.env.example

@@ -1,29 +1,49 @@
 # =============================================================================
 # Turnstone Environment Variables
-# Copy to .env and adjust values for your deployment
+# Copy to .env and adjust values for your deployment.
+#
+# Usage:
+# Single node: docker compose --profile production up
+# 10-node cluster: docker compose --profile cluster up
 # =============================================================================
 
 # -- LLM Backend --------------------------------------------------------------
 LLM_BASE_URL=http://host.docker.internal:8000/v1
-OPENAI_API_KEY=sk-...
-# ANTHROPIC_API_KEY=sk-ant-...  # Set instead for Anthropic provider
-# TAVILY_API_KEY=tvly-...       # For web search fallback (local models only)
+OPENAI_API_KEY=dummy
+# ANTHROPIC_API_KEY=sk-ant-...# Set instead of OPENAI_API_KEY for Anthropic
+# TAVILY_API_KEY=tvly-... # Web search fallback (local models only)
+# MODEL=# Override default model alias
 
-# -- Database (production profile) --------------------------------------------
-# DB_BACKEND=postgresql
+# -- Authentication (required) ------------------------------------------------
+# Generate with: python -c "import secrets; print(secrets.token_hex(32))"
+TURNSTONE_JWT_SECRET=changeme-to-32-bytes-of-hex
+
+# -- Database ------------------------------------------------------------------
+# Single-node default is SQLite (zero config). Set these for PostgreSQL:
+# TURNSTONE_DB_BACKEND=postgresql
 # POSTGRES_USER=turnstone
 # POSTGRES_PASSWORD=changeme
-# DATABASE_URL=postgresql+psycopg://turnstone:changeme@postgres:5432/turnstone
-
-# -- Redis ---------------------------------------------------------------------
-# REDIS_PASSWORD=
-# REDIS_PORT=6379
-
-# -- Authentication ------------------------------------------------------------
-# TURNSTONE_AUTH_ENABLED=true
-# TURNSTONE_AUTH_TOKEN=your-secret-token
-# TURNSTONE_JWT_SECRET=python -c "import secrets; print(secrets.token_hex(32))"
+# TURNSTONE_DB_URL=postgresql+psycopg://turnstone:changeme@postgres:5432/turnstone
 
 # -- Ports ---------------------------------------------------------------------
 # SERVER_PORT=8080
 # CONSOLE_PORT=8090
+
+# -- Workspace -----------------------------------------------------------------
+# Bind-mount a host directory into the container at /workspace.
+# The model can read/write files here. Default: empty Docker volume.
+# WORKSPACE_MOUNT=/path/to/your/project
+
+# -- Agent behavior ------------------------------------------------------------
+# SKIP_PERMISSIONS=true # Auto-approve all tool calls (dev only)
+# MCP_CONFIG=/workspace/mcp.json# MCP server configuration file
+
+# -- Discord channel gateway ---------------------------------------------------
+# TURNSTONE_DISCORD_TOKEN=
+# TURNSTONE_DISCORD_GUILD=0
+
+# -- Cluster (profile: cluster) -----------------------------------------------
+# These are set per-node in compose.yaml; only override for custom topologies.
+# TURNSTONE_NODE_ID=node-1
+# TURNSTONE_ADVERTISE_URL=http://server-1:8080
+

.github/renovate.json

@@ -41,6 +41,14 @@
       "matchStrings": ["mermaid-(?<currentValue>[\\d.]+)/"],
       "depNameTemplate": "mermaid",
       "datasourceTemplate": "npm"
+    },
+    {
+      "customType": "regex",
+      "description": "Track vendored hls.js version",
+      "managerFilePatterns": ["/pyproject\\.toml$/"],
+      "matchStrings": ["hls-(?<currentValue>[\\d.]+)/"],
+      "depNameTemplate": "hls.js",
+      "datasourceTemplate": "npm"
     }
   ],
   "packageRules": [
@@ -83,7 +91,7 @@
     {
       "description": "Infrastructure dependencies",
       "groupName": "Infrastructure",
-      "matchPackageNames": ["structlog", "redis", "croniter", "discord.py"],
+      "matchPackageNames": ["structlog", "croniter", "discord.py"],
       "schedule": ["before 9am on the first day of the month"],
       "automerge": true,
       "matchUpdateTypes": ["patch"]
@@ -91,7 +99,7 @@
     {
       "description": "Vendored JS — CI workflow downloads files automatically",
       "groupName": "Vendored JS",
-      "matchPackageNames": ["katex", "highlight.js", "mermaid"],
+      "matchPackageNames": ["katex", "highlight.js", "mermaid", "hls.js"],
       "schedule": ["before 9am on the first day of the month"],
       "automerge": false
     },
@@ -101,7 +109,6 @@
       "matchPackageNames": [
         "ruff",
         "mypy",
-        "types-redis",
         "pytest",
         "pytest-cov",
         "pre-commit"

.github/workflows/ci.yml

@@ -2,9 +2,13 @@ name: CI
 
 on:
   push:
-    branches: [main]
+    branches: [main, "stable/*"]
+    tags: ["v*"]
   pull_request:
-    branches: [main]
+    branches: [main, "stable/*"]
+
+permissions:
+  contents: read
 
 jobs:
   lint:
@@ -25,8 +29,8 @@ jobs:
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
         with:
           python-version: "3.14"
-      - run: pip install mypy types-redis
-      - run: pip install -e ".[mq]"
+      - run: pip install mypy
+      - run: pip install -e ".[all]"
       - run: mypy turnstone/
 
   test:
@@ -39,9 +43,9 @@ jobs:
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
         with:
           python-version: ${{ matrix.python-version }}
-      - run: pip install -e ".[test,mq]"
+      - run: pip install -e ".[test]"
       - run: pytest tests/ -m "not live" --cov=turnstone --cov-report=term-missing --cov-report=xml -q
-      - uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         if: always()
         with:
           name: coverage-${{ matrix.python-version }}
@@ -68,11 +72,58 @@ jobs:
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
         with:
           python-version: "3.14"
-      - run: pip install -e ".[test,mq,postgres]"
+      - run: pip install -e ".[test,postgres]"
       - run: pytest tests/ -m "not live" --storage-backend=postgresql -q
         env:
           TURNSTONE_TEST_PG_URL: postgresql+psycopg://postgres:postgres@localhost:5432/turnstone_test
 
+  wheel-completeness:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: "3.14"
+      - run: pip install build
+      - run: python -m build --wheel
+      - name: Check all data files are in wheel
+        run: |
+          SOURCE=$(find turnstone -type f \
+            ! -name '*.py' ! -name '*.pyc' ! -path '*__pycache__*' \
+            | sort)
+          WHEEL=$(python -m zipfile -l dist/*.whl \
+            | awk '{print $1}' \
+            | grep -v '\.py$' | grep -v '\.dist-info' | grep -v '\.pyc' | grep -v '^File$' \
+            | sort)
+
+          # Files intentionally excluded from the wheel (one per line)
+          ALLOW="
+          turnstone/core/storage/migrations/script.py.mako
+          "
+
+          MISSING=$(comm -23 <(echo "$SOURCE") <(echo "$WHEEL") \
+            | grep -vFxf <(echo "$ALLOW" | sed '/^[[:space:]]*$/d; s/^[[:space:]]*//' ) || true)
+
+          if [ -n "$MISSING" ]; then
+            echo "::error::Data files in source tree but missing from wheel:"
+            echo "$MISSING"
+            echo ""
+            echo "Add them to [tool.hatch.build.targets.wheel] in pyproject.toml"
+            echo "or to the ALLOW list in this job if intentionally excluded."
+            exit 1
+          fi
+          echo "All source data files present in wheel"
+      - name: Smoke-test entry points from installed wheel
+        run: |
+          python -m venv /tmp/smoke
+          /tmp/smoke/bin/pip install dist/*.whl
+          /tmp/smoke/bin/turnstone --help
+          /tmp/smoke/bin/turnstone-server --help
+          /tmp/smoke/bin/turnstone-console --help
+          /tmp/smoke/bin/turnstone-admin --help
+          /tmp/smoke/bin/turnstone-channel --help
+          /tmp/smoke/bin/turnstone-bootstrap --help
+
   lock-check:
     runs-on: ubuntu-latest
     steps:
@@ -104,7 +155,7 @@ jobs:
         working-directory: sdk/typescript
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
-      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
         with:
           node-version: "24"
       - run: npm ci

.github/workflows/docker-publish.yml

@@ -0,0 +1,81 @@
+name: Publish Docker Image
+
+on:
+  workflow_run:
+    workflows: ["CI"]
+    types: [completed]
+
+concurrency:
+  group: docker-${{ github.event.workflow_run.head_sha }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  packages: write
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  docker:
+    if: >-
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.head_repository.full_name == github.repository
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          ref: ${{ github.event.workflow_run.head_sha }}
+          fetch-depth: 0
+
+      - name: Resolve release tag
+        id: tag
+        run: |
+          TAG=$(git tag --points-at HEAD | grep '^v' | head -1)
+          if [ -z "$TAG" ]; then
+            echo "No v* tag at HEAD — skipping publish"
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Log in to GHCR
+        if: steps.tag.outputs.skip == 'false'
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Compute Docker tags
+        if: steps.tag.outputs.skip == 'false'
+        id: tags
+        env:
+          REF: ${{ steps.tag.outputs.tag }}
+        run: |
+          VERSION="${REF#v}"
+          FULL="${REGISTRY}/${IMAGE_NAME}"
+          FULL="${FULL,,}"
+
+          if echo "$VERSION" | grep -qE '(a|b|rc)[0-9]+$'; then
+            TAGS="${FULL}:${VERSION},${FULL}:experimental"
+          else
+            MINOR="${VERSION%.*}"
+            TAGS="${FULL}:${VERSION},${FULL}:${MINOR},${FULL}:stable,${FULL}:latest"
+          fi
+          echo "tags=${TAGS}" >> "$GITHUB_OUTPUT"
+
+      - uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4
+        if: steps.tag.outputs.skip == 'false'
+
+      - name: Build and push
+        if: steps.tag.outputs.skip == 'false'
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.tags.outputs.tags }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.github/workflows/docker-scan.yml

@@ -1,22 +0,0 @@
-name: Docker Security Scan
-
-on:
-  push:
-    branches: [main]
-  schedule:
-    - cron: "0 6 * * 1"  # Weekly Monday 06:00 UTC
-
-permissions:
-  contents: read
-
-jobs:
-  scan:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
-      - run: docker build -t turnstone:scan .
-      - uses: aquasecurity/trivy-action@57a97c7e7821a5776cebc9bb87c984fa69cba8f1 # 0.35.0
-        with:
-          image-ref: "turnstone:scan"
-          severity: "HIGH,CRITICAL"
-          exit-code: "1"

.github/workflows/publish.yml

@@ -1,8 +1,13 @@
 name: Publish to PyPI
 
 on:
-  push:
-    tags: ["v*"]
+  workflow_run:
+    workflows: ["CI"]
+    types: [completed]
+
+concurrency:
+  group: publish-${{ github.event.workflow_run.head_sha }}
+  cancel-in-progress: true
 
 permissions:
   contents: write
@@ -10,20 +15,43 @@ permissions:
 
 jobs:
   publish:
+    if: github.event.workflow_run.conclusion == 'success'
     runs-on: ubuntu-latest
     environment: pypi
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          ref: ${{ github.event.workflow_run.head_sha }}
+          fetch-depth: 0
+
+      - name: Resolve release tag
+        id: tag
+        run: |
+          TAG=$(git tag --points-at HEAD | grep '^v' | head -1)
+          if [ -z "$TAG" ]; then
+            echo "No v* tag at HEAD — skipping publish"
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+          fi
+
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        if: steps.tag.outputs.skip == 'false'
         with:
           python-version: "3.14"
       - run: pip install build
+        if: steps.tag.outputs.skip == 'false'
       - run: python -m build
-      - uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # release/v1
+        if: steps.tag.outputs.skip == 'false'
+      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1
+        if: steps.tag.outputs.skip == 'false'
 
       - name: Create GitHub Release
-        uses: softprops/action-gh-release@153bb8e04406b158c6c84fc1615b65b24149a1fe # v2
+        if: steps.tag.outputs.skip == 'false'
+        uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda # v3
         with:
+          tag_name: ${{ steps.tag.outputs.tag }}
           generate_release_notes: true
           draft: false
-          prerelease: ${{ contains(github.ref, '-') }}
+          prerelease: ${{ contains(steps.tag.outputs.tag, 'a') || contains(steps.tag.outputs.tag, 'b') || contains(steps.tag.outputs.tag, 'rc') }}

.github/workflows/vendor-js.yml

@@ -48,7 +48,7 @@ jobs:
         id: detect
         run: |
           updates=()
-          for lib in katex hljs mermaid; do
+          for lib in katex hljs mermaid hls; do
             version=$(grep -oE "${lib}-[0-9.]+" pyproject.toml | head -1 | sed "s/${lib}-//")
             [[ -z "$version" ]] && continue
             [[ -d "turnstone/shared_static/${lib}-${version}" ]] && continue

.gitignore

@@ -21,3 +21,5 @@ PROGRESS.md
 .coverage
 tools/skill_audit_analysis/data/
 tools/skill_audit_analysis/output/
+design_ideas/
+.claude/

.pre-commit-config.yaml

@@ -10,7 +10,7 @@ repos:
     rev: v1.19.1
     hooks:
       - id: mypy
-        additional_dependencies: [types-redis>=4.6, redis>=7.2]
+        additional_dependencies: []
         args: [--config-file=pyproject.toml]
         pass_filenames: false
         entry: mypy turnstone/

.trivyignore

@@ -1,4 +0,0 @@
-# libexpat integer overflow — no fix available in Debian repos yet
-# https://avd.aquasec.com/nvd/cve-2026-25210
-# Review: remove this entry once a patched libexpat1 is published
-CVE-2026-25210

CHANGELOG.md

@@ -0,0 +1,308 @@
+# Changelog
+
+All notable changes to turnstone are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [PEP 440](https://peps.python.org/pep-0440/) for
+version numbers (`X.Y.Z`, with `X.Y.ZaN` / `bN` / `rcN` for pre-releases).
+
+Three release tracks are maintained:
+
+- **`stable/1.0`** — patch-only (`v1.0.x`)
+- **`stable/1.3`** — patch-only (`v1.3.x`)
+- **`stable/1.4`** — patch-only (`v1.4.x`)
+- **`main`** — experimental (`v1.5.0aN`)
+
+## [Unreleased]
+
+## [1.4.0]
+
+User-visible additions: a full attachment system (images + text documents,
+including pre-creation uploads), a unified dashboard composer, a Slack
+channel adapter, per-call plan/task model selection with an admin UI, and
+provider capability passthrough.
+
+This release introduces two forward-only schema migrations
+(`037_workstream_attachments`, `038_workstream_attachments_reserved_at`)
+that the server applies automatically on first startup against an
+existing 1.3.x database.  Both are additive; no data loss.  See
+**Database migrations** below for details.
+
+### Added
+
+- **Workstream attachments** — images (png/jpeg/gif/webp, 4 MiB cap) and
+  text documents (any `text/*` MIME, allowlisted application MIMEs, or
+  known text extensions; 512 KiB cap; UTF-8 enforced).  Magic-byte image
+  sniffing on upload; per-(ws, user) pending cap of 10.  Three-state
+  lifecycle (`pending → reserved → consumed`) with reservation tokens
+  threaded through `/v1/api/send` so queued multimodal turns can't lose
+  files to overlapping sends.  Provider-side translation: Anthropic
+  emits native document blocks; OpenAI Chat Completions inlines them as
+  escaped `<document>` text blocks; Responses API emits `input_text`
+  with the same wrapper. (#356)
+- **Attachments at workstream-creation time** —
+  `POST /v1/api/workstreams/new` accepts `multipart/form-data` (one
+  `meta` JSON field plus 0..N `file` parts).  Files are validated and
+  reserved onto the first turn before the dispatch worker fires; failure
+  rolls back the fresh workstream so no orphan rows leak.  Web UI
+  (new-workstream modal + dashboard composer), Python SDK, and
+  TypeScript SDK all gained attachment support.  Cluster routing
+  (`/v1/api/route/workstreams/{ws_id}/attachments`) extended to forward
+  multipart bodies + preserve upstream headers (CSP, Content-Disposition).
+  SDKs auto-generate `ws_id` client-side so cluster-routed callers can
+  bind the body to the owning node before it lands. (#362)
+- **Slack channel adapter** (Socket Mode) — mirrors the Discord adapter:
+  per-user channel sessions via configurable slash command, DM routing
+  without slash command, SSE event consumption, tool approval buttons
+  with per-user owner enforcement, plan-review approve / request-changes
+  modal, notification reply routing back into the workstream, and
+  session recovery after restart via persisted recoverable route keys
+  (the bot re-subscribes to existing Slack-routed workstreams when it
+  comes back).  Install with `pip install 'turnstone[slack]'`. (#355)
+- **Console admin UX support for Slack** — channel-link modal offers
+  Slack alongside Discord; skill notify-on-complete forms expose a
+  per-row channel-type dropdown (and no longer hardcode `discord`);
+  per-platform `.scope-discord` / `.scope-slack` badge classes with
+  theme-aware tokens (`--discord` / `--slack`) so light theme passes
+  WCAG AA. (#365)
+- **Per-call plan/task model selection** — `plan_model` and `task_model`
+  are now distinct from the conversation model and from each other,
+  with configurable reasoning effort per agent.  Three layers:
+  - **Backend split** (`#54dd557`) — `ModelRegistry` gains `plan_model`,
+    `task_model`, `plan_effort`, `task_effort`; per-kind overrides win
+    over the legacy `agent_model`, which still works as the single-knob
+    fallback.  `resolve_agent_alias(kind)` and `resolve_agent_effort(kind)`
+    centralise resolution.  Loader validates effort against
+    `{none, minimal, low, medium, high, xhigh, max}` with warn+drop on
+    typos.
+  - **Runtime configurability** (`#360`) — `ConfigStore` admin tab in
+    the console UI lets operators switch alias and reasoning effort per
+    agent **without restarting**.  `INHERIT_EMPTY_LABEL_KEYS` shows
+    `(inherit)` for empty effort selections — distinct from the literal
+    `none` choice which actually disables reasoning.  Routing overrides
+    apply on `/v1/api/_internal/config-reload` (admin saves), and
+    `model-reload` short-circuits when nothing changed so no in-flight
+    clients churn.
+  - **Per-call override** (`#361`) — the calling LLM can pass
+    `model="<alias>"` to `plan_agent` or `task_agent` to override the
+    operator-configured per-kind model for that one invocation.  Tool
+    descriptions list the live registered aliases (refreshed when the
+    operator hits "sync to nodes"), so the LLM always sees current
+    options.  Bad aliases return a corrective error dict listing the
+    available choices.  No whitelist — cost control is intentionally
+    ceded to the model.  Plan-retry path reuses the alias so coaching
+    reflects real model behaviour. (#360, #361)
+- **Provider capability passthrough** — resolved per-model capabilities
+  (vision, reasoning, native web search, thinking_mode, token_param,
+  etc.) flow through to provider clients via a new `capabilities`
+  parameter on `create_streaming` / `create_completion`, so feature
+  gating no longer relies on string matching and admin-UI / config.toml
+  overrides actually reach the provider.  Defensive shallow-copy in
+  `_finalize_extra_body` so callers reusing the same dict across models
+  are safe; deep-merge of `chat_template_kwargs` so operators can
+  extend instead of silently overwriting. (#352)
+- **Server compatibility layer for local model servers** — vLLM and
+  llama.cpp profiles suggest the right thinking mode and per-server
+  workarounds (`skip_special_tokens` for vLLM, `reasoning_format` for
+  llama.cpp) during model detection.  Admin UI gains structured fields
+  for server type, thinking mode, and extra body params, hidden for
+  non-local providers (openai/anthropic/google).  New `thinking_param`
+  text field surfaces the alias name (default `enable_thinking`;
+  Granite/DeepSeek use `thinking`).  Verified end-to-end against real
+  vLLM (Gemma 4 31B) and llama.cpp (Gemma 4 E4B) servers. (#352)
+- **Claude Opus 4.7 support** — `claude-opus-4-7` capability entry
+  (1M ctx, 128K output, adaptive thinking, `supports_temperature=False`,
+  `thinking_display=summarized`).  New `ModelCapabilities.thinking_display`
+  field — Opus 4.7 omits thinking by default but always sends summarized
+  blocks back through the provider boundary.  Adds `xhigh` effort level
+  to the global mapping and to Opus 4.7's `effort_levels`; admin-console
+  skill-template dropdowns gained `xhigh` and `max` options.  Reasoning
+  effort label capitalization aligned across all console dropdowns.
+  (#357 — also in 1.3.1)
+- **Dashboard composer refactor** — unified single-flow create from the
+  per-node dashboard.  Multi-line textarea + collapsible Options panel
+  (model / judge / skill) + paperclip + drag-drop / paste-image + chip
+  strip.  Submit-button label dynamically toggles between `Create`
+  (empty) and `Send` (text or attachments staged); Enter and click both
+  go through the same `dashboardSubmit()`.  Replaces the inconsistent
+  prior split where Enter created+sent raw and the button opened a
+  separate modal.  Options panel state persists in `localStorage`;
+  active non-default selections render as an inline summary chip beside
+  the Options button; drag-over shows an explicit "Drop to attach"
+  overlay.  The tab-bar `+` new-workstream modal also gained a paperclip
+  + chip strip + first-message field so the same flow is reachable from
+  both entry points. (#362, #366)
+- **Workstream attachments — orphan reservation sweep** — periodic
+  background sweep clears `reserved_for_msg_id` on rows whose
+  `reserved_at` exceeds a 1-hour threshold, self-healing reservations
+  leaked by process crashes between reserve and consume.  Backed by a
+  partial index on `(reserved_at) WHERE reserved_at IS NOT NULL` so the
+  scan stays cheap as the consumed-history grows.  Threshold tracks
+  reservation age, not upload age, so a long-pending fresh send can't
+  be racially unreserved. (#363)
+- **`SendResponse` extended** — `attached_ids`,
+  `dropped_attachment_ids`, `priority`, `msg_id` fields exposed in
+  Pydantic + TypeScript SDKs so attachment-aware clients can detect
+  partial reservations and dequeue queued messages. (#365)
+
+### Changed
+
+- **`plan_model` and `task_model` now split** from the conversation
+  model and from each other — operators who rely on a single model for
+  all three should set both `plan_model` and `task_model` explicitly in
+  their config; otherwise both default to the conversation model so
+  behaviour is unchanged. (#54dd557)
+- **Channel notify-on-complete `channel_type` is no longer hardcoded
+  in the admin UI** — operators creating notify targets through the
+  skill admin form previously got `channel_type: "discord"` regardless
+  of what they wanted.  Existing skill JSON values are unaffected; only
+  newly created targets through the form differ. (#365)
+- **Slack adapter approval previews** — capped at 600 chars per item
+  with a 2700-char total budget so multi-tool approval batches never
+  exceed Slack's 3000-char `section.text` limit.  Truncated batches
+  show a `…and N more (preview truncated)` suffix. (#365)
+- **PostgreSQL deployment image** swapped from `bitnami/pgbouncer` to
+  `edoburu/pgbouncer` to track upstream releases and reduce image size.
+  Environment variables remapped to the edoburu naming, ports updated
+  to match documented expectations, and the Kubernetes Helm Chart link
+  in the deployment docs now points at the same container.  Review
+  your helm values if you depend on `bitnami`-specific environment
+  variable conventions. (#353)
+
+### Fixed
+
+- **`plan_resolved` SSE broadcast** — when one client resolved a plan
+  approval, other clients viewing the same workstream now have the
+  approval card dismissed in sync. (#87a9af1)
+- **Slack notification reply routing** — one notification reply
+  previously pinned every later assistant response for that workstream
+  to the notification thread until the bot restarted.  Reply-route
+  override now clears on `StreamEndEvent`. (#365)
+- **Slack plan-review mrkdwn fence** — plan content containing triple
+  backticks (very common — plans often quote code) no longer breaks the
+  surrounding fence and lets later content render as live markup.  The
+  shared `_sanitize_slack_preview` helper splices a zero-width space
+  inside any ``` ``` `` sequence while keeping single backticks
+  readable. (#365)
+- **Slack-routed workstreams now load the chat-specific system prompt**
+  via `client_type="chat"`, matching Discord. (#365)
+- **`/v1/api/workstreams/new` no longer emits a phantom
+  `ws_created`/`ws_closed` SSE pair** when attachment validation
+  rejects a multipart create.  Validation runs before the broadcast so
+  failed creates are silent on dashboards. (#362)
+- **Multipart Content-Type boundary preservation** in console routing
+  proxy — `boundary=` parameter is case-sensitive and was being
+  lowercased before forwarding to the upstream node, breaking parsing
+  for clients that used mixed-case boundaries (most browsers). (#362)
+- **Local-theme contrast for new badge colors** — `.scope-discord` and
+  `.scope-slack` first shipped with raw hex that failed WCAG AA on
+  light theme (1.8:1 / 2.4:1).  Theme-aware `--discord` / `--slack`
+  tokens with proper light variants now pass. (#365)
+- **Cross-user attachment fetch hardening** — `get_attachment_content`
+  now scopes the row by `user_id` in addition to `ws_id`, so an
+  unowned workstream can't be a vector for cross-user blob fetches via
+  attachment-id guessing. (#356)
+- **Attachment-list DoS guard** — `/v1/api/send` rejects
+  `attachment_ids` lists longer than the per-(ws, user) pending cap
+  with a 400, preventing hostile clients from blowing up the storage
+  `IN (...)` clause. (#356)
+- **Bounded LRU for upload locks** — the per-(ws, user) attachment
+  upload-lock map now evicts the oldest unlocked entries past a soft
+  cap, so the in-process map can't grow unbounded on long-running
+  nodes. (#356)
+- **3.12 CI deadlock on attachment uploads** — the upload-lock was
+  initially an `asyncio.Lock`, but Starlette's `TestClient` runs each
+  request on a fresh anyio task / event loop, so the cached lock's
+  `_waiters` bound to the first loop and a later request would block
+  on a Future from a closed loop (silent deadlock).  Switched to
+  `threading.Lock` — loop-agnostic, and the critical section is one
+  COUNT + one INSERT.  Same root cause is reproducible against any
+  Starlette TestClient harness on Python ≥ 3.10; 3.12 surfaces it
+  more often.  Production users on a single event loop weren't
+  affected, but the test environment was. (#356)
+
+### Security
+
+- **Slack approval per-user authentication** — only the session owner
+  can click Approve/Deny on a Slack tool-approval card.  Without this,
+  any channel member with view access could approve dangerous tool
+  calls initiated by someone else. (#355)
+- **Attachment ownership masking** — cross-user/cross-workstream
+  attachment ID lookups return 404 (not 403) so non-owners can't
+  enumerate workstream existence by response code. (#356)
+- Bumped Debian base image; remaining unfixable `jq` CVEs are
+  documented and exception-listed. (#aaea4d3)
+
+### Database migrations
+
+- **`037_workstream_attachments`** — new `workstream_attachments` table
+  with the lifecycle columns described above.  Indexes for ws_id,
+  pending lookups, message linkage, and reservation scoping.
+- **`038_workstream_attachments_reserved_at`** — adds `reserved_at`
+  column for the orphan-sweep staleness signal, plus a partial index
+  on `reserved_at IS NOT NULL` so the periodic scan is cheap.
+
+Both migrations are additive and idempotent, and the server applies
+them automatically on first startup against an existing 1.3.x database.
+No manual `alembic upgrade` step is required — though running it
+manually beforehand (e.g. as part of a phased deploy) remains safe.
+
+### SDK
+
+Python + TypeScript clients gained:
+
+- `AttachmentUpload` type
+- `upload_attachment(ws_id, filename, data, mime_type=None)`
+- `list_attachments(ws_id)`
+- `get_attachment_content(ws_id, attachment_id) → bytes / Blob`
+- `delete_attachment(ws_id, attachment_id)`
+- `send(message, ws_id, attachment_ids=...)` (extended)
+- `create_workstream(..., attachments=[...])` — multipart variant with
+  client-side `ws_id` generation for cluster-routed callers
+- Console SDK: `route_create_workstream(attachments=...)`,
+  `route_upload_attachment`, `route_list_attachments`,
+  `route_get_attachment_content`, `route_delete_attachment`
+- Refusal of `attachments + target_node` combination at the SDK
+  boundary (the multipart routing layer doesn't honor `target_node`,
+  so silently picking the wrong node is now an explicit error)
+- `PlanResolvedEvent` SSE event with type guard, dispatched when one
+  client (e.g. mobile) resolves a plan so other connected clients can
+  dismiss their plan-approval modal in sync.  Available in both the
+  Python and TypeScript SDKs. (#87a9af1)
+
+### Operational
+
+- **CI vendor-asset auto-download covers `hls.js`** — the
+  `vendor-js.yml` workflow previously only iterated katex/hljs/mermaid,
+  so Renovate bumps for `hls.js` failed the wheel-completeness check
+  and required manual file downloads.  Detection loop now includes
+  `hls`, so future Renovate bumps are merge-ready without intervention.
+  (#354)
+
+### Contributors
+
+Thanks to the people who made this release happen — especially the
+external contributors who picked up substantial pieces of work:
+
+- **[@daoxley](https://github.com/daoxley)** — designed and shipped
+  the Slack channel adapter (Socket Mode bot, per-user sessions,
+  approvals, plan-review, notification routing).  Major new feature
+  surface in #355.
+- **[@pizzaandcheese](https://github.com/pizzaandcheese)** — replaced
+  the deprecated bitnami pgbouncer image with the edoburu image,
+  remapped environment variables, ports, and helm chart references.
+  Operationally important for anyone running our reference Postgres
+  deployment (#353).
+- Renovate kept dependencies and the JS vendor tree current via
+  several automated bumps.
+
+If you're interested in contributing, channel-attachment ingest from
+Discord + Slack is the headline 1.4.1 feature and a solid place to
+start — see the open issues on GitHub or open one to scope a piece.
+
+## [1.3.1]
+
+### Added
+
+- Backport: Claude Opus 4.7 support (provider capabilities, tokenizer,
+  adaptive thinking). (#357)

CONTRIBUTING.md

@@ -26,7 +26,15 @@ transferring ownership.
 ```
 python -m venv .venv
 source .venv/bin/activate
-pip install -e ".[test]"
+pip install -e ".[test,dev]"
+```
+
+The `dev` extra installs `ruff` and `mypy`. Before pushing, run:
+
+```
+ruff check turnstone tests
+mypy turnstone
+pytest
 ```
 
 ## Guidelines

Dockerfile

@@ -1,6 +1,6 @@
 # =============================================================================
 # Turnstone — Docker build with uv for reproducible, locked installs
-# Single image for all services: server, bridge, console, sim, eval
+# Single image for all services: server, console, channel, eval
 # =============================================================================
 
 FROM python:3.14-slim
@@ -8,33 +8,39 @@ FROM python:3.14-slim
 LABEL org.opencontainers.image.title="turnstone" \
       org.opencontainers.image.description="Multi-node AI orchestration platform"
 
-COPY --from=ghcr.io/astral-sh/uv:0.11.2 /uv /usr/local/bin/uv
+COPY --from=ghcr.io/astral-sh/uv:0.11.7 /uv /usr/local/bin/uv
 
 # Remove the slim image's man page exclusion so man-db has actual content
 RUN rm -f /etc/dpkg/dpkg.cfg.d/docker
 
 # System dependencies: psycopg (libpq5), developer tooling for agent workflows
 RUN apt-get update && apt-get upgrade -y && apt-get install -y --no-install-recommends \
-    libpq5 git curl jq man-db manpages \
+    libpq5 git curl jq man-db manpages procps file \
     && rm -rf /var/lib/apt/lists/*
 
+# Node.js LTS (for npx-based MCP servers like @modelcontextprotocol/server-github)
+COPY --from=node:24-slim /usr/local/bin/node /usr/local/bin/node
+COPY --from=node:24-slim /usr/local/lib/node_modules /usr/local/lib/node_modules
+RUN ln -s ../lib/node_modules/npm/bin/npm-cli.js /usr/local/bin/npm \
+    && ln -s ../lib/node_modules/npm/bin/npx-cli.js /usr/local/bin/npx
+
 # Non-root user
 RUN useradd --create-home --shell /bin/bash turnstone
 
 WORKDIR /app
 
-# Compile bytecode for faster startup
-ENV UV_COMPILE_BYTECODE=1
-
 # Install dependencies first (cached layer — only re-runs when deps change)
 COPY pyproject.toml uv.lock README.md LICENSE ./
 RUN uv sync --frozen --no-install-project --no-dev \
-    --extra all
+    --no-compile --extra all
 
 # Install the project itself
 COPY turnstone/ turnstone/
 RUN uv sync --frozen --no-dev \
-    --extra all
+    --no-compile --extra all
+
+# Compile bytecode in a separate step (avoids fd exhaustion during install)
+RUN python -m compileall -q .venv turnstone/
 
 # Add venv to PATH so entry points are found
 ENV PATH="/app/.venv/bin:$PATH"
@@ -49,6 +55,9 @@ COPY docker/entrypoint.sh /usr/local/bin/entrypoint.sh
 WORKDIR /data
 RUN chown turnstone:turnstone /data
 
+# Workspace mount point — bind-mount a host directory here
+RUN mkdir -p /workspace && chown turnstone:turnstone /workspace
+
 USER turnstone
 
 ENTRYPOINT ["entrypoint.sh"]

QUICKSTART.md

@@ -45,9 +45,9 @@ That's it — no flags, no arguments. The wizard prompts for everything.
 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.
+  1 server + console + PostgreSQL. Good for most use cases.
 - **Multi-node cluster** (`docker compose --profile cluster up`) —
-  10-node server/bridge fleet + PostgreSQL + Redis. For high-throughput or
+  10-node server fleet + console + PostgreSQL. For high-throughput or
   HA deployments.
 
 ## Example Session
@@ -55,7 +55,7 @@ The wizard supports two deployment modes:
 ```
 $ turnstone-bootstrap
 
- Turnstone Bootstrap Wizard  v0.5.4
+ Turnstone Bootstrap Wizard  v1.5.0
  ────────────────────────────────────────────────
 
  Which provider for this wizard?
@@ -87,6 +87,6 @@ $ turnstone-bootstrap
 
 ## 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
+- [Docker Deployment](docs/docker.md) — manual compose setup and profiles
+- [Security](docs/security.md) — auth architecture and token types
+- [Governance](docs/governance.md) — roles, policies, and templates

README.md

@@ -5,418 +5,145 @@
 [![Python](https://img.shields.io/pypi/pyversions/turnstone)](https://pypi.org/project/turnstone/)
 [![License](https://img.shields.io/badge/license-BSL--1.1-blue)](LICENSE)
 
-Experimental multi-node AI orchestration platform. Deploy tool-using AI agents across a cluster of servers, driven by message queues or interactive interfaces.
+Multi-node AI orchestration platform. Deploy tool-using AI agents across a cluster of servers with direct HTTP routing, interactive interfaces, and enterprise governance.
 
-> **Beta — Use at your own risk.** Turnstone is under active development and has not reached a stable release. APIs, configuration formats, and database schemas may change between versions without migration paths. We make no guarantees of determinism, reliability, or backward compatibility. Evaluate thoroughly before deploying to any environment where these properties matter.
+<p align="center">
+  <img src="docs/assets/hero.png" alt="Turnstone console — multi-workstream AI orchestration with mermaid diagrams" width="960"/>
+</p>
 
 Named after the [Ruddy Turnstone](https://en.wikipedia.org/wiki/Ruddy_turnstone) (*Arenaria interpres*) — a shorebird that flips stones to discover what's hiding underneath.
 
+### Release Tracks
+
+| Track | Install | Docker | Description |
+|-------|---------|--------|-------------|
+| **Stable** | `pip install turnstone` | `ghcr.io/turnstonelabs/turnstone:stable` | Production-grade. Bugfixes only. |
+| **Experimental** | `pip install turnstone --pre` | `ghcr.io/turnstonelabs/turnstone:experimental` | New features. May have rough edges. |
+
+See [docs/releasing.md](docs/releasing.md) for the full release process.
+
 ## 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.
 
 - **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, reverse proxy for server UIs
-- **Intent validation** — an LLM judge evaluates every tool call before approval, presenting risk assessments and evidence-based recommendations so users can make informed decisions instead of blindly approving raw tool calls
-- **Governance & compliance** — RBAC, OIDC SSO (Okta, Azure AD, Google, Keycloak), tool policies, skills (reusable behavioral profiles with security scanning), usage tracking, and append-only audit logs
-- **Cluster simulator** — test the stack at scale (up to 1000 nodes) without an LLM backend
-
-Works with any OpenAI-compatible API (vLLM, llama.cpp, NVIDIA NIM) or Anthropic's native Messages API. Supports [MCP](https://modelcontextprotocol.io/) for external tool servers with native deferred tool loading on Anthropic and OpenAI APIs (BM25 fallback for local models).
+- **Cluster dashboard** — real-time view of all nodes and workstreams with console routing proxy
+- **Intent validation** — LLM judge evaluates every tool call with risk assessments and evidence
+- **Governance** — RBAC, OIDC SSO, tool policies, skills, usage tracking, audit logs
+- **Multi-provider** — OpenAI-compatible APIs (vLLM, llama.cpp, NIM), Anthropic Messages API, and Google Gemini
+- **MCP support** — external tool servers with native deferred loading (Anthropic/OpenAI) or BM25 fallback
 
 <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"/>
+  <img src="docs/diagrams/architecture-overview.svg" alt="Turnstone system architecture" width="960"/>
 </p>
 
 ## Quickstart
 
-### Interactive (terminal)
-
 ```bash
 pip install turnstone
+
+# Terminal REPL
 turnstone --base-url http://localhost:8000/v1
+
+# Browser UI
+turnstone-server --port 8080 --base-url http://localhost:8000/v1
+
+# Cluster dashboard
+pip install turnstone[console]
+turnstone-console --port 8090
 ```
 
-### Interactive (browser)
+For PostgreSQL (recommended for production):
 
 ```bash
+pip install turnstone[postgres]
+export TURNSTONE_DB_BACKEND=postgresql
+export TURNSTONE_DB_URL="postgresql+psycopg://user:pass@localhost:5432/turnstone"
 turnstone-server --port 8080 --base-url http://localhost:8000/v1
 ```
 
-### Queue-driven (programmatic)
-
-```bash
-pip install turnstone[mq]
-turnstone-bridge --server-url http://localhost:8080 --redis-host localhost
-```
-
-```python
-from turnstone.mq import TurnstoneClient
-
-with TurnstoneClient() as client:
-    # Generic — any available node picks it up
-    result = client.send_and_wait("Analyze the error logs", auto_approve=True)
-    print(result.content)
-
-    # Directed — must run on a specific server
-    result = client.send_and_wait(
-        "Check disk I/O on this server",
-        target_node="server-12",
-        auto_approve=True,
-    )
-```
-
-### Cluster dashboard
-
-```bash
-pip install turnstone[console]
-turnstone-console --redis-host localhost --port 8090
-```
-
-Then open `http://localhost:8090` for the cluster-wide dashboard. Create workstreams from the console and interact with any node's server UI through the built-in reverse proxy — no direct server port access required.
-
 ### Docker
 
 ```bash
 cp .env.example .env  # edit LLM_BASE_URL, OPENAI_API_KEY, etc.
-docker compose up     # starts redis + server + bridge + console (SQLite)
+docker compose --profile production up
 ```
 
-For production with PostgreSQL:
+See [QUICKSTART.md](QUICKSTART.md) for the bootstrap wizard and [docs/docker.md](docs/docker.md) for Docker configuration and profiles.
 
-```bash
-# Requires POSTGRES_PASSWORD and DB_BACKEND=postgresql in .env (or exported)
-docker compose --profile production up  # adds PostgreSQL, uses it as database
+### Programmatic (SDK)
+
+```python
+from turnstone.sdk import TurnstoneServer
+
+with TurnstoneServer("http://localhost:8080", token="tok_xxx") as client:
+    ws = client.create_workstream(name="demo")
+    result = client.send_and_wait("Analyze the error logs", ws.ws_id, auto_approve=True)
+    print(result.content)
 ```
 
-Console dashboard at http://localhost:8090. See [docs/docker.md](docs/docker.md) for configuration, scaling, and profiles.
-
-### Simulator
-
-Test the multi-node stack at scale without an LLM backend:
-
-```bash
-docker compose --profile sim up redis console sim
-```
-
-Or standalone:
-
-```bash
-pip install turnstone[sim]
-turnstone-sim --nodes 100 --scenario steady --duration 60 --mps 10
-```
-
-See [docs/simulator.md](docs/simulator.md) for scenarios, CLI reference, and metrics.
-
-## Architecture
-
-### Diagrams
-
-Detailed UML diagrams are available in [`docs/diagrams/`](docs/diagrams/):
-
-| Diagram | Description |
-|---------|-------------|
-| [System Context](docs/diagrams/png/01-system-context.png) | Top-level components and external dependencies |
-| [Package Structure](docs/diagrams/png/02-package-structure.png) | Python modules and dependency graph |
-| [Core Engine Classes](docs/diagrams/png/03-core-engine-classes.png) | SessionUI protocol, ChatSession, LLMProvider, WorkstreamManager |
-| [Conversation Turn](docs/diagrams/png/04-conversation-turn.png) | Full message lifecycle through the engine (provider-agnostic) |
-| [Tool Pipeline](docs/diagrams/png/05-tool-pipeline.png) | Three-phase prepare/approve/execute |
-| [MQ Protocol](docs/diagrams/png/06-mq-protocol.png) | 9 inbound + 19 outbound message types |
-| [Message Routing](docs/diagrams/png/07-message-routing.png) | Multi-node routing scenarios |
-| [Redis Key Schema](docs/diagrams/png/08-redis-key-schema.png) | All Redis keys, types, and TTLs |
-| [Workstream States](docs/diagrams/png/09-workstream-states.png) | State machine transitions |
-| [Simulator](docs/diagrams/png/10-simulator-architecture.png) | SimCluster, dispatchers, scenarios |
-| [Console Data Flow](docs/diagrams/png/11-console-data-flow.png) | Dashboard data collection threads |
-| [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 |
-| [WS Template Architecture](docs/diagrams/png/21-ws-template-architecture.png) | Workstream template application and lifecycle |
-| [Judge Architecture](docs/diagrams/png/22-judge-architecture.png) | Intent validation two-tier evaluation pipeline |
-| [OIDC Architecture](docs/diagrams/png/25-oidc-architecture.png) | OIDC SSO authorization code flow with PKCE |
-
-### 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
-- **OIDC SSO** — single sign-on via any OpenID Connect provider (Okta, Azure AD, Google, Keycloak); Authorization Code Flow with PKCE, auto-provisioning, claim-based role mapping with demotion propagation; see [docs/oidc.md](docs/oidc.md)
-- **Tool policies** — glob-pattern rules (`allow` / `deny` / `ask`) with priority ordering; automate approvals or lock down dangerous tools
-- **Skills** — reusable behavioral profiles with system prompts, `{{variable}}` substitution, session config (model, temperature, token budget), install-time security scanning, version history, external discovery (skills.sh / GitHub), and runtime `skill` tool for model-driven skill activation
-- **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 (13 tabs) and the full REST API. Runtime settings (model, tools, rate limiting, health, judge, memory) are configurable via the admin Settings tab — no config file edits or restarts needed for most changes. See [docs/governance.md](docs/governance.md) for setup and [docs/settings.md](docs/settings.md) for the settings reference.
-
-### Intent Validation (LLM Judge)
-
-Every tool call that requires human approval is evaluated by an intent validation judge that provides a structured risk assessment alongside the approval prompt — so instead of "approve this bash command?", users see a verdict with risk level, confidence, recommendation, and reasoning.
-
-The system uses a two-tier evaluation pipeline:
-
-1. **Heuristic tier** (instant, free) — 36 pattern-based rules classify tool calls by severity. Catches destructive commands (`rm -rf /`, `DROP TABLE`), privilege escalation (`sudo`), credential access, supply chain risks, browser data export, cloud infrastructure mutations, and more. Results appear immediately.
-2. **LLM judge tier** (async) — A full LLM evaluation runs in the background with access to `read_file` and `list_directory` for evidence gathering. The judge can inspect files that a write would overwrite, check directory contents before a delete, and cite specific evidence in its reasoning. Results update the UI progressively when ready.
-
-The judge defaults to the same model as the session (self-consistency) but can be configured to use a separate model — useful when running a small local model for tasks but wanting a commercial model for safety evaluation.
-
-```toml
-[judge]
-enabled = true           # on by default
-model = ""               # empty = same as session model
-provider = ""            # empty = same as session provider
-timeout = 60.0           # generous for local models
-```
-
-Verdicts are persisted for audit and exposed via Prometheus metrics (`turnstone_judge_verdicts_total`, `turnstone_judge_llm_latency_seconds`).
-
-Skills are also scanned at install time — the scanner evaluates content, supply chain, vulnerability, and declared capability risk across four independent axes. Results populate `scan_status` (tier) and `scan_report` (structured JSON breakdown) on the skill record so administrators can assess risk before enabling a skill.
-
-Tool execution results are evaluated by an output guard before entering the conversation — detecting prompt injection payloads in fetched content, credential leakage in command output, and encoded payloads. Detected credentials are automatically redacted.
-
-See [docs/judge.md](docs/judge.md) for the full guide.
-
-## Multi-node routing
-
-Each Turnstone server runs a bridge process. Bridges share a Redis instance for coordination:
-
-| Redis Key | Purpose |
-|-----------|---------|
-| `turnstone:inbound` | Shared work queue — generic tasks, any node |
-| `turnstone:inbound:{node_id}` | Per-node queue — directed tasks |
-| `turnstone:ws:{ws_id}` | Workstream ownership — auto-routes follow-ups |
-| `turnstone:node:{node_id}` | Node heartbeat + metadata for discovery |
-| `turnstone:events:{ws_id}` | Per-workstream event pub/sub |
-| `turnstone:events:global` | Global event pub/sub |
-| `turnstone:events:cluster` | Cluster-wide state changes (for turnstone-console) |
-
-**Routing rules:**
-1. Message has `target_node` → routes to that node's queue
-2. Message has `ws_id` → looks up owner, routes to owning node
-3. Neither → shared queue, next available bridge picks it up
-
-Bridges BLPOP from their per-node queue (priority) then the shared queue. Directed work always takes precedence.
-
 ## Tools
 
-15 built-in tools, 2 agent tools, plus external tools via MCP:
+Built-in tools for shell, files, search, web, memory, notifications, and autonomous sub-agents — plus external tools via [MCP](https://modelcontextprotocol.io/) with native deferred loading. See [docs/tools.md](docs/tools.md) for the full reference and [docs/mcp-registry.md](docs/mcp-registry.md) for MCP configuration.
 
-| Tool | Description | Auto-approved |
-|------|-------------|:---:|
-| `bash` | Execute shell commands | |
-| `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 |
-| `math` | Sandboxed Python evaluation | |
-| `man` | Read man pages | yes |
-| `web_fetch` | Fetch URL content | |
-| `web_search` | Web search (provider-native or Tavily) | |
-| `memory` | Structured persistent memory (save/search/delete/list) | yes |
-| `recall` | Search conversation history | 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 | |
+## Architecture
 
-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).
+**Single-node**: Client → Server (direct HTTP + SSE). No external dependencies beyond the database.
 
-### MCP Tool Servers
+**Multi-node**: Client → Console (rendezvous routing proxy) → Server nodes. The console picks the target node for each workstream via rendezvous (HRW) hashing over the live service registry — pure function of `(ws_id, live_nodes)`, no stored bucket state, deterministic across readers. A node join or drop only re-routes the keys that score highest on the affected node.
 
-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`.
+| Component | Purpose |
+|-----------|---------|
+| `turnstone` | Terminal CLI (REPL) |
+| `turnstone-server` | Web UI + REST API + SSE events |
+| `turnstone-console` | Cluster dashboard + routing proxy + admin panel |
+| `turnstone-channel` | Channel gateway (Discord and Slack adapters) |
+| `turnstone-admin` | User/token management CLI |
+| `turnstone-eval` | Eval harness for prompt/tool optimization |
+| `turnstone-bootstrap` | LLM-guided setup wizard |
 
-Configure via `config.toml` or `--mcp-config`:
+### Diagrams
 
-```toml
-[mcp.servers.github]
-command = "npx"
-args = ["-y", "@modelcontextprotocol/server-github"]
+UML diagrams in [`docs/diagrams/`](docs/diagrams/):
 
-[mcp.servers.github.env]
-GITHUB_TOKEN = "ghp_..."
-```
+| Diagram | Description |
+|---------|-------------|
+| [System Context](docs/diagrams/png/01-system-context.png) | Components and external dependencies |
+| [Package Structure](docs/diagrams/png/02-package-structure.png) | Python modules and dependency graph |
+| [Core Engine](docs/diagrams/png/03-core-engine-classes.png) | SessionUI, ChatSession, LLMProvider |
+| [Conversation Turn](docs/diagrams/png/04-conversation-turn.png) | Message lifecycle through the engine |
+| [Tool Pipeline](docs/diagrams/png/05-tool-pipeline.png) | Prepare / approve / execute |
+| [Workstream States](docs/diagrams/png/09-workstream-states.png) | State machine transitions |
+| [Console Data Flow](docs/diagrams/png/11-console-data-flow.png) | Dashboard data collection |
+| [Deployment](docs/diagrams/png/12-deployment.png) | Docker Compose topology |
+| [Auth](docs/diagrams/png/15-auth-architecture.png) | JWT, scopes, login flows |
+| [Channels](docs/diagrams/png/16-channel-architecture.png) | Discord / Slack adapters + routing |
+| [Judge](docs/diagrams/png/22-judge-architecture.png) | Intent validation pipeline |
+| [OIDC](docs/diagrams/png/25-oidc-architecture.png) | SSO authorization code flow |
 
-Or use a standard MCP JSON config file:
+## Documentation
 
-```bash
-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 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
-
-Turnstone supports multiple model backends per server instance, including different LLM providers. `ChatSession` delegates all API communication to pluggable `LLMProvider` adapters — the internal message format stays OpenAI-like, and each provider translates at the API boundary. Define named models in `config.toml` and select per-workstream or switch mid-session with `/model <alias>`.
-
-```toml
-[models.local]
-base_url = "http://localhost:8000/v1"
-model = "qwen3-32b"
-# provider defaults to "openai" (works with vLLM, llama.cpp, etc.)
-
-[models.claude]
-provider = "anthropic"
-api_key = "sk-ant-..."
-model = "claude-opus-4-6"
-context_window = 200000
-
-[models.openai]
-base_url = "https://api.openai.com/v1"
-api_key = "sk-..."
-model = "gpt-5"
-context_window = 400000
-
-[model]
-default = "local"              # which model to use by default
-fallback = ["claude", "openai"]  # try these if the primary is unreachable
-agent_model = "claude"         # optional: separate model for plan/task sub-agents
-```
-
-Supported providers: `"openai"` (default -- OpenAI, vLLM, llama.cpp, any OpenAI-compatible API) and `"anthropic"` (Anthropic Messages API, requires `pip install turnstone[anthropic]`).
-
-Use `/model` to show available models, `/model claude` to switch. Workstreams created via the API accept an optional `model` parameter.
-
-## Configuration
-
-All entry points read `~/.config/turnstone/config.toml`. CLI flags override config values.
-
-```toml
-[api]
-base_url = "http://localhost:8000/v1"
-api_key = ""
-# tavily_key = ""      # only needed for local/vLLM models without native search
-
-[model]
-name = ""              # empty = auto-detect
-temperature = 0.5
-reasoning_effort = "medium"
-default = "default"    # model alias for new workstreams
-fallback = []          # ordered list of fallback model aliases
-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"
-port = 8080
-max_workstreams = 50       # auto-evicts oldest idle when full
-
-[redis]
-host = "localhost"
-port = 6379
-password = ""
-
-[bridge]
-server_url = "http://localhost:8080"
-node_id = ""           # empty = hostname_xxxx
-
-[console]
-host = "0.0.0.0"
-port = 8090
-url = "http://localhost:8090"  # used by CLI /cluster commands
-poll_interval = 10
-
-[health]
-backend_probe_interval = 30
-backend_probe_timeout = 5
-circuit_breaker_threshold = 5
-circuit_breaker_cooldown = 60
-
-[ratelimit]
-enabled = true
-requests_per_second = 10.0
-burst = 20
-
-[database]
-backend = "sqlite"     # "sqlite" (default) or "postgresql"
-path = ".turnstone.db" # SQLite file path (relative to working directory)
-# url = "postgresql+psycopg://user:pass@host:5432/turnstone"  # PostgreSQL
-# pool_size = 2        # PostgreSQL connection pool size (per process)
-
-[judge]
-enabled = true         # intent validation for tool approvals (--no-judge to disable)
-model = ""             # empty = same as session model (self-consistency)
-provider = ""          # empty = same as session provider
-timeout = 60.0         # LLM judge timeout in seconds
-confidence_threshold = 0.7
-
-[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"
-args = ["-y", "@modelcontextprotocol/server-example"]
-# type = "stdio"       # "stdio" (default) or "http"
-# url = ""             # for HTTP transport
-```
-
-Precedence: CLI args > environment variables > config.toml > defaults.
-
-## Workstreams
-
-Parallel independent conversations, each with its own session and state:
-
-| Symbol | State | Meaning |
-|--------|-------|---------|
-| `·` | idle | Waiting for input |
-| `◌` | thinking | Model is generating |
-| `▸` | running | Tool execution in progress |
-| `◆` | attention | Waiting for approval |
-| `✖` | error | Something went wrong |
-
-Idle workstreams are automatically cleaned up after 2 hours (configurable). In multi-node deployments, workstream ownership is tracked in Redis — follow-up messages auto-route to the owning node.
-
-## Monitoring
-
-`/metrics` endpoint exposes Prometheus-format metrics:
-
-- `turnstone_tokens_total{direction}` — prompt/completion token counters
-- `turnstone_tool_calls_total{tool}` — per-tool invocation counts
-- `turnstone_workstream_context_ratio{ws_id}` — per-workstream context utilization
-- `turnstone_http_request_duration_seconds` — request latency histogram
-- `turnstone_workstreams_by_state{state}` — workstream state gauges
-- `turnstone_sse_connections_active` — current open SSE connections
-- `turnstone_ratelimit_rejected_total` — requests rejected by rate limiter
-- `turnstone_backend_up` — LLM backend reachability (0/1)
-- `turnstone_circuit_state` — circuit breaker state (0=closed, 1=open, 2=half_open)
-- `turnstone_workstreams_evicted_total` — workstreams auto-evicted at capacity
-- `turnstone_judge_verdicts_total{tier,risk_level}` — intent validation verdicts by tier and risk
-- `turnstone_judge_llm_latency_seconds` — LLM judge evaluation latency histogram
-- `turnstone_judge_enabled` — whether the intent validation judge is active (0/1)
-
-Per-workstream metrics are labeled by `ws_id` (bounded by `[server].max_workstreams`).
-
-### Health & Rate Limiting
-
-**Health degradation.** A background `BackendHealthMonitor` probes the LLM backend every `backend_probe_interval` seconds. When the backend is unreachable, `/health` reports `"status": "degraded"` (HTTP 200) and the `turnstone_backend_up` gauge drops to 0.
-
-**Circuit breaker.** After `circuit_breaker_threshold` consecutive probe failures the circuit opens (CLOSED -> OPEN). While open, `ChatSession._create_stream_with_retry` skips the backend entirely and returns an error. After `circuit_breaker_cooldown` seconds the circuit enters HALF_OPEN, allowing a single probe. A successful probe closes the circuit; a failure re-opens it.
-
-**Per-IP rate limiting.** When `[ratelimit].enabled` is true, each client IP is tracked with a token-bucket limiter (`requests_per_second` / `burst`). Rate limiting is applied in `do_GET`/`do_POST` after authentication but before route dispatch. `/health` and `/metrics` are exempt. Requests that exceed the limit receive HTTP 429 with a `Retry-After` header.
-
-**Workstream eviction.** When `WorkstreamManager.create()` would exceed `max_workstreams`, the oldest IDLE workstream is automatically evicted and the `turnstone_workstreams_evicted_total` counter is incremented. Configure via `[server].max_workstreams` (default 50).
+| Topic | Link |
+|-------|------|
+| Configuration reference | [docs/settings.md](docs/settings.md) |
+| API reference | [docs/api-reference.md](docs/api-reference.md) |
+| Docker deployment | [docs/docker.md](docs/docker.md) |
+| Intent validation (judge) | [docs/judge.md](docs/judge.md) |
+| Governance & RBAC | [docs/governance.md](docs/governance.md) |
+| OIDC SSO | [docs/oidc.md](docs/oidc.md) |
+| TLS / mTLS | [docs/tls.md](docs/tls.md) |
+| Channel integrations | [docs/channels.md](docs/channels.md) |
+| Console dashboard | [docs/console.md](docs/console.md) |
+| Eval harness | [docs/eval.md](docs/eval.md) |
+| Tools reference | [docs/tools.md](docs/tools.md) |
+| MCP integration | [docs/mcp-registry.md](docs/mcp-registry.md) |
 
 ## Requirements
 
 - Python 3.11+
-- An OpenAI-compatible API endpoint ([vLLM](https://github.com/vllm-project/vllm), [NVIDIA NIM](https://build.nvidia.com/), [llama.cpp](https://github.com/ggml-org/llama.cpp), etc.) or an Anthropic API key
-- Redis (for message queue bridge — `pip install turnstone[mq]`)
-- Anthropic provider (optional — `pip install turnstone[anthropic]`)
-- PostgreSQL (optional, for production — `pip install turnstone[postgres]`)
-- Math sandbox packages (optional — `pip install turnstone[sandbox]` for sympy, numpy, scipy, pytest)
-- [Git LFS](https://git-lfs.com/) (for cloning — diagram PNGs are stored in LFS)
+- An OpenAI-compatible API endpoint, Anthropic API key, or Google Gemini API key
+- Optional: PostgreSQL (`pip install turnstone[postgres]`), Anthropic (`pip install turnstone[anthropic]`)
+- [Git LFS](https://git-lfs.com/) for cloning (diagram PNGs)
 
 ## License
 

THIRD-PARTY-NOTICES

@@ -95,3 +95,22 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+================================================================================
+
+hls.js 1.6.15
+https://github.com/video-dev/hls.js
+
+Copyright 2017 Dailymotion
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

deploy/docker-compose.bare-metal.yml

@@ -0,0 +1,40 @@
+# Bare-metal overlay — expose PostgreSQL and let the console reach
+# a turnstone-server running outside Docker on the host machine.
+#
+# Requires TURNSTONE_HOST_IP set to the host's routable IP address.
+#
+# Usage:
+#   export TURNSTONE_HOST_IP="$(hostname -I | awk '{print $1}')"
+#   docker compose --profile production \
+#     -f compose.yaml -f deploy/docker-compose.bare-metal.yml up
+#
+# Then on the host:
+#   export TURNSTONE_JWT_SECRET="<same as .env>"
+#   export TURNSTONE_DB_BACKEND=postgresql
+#   export TURNSTONE_DB_URL="postgresql://turnstone:<pw>@localhost:5432/turnstone"
+#   export TURNSTONE_NODE_ID="bare-metal-1"
+#   export TURNSTONE_ADVERTISE_URL="http://${TURNSTONE_HOST_IP}:8080"
+#   python -m turnstone.server --host 0.0.0.0 --port 8080 \
+#     --base-url http://localhost:8000/v1 --api-key "$OPENAI_API_KEY"
+
+services:
+  postgres:
+    ports:
+      - "${POSTGRES_PORT:-5432}:5432"
+
+  console:
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    environment:
+      # Console needs to reach the bare-metal server on the host
+      TURNSTONE_SERVER_URL: "http://${TURNSTONE_HOST_IP}:${SERVER_PORT:-8080}"
+
+  channel:
+    ports:
+      - "${CHANNEL_PORT:-8091}:8091"
+    environment:
+      # Channel gateway advertises with host-routable IP so the
+      # bare-metal server can reach it for schedule notifications
+      TURNSTONE_CHANNEL_ADVERTISE_URL: "http://${TURNSTONE_HOST_IP}:${CHANNEL_PORT:-8091}"
+      # Channel needs to reach the bare-metal server on the host
+      TURNSTONE_SERVER_URL: "http://${TURNSTONE_HOST_IP}:${SERVER_PORT:-8080}"

deploy/docker-compose.tls.yml

@@ -3,12 +3,12 @@
 # Usage (requires base compose.yaml with production profile):
 #   docker compose -f compose.yaml -f deploy/docker-compose.tls.yml --profile production up
 #
-# The tls-init service bootstraps a CA and issues a cert for Redis.
+# The tls-init service bootstraps a CA and issues certs.
 # All turnstone services auto-provision their own certs via the
 # console's ACME endpoint.
 
 services:
-  # Bootstrap: create CA + Redis cert before anything starts.
+  # Bootstrap: create CA before anything starts.
   # Runs as root to create directories in the volume, then chowns
   # to turnstone:turnstone with restrictive perms (keys 0600).
   tls-init:
@@ -19,7 +19,7 @@ services:
       - -c
       - |
         set -e
-        turnstone-admin tls-bootstrap --out /certs --issue redis
+        turnstone-admin tls-bootstrap --out /certs
         chown -R turnstone:turnstone /certs
         find /certs -type d -exec chmod 750 {} +
         find /certs -type f -name '*key.pem' -exec chmod 600 {} +
@@ -45,11 +45,7 @@ services:
       - turnstone-console
       - --host=0.0.0.0
       - --port=8090
-      - --redis-host=redis
-      - --redis-port=6379
       - --poll-interval=${CONSOLE_POLL_INTERVAL:-10}
-      - --redis-tls
-      - --redis-tls-ca=/certs/ca.pem
 
   # Server: auto-provisions certs via console ACME, serves HTTPS
   server:
@@ -64,41 +60,14 @@ services:
     # Disable healthcheck — server serves HTTPS with mTLS which the
     # stdlib healthcheck script can't satisfy. The base compose
     # healthcheck uses plain HTTP which won't work on an HTTPS listener.
-    # TODO: wire healthcheck with client cert from /certs volume
     healthcheck:
       disable: true
 
-  # Bridge: mTLS to server + Redis TLS
-  bridge:
-    depends_on:
-      console:
-        condition: service_healthy
-      server:
-        condition: service_started
-      redis:
-        condition: service_healthy
-    volumes:
-      - tls-certs:/certs:ro
-    environment:
-      TURNSTONE_TLS_ENABLED: "true"
-      TURNSTONE_TLS_SANS: "bridge"
-    command:
-      - turnstone-bridge
-      - --server-url=http://server:8080
-      - --redis-host=redis
-      - --redis-port=6379
-      - --heartbeat-ttl=${HEARTBEAT_TTL:-60}
-      - --approval-timeout=${APPROVAL_TIMEOUT:-3600}
-      - --redis-tls
-      - --redis-tls-ca=/certs/ca.pem
-
-  # Channel: Redis TLS
+  # Channel: TLS
   channel:
     depends_on:
       console:
         condition: service_healthy
-      redis:
-        condition: service_healthy
     volumes:
       - tls-certs:/certs:ro
     environment:
@@ -109,38 +78,8 @@ services:
       - -c
       - >-
         turnstone-channel
-        --redis-host=redis
-        --redis-port=6379
-        --redis-tls
-        --redis-tls-ca=/certs/ca.pem
         --http-host=0.0.0.0
         $${TURNSTONE_DISCORD_GUILD:+--discord-guild $$TURNSTONE_DISCORD_GUILD}
 
-  # Redis: TLS with certs from bootstrap
-  redis:
-    depends_on:
-      tls-init:
-        condition: service_completed_successfully
-    volumes:
-      - tls-certs:/certs:ro
-    command:
-      - sh
-      - -c
-      - |
-        ARGS="--tls-port 6379 --port 0 \
-          --tls-cert-file /certs/certs/redis/cert.pem \
-          --tls-key-file /certs/certs/redis/key.pem \
-          --tls-ca-cert-file /certs/ca.pem \
-          --tls-auth-clients no"
-        if [ -n "$$REDIS_PASSWORD" ]; then
-          ARGS="$$ARGS --requirepass $$REDIS_PASSWORD"
-        fi
-        exec redis-server $$ARGS
-    healthcheck:
-      test: ["CMD-SHELL", "if [ -n \"$$REDIS_PASSWORD\" ]; then redis-cli --tls --cacert /certs/ca.pem -a $$REDIS_PASSWORD ping; else redis-cli --tls --cacert /certs/ca.pem ping; fi"]
-      interval: 5s
-      timeout: 3s
-      retries: 5
-
 volumes:
   tls-certs:

deploy/helm/turnstone/Chart.yaml

@@ -10,7 +10,3 @@ dependencies:
     version: ~18.5.0
     repository: https://charts.bitnami.com/bitnami
     condition: postgresql.enabled
-  - name: redis
-    version: ~25.3.0
-    repository: https://charts.bitnami.com/bitnami
-    condition: redis.enabled

deploy/helm/turnstone/templates/NOTES.txt

@@ -25,14 +25,10 @@ Then open: http://localhost:{{ .Values.console.service.port }}
 
 Components deployed:
   - Server:  {{ include "turnstone.fullname" . }}-server  ({{ .Values.server.replicas }} replica(s))
-  - Bridge:  {{ include "turnstone.fullname" . }}-bridge  ({{ .Values.bridge.replicas }} replica(s))
   - Console: {{ include "turnstone.fullname" . }}-console ({{ .Values.console.replicas }} replica(s))
 {{- if .Values.postgresql.enabled }}
   - PostgreSQL (bitnami subchart)
 {{- end }}
-{{- if .Values.redis.enabled }}
-  - Redis (bitnami subchart)
-{{- end }}
 
 {{- if not .Values.llm.apiKey }}
 {{- if not .Values.llm.existingSecret }}

deploy/helm/turnstone/templates/_helpers.tpl

@@ -110,28 +110,6 @@ Determine the PostgreSQL username.
 {{- end }}
 {{- end }}
 
-{{/*
-Determine the Redis host.
-*/}}
-{{- define "turnstone.redis.host" -}}
-{{- if .Values.redis.enabled }}
-{{- printf "%s-redis-master" .Release.Name }}
-{{- else }}
-{{- .Values.redis.external.host }}
-{{- end }}
-{{- end }}
-
-{{/*
-Determine the Redis port.
-*/}}
-{{- define "turnstone.redis.port" -}}
-{{- if .Values.redis.enabled }}
-{{- printf "6379" }}
-{{- else }}
-{{- .Values.redis.external.port | toString }}
-{{- end }}
-{{- end }}
-
 {{/*
 Determine the secret name for LLM API keys.
 */}}

deploy/helm/turnstone/templates/configmap.yaml

@@ -14,8 +14,6 @@ data:
   TURNSTONE_SERVER_PORT: {{ .Values.server.service.port | quote }}
   TURNSTONE_CONSOLE_HOST: "0.0.0.0"
   TURNSTONE_CONSOLE_PORT: {{ .Values.console.service.port | quote }}
-  TURNSTONE_REDIS_HOST: {{ include "turnstone.redis.host" . | quote }}
-  TURNSTONE_REDIS_PORT: {{ include "turnstone.redis.port" . | quote }}
   TURNSTONE_POLL_INTERVAL: "5"
   {{- if .Values.llm.baseUrl }}
   TURNSTONE_LLM_BASE_URL: {{ .Values.llm.baseUrl | quote }}

deploy/helm/turnstone/templates/deployment-bridge.yaml

@@ -1,45 +0,0 @@
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  name: {{ include "turnstone.fullname" . }}-bridge
-  labels:
-    {{- include "turnstone.labels" . | nindent 4 }}
-    app.kubernetes.io/component: bridge
-spec:
-  replicas: {{ .Values.bridge.replicas }}
-  selector:
-    matchLabels:
-      {{- include "turnstone.selectorLabels" . | nindent 6 }}
-      app.kubernetes.io/component: bridge
-  template:
-    metadata:
-      labels:
-        {{- include "turnstone.selectorLabels" . | nindent 8 }}
-        app.kubernetes.io/component: bridge
-    spec:
-      serviceAccountName: {{ include "turnstone.serviceAccountName" . }}
-      containers:
-        - name: bridge
-          image: {{ include "turnstone.image" . }}
-          imagePullPolicy: {{ .Values.image.pullPolicy }}
-          command:
-            - turnstone-bridge
-            - --server-url={{ printf "http://%s-server:%s" (include "turnstone.fullname" .) (.Values.server.service.port | toString) }}
-            - --redis-host={{ include "turnstone.redis.host" . }}
-            - --redis-port={{ include "turnstone.redis.port" . }}
-          envFrom:
-            - configMapRef:
-                name: {{ include "turnstone.fullname" . }}-config
-            - secretRef:
-                name: {{ include "turnstone.llm.secretName" . }}
-                optional: true
-          {{- if and .Values.auth.enabled .Values.auth.existingSecret }}
-          env:
-            - name: TURNSTONE_AUTH_TOKEN
-              valueFrom:
-                secretKeyRef:
-                  name: {{ .Values.auth.existingSecret }}
-                  key: TURNSTONE_AUTH_TOKEN
-          {{- end }}
-          resources:
-            {{- toYaml .Values.bridge.resources | nindent 12 }}

deploy/helm/turnstone/templates/deployment-console.yaml

@@ -26,8 +26,6 @@ spec:
             - turnstone-console
             - --host=0.0.0.0
             - --port={{ .Values.console.service.port }}
-            - --redis-host={{ include "turnstone.redis.host" . }}
-            - --redis-port={{ include "turnstone.redis.port" . }}
           ports:
             - name: http
               containerPort: {{ .Values.console.service.port }}
@@ -38,13 +36,13 @@ spec:
             - secretRef:
                 name: {{ include "turnstone.llm.secretName" . }}
                 optional: true
-          {{- if and .Values.auth.enabled .Values.auth.existingSecret }}
+          {{- if or .Values.auth.existingSecret .Values.auth.jwtSecret }}
           env:
-            - name: TURNSTONE_AUTH_TOKEN
+            - name: TURNSTONE_JWT_SECRET
               valueFrom:
                 secretKeyRef:
-                  name: {{ .Values.auth.existingSecret }}
-                  key: TURNSTONE_AUTH_TOKEN
+                  name: {{ include "turnstone.auth.secretName" . }}
+                  key: TURNSTONE_JWT_SECRET
           {{- end }}
           readinessProbe:
             httpGet:

deploy/helm/turnstone/templates/deployment-server.yaml

@@ -41,12 +41,12 @@ spec:
           env:
             - name: TURNSTONE_DB_URL
               value: "postgresql+psycopg://$(TURNSTONE_DB_USER):$(POSTGRES_PASSWORD)@$(TURNSTONE_DB_HOST):$(TURNSTONE_DB_PORT)/$(TURNSTONE_DB_NAME)"
-          {{- if and .Values.auth.enabled .Values.auth.existingSecret }}
-            - name: TURNSTONE_AUTH_TOKEN
+          {{- if or .Values.auth.existingSecret .Values.auth.jwtSecret }}
+            - name: TURNSTONE_JWT_SECRET
               valueFrom:
                 secretKeyRef:
-                  name: {{ .Values.auth.existingSecret }}
-                  key: TURNSTONE_AUTH_TOKEN
+                  name: {{ include "turnstone.auth.secretName" . }}
+                  key: TURNSTONE_JWT_SECRET
           {{- end }}
           readinessProbe:
             httpGet:

deploy/helm/turnstone/templates/secret.yaml

@@ -15,14 +15,7 @@ data:
   {{- else if and (not .Values.postgresql.enabled) .Values.database.external.password }}
   POSTGRES_PASSWORD: {{ .Values.database.external.password | b64enc | quote }}
   {{- end }}
-  {{- if and .Values.auth.enabled .Values.auth.token (not .Values.auth.existingSecret) }}
-  TURNSTONE_AUTH_TOKEN: {{ .Values.auth.token | b64enc | quote }}
-  {{- end }}
-  {{- if and .Values.redis.enabled .Values.redis.auth }}
-  {{- if .Values.redis.auth.password }}
-  REDIS_PASSWORD: {{ .Values.redis.auth.password | b64enc | quote }}
-  {{- end }}
-  {{- else if and (not .Values.redis.enabled) .Values.redis.external.password }}
-  REDIS_PASSWORD: {{ .Values.redis.external.password | b64enc | quote }}
+  {{- if and .Values.auth.jwtSecret (not .Values.auth.existingSecret) }}
+  TURNSTONE_JWT_SECRET: {{ .Values.auth.jwtSecret | b64enc | quote }}
   {{- end }}
 {{- end }}

deploy/helm/turnstone/values.yaml

@@ -24,16 +24,6 @@ postgresql:
     database: turnstone
     username: turnstone
 
-# -- Redis configuration
-redis:
-  enabled: true
-  architecture: standalone
-  # External Redis settings (used when redis.enabled is false)
-  external:
-    host: ""
-    port: 6379
-    existingSecret: ""
-
 # -- Turnstone server (main API + web UI)
 server:
   replicas: 1
@@ -48,17 +38,6 @@ server:
     type: ClusterIP
     port: 8080
 
-# -- Turnstone bridge (Redis MQ connector)
-bridge:
-  replicas: 1
-  resources:
-    requests:
-      cpu: 250m
-      memory: 256Mi
-    limits:
-      cpu: "1"
-      memory: 512Mi
-
 # -- Turnstone console (cluster dashboard)
 console:
   replicas: 1
@@ -80,10 +59,9 @@ llm:
   apiKey: ""
   existingSecret: ""
 
-# -- Authentication
+# -- Authentication (always enabled, JWT secret required)
 auth:
-  enabled: false
-  token: ""
+  jwtSecret: ""
   existingSecret: ""
 
 # -- Ingress configuration

deploy/openshell/turnstone-policy.yaml

@@ -1,8 +1,8 @@
 # OpenShell sandbox policy for Turnstone AI orchestration platform.
 #
 # This policy wraps a turnstone-server process (the primary sandbox target).
-# The bridge, console, and channel gateway are separate processes that would
-# each need their own sandbox with a tailored policy variant.
+# The console and channel gateway are separate processes that would each
+# need their own sandbox with a tailored policy variant.
 #
 # Usage:
 #   openshell sandbox run \
@@ -23,7 +23,6 @@
 #
 # Customization points (search for "CUSTOMIZE"):
 #   - OIDC issuer endpoint
-#   - Redis host/port (if not localhost)
 #   - MCP HTTP server endpoints
 #   - Additional tool binaries
 #   - web_fetch domain allowlist
@@ -166,20 +165,6 @@ network_policies:
   #     - path: /usr/bin/python3*
   #     - path: /usr/local/bin/python3*
 
-  # --- Redis (MQ) ---
-  # CUSTOMIZE: if Redis is not on localhost, add host + allowed_ips.
-  # localhost is blocked by default SSRF protection, so we need allowed_ips.
-
-  redis:
-    name: redis-mq
-    endpoints:
-      - port: 6379
-        allowed_ips:
-          - "127.0.0.1"
-    binaries:
-      - path: /usr/bin/python3*
-      - path: /usr/local/bin/python3*
-
   # --- Discord (channel integration) ---
   # Uncomment if using turnstone-channel with Discord adapter.
 

deploy/terraform/examples/aws-ecs-basic/outputs.tf

@@ -22,8 +22,3 @@ output "rds_endpoint" {
   description = "RDS PostgreSQL endpoint."
   value       = module.turnstone.rds_endpoint
 }
-
-output "redis_endpoint" {
-  description = "ElastiCache Redis endpoint."
-  value       = module.turnstone.redis_endpoint
-}

deploy/terraform/examples/aws-ecs-basic/variables.tf

@@ -10,7 +10,7 @@ variable "vpc_id" {
 }
 
 variable "private_subnet_ids" {
-  description = "List of private subnet IDs for ECS tasks, RDS, and ElastiCache."
+  description = "List of private subnet IDs for ECS tasks and RDS."
   type        = list(string)
 }
 

deploy/terraform/modules/aws-ecs/elasticache.tf

@@ -1,30 +0,0 @@
-# ---------- ElastiCache Subnet Group ----------
-
-resource "aws_elasticache_subnet_group" "this" {
-  name       = "${var.name_prefix}-${var.environment}"
-  subnet_ids = var.private_subnet_ids
-  tags       = local.common_tags
-}
-
-# ---------- ElastiCache Redis Replication Group ----------
-
-resource "aws_elasticache_replication_group" "this" {
-  replication_group_id = "${var.name_prefix}-${var.environment}"
-  description          = "Turnstone Redis for MQ and session state"
-
-  engine               = "redis"
-  engine_version       = "7.1"
-  node_type            = var.redis_node_type
-  num_cache_clusters   = 1
-  port                 = 6379
-
-  subnet_group_name  = aws_elasticache_subnet_group.this.name
-  security_group_ids = [aws_security_group.redis.id]
-
-  at_rest_encryption_enabled = true
-  transit_encryption_enabled = true
-
-  automatic_failover_enabled = false
-
-  tags = local.common_tags
-}

deploy/terraform/modules/aws-ecs/iam.tf

@@ -40,8 +40,8 @@ resource "aws_iam_role_policy" "ecs_execution_secrets" {
           [
             aws_secretsmanager_secret.openai_api_key.arn,
             aws_secretsmanager_secret.db_password.arn,
+            aws_secretsmanager_secret.jwt_secret.arn,
           ],
-          var.auth_token != "" ? [aws_secretsmanager_secret.auth_token[0].arn] : [],
         )
       },
     ]

deploy/terraform/modules/aws-ecs/main.tf

@@ -27,7 +27,6 @@ locals {
     { name = "TURNSTONE_ENV", value = var.environment },
     { name = "TURNSTONE_DB_BACKEND", value = "postgresql" },
     { name = "TURNSTONE_LLM_BASE_URL", value = var.llm_base_url },
-    { name = "TURNSTONE_REDIS_URL", value = "redis://${aws_elasticache_replication_group.this.primary_endpoint_address}:6379/0" },
   ]
 
   # Secrets pulled from Secrets Manager at container start.
@@ -42,20 +41,26 @@ locals {
     },
   ]
 
-  auth_env = var.auth_token != "" ? [
-    { name = "TURNSTONE_AUTH_ENABLED", value = "true" },
-  ] : []
-
-  auth_secrets = var.auth_token != "" ? [
+  auth_secrets = [
     {
-      name      = "TURNSTONE_AUTH_TOKEN"
-      valueFrom = aws_secretsmanager_secret_version.auth_token[0].arn
+      name      = "TURNSTONE_JWT_SECRET"
+      valueFrom = aws_secretsmanager_secret_version.jwt_secret.arn
     },
-  ] : []
+  ]
 }
 
 # ---------- Secrets Manager ----------
 
+resource "aws_secretsmanager_secret" "jwt_secret" {
+  name = "${var.name_prefix}-${var.environment}-jwt-secret"
+  tags = local.common_tags
+}
+
+resource "aws_secretsmanager_secret_version" "jwt_secret" {
+  secret_id     = aws_secretsmanager_secret.jwt_secret.id
+  secret_string = var.jwt_secret
+}
+
 resource "aws_secretsmanager_secret" "openai_api_key" {
   name = "${var.name_prefix}-${var.environment}-openai-api-key"
   tags = local.common_tags
@@ -66,17 +71,7 @@ resource "aws_secretsmanager_secret_version" "openai_api_key" {
   secret_string = var.openai_api_key
 }
 
-resource "aws_secretsmanager_secret" "auth_token" {
-  count = var.auth_token != "" ? 1 : 0
-  name  = "${var.name_prefix}-${var.environment}-auth-token"
-  tags  = local.common_tags
-}
 
-resource "aws_secretsmanager_secret_version" "auth_token" {
-  count         = var.auth_token != "" ? 1 : 0
-  secret_id     = aws_secretsmanager_secret.auth_token[0].id
-  secret_string = var.auth_token
-}
 
 resource "aws_secretsmanager_secret" "db_password" {
   name = "${var.name_prefix}-${var.environment}-db-password"
@@ -141,7 +136,7 @@ resource "aws_ecs_task_definition" "server" {
         { containerPort = 8080, protocol = "tcp" },
       ]
 
-      environment = concat(local.common_env, local.auth_env)
+      environment = local.common_env
       secrets     = concat(local.common_secrets, local.auth_secrets)
 
       logConfiguration = {
@@ -187,57 +182,6 @@ resource "aws_ecs_service" "server" {
   depends_on = [aws_lb_target_group.server]
 }
 
-# ---------- Bridge Task Definition + Service ----------
-
-resource "aws_ecs_task_definition" "bridge" {
-  family                   = "${var.name_prefix}-bridge"
-  requires_compatibilities = ["FARGATE"]
-  network_mode             = "awsvpc"
-  cpu                      = var.bridge_cpu
-  memory                   = var.bridge_memory
-  execution_role_arn       = aws_iam_role.ecs_execution.arn
-  task_role_arn            = aws_iam_role.ecs_task.arn
-  tags                     = local.common_tags
-
-  container_definitions = jsonencode([
-    {
-      name      = "bridge"
-      image     = local.full_image
-      essential = true
-      command   = ["turnstone-bridge"]
-
-      environment = concat(local.common_env, local.auth_env)
-      secrets     = concat(local.common_secrets, local.auth_secrets)
-
-      logConfiguration = {
-        logDriver = "awslogs"
-        options = {
-          "awslogs-group"         = aws_cloudwatch_log_group.this.name
-          "awslogs-region"        = data.aws_region.current.name
-          "awslogs-stream-prefix" = "bridge"
-        }
-      }
-    },
-  ])
-}
-
-resource "aws_ecs_service" "bridge" {
-  name            = "${var.name_prefix}-bridge"
-  cluster         = aws_ecs_cluster.this.id
-  task_definition = aws_ecs_task_definition.bridge.arn
-  desired_count   = 1
-  launch_type     = "FARGATE"
-  tags            = local.common_tags
-
-  network_configuration {
-    subnets          = var.private_subnet_ids
-    security_groups  = [aws_security_group.ecs_tasks.id]
-    assign_public_ip = false
-  }
-
-  depends_on = [aws_ecs_service.server]
-}
-
 # ---------- Console Task Definition + Service ----------
 
 resource "aws_ecs_task_definition" "console" {
@@ -261,7 +205,7 @@ resource "aws_ecs_task_definition" "console" {
         { containerPort = 8090, protocol = "tcp" },
       ]
 
-      environment = concat(local.common_env, local.auth_env)
+      environment = local.common_env
       secrets     = concat(local.common_secrets, local.auth_secrets)
 
       logConfiguration = {

deploy/terraform/modules/aws-ecs/outputs.tf

@@ -22,8 +22,3 @@ output "rds_endpoint" {
   description = "Endpoint of the RDS PostgreSQL instance (host:port)."
   value       = aws_db_instance.this.endpoint
 }
-
-output "redis_endpoint" {
-  description = "Primary endpoint of the ElastiCache Redis replication group."
-  value       = aws_elasticache_replication_group.this.primary_endpoint_address
-}

deploy/terraform/modules/aws-ecs/security.tf

@@ -112,22 +112,3 @@ resource "aws_vpc_security_group_ingress_rule" "rds_from_ecs" {
   referenced_security_group_id = aws_security_group.ecs_tasks.id
   tags                         = local.common_tags
 }
-
-# ---------- Redis Security Group ----------
-
-resource "aws_security_group" "redis" {
-  name        = "${var.name_prefix}-redis-${var.environment}"
-  description = "Allow Redis access from ECS tasks"
-  vpc_id      = var.vpc_id
-  tags        = local.common_tags
-}
-
-resource "aws_vpc_security_group_ingress_rule" "redis_from_ecs" {
-  security_group_id            = aws_security_group.redis.id
-  description                  = "Redis from ECS tasks"
-  from_port                    = 6379
-  to_port                      = 6379
-  ip_protocol                  = "tcp"
-  referenced_security_group_id = aws_security_group.ecs_tasks.id
-  tags                         = local.common_tags
-}

deploy/terraform/modules/aws-ecs/variables.tf

@@ -6,7 +6,7 @@ variable "vpc_id" {
 }
 
 variable "private_subnet_ids" {
-  description = "List of private subnet IDs for ECS tasks, RDS, and ElastiCache."
+  description = "List of private subnet IDs for ECS tasks and RDS."
   type        = list(string)
 }
 
@@ -50,14 +50,6 @@ variable "db_instance_class" {
   default     = "db.t4g.micro"
 }
 
-# --- ElastiCache ---
-
-variable "redis_node_type" {
-  description = "ElastiCache node type for Redis."
-  type        = string
-  default     = "cache.t4g.micro"
-}
-
 # --- ECS Task Sizing ---
 
 variable "server_cpu" {
@@ -72,18 +64,6 @@ variable "server_memory" {
   default     = 1024
 }
 
-variable "bridge_cpu" {
-  description = "CPU units for the bridge task."
-  type        = number
-  default     = 256
-}
-
-variable "bridge_memory" {
-  description = "Memory (MiB) for the bridge task."
-  type        = number
-  default     = 512
-}
-
 variable "console_cpu" {
   description = "CPU units for the console task."
   type        = number
@@ -110,11 +90,10 @@ variable "name_prefix" {
   default     = "turnstone"
 }
 
-variable "auth_token" {
-  description = "Optional authentication token for the Turnstone API. Empty string disables auth."
+variable "jwt_secret" {
+  description = "JWT signing secret for Turnstone auth (required, min 32 characters)."
   type        = string
   sensitive   = true
-  default     = ""
 }
 
 variable "certificate_arn" {

docker/mcp-ddg.json

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

docs/api-reference.md

@@ -2,8 +2,6 @@
 
 ## Overview
 
-> See also: [MQ Protocol diagram](diagrams/png/06-mq-protocol.png) | [Message Routing diagram](diagrams/png/07-message-routing.png) | [Redis Key Schema diagram](diagrams/png/08-redis-key-schema.png)
-
 `turnstone-server` exposes a browser-based chat UI backed by a
 **Starlette** ASGI application served by **uvicorn**. The server uses
 **Server-Sent Events (SSE)** via `sse-starlette` for real-time streaming
@@ -58,7 +56,7 @@ console.log(result.content);
 
 ## Authentication
 
-When auth is enabled (`[auth].enabled = true` or `TURNSTONE_AUTH_ENABLED=1`), all API endpoints except public paths require a valid token.
+Auth is always enabled. All API endpoints except public paths require a valid token.
 
 ### Sending Credentials
 
@@ -67,15 +65,14 @@ Include a token in one of two ways:
 - **Bearer header**: `Authorization: Bearer <token>`
 - **Cookie**: `turnstone_auth=<token>` (set automatically by the login endpoint)
 
-The server accepts three token types:
+The server accepts two token types:
 
 | Type | Format | Example |
 |------|--------|---------|
 | JWT | Base64 segments separated by dots | `eyJhbG...` |
 | API token | `ts_` prefix + 64 hex chars | `ts_a1b2c3d4...` |
-| Config token | Arbitrary string from `config.toml` | `my-secret-token` |
 
-JWTs are the recommended credential for browser sessions. API tokens are suitable for programmatic access and CI/CD. Config tokens are a simple option for single-node deployments.
+JWTs are the recommended credential for browser sessions. API tokens are suitable for programmatic access and CI/CD.
 
 ### `POST /v1/api/auth/login`
 
@@ -523,7 +520,7 @@ inactivity.
 
 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
+so multiple consumers (browser, 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.
 
@@ -845,6 +842,15 @@ button automatically.
 
 Creates a new workstream. The server supports up to 10 concurrent workstreams.
 
+The endpoint accepts **either** `application/json` (legacy shape) **or**
+`multipart/form-data` when you want to upload attachments at creation
+time.  Multipart requests carry one `meta` field containing the JSON body
+shown below plus zero-or-more `file` parts; each file is validated and
+reserved onto the new workstream's first turn before the dispatch worker
+runs, so queued multimodal turns cannot lose files to racing sends.  If
+validation fails the fresh workstream is rolled back so no orphan rows
+leak.
+
 **Request body:**
 
 ```json
@@ -860,6 +866,7 @@ All fields are optional. The body can be empty or an empty JSON object.
 | `auto_approve`   | bool   | false   | Auto-approve all tool calls for this workstream                |
 | `resume_ws`      | string | ""      | Workstream ID to resume atomically during creation (empty = fresh)|
 | `skill`          | string | ""      | Skill name. Applies content (system prompt), model, temperature, reasoning effort, max tokens, auto-approve policy, token budget, and other session config from the skill. Returns 400 if not found or disabled. Ignored when `resume_ws` is set (resumed sessions restore their own skill). |
+| `judge_model`    | string | ""      | Optional model alias for the judge (overrides default judge model for this workstream) |
 
 > **Skill behavior:** When `skill` is specified, the skill's content is injected as a system message and its session config fields (model, temperature, auto-approve, token budget, etc.) override system defaults for the new workstream.
 
@@ -917,6 +924,255 @@ Status code: `400`
 
 ---
 
+### `POST /v1/api/workstreams/{ws_id}/attachments`
+
+Upload an image or text document and attach it to the caller's next user
+turn on this workstream.
+
+- Images (png/jpeg/gif/webp) are capped at **4 MiB** and validated via
+  magic-byte sniff on upload.
+- Text documents (any `text/*` MIME, allow-listed application MIMEs, or
+  known text extensions) are capped at **512 KiB** and must be UTF-8.
+- Per-(workstream, user) pending cap is **10** attachments.
+
+The attachment moves through three states: `pending → reserved →
+consumed`.  Reservation tokens are threaded through
+`POST /v1/api/send` so a queued multimodal turn cannot lose its file to
+an overlapping send.
+
+Ownership failures are masked as `404` so non-owners cannot enumerate
+workstream existence.
+
+**Content-Type:** `multipart/form-data` with a single `file` field.
+
+**Response (success):** `200`
+
+```json
+{
+  "attachment_id": "att_abc123",
+  "kind": "image",
+  "mime_type": "image/png",
+  "size_bytes": 73240,
+  "filename": "screenshot.png",
+  "state": "pending"
+}
+```
+
+**Errors:**
+
+| Code | Meaning                                                 |
+|------|---------------------------------------------------------|
+| 400  | Missing/invalid form, unsupported MIME, not UTF-8, etc. |
+| 403  | Auth/scope failure                                      |
+| 404  | Workstream not found / not owned by caller              |
+| 409  | Pending-cap reached                                     |
+| 413  | Payload exceeds size cap                                |
+
+---
+
+### `GET /v1/api/workstreams/{ws_id}/attachments`
+
+List the caller's **pending** (unconsumed) attachments for this
+workstream.  Ownership failures are masked as `404`.
+
+**Response:** `200`
+
+```json
+{
+  "attachments": [
+    {
+      "attachment_id": "att_abc123",
+      "kind": "image",
+      "mime_type": "image/png",
+      "size_bytes": 73240,
+      "filename": "screenshot.png",
+      "state": "pending"
+    }
+  ]
+}
+```
+
+---
+
+### `GET /v1/api/workstreams/{ws_id}/attachments/{attachment_id}/content`
+
+Returns the raw bytes of an attachment with its stored `Content-Type`.
+Useful for previewing an image or replaying a document.  Ownership
+failures are masked as `404`.
+
+**Response:** `200` — binary body, original `Content-Type`.
+
+---
+
+### `DELETE /v1/api/workstreams/{ws_id}/attachments/{attachment_id}`
+
+Remove a pending attachment.  Consumed attachments return `404` (they
+are part of a committed conversation turn).  Ownership failures are also
+masked as `404`.
+
+**Response:** `200`
+
+```json
+{"deleted": "att_abc123"}
+```
+
+---
+
+### `POST /v1/api/workstreams/{ws_id}/delete`
+
+Permanently delete a saved workstream and all its messages from storage.
+
+**Path parameters:**
+
+| Parameter | Type   | Description          |
+|-----------|--------|----------------------|
+| `ws_id`   | string | Workstream ID        |
+
+**Response (success):** `200`
+
+```json
+{"deleted": "a1b2c3d4"}
+```
+
+**Response (not found):** `404`
+
+```json
+{"error": "Workstream not found"}
+```
+
+---
+
+### `POST /v1/api/workstreams/{ws_id}/open`
+
+Load a saved workstream into memory with its original `ws_id`. If the
+workstream is already loaded, returns immediately with `already_loaded: true`.
+
+**Path parameters:**
+
+| Parameter | Type   | Description          |
+|-----------|--------|----------------------|
+| `ws_id`   | string | Workstream ID        |
+
+**Response (success):** `200`
+
+```json
+{"ws_id": "a1b2c3d4", "name": "refactor"}
+```
+
+**Response (already loaded):** `200`
+
+```json
+{"ws_id": "a1b2c3d4", "name": "refactor", "already_loaded": true}
+```
+
+---
+
+### `POST /v1/api/workstreams/{ws_id}/title`
+
+Set a workstream title manually. The title is stored as the workstream alias.
+
+**Path parameters:**
+
+| Parameter | Type   | Description          |
+|-----------|--------|----------------------|
+| `ws_id`   | string | Workstream ID        |
+
+**Request body:**
+
+```json
+{"title": "JWT Authentication Refactor"}
+```
+
+| Field   | Type   | Required | Description            |
+|---------|--------|----------|------------------------|
+| `title` | string | yes      | New workstream title   |
+
+**Response (success):** `200`
+
+```json
+{"status": "ok", "title": "JWT Authentication Refactor"}
+```
+
+**Response (conflict):** `409`
+
+```json
+{"error": "That name is already used by another workstream"}
+```
+
+---
+
+### `POST /v1/api/workstreams/{ws_id}/refresh-title`
+
+Regenerate the workstream title via LLM based on conversation content.
+
+**Path parameters:**
+
+| Parameter | Type   | Description          |
+|-----------|--------|----------------------|
+| `ws_id`   | string | Workstream ID        |
+
+**Response (success):** `200`
+
+```json
+{"status": "ok"}
+```
+
+---
+
+### `GET /v1/api/admin/settings`
+
+List `interface.*` settings with their current values and sources. Requires
+`read` scope on the server.
+
+**Response:** `200`
+
+```json
+{
+  "settings": [
+    {
+      "key": "interface.close_tab_action",
+      "value": "last_used",
+      "source": "default",
+      "type": "str",
+      "description": "Determines which workstream to switch to after closing a tab."
+    }
+  ]
+}
+```
+
+---
+
+### `POST|PUT /v1/api/admin/settings/{key}`
+
+Update an `interface.*` setting. Only keys in the `interface` section are
+accepted; other keys return `400`.
+
+**Path parameters:**
+
+| Parameter | Type   | Description                         |
+|-----------|--------|-------------------------------------|
+| `key`     | string | Setting key (e.g. `interface.theme`) |
+
+**Request body:**
+
+```json
+{"value": "light"}
+```
+
+| Field   | Type | Required | Description    |
+|---------|------|----------|----------------|
+| `value` | any  | yes      | New value      |
+
+**Response (success):** `200`
+
+```json
+{"status": "ok", "key": "interface.theme", "value": "light"}
+```
+
+**Error:** `400` if the key is not in the `interface` section.
+
+---
+
 ### `GET /v1/api/watches`
 
 List active watches on this server node. Optionally filter by workstream.
@@ -1355,7 +1611,7 @@ version. Requires the `admin.skills` permission.
 
 ```json
 {
-  "scan_status": "medium",
+  "risk_level": "medium",
   "scan_report": "{\"composite\": 1.75, \"details\": {...}}",
   "scan_version": "1"
 }
@@ -1859,3 +2115,53 @@ turnstone_tokens_total{type="completion"} 12150
 turnstone_tool_calls_total{tool="bash"} 7
 turnstone_tool_calls_total{tool="read_file"} 3
 ```
+
+---
+
+## Console Routing Proxy Endpoints
+
+These endpoints are served by the console (`turnstone-console`) and proxy
+requests to the correct server node via rendezvous (HRW) hashing over the
+live service registry. In multi-node deployments, clients (SDK, channel
+gateway) talk to the console instead of individual server nodes.
+
+### `POST /v1/api/route/workstreams/new`
+
+Create a workstream via rendezvous routing. The console generates the `ws_id`,
+routes to the rendezvous-selected node, and includes `node_url` in the
+response for direct SSE connections.
+
+### `POST /v1/api/route/send`
+
+Proxy a message to the workstream's assigned server node.
+
+### `POST /v1/api/route/approve`
+
+Proxy an approval response to the workstream's assigned server node.
+
+### `POST /v1/api/route/cancel`
+
+Cancel generation on a workstream.
+
+### `POST /v1/api/route/command`
+
+Send a slash command to a workstream.
+
+### `POST /v1/api/route/plan`
+
+Send plan review feedback to a workstream.
+
+### `POST /v1/api/route/workstreams/close`
+
+Close a workstream.
+
+### `GET /v1/api/route?ws_id=X`
+
+Look up which server node owns a workstream. Returns `{"node_url": "...", "node_id": "..."}`.
+Used by channel adapters to open direct SSE connections to the correct server node.
+
+### `GET /metrics` (Console)
+
+Prometheus metrics for the console routing layer. Includes:
+`turnstone_router_requests_total`, `turnstone_router_request_duration_seconds`,
+`turnstone_router_membership_size`, `turnstone_router_refresh_total`.

docs/architecture.md

@@ -18,11 +18,11 @@ plugs in.
 |---------|--------|----------|---------|
 | `turnstone` | `turnstone.cli` | `TerminalUI` | Interactive terminal REPL |
 | `turnstone-server` | `turnstone.server` | `WebUI` | Browser-based chat (HTTP + SSE) |
-| `turnstone-bridge` | `turnstone.mq.bridge` | Bridge | Message queue ↔ HTTP API bridge |
 | `turnstone-console` | `turnstone.console.server` | ClusterCollector | Cluster dashboard (aggregates all nodes) |
 | `turnstone-eval` | `turnstone.eval` | `NullUI` | Headless evaluation and prompt optimization |
-| `turnstone-channel` | `turnstone.channels.cli` | ChannelAdapter | Channel gateway (Discord, Slack, etc.) via Redis MQ |
-| `turnstone-admin` | `turnstone.core.admin_cli` | — | Offline user and API token management |
+| `turnstone-channel` | `turnstone.channels.cli` | ChannelAdapter | Channel gateway (Discord, Slack, etc.) |
+| `turnstone-admin` | `turnstone.admin` | — | Offline user and API token management |
+| `turnstone-bootstrap` | `turnstone.bootstrap` | — | LLM-guided setup wizard |
 
 ---
 
@@ -37,12 +37,16 @@ turnstone/
     session.py        ChatSession engine, SessionUI protocol, tool dispatch
     providers/        LLM provider adapters (pluggable backend layer)
       _protocol.py    LLMProvider protocol, ModelCapabilities, StreamChunk, CompletionResult
-      _openai.py      OpenAIProvider — OpenAI, vLLM, llama.cpp, any compatible API
+      _openai.py      OpenAIProvider facade (re-exports Chat/Responses providers)
+      _openai_chat.py       OpenAIChatCompletionsProvider — vLLM, llama.cpp, local compatible APIs
+      _openai_responses.py  OpenAIResponsesProvider — commercial OpenAI Responses API
+      _openai_common.py     Shared ModelCapabilities table + helpers
       _anthropic.py   AnthropicProvider — Anthropic Messages API, native streaming, thinking
+      _google.py      GoogleProvider — Google Gemini via OpenAI-compat endpoint
       __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, dynamic refresh, async-sync bridge
+    mcp_client.py     MCPClientManager — MCP server connections, tool discovery, dynamic refresh
     tool_search.py    Dynamic tool search — BM25 index, session-scoped tool visibility
     watch.py          WatchRunner daemon — periodic command polling, condition DSL, result dispatch
     judge.py          Intent validation — heuristic rules + LLM judge, advisory verdicts
@@ -74,24 +78,20 @@ turnstone/
     _base.py          Shared httpx async client, auth, error handling
     _sync.py          Background event loop for sync wrappers
     _types.py         TurnResult + TurnstoneAPIError
-  mq/
-    protocol.py       Inbound/outbound message dataclasses (JSON serialization)
-    broker.py         Abstract MessageBroker protocol + RedisBroker
-    bridge.py         Bridge service (queue ↔ turnstone-server HTTP API)
-    client.py         TurnstoneClient library + TurnResult for MQ-based access
   console/
-    collector.py      ClusterCollector — aggregates state from all nodes via Redis + HTTP
-    scheduler.py      TaskScheduler — background cron/at scheduler, dispatches via MQ
+    collector.py      ClusterCollector — aggregates state from all nodes via SSE
+    scheduler.py      TaskScheduler — background cron/at scheduler, dispatches via HTTP
     server.py         Cluster dashboard HTTP server + SSE + CLI entry point
     static/           Cluster dashboard web UI (page-specific HTML, CSS, JS)
   channels/
     cli.py            Unified channel gateway entry point (turnstone-channel)
-    _protocol.py      ChannelAdapter protocol, ChannelEvent dataclass
-    _routing.py       ChannelRouter — channel/thread ↔ workstream mapping via MQ
+    _protocol.py      ChannelAdapter protocol
+    _routing.py       ChannelRouter — channel/thread ↔ workstream mapping via HTTP
     _config.py        Base ChannelConfig dataclass
     discord/          Discord adapter (bot, cog, views, streaming, config)
+    slack/            Slack adapter (Socket Mode bot, DM routing, approval buttons)
   shared_static/      Shared design system (base.css, auth.js, theme.js, toast.js, utils.js, kb.js)
-    katex-0.16.44/    Vendored KaTeX math rendering library (MIT, woff2 fonts)
+    katex-0.16.45/    Vendored KaTeX math rendering library (MIT, woff2 fonts)
   ui/
     colors.py         ANSI color constants with NO_COLOR support
     markdown.py       Streaming terminal markdown renderer (line-buffered)
@@ -102,7 +102,7 @@ turnstone/
       renderer.js     Markdown + LaTeX renderer (tables, nested lists, blockquotes, KaTeX math)
       app.js          Split-pane UI (Pane class, binary layout tree, SSE, tool approval)
   tools/
-    *.json            15 tool schemas (OpenAI function-calling format + turnstone metadata)
+    *.json            19 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/`.
@@ -448,13 +448,15 @@ from each schema and builds:
 - `PRIMARY_KEY_MAP` -- `{name: primary_key}` for JSON fallback recovery
 - `merge_mcp_tools(builtin, mcp_tools)` -- merges built-in + MCP tools at session init
 
-### 13 Tools by Category
+### 19 Tools by Category
 
 **Read-only (auto-approve)**:
 - `read_file` -- read file contents with optional offset/limit
+- `diff_file` -- show diff between two files / versions
 - `search` -- ripgrep-based codebase search
 - `man` -- read man pages
 - `recall` -- search conversation history
+- `read_resource` -- read an MCP resource by URI
 
 **Write (requires approval)**:
 - `bash` -- execute shell commands (with safety checks via `turnstone.core.safety`)
@@ -463,13 +465,20 @@ from each schema and builds:
 - `math` -- execute Python in sandboxed subprocess (via `turnstone.core.sandbox`)
 - `web_fetch` -- fetch a URL (with SSRF protection via `turnstone.core.web`)
 - `web_search` -- search the web (provider-native for Anthropic/OpenAI, Tavily fallback for local models)
+- `notify` -- send a user-facing notification (Discord/Slack, optional reply routing)
+- `watch` -- schedule a recurring poll with condition DSL
 
 **Agent (delegated sub-sessions)**:
-- `task` -- delegate to a sub-agent with full tool access (`TASK_AGENT_TOOLS`)
-- `plan` -- explore codebase and write a structured plan (`AGENT_TOOLS`)
+- `task_agent` -- delegate to a sub-agent with full tool access (`TASK_AGENT_TOOLS`)
+- `plan_agent` -- explore codebase and write a structured plan (`AGENT_TOOLS`)
 
-**Memory (structured persistent store)**:
+**Memory / skills / prompts**:
 - `memory` -- save, search, delete, or list memories (typed and scoped)
+- `skill` -- invoke a skill (governed, versioned procedure)
+- `use_prompt` -- fetch and apply a prompt template
+
+Tool names are `plan_agent` / `task_agent` (not `plan` / `task`); bare words
+collide with chat-template channels on some local models.
 
 ### Prepare / Execute Pattern
 
@@ -488,14 +497,14 @@ separation allows the UI to show previews before any side effects occur.
 
 ### Agent Tools
 
-`task` and `plan` invoke `_run_agent()`, which runs a multi-turn loop with
-a subset of tools and its own system prompt. The sub-agent runs
+`task_agent` and `plan_agent` invoke `_run_agent()`, which runs a multi-turn
+loop with a subset of tools and its own system prompt. The sub-agent runs
 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
+- **task_agent**: uses `self._task_tools` (`TASK_AGENT_TOOLS` + MCP tools)
+- **plan_agent**: uses `self._agent_tools` (`AGENT_TOOLS` + MCP tools). Writes output
   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
+  don't collide. On repeat invocations the prior `plan_agent` 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
   prepended to the agent's conversation.
@@ -553,6 +562,21 @@ expanded tools).
 **Tool naming:** `mcp__{server}__{tool}` — double underscore delimiter, validated
 at connection time (server names with `__` are rejected).
 
+**Resilience:** Each MCP server has an independent circuit breaker that opens
+after 3 consecutive transport failures (timeouts, broken pipes, connection
+resets). Cooldown uses capped exponential backoff (30 s base, 5 min max) with
+per-server jitter to avoid thundering herd. Protocol-level errors (`McpError`)
+from a healthy connection do not trip the breaker. When the cooldown expires
+(half-open), the next operation attempt triggers automatic reconnection. Manual
+`/mcp refresh` also clears the circuit on success. All sync bridge methods
+(`call_tool_sync`, `read_resource_sync`, `get_prompt_sync`, `refresh_sync`)
+cancel orphaned futures on timeout to prevent coroutine accumulation on the
+background event loop. Push notification refreshes are debounced (5 s per
+server) to protect against notification storms. The periodic refresh loop
+attempts reconnection for disconnected servers with exponential backoff
+(60 s–1 h). Transport stream references are pre-closed before stack teardown to
+work around the MCP SDK's anyio cancel-scope CPU busy-loop (SDK #2147).
+
 **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.
@@ -584,6 +608,7 @@ LLMProvider (protocol)
     |
     +--- OpenAIProvider  --- OpenAI, vLLM, llama.cpp, any /v1/chat/completions API
     +--- AnthropicProvider --- Anthropic Messages API (native streaming, thinking)
+    +--- GoogleProvider  --- Google Gemini via /v1beta/openai/ (extends OpenAIProvider)
 ```
 
 **Protocol methods:**
@@ -637,6 +662,13 @@ both streaming and non-streaming responses. The `anthropic` SDK is imported
 lazily so it remains an optional dependency (`pip install
 turnstone[anthropic]`).
 
+**GoogleProvider** (`_google.py`): extends `OpenAIChatCompletionsProvider` for
+the Gemini `/v1beta/openai/` endpoint. Uses a single default
+`ModelCapabilities` (2M context window, 65K max output tokens,
+`token_param=max_tokens`) since Google updates models frequently. No static
+per-model capability table. Google's endpoint is wire-compatible with the
+OpenAI SDK, so no extra dependency is needed.
+
 **Factory functions** (`__init__.py`): `create_provider(name)` returns a
 singleton provider instance (thread-safe). `create_client(name, base_url,
 api_key)` creates the appropriate SDK client.
@@ -665,6 +697,10 @@ api_key = "sk-..."
 model = "gpt-5"
 context_window = 400000
 
+[models.gemini]
+provider = "google"
+model = "gemini-2.5-pro"
+
 [model]
 default = "local"
 fallback = ["claude", "openai"]
@@ -672,7 +708,28 @@ agent_model = "claude"
 ```
 
 Each `[models.*]` entry produces a `ModelConfig` with a `provider` field
-(default: `"openai"`). Supported values: `"openai"` and `"anthropic"`.
+(default: `"openai"`). Supported values: `"openai"`, `"anthropic"`, `"google"`,
+and `"openai-compatible"`.
+
+**Per-model sampling overrides:** Each model can specify `temperature`,
+`max_tokens`, and `reasoning_effort` to override the global defaults from
+ConfigStore. When unset (`NULL`), the global default is used.
+
+```toml
+[models.local]
+base_url = "http://localhost:8000/v1"
+model = "qwen3-32b"
+temperature = 0.7
+max_tokens = 8192
+
+[models.o3]
+base_url = "https://api.openai.com/v1"
+api_key = "sk-..."
+model = "o3"
+reasoning_effort = "high"
+# temperature omitted — uses global default
+```
+
 An optional `[models.*.capabilities]` sub-table overrides per-model
 `ModelCapabilities` flags (useful for local models whose capabilities
 cannot be detected programmatically):
@@ -686,9 +743,15 @@ model = "qwen-3.5-vl"
 supports_vision = true
 ```
 
+**Database model definitions:** On server entry points, models can also be
+defined in the `model_definitions` table (admin Models tab). DB models support
+the same per-model sampling overrides. Config.toml models override DB models
+with the same alias in-memory (the DB rows are never modified).
+
 **Lifecycle:**
-1. `load_model_registry()` reads `[models.*]` sections from config.toml and
-   builds a `"default"` entry from CLI `--base-url`/`--model`/`--api-key` args
+1. `load_model_registry()` loads DB model definitions (if storage available),
+   then overlays `[models.*]` from config.toml, then builds a `"default"` entry
+   from CLI `--base-url`/`--model`/`--api-key` args
 2. The registry is passed to the session factory closure in both `cli.py` and
    `server.py`; each workstream resolves its model on creation
 3. `ModelRegistry.get_client()` lazily creates SDK client instances via
@@ -697,15 +760,15 @@ supports_vision = true
 4. `ModelRegistry.get_provider()` lazily creates `LLMProvider` instances via
    `create_provider()` (also cached and thread-safe)
 5. `/model` command shows available models; `/model <alias>` switches the
-   active workstream's client, model, and context window
+   active workstream's client, model, context window, and per-model sampling
+   parameters
 6. `_create_stream_with_retry()` tries the primary model, then each fallback
    alias in order if the primary is unreachable
 7. `_run_agent()` resolves `registry.agent_model` (if set) for plan/task
    sub-agents, allowing a cheaper model for autonomous loops
 
 **Per-workstream selection:** `POST /v1/api/workstreams/new` accepts an optional
-`"model"` field. The bridge `CreateWorkstreamMessage` carries the same field
-through the MQ protocol, along with `skill` (skill name)
+`"model"` field, along with `skill` (skill name)
 which can override the model before workstream creation.
 
 ### Tool Output Truncation
@@ -821,7 +884,7 @@ and are the single source of truth for both backends and Alembic migrations.
 | `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 |
-| `list_workstreams(node_id, limit)` | List workstreams, optionally by node |
+| `list_workstreams(node_id, limit, *, parent_ws_id, kind, user_id)` | List workstreams, optionally filtered by node, parent, kind, or owning user |
 | `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 |
 | `search_history(query, limit)` | Full-text search (FTS5 on SQLite, tsvector on PostgreSQL) |
@@ -1023,13 +1086,10 @@ limits using a token-bucket algorithm. Each IP gets a `TokenBucket` with
 Turnstone supports three authentication mechanisms, unified behind an
 `AuthResult` dataclass that carries `user_id`, `scopes`, and `token_source`:
 
-1. **Config-file tokens** — static secrets in `config.toml` `[[auth.tokens]]`
-   or the `TURNSTONE_AUTH_TOKEN` env var. Validated in-memory via
-   `hmac.compare_digest`. Map to scopes through their role (`read` or `full`).
-2. **API tokens** — database-backed, prefixed `ts_`, stored as SHA-256 hashes
+1. **API tokens** — database-backed, prefixed `ts_`, stored as SHA-256 hashes
    in the `api_tokens` table. Can be exchanged for JWTs via
    `POST /v1/api/auth/login`.
-3. **JWTs** — short-lived HMAC-SHA256 session tokens (default 24h) issued after
+2. **JWTs** — short-lived HMAC-SHA256 session tokens (default 24h) issued after
    successful credential validation. Contain `sub` (user_id), `scopes`, and
    `src` (origin) in claims.
 
@@ -1053,9 +1113,8 @@ Three hierarchical scopes control endpoint access:
 2. **Token extraction** — `Authorization: Bearer <token>` header first, then
    `turnstone_auth` cookie as fallback.
 3. **Token type detection** — dots in the token indicate JWT; `ts_` prefix
-   indicates API token; otherwise config-file token.
-4. **Validation** — JWT signature check, API token hash lookup in storage, or
-   config-token hmac comparison.
+   indicates API token.
+4. **Validation** — JWT signature check or API token hash lookup in storage.
 5. **Scope check** — `required_scope(method, path)` determines the minimum
    scope; the request is rejected with 403 if the token lacks it.
 6. **Context propagation** — on success, `ctx_user_id` is set so structured
@@ -1066,8 +1125,9 @@ Three hierarchical scopes control endpoint access:
 - **Console** is the auth management hub — it hosts the admin endpoints for
   creating users, issuing API tokens, and managing channel mappings. User
   records and token hashes live in the shared storage backend. The console
-  dashboard includes an **admin panel** (14 tabs) for managing
-  credentials, governance, MCP servers, and runtime settings through the browser.
+  dashboard includes an **admin panel** (18 tabs) for managing
+  credentials, governance, MCP servers, models, node metadata, and runtime
+  settings through the browser.
 - **Server** is a JWT validator only — it validates tokens on each request but
   never creates users or tokens. Both processes share the same `jwt_secret`
   (via `TURNSTONE_JWT_SECRET` env var or `[auth].jwt_secret` config).
@@ -1205,95 +1265,39 @@ calls `_fg_event.wait()`, which blocks the worker thread until the user
 switches to that workstream. The `_bg_attention_notify` callback writes a
 bell + status line to stderr to alert the user.
 
-### Message Queue Bridge
-
-```
-Main thread              Global SSE thread         Per-WS SSE threads (×N)
-+------------------+     +------------------+      +-------------------+
-| Inbound loop     |     | GET /events/glob |      | GET /events?ws_id |
-| BLPOP on Redis   |     | Parse SSE via    |      | Parse SSE via     |
-|                  |     |   httpx-sse      |      |   httpx-sse       |
-| Dispatch to      |     | Forward state    |      | Forward content,  |
-|   handler        |     |   changes        |      |   tool results    |
-| POST to server   |     | Detect turn      |      | Handle approval   |
-| Publish ACK      |     |   completion     |      |   forwarding      |
-+------------------+     +------------------+      +-------------------+
-       |                         |                         |
-       +-- Redis inbound queue   +-- Redis pub/sub         +-- Redis pub/sub
-           (RPUSH/BLPOP)             (PUBLISH)                 (PUBLISH)
-                                                               + response queue
-                                                                 (BLPOP on
-                                                                  approval)
-```
-
-**Approval flow:** When a per-WS SSE thread receives an `approve_request`, it checks
-the workstream's `auto_approve_tools` set. If all requested tools are in the set, the
-bridge auto-approves via `POST /v1/api/approve`. Otherwise, it publishes an
-`ApprovalRequestEvent` to the outbound channel with a `request_id`, then blocks on
-`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. The server accumulates content tokens in the WebUI and
-piggybacks the full response text onto the `ws_state → idle` global SSE event.
-When the bridge receives this event, it emits a synthetic `TurnCompleteEvent`
-carrying the correlation ID and the server-provided `content`. This lets downstream
-consumers (e.g. the Discord bot) recover the full response when individual
-`ContentEvent`s were missed, and serves as the primary delivery path for
-bidirectional notification DM forwarding.
-
-**Multi-node routing:** Each bridge retrieves its `node_id` from the server's
-`/health` endpoint on startup (with exponential backoff retry). The server
-generates the `node_id` (`{hostname}_{4hex}`) and is the sole authority for
-node identity. The bridge BLPOPs
-from both `turnstone:inbound:{node_id}` (directed, priority) and `turnstone:inbound` (shared).
-Messages with `target_node` set are pushed to the target's per-node queue. Messages
-for existing workstreams are auto-routed via `turnstone:ws:{ws_id}` ownership keys in Redis.
-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
 
 ```
-Monitoring (3 daemon threads)        Control + Proxy (async Starlette)
+Monitoring (2 daemon threads)        Control + Proxy (async Starlette)
 +------------------+                 +----------------------------+
-| Event subscriber |                 | POST /v1/api/cluster/      |
-| SUBSCRIBE on     |                 |   workstreams/new          |
-| events:cluster   |                 |   → LPUSH to Redis         |
-+------------------+                 |     inbound:{node_id}      |
-| Node discovery   |                 +----------------------------+
-| SCAN node:* keys |                 | GET /node/{node_id}/       |
-| every 15 seconds |                 |   → httpx.AsyncClient      |
-+------------------+                 |     proxy to server_url    |
-| Poll loop        |                 | GET /node/{id}/v1/api/events |
-| GET /v1/api/dash |                 |   → SSE stream proxy       |
-| GET /health      |                 | POST /node/{id}/v1/api/send  |
-| ThreadPoolExec   |                 |   → forwarded to server    |
+| Node discovery   |                 | POST /v1/api/cluster/      |
+| Service registry |                 |   workstreams/new          |
+| every 60 seconds |                 |   → POST to target server  |
 +------------------+                 +----------------------------+
+| SSE manager      |                 | GET /node/{node_id}/       |
+| asyncio loop     |                 |   → httpx.AsyncClient      |
+| 1 task per node  |                 |     proxy to server_url    |
+| /events/global   |                 | GET /node/{id}/v1/api/events |
+| snapshot+deltas  |                 |   → SSE stream proxy       |
++------------------+                 | POST /node/{id}/v1/api/send  |
+                                     |   → forwarded to server    |
+                                     +----------------------------+
 ```
 
 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. 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 main server. `ClusterCollector` runs two daemon threads: a discovery loop
+that queries the service registry every 60 seconds, and an SSE manager that
+runs a single asyncio event loop multiplexing persistent SSE connections to
+all nodes via `GET /v1/api/events/global`. Each node delivers a full snapshot
+on connect followed by real-time delta events — state changes, health
+transitions, and aggregate metrics arrive sub-second instead of on a 15-second
+poll cycle.
 
 The console has two write-path capabilities:
 
-1. **Workstream creation** — pushes `CreateWorkstreamMessage` to Redis inbound
-   queues targeting specific nodes. The bridge on each node picks up the message
-   and creates the workstream on the local server. Auto-selects the node with
+1. **Workstream creation** — sends HTTP requests to target server nodes
+   to create workstreams. Auto-selects the node with
    the most available capacity if no target is specified. When a `skill`
    field is present, the server resolves the skill BEFORE `mgr.create()`
    (applying the model override to the creation request) and snapshot-applies
@@ -1358,9 +1362,10 @@ setup, auth headers, `_request()` (REST) and `_stream_sse()` (SSE). Sync
 clients delegate through `_SyncRunner` which maintains a persistent background
 event loop on a daemon thread.
 
-**Event types**: 27 standalone dataclasses in `events.py` with a type-registry
-pattern matching `OutboundEvent.from_json()` from `mq/protocol.py`. Events are
-decoupled from the MQ package so SDK consumers don't need the `redis` dependency.
+**Event types**: 38 standalone dataclasses in `events.py` with a type-registry
+dispatch (`from_json()` on each event). Events are decoupled from server
+internals — the SDK parses SSE frames directly from the `/v1/api/events`
+streams.
 
 **TypeScript SDK**: `sdk/typescript/` — separate npm package with the same API
 surface. Zero browser dependencies, SSE via `fetch` + `ReadableStream` parsing.
@@ -1381,29 +1386,29 @@ with TurnstoneServer("http://localhost:8080", token="tok_xxx") as client:
 
 > See also: [Channel Integrations guide](channels.md)
 
-The `turnstone-channel` gateway bridges external messaging platforms
-(Discord, Slack, Teams) to the turnstone cluster via Redis MQ. Each
+The `turnstone-channel` gateway connects external messaging platforms
+(Discord and Slack today, with an adapter protocol for future platforms) to
+the turnstone cluster via HTTP. Each
 platform adapter implements the `ChannelAdapter` protocol and translates
-between platform-native events and turnstone MQ messages.
+between platform-native events and turnstone server API calls.
 
 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 resume via the
-`resume_ws` field on `CreateWorkstreamMessage` — the server resumes
+`resume_ws` field on the workstream creation request — 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.
+request, eliminating ordering fragility.
 
-Discord ships as the first adapter. See [channels.md](channels.md) for
+Discord and Slack adapters ship today. See [channels.md](channels.md) for
 setup instructions, configuration reference, and the adapter development
 guide.
 
 ### Notification Subsystem
 
 The `notify` tool enables the LLM to send notifications to users or
-channels without going through MQ. The server calls the channel gateway
+channels directly. The server calls the channel gateway
 directly over HTTP for lower latency: `_exec_notify()` queries the
 `services` database table for healthy channel gateways (heartbeat within
 120 seconds), authenticates with a service JWT (`aud: turnstone-channel`),
@@ -1417,11 +1422,11 @@ 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).
 
 **Bidirectional replies:** When a user replies to a notification DM, the
-Discord bot looks up the originating `ws_id` from the tracked message ID,
-verifies the replying user matches the notification recipient, and routes
-the reply to the workstream via `router.send_message()`. The workstream's
-response is forwarded back to the DM via a temporary entry in
-`_notify_reply_channels`. On `TurnCompleteEvent`, the response message is
+channel adapter (Discord or Slack) looks up the originating `ws_id` from the
+tracked message ID, verifies the replying user matches the notification
+recipient, and routes the reply to the workstream via `router.send_message()`.
+The workstream's response is forwarded back to the DM via a temporary entry
+in `_notify_reply_channels`. On `TurnCompleteEvent`, the response message is
 itself tracked for further replies, enabling multi-turn DM conversations
 without requiring the user to open the web UI. Tracking entries are capped
 at 100 (FIFO eviction) and cleaned up on workstream close.
@@ -1454,11 +1459,10 @@ and workstreams record which skill and version spawned them. Token budget
 enforcement tracks consumption in `session.send()` with 80% warning and
 100% approval gate via the `__budget_override__` synthetic tool name.
 
-The console admin panel adds 5 governance tabs (Roles, Policies, Skills,
-Usage, Audit), a Memories tab, a Settings tab (form-based editor for all
-ConfigStore settings), and an MCP Servers tab (database-backed server
-definitions with live connection status and cluster-wide reload) for a
-total of 13 tabs, all permission-gated.
+The console admin panel exposes these capabilities as 18 permission-gated
+tabs: Users, API Tokens, Channels, Schedules, Watches, Roles, Policies,
+Prompts, Judge, Skills, MCP Servers, Usage, Audit, Memories, Models, Nodes,
+Settings, and TLS.
 Both Python and TypeScript SDKs expose governance methods on the console
 client.
 

docs/assets/hero.png

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

docs/bulk-endpoints.md

@@ -0,0 +1,237 @@
+# Bulk endpoint shape contract
+
+Turnstone exposes several endpoints and tool calls that take multiple
+ids and return a per-id outcome.  Over the last few phases two
+**distinct** response shapes have settled, one per semantic category.
+This doc codifies both so a future endpoint author can pick the right
+shape by semantics instead of by coin-flip.
+
+Existing bulk endpoints at time of writing:
+
+| Endpoint / tool                                         | Category                 | Response shape                          |
+|---------------------------------------------------------|--------------------------|------------------------------------------|
+| `GET  /v1/api/cluster/ws/live?ids=a,b,c`                | bulk read                | `{results, denied, truncated}`           |
+| model tool `spawn_batch`                                 | bulk create (per-item)   | `{results, denied}`                      |
+| `POST /v1/api/coordinator/{ws_id}/stop_cascade`          | cascade mutation         | `{cancelled, failed, skipped}`           |
+| `POST /v1/api/coordinator/{ws_id}/close_all_children`    | cascade mutation         | `{closed, failed, skipped}`              |
+
+---
+
+## Why two shapes
+
+The ask-to-outcome mapping is fundamentally different between the
+two categories, and a one-size-fits-all envelope ends up papering
+over distinctions the caller genuinely needs to branch on.
+
+**Bulk read / bulk create-with-payload.**  Each input id (or batch
+index) carries a *request-side* concept — "give me the live block
+for this ws_id" or "spawn a child with this spec" — and each
+successful output carries a *payload* — the live block, or the new
+workstream's identifying triple.  The interesting distinction on
+failure is *ownership / validation* (caller can't see that id, spec
+was malformed) — independent of the storage state.
+
+**Cascade mutation.**  The action is uniform across every id (cancel
+this subtree, close this child).  The interesting distinctions on
+outcome are *did it reach the terminal state?* (succeeded / already
+was there / the dispatch itself failed) — driven by the storage
+state plus transport reliability, not by the caller's input.
+
+Trying to unify these forces either:
+
+- a stateless `denied` bucket that has to carry "already gone"
+  *and* "you don't have permission" *and* "transport failed" with a
+  separate reason string — reviewers end up string-matching to branch.
+- or a per-item-payload map for cascade mutations where every
+  successful value is the same sentinel — carrier with no payload.
+
+So: two shapes, one per category.  The rest of this doc spells out
+each.
+
+---
+
+## Shape A — bulk read / bulk create-with-payload
+
+```json
+{
+  "results":  { "<key>": <value-or-null>, ... },
+  "denied":   [ "<key>", ... ],
+  "truncated": false
+}
+```
+
+**`results`** is a key-indexed map of the positive-path payload.
+The key is the input id for read endpoints (`cluster/ws/live` uses
+the ws_id), or the input-array index (stringified) for create
+endpoints that want ordering preserved (`spawn_batch` uses `"0"`,
+`"1"`, ...).  The value is whatever the endpoint produces per
+success — a live block, a `{ws_id, name, node_id, status}` triple,
+etc.  A `null` value (read endpoints only) means "the id existed and
+you own it, but the live block wasn't available" — distinct from
+"denied".
+
+**`denied`** is the negative-path list.  For read endpoints it's a
+flat list of ids (preserves input order so callers can re-zip
+against their input).  For create endpoints with per-item payloads
+it's a list of `{idx, reason}` objects (`spawn_batch`'s validation
+and spawn-error rows; also the operator-reject surface when per-item
+selective-deny ships).  Include every reason that's *not* the
+positive path — authz, ownership, validation, already-consumed,
+spawn failure — so callers don't branch on status codes.
+
+**`truncated`** is a boolean set to `true` when the server's
+per-endpoint input cap was exceeded and the tail was dropped.  The
+endpoint docs each spell out the cap (50 for `cluster/ws/live`).
+`spawn_batch` hard-errors on overflow instead of silently
+truncating — it omits the field entirely rather than carry a
+permanently-false flag.
+
+### Example — `cluster/ws/live`
+
+```http
+GET /v1/api/cluster/ws/live?ids=a1b2,c3d4,nonexistent,foreign HTTP/1.1
+```
+
+```json
+{
+  "results": {
+    "a1b2": {"state": "running", "tokens": 12843, "activity": "..."},
+    "c3d4": null
+  },
+  "denied": ["nonexistent", "foreign"],
+  "truncated": false
+}
+```
+
+Callers that need ordered output zip their original id list against
+this map; ids in `denied` drop out of the zip cleanly.  A live-block
+`null` doesn't route to `denied` — the row exists and the caller
+owns it; the node is just currently unreachable.
+
+### Example — `spawn_batch`
+
+```json
+{
+  "results": {
+    "0": {"ws_id": "d4e5f6...", "name": "csrf-audit", "node_id": "gpu-3", "status": 200},
+    "2": {"ws_id": "f1a2b3...", "name": "xss-audit",  "node_id": "gpu-1", "status": 200}
+  },
+  "denied": [
+    {"idx": 1, "reason": "skill not found: nonexistent-skill"}
+  ]
+}
+```
+
+Indexes are stringified to keep the envelope JSON-safe and
+consistently-typed across the read and create cases.
+
+---
+
+## Shape B — cascade mutation
+
+```json
+{
+  "status":       "ok",
+  "<bucket>":     [ "<ws_id>", ... ],
+  "failed":       [ "<ws_id>", ... ],
+  "skipped":      [ "<ws_id>", ... ]
+}
+```
+
+Where `<bucket>` is the endpoint-specific name for "succeeded" —
+`cancelled` for `stop_cascade`, `closed` for `close_all_children`.
+The three buckets partition the input set exactly once:
+
+| Bucket        | Meaning                                                                       |
+|---------------|-------------------------------------------------------------------------------|
+| `<bucket>`    | Action dispatch accepted; target reached the intended terminal state.         |
+| `failed`      | Dispatch returned a non-404 error (transport issue, upstream 5xx, exception). |
+| `skipped`     | Upstream 404 — stale registry entry, row already deleted, or peer gone.       |
+
+The split between `failed` and `skipped` is load-bearing.  `failed`
+is actionable — the operator may want to retry, or the cascade may
+be partial.  `skipped` is pre-resolved — the target is already in
+the terminal state the cascade was aiming at, so it's neither a
+win to report nor a fault to fix.
+
+### Example — `stop_cascade`
+
+```json
+{
+  "status": "ok",
+  "cancelled": ["child-1", "child-3"],
+  "failed":    [],
+  "skipped":   ["child-2"]
+}
+```
+
+A subsequent retry would target only `failed` ids, not `skipped`
+ones — the latter are already done.
+
+### Example — `close_all_children`
+
+```json
+{
+  "status": "ok",
+  "closed":  ["child-1", "child-3"],
+  "failed":  ["child-2"],
+  "skipped": []
+}
+```
+
+Same partition, different success-bucket name.  When `coord_client`
+is unavailable (session loaded but no HTTP client attached — a
+construction bug) every id goes to `failed` so the operator notices
+rather than getting a silent all-skipped response.
+
+---
+
+## Guidance for future bulk endpoints
+
+1. **Pick by semantics, not by "what shape is nearby."**
+   - Mutation that's uniform across ids + terminal-state outcome?  →
+     **Shape B** (cascade mutation).
+   - Read or create where the input id carries payload, or where the
+     denial axis is independent of storage state?  →  **Shape A**
+     (bulk read / bulk create-with-payload).
+
+2. **Cap the input.**  Both shapes assume a bounded input — the
+   server rejects or silently truncates past the cap.  Document the
+   cap in the endpoint's OpenAPI description.  Shape A uses
+   `truncated: true` on quiet truncation; Shape B hard-errors on
+   overflow.
+
+3. **Match existing bucket names for the same semantic.**  Use
+   `failed` and `skipped` verbatim in Shape B — the per-endpoint
+   success bucket is the only slot that varies.  Use `results` and
+   `denied` verbatim in Shape A; the per-endpoint `<key>` /
+   `<value>` types vary.
+
+4. **Audit the verbose shape.**  Both endpoints emit a corresponding
+   audit event with the full before/after bucket lists — the SSE
+   stream and the in-process response give live feedback, but a
+   postmortem operator will read the audit row.  Use
+   `_emit_coord_audit` (coordinator-scoped) or `record_audit`
+   directly; don't inline.
+
+5. **Don't mix shapes within one endpoint.**  If a bulk endpoint
+   wants both partial-success creation AND per-item failure reasons
+   (like `spawn_batch` with its `{idx, reason}` denial rows), that's
+   Shape A with a richer denial element — not a blend with Shape B.
+
+---
+
+## History
+
+- **Phase 6** shipped `cluster/ws/live` as the first Shape A endpoint
+  (`{results, denied, truncated}`).
+- **Phase 7** shipped `stop_cascade` as the first Shape B endpoint
+  (`{cancelled, failed, skipped}`).
+- **Phase 8 PR A** shipped `spawn_batch` (Shape A, keyed by idx) and
+  `close_all_children` (Shape B, twin of `stop_cascade`), which
+  crystallised the two-shape-per-semantic-category policy codified
+  here.
+
+Before adding a third shape, read this doc and argue for why the
+new surface doesn't fit either A or B.  Two idioms in the cluster
+API is a finite operator tax; three is one too many.

docs/channels.md

@@ -1,43 +1,44 @@
 # Channel Integrations
 
 The `turnstone-channel` gateway connects external messaging platforms to
-turnstone workstreams via Redis MQ. Each platform adapter translates
+turnstone workstreams via direct HTTP to the server (single-node) or the
+console routing proxy (multi-node). Each platform adapter translates
 platform-native events (messages, button clicks, slash commands) into
-turnstone MQ messages, and renders workstream output back into the
+turnstone API calls, and renders workstream output back into the
 platform's UI.
 
-Discord ships as the first adapter. The adapter protocol is designed for
-future Slack and Teams integrations.
+Discord and Slack adapters ship today. The adapter protocol is designed
+so new platforms can be added with only a new package under
+`turnstone/channels/<platform>/`.
 
 ---
 
 ## Architecture
 
 ```
-Discord Gateway
-      |
-      v
-turnstone-channel  (Discord adapter)
-      |
-      v
-  Redis MQ
-      |
-      v
-turnstone-bridge  ──>  turnstone-server
+Discord Gateway        Slack (Socket Mode WebSocket)
+       \                  /
+        v                v
+       turnstone-channel  (one or more adapters)
+              |
+              v
+       turnstone-server   (direct HTTP)
+              or
+       turnstone-console  (routing proxy, multi-node)
 ```
 
+A single `turnstone-channel` process can run multiple adapters
+simultaneously (e.g. Discord + Slack) — pass the tokens for each
+platform you want to enable.
+
 Key components:
 
 - **ChannelAdapter protocol** (`turnstone/channels/_protocol.py`) — generic
   interface for any messaging platform. Defines `start()`, `stop()`,
-  `send()`, `send_notification()`, `edit_message()`,
-  `send_approval_request()`, `send_plan_review()`, and `create_thread()`.
+  `send()`, and `send_notification()`.
 - **ChannelRouter** (`turnstone/channels/_routing.py`) — maps
   channel/thread IDs to turnstone workstream IDs. Handles workstream
-  creation via MQ, stale route detection, and user identity resolution.
-- **AsyncRedisBroker** (`turnstone/mq/async_broker.py`) — async Redis
-  client compatible with discord.py's event loop. Used by the router for
-  pub/sub and queue operations.
+  creation via HTTP, stale route detection, and user identity resolution.
 - **channel_users table** — maps `(channel_type, channel_user_id)` to a
   turnstone `user_id`. Messages from unlinked users are silently dropped.
 - **channel_routes table** — persistent channel-to-workstream mappings.
@@ -84,8 +85,7 @@ TURNSTONE_DISCORD_GUILD=123456789  # optional, restrict to one guild
 turnstone-channel \
   --discord-token "your-bot-token" \
   --discord-guild 123456789 \
-  --redis-host localhost \
-  --redis-port 6379
+  --server-url http://localhost:8080
 ```
 
 **Docker Compose** (production profile):
@@ -124,6 +124,68 @@ An admin can also force-link or unlink users via the console admin panel
 
 ---
 
+## Slack Setup
+
+Slack uses **Socket Mode**, so no public URL or API Gateway is required — Slack
+connects outbound to the bot via a WebSocket. Install with:
+
+```bash
+pip install 'turnstone[slack]'
+```
+
+### 1. Create a Slack App
+
+1. Go to https://api.slack.com/apps and click **Create New App**
+2. Under **Settings > Socket Mode**, enable Socket Mode. This generates an
+   **App-Level Token** (prefix `xapp-`) — copy it.
+3. Under **OAuth & Permissions**, add these **Bot Token Scopes**:
+   `chat:write`, `chat:write.public`, `channels:history`, `im:history`,
+   `groups:history`, `mpim:history`, `reactions:write`, `commands`
+4. Under **Event Subscriptions** (Socket Mode delivers events), subscribe
+   to bot events: `message.channels`, `message.im`, `message.groups`
+5. Under **Slash Commands**, create a command (default `/turnstone`)
+6. Install the app to your workspace to generate the **Bot User OAuth
+   Token** (prefix `xoxb-`).
+
+### 2. Configure Turnstone
+
+**Environment variables** (recommended for Docker):
+
+```bash
+TURNSTONE_SLACK_TOKEN=xoxb-...        # Bot User OAuth Token
+TURNSTONE_SLACK_APP_TOKEN=xapp-...    # App-Level Token (Socket Mode)
+TURNSTONE_SLACK_CHANNELS=             # optional, comma-separated channel IDs
+TURNSTONE_SLACK_SLASH_COMMAND=/turnstone
+```
+
+**CLI flags** (bare-metal):
+
+```bash
+turnstone-channel \
+  --slack-token "xoxb-..." \
+  --slack-app-token "xapp-..." \
+  --slack-slash-command /turnstone \
+  --server-url http://localhost:8080
+```
+
+The Slack and Discord adapters can be enabled together — pass tokens for
+both and the gateway hosts both adapters in one process.
+
+### 3. Usage
+
+- **DM the bot**: messages sent directly to the bot create a workstream
+  scoped to that DM; the slash command is not required.
+- **Slash command**: `/turnstone <message>` in any channel the bot can
+  see starts a per-user channel session.
+- Tool approvals render as Slack **Block Kit** buttons; only the user
+  who owns the workstream can approve/reject.
+- Plan reviews render as a modal with approve / request-changes actions.
+- Notifications and reply routing work identically to Discord.
+- Session recovery: persisted channel routes are re-subscribed when the
+  bot restarts, so existing Slack conversations keep flowing.
+
+---
+
 ## Usage
 
 ### Conversations
@@ -138,7 +200,7 @@ An admin can also force-link or unlink users via the console admin panel
   thread auto-creates a new workstream and atomically resumes the
   previous workstream via the `resume_ws` field on
   `CreateWorkstreamMessage`. The server resumes the workstream during
-  creation (same HTTP request), and the bridge emits a
+  creation (same HTTP request), and the server emits a
   `WorkstreamResumedEvent` back to the channel. The thread receives a
   *"Resumed: {name} ({count} messages restored)"* confirmation.
 
@@ -160,8 +222,7 @@ an orange embed with:
 - Tool name and argument preview
 - **Approve** (green), **Reject** (red), **Always Approve** (gray) buttons
 - Only linked users can interact with approval buttons
-- The approval decision is forwarded through MQ to the bridge, which
-  relays it to the server
+- The approval decision is forwarded to the server via HTTP
 
 Buttons use static `custom_id` values so they survive bot restarts.
 Correlation data (`ws_id`, `correlation_id`) is stored in the embed footer.
@@ -181,7 +242,7 @@ Plan review requests are displayed as a blue embed with:
 - **Approve Plan** (green) button — approves the plan with empty feedback
 - **Request Changes** (gray) button — opens a modal for feedback text
   (up to 2000 characters)
-- Feedback is forwarded through MQ as a `PlanFeedbackMessage`
+- Feedback is forwarded to the server via HTTP
 
 ---
 
@@ -189,21 +250,25 @@ Plan review requests are displayed as a blue embed with:
 
 | CLI Flag | Env Var | Default | Description |
 |----------|---------|---------|-------------|
-| `--discord-token` | `TURNSTONE_DISCORD_TOKEN` | — | Bot token (required to enable Discord) |
+| `--discord-token` | `TURNSTONE_DISCORD_TOKEN` | — | Discord bot token (required to enable Discord) |
 | `--discord-guild` | — | `0` (all guilds) | Restrict to a single Discord guild |
-| `--discord-channels` | — | empty (all) | Comma-separated channel IDs to allow |
-| `--redis-host` | `REDIS_HOST` | `localhost` | Redis host |
-| `--redis-port` | — | `6379` | Redis port |
-| `--redis-password` | `REDIS_PASSWORD` | — | Redis password |
-| `--redis-db` | — | `0` | Redis DB number |
+| `--discord-channels` | — | empty (all) | Comma-separated Discord channel IDs to allow |
+| `--slack-token` | `TURNSTONE_SLACK_TOKEN` | — | Slack Bot User OAuth token (`xoxb-…`, required to enable Slack) |
+| `--slack-app-token` | `TURNSTONE_SLACK_APP_TOKEN` | — | Slack App-Level token (`xapp-…`, required with `--slack-token`) |
+| `--slack-channels` | `TURNSTONE_SLACK_CHANNELS` | empty (all) | Comma-separated Slack channel IDs to allow |
+| `--slack-slash-command` | `TURNSTONE_SLACK_SLASH_COMMAND` | `/turnstone` | Slash command name registered in the Slack app |
+| `--server-url` | `TURNSTONE_SERVER_URL` | `http://localhost:8080` | Server URL (single-node) |
+| `--console-url` | `TURNSTONE_CONSOLE_URL` | — | Console URL (multi-node routing proxy) |
 | `--model` | — | server default | Default model for new workstreams |
 | `--auto-approve` | — | `false` | Auto-approve ALL tool calls (skips approval buttons entirely) |
 | `--http-host` | — | `127.0.0.1` | HTTP server bind address for notify endpoint |
 | `--http-port` | `TURNSTONE_CHANNEL_PORT` | `8091` | HTTP server port |
-| `--auth-token` | `TURNSTONE_CHANNEL_AUTH_TOKEN` | — | Static auth token for `/v1/api/notify` (alternative to JWT) |
 | `--log-level` | `TURNSTONE_LOG_LEVEL` | `INFO` | Log level |
 | `--log-format` | `TURNSTONE_LOG_FORMAT` | `auto` | Log format (`auto`/`json`/`text`) |
 
+At least one of `--discord-token` or `--slack-token` must be supplied.
+Passing both starts both adapters in the same process.
+
 ---
 
 ## User Identity
@@ -232,13 +297,13 @@ 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) and creates a new workstream with the old `ws_id`
-   as `resume_ws` on the `CreateWorkstreamMessage`. The server resumes
+   route and creates a new workstream with the old `ws_id`
+   as `resume_ws` on the creation request. The server resumes
    the workstream during creation (no separate command or reverse lookup
-   needed). The bridge emits a `WorkstreamResumedEvent` to the channel, and
+   needed). The channel receives a `WorkstreamResumedEvent`, 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
+5. **Close** — `/close` command closes the workstream via HTTP, deletes the
    route, unsubscribes from events, and archives the Discord thread.
 
 ---
@@ -257,14 +322,14 @@ waiting for them to check in.
 Two modes:
 
 - **Username** — provide a turnstone `username`. The gateway resolves
-  it via the `channel_users` table and sends to all linked channels
-  (e.g. Discord + future Slack).
+  it via the `channel_users` table and sends to every linked platform
+  the user has (e.g. Discord + Slack).
 - **Direct** — provide `channel_type` + `channel_id` to target a
   specific platform channel or user DM.
 
 ### Delivery Flow
 
-Notifications bypass MQ for lower latency. The server calls the channel
+Notifications use direct HTTP for low latency. The server calls the channel
 gateway directly over HTTP:
 
 1. The LLM calls the `notify` tool with a message and target
@@ -328,11 +393,11 @@ The `services` table schema:
 ### Security
 
 - **Authentication** — the gateway's `POST /v1/api/notify` endpoint
-  requires authentication. Configure either `TURNSTONE_JWT_SECRET`
-  (the server mints JWTs with `aud: turnstone-channel` automatically)
-  or a static token via `--auth-token`. If neither is set, the
-  gateway fails closed and rejects all requests with 401. Server JWTs
-  (`aud: turnstone-server`) are rejected.
+  requires authentication. Configure `TURNSTONE_JWT_SECRET` so the
+  server can mint JWTs with `aud: turnstone-channel` automatically.
+  If the secret is not set, the gateway fails closed and rejects all
+  requests with 401. Server JWTs (`aud: turnstone-server`) are
+  rejected.
 - **Rate limit** — maximum 5 notifications per turn. The counter only
   increments on successful delivery, so failures don't consume the
   budget.
@@ -359,10 +424,6 @@ class ChannelAdapter(Protocol):
     async def stop(self) -> None: ...
     async def send(self, channel_id: str, content: str) -> str: ...
     async def send_notification(self, channel_id: str, content: str, ws_id: str) -> str: ...
-    async def edit_message(self, channel_id: str, message_id: str, content: str) -> None: ...
-    async def send_approval_request(self, channel_id: str, ws_id: str, correlation_id: str, items: list[dict]) -> None: ...
-    async def send_plan_review(self, channel_id: str, ws_id: str, correlation_id: str, content: str) -> None: ...
-    async def create_thread(self, parent_channel_id: str, name: str, message_id: str = "") -> str: ...
 ```
 
 `send_notification()` is like `send()` but associates the outgoing
@@ -370,6 +431,11 @@ message with a `ws_id` so that user replies can be routed back to the
 originating workstream. Adapters must track the mapping from outgoing
 message ID to `(ws_id, target_user_id)` and handle DM replies.
 
+Platform-specific concerns — approval prompts, plan reviews, message
+edits, thread creation — live inside the adapter implementation and are
+not part of the protocol surface. Each adapter drives those via its
+own `_on_ws_event` dispatcher using SDK-native APIs.
+
 To add a new platform:
 
 1. Create `turnstone/channels/<platform>/` package

docs/console.md

@@ -1,16 +1,16 @@
 # Cluster Dashboard (turnstone-console)
 
-`turnstone-console` is a cluster management service that provides cluster-wide visibility and control across all turnstone nodes. It connects to the shared Redis broker, discovers nodes via heartbeat keys, polls each node's HTTP API for workstream data, and subscribes to a cluster event channel for real-time state changes.
+`turnstone-console` is a cluster management service that provides cluster-wide visibility and control across all turnstone nodes. It discovers nodes via the `services` database table and subscribes to each node's SSE event stream for real-time workstream, health, and metric updates.
 
-The console also supports **workstream creation** (dispatched via MQ to target nodes) and a **reverse proxy** that serves each node's server UI through the console port — so users only need network access to the console, not to individual server nodes.
+The console also supports **workstream creation** (dispatched via HTTP proxy to target nodes) and a **reverse proxy** that serves each node's server UI through the console port — so users only need network access to the console, not to individual server nodes.
 
 ## Architecture
 
 > See also: [Console Data Flow diagram](diagrams/png/11-console-data-flow.png)
 
 ```
-                        ┌── Redis ←── turnstone-bridge ←── turnstone-server
-                        │    (MQ)        (per node)           (per node)
+                        ┌── services table ──  turnstone-server
+                        │   (node registry)      (per node)
 turnstone-console ──────┤
    (one instance)       │
                         └── turnstone-server (direct HTTP proxy)
@@ -21,45 +21,28 @@ turnstone-console ──────┤
 
 Data flows in two directions:
 
-- **Inbound (monitoring):** Bridges publish state changes to `{prefix}:events:cluster` on Redis pub/sub. The console subscribes for real-time updates and periodically polls each node's `GET /v1/api/dashboard` for full workstream snapshots.
-- **Outbound (control):** The console pushes `CreateWorkstreamMessage` to Redis inbound queues targeting specific nodes. Bridges pick up these messages and create workstreams on their local servers.
+- **Inbound (monitoring):** The console discovers nodes via the `services` database table (nodes register on startup and send periodic heartbeats). It opens a persistent SSE connection to each node's `GET /v1/api/events/global` endpoint, receiving a full snapshot on connect followed by real-time delta events (state changes, health transitions, aggregate metrics).
+- **Outbound (control):** The console proxies workstream creation requests to target nodes via HTTP.
 - **Proxy (pass-through):** The console reverse-proxies each node's server UI at `/node/{node_id}/`, forwarding HTTP and SSE traffic so the browser never contacts server nodes directly.
 
 ### Data Sources
 
 | Source | Method | Direction | Data |
 |--------|--------|-----------|------|
-| Redis heartbeats | `SCAN turnstone:node:*` | Read | Node discovery (node_id, server_url, started) |
-| Redis pub/sub | `SUBSCRIBE turnstone:events:cluster` | Read | State changes, creates, closes, renames |
-| Node HTTP API | `GET {server_url}/v1/api/dashboard` | Read | Full workstream list with tokens, context, activity |
-| Node HTTP API | `GET {server_url}/health` | Read | Node health status |
-| Redis inbound queue | `RPUSH turnstone:inbound:{node_id}` | Write | Workstream creation commands |
+| `services` table | Database query | Read | Node discovery (node_id, server_url, started) |
+| Node SSE | `GET {server_url}/v1/api/events/global` | Stream | Snapshot on connect, then real-time delta events (state, health, aggregate) |
+| Node HTTP API | `POST {server_url}/v1/api/workstreams/new` | Write | Workstream creation |
 | Node HTTP API | `GET/POST {server_url}/*` | Proxy | Server UI, API requests, SSE streams |
 
-### Redis Key: Cluster Event Channel
-
-Bridges publish to `{prefix}:events:cluster` whenever a workstream state change, creation, closure, or rename occurs. Events include `node_id` so the console can attribute them to the correct node.
-
-Event types on the cluster channel:
-
-| Event | Fields | Trigger |
-|-------|--------|---------|
-| `cluster_state` | ws_id, state, node_id, tokens, context_ratio, activity | Workstream state transition |
-| `ws_created` | ws_id, name, node_id | New workstream created |
-| `ws_closed` | ws_id | Workstream closed |
-| `ws_rename` | ws_id, name | Workstream renamed |
-
 ---
 
 ## ClusterCollector
 
-The collector (`turnstone/console/collector.py`) maintains an in-memory snapshot of all nodes and workstreams. Three daemon threads handle data acquisition:
+The collector (`turnstone/console/collector.py`) maintains an in-memory snapshot of all nodes and workstreams. Two daemon threads handle data acquisition:
 
-1. **Event subscriber** — subscribes to `{prefix}:events:cluster` via `RedisBroker.subscribe_cluster()`. Applies state changes, creates, closes, and renames to the in-memory model immediately.
+1. **Node discovery** — queries the `services` database table every 60 seconds. Adds newly discovered nodes, removes expired ones (stale heartbeats), emits `node_joined` / `node_lost` events to SSE listeners, and spawns/cancels SSE tasks for new/lost nodes.
 
-2. **Node discovery** — scans heartbeat keys every 15 seconds via `broker.list_nodes()`. Adds newly discovered nodes, removes expired ones, emits `node_joined` / `node_lost` events to SSE listeners.
-
-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.
+2. **SSE manager** — a single asyncio event loop on one thread multiplexes persistent SSE connections to all discovered nodes via `GET /v1/api/events/global`. Each connection receives a `node_snapshot` on connect (workstreams, health, aggregate) followed by real-time delta events (`ws_state`, `ws_created`, `ws_closed`, `ws_rename`, `health_changed`, `aggregate`). On disconnect, the node is marked unreachable and the connection is retried with exponential backoff (1s–30s). An `?expected_node_id=` query parameter provides identity verification against IP reuse (server returns 409 on mismatch).
 
 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.
 
@@ -70,7 +53,7 @@ All reads and writes to the node/workstream map are protected by a single `threa
 ### Scale Considerations
 
 - **50,000 workstreams** (1,000 nodes × 50 per node) at ~500 bytes each = ~25 MB in memory
-- **1,000 nodes** polled in parallel — fan-out concurrency is configurable via `cluster.node_fan_out_limit` (default 200), yielding 5 batches at ~100ms each = ~0.5 second poll cycle
+- **1,000 nodes** connected via persistent SSE — a single asyncio event loop multiplexes all connections with negligible overhead. Ensure `ulimit -n` >= 4096 for fd headroom
 - **Filtering and pagination** run in-memory on the full workstream list — sub-millisecond at this scale
 - **SSE fan-out** uses per-client queues (2,000 events) — backed-up clients get events dropped, not blocking
 - **Database** — for clusters sharing PostgreSQL, use [PgBouncer](pgbouncer.md) in transaction pooling mode
@@ -183,7 +166,7 @@ Full cluster state in a single response — all nodes with their workstreams plu
 
 ### `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.
+Create a new workstream on a target node. The console proxies the creation request to the target node's HTTP API. Requires `write` scope.
 
 Request:
 
@@ -197,9 +180,9 @@ Request:
 
 All fields are optional:
 - `node_id` — targeting mode:
-  - **omitted or `"auto"`** — console picks the reachable node with the most available capacity (max_ws - ws_total) and pushes to its directed queue.
-  - **`"pool"`** — pushes to the shared inbound queue; the next available bridge picks it up (true general-pool dispatch).
-  - **specific node ID** — pushes to that node's directed queue.
+  - **omitted or `"auto"`** — console picks the reachable node with the most available capacity (max_ws - ws_total) and proxies the request to it.
+  - **`"pool"`** — console picks a reachable node with available capacity using round-robin selection.
+  - **specific node ID** — proxies the request to that node directly.
 - `name` — workstream display name. Auto-generated if omitted.
 - `model` — model alias from the target node's registry. Uses the node's default model if omitted.
 
@@ -213,7 +196,7 @@ Response:
 }
 ```
 
-Creation is asynchronous — the response confirms the MQ message was dispatched. A `ws_created` event on the cluster SSE stream confirms the workstream was actually created.
+The response confirms the workstream creation request was proxied to the target node. A `ws_created` event on the cluster SSE stream confirms the workstream was actually created.
 
 ### `GET /v1/api/cluster/events`
 
@@ -395,10 +378,13 @@ Breadcrumb: `Cluster > Running` or `Cluster > db-west-04`. Server-side paginated
 
 Triggered by the "+ new" header button. A modal dialog with:
 
-- **Node selector** — dropdown with three targeting modes: "Auto (best available)" picks the node with the most headroom, "General pool (any node)" pushes to the shared queue for any bridge to pick up, or a specific node from the list (showing capacity).
+- **Node selector** — dropdown with three targeting modes: "Auto (best available)" picks the node with the most headroom, "General pool (any node)" picks a node with available capacity using round-robin, or a specific node from the list (showing capacity).
 - **Profile** — optional dropdown listing enabled skills. Applies the skill's model, auto-approve policy, token budget, and other behavioral settings at creation time.
 - **Name** — optional text input. Auto-generated if left empty.
 - **Model** — optional text input for a model alias from the target node's registry.
+- **Judge Model** — optional text input for the judge model alias (overrides the default judge model for this workstream).
+
+Keyboard shortcuts: Ctrl+Shift+R (refresh title), Ctrl+Shift+E (edit title), Ctrl+Shift+F (fork), Ctrl+Shift+X (delete). Press ? for full shortcut help.
 
 On submit, `POST /v1/api/cluster/workstreams/new` dispatches the creation request. A toast confirms success; the SSE stream delivers the `ws_created` event to update the dashboard.
 
@@ -410,10 +396,19 @@ The browser maintains a local `clusterState` object that mirrors the cluster sna
 
 Accessed via the "admin" button in the header (visible when authenticated
 with `approve` scope). Provides user, API token, channel link, MCP server,
-and skill management with 13 tabs (see also
-[Governance](governance.md) for
-the Roles, Policies, Skills, Usage, and Audit tabs, and
-[Settings](settings.md) for the database-backed configuration editor):
+and skill management with 18 tabs (Users, API Tokens, Channels, Schedules,
+Watches, Roles, Policies, Prompts, Judge, Skills, MCP Servers, Usage,
+Audit, Memories, Models, Nodes, Settings, TLS).  See also
+[Governance](governance.md) for the Roles, Policies, Skills, Usage, and
+Audit tabs, and [Settings](settings.md) for the database-backed
+configuration editor.
+
+The **Channels** tab links users to either a Discord or Slack account
+via a per-row channel-type selector.  The **Models** tab is a CRUD
+editor for `model_definitions`, the **Nodes** tab edits per-node
+metadata, and the **TLS** tab manages CA and leaf certificates for the
+internal mTLS fabric.  The **Settings** tab edits ConfigStore values
+live; edits apply without restart.
 
 **Users tab:**
 
@@ -482,17 +477,17 @@ to create the initial admin user and receive a JWT in one step. See
 
 ## Scheduled Tasks
 
-The console includes a background **TaskScheduler** daemon that creates workstreams on a timed basis via the MQ broker. It supports cron-based recurring schedules and one-shot `at` schedules.
+The console includes a background **TaskScheduler** daemon that creates workstreams on a timed basis via HTTP proxy to target nodes. It supports cron-based recurring schedules and one-shot `at` schedules.
 
 ### Architecture
 
 The scheduler runs as a daemon thread inside the console process. Every `check_interval` seconds (default 15) it:
 
-1. Acquires a distributed lock via Redis `SET NX EX` (prevents duplicate dispatch in multi-console deployments)
+1. Acquires a distributed lock via the `system_settings` table (prevents duplicate dispatch in multi-console deployments)
 2. Queries the storage backend for tasks whose `next_run <= now` and `enabled = true`
-3. Dispatches each due task as one or more `CreateWorkstreamMessage` via MQ
+3. Dispatches each due task as one or more workstream creation requests via HTTP proxy
 4. Updates `last_run` and computes the next `next_run` (or disables one-shot `at` tasks)
-5. Releases the lock via Lua script (safe conditional delete)
+5. Releases the lock
 
 Run history is automatically pruned (runs older than 90 days) approximately once per hour.
 
@@ -508,7 +503,7 @@ Run history is automatically pruned (runs older than 90 days) approximately once
 | Mode | Behavior |
 |------|----------|
 | `auto` | Picks the reachable node with the most available capacity |
-| `pool` | Pushes to the shared inbound queue (any bridge picks it up) |
+| `pool` | Picks a reachable node with available capacity using round-robin |
 | `all` | Fan-out to all reachable nodes (capped at `max_fan_out`, default 20) |
 | `<node_id>` | Targets a specific node by ID |
 
@@ -645,12 +640,6 @@ CLI flags for `turnstone-console`:
 |------|---------|-------------|
 | `--host` | `0.0.0.0` | Bind host |
 | `--port` | `8090` | HTTP port |
-| `--redis-host` | `localhost` | Redis host |
-| `--redis-port` | `6379` | Redis port |
-| `--redis-password` | `$REDIS_PASSWORD` | Redis password |
-| `--redis-db` | `0` | Redis DB |
-| `--poll-interval` | `10` | Node polling interval (seconds) |
-| `--auth-token` | `$TURNSTONE_AUTH_TOKEN` | Bearer token for server node communication and proxy |
 | `--log-level` | `INFO` | Log level |
 
 Config file (`~/.config/turnstone/config.toml`):
@@ -660,12 +649,6 @@ Config file (`~/.config/turnstone/config.toml`):
 host = "0.0.0.0"
 port = 8090
 url = "http://localhost:8090"   # used by CLI /cluster commands
-poll_interval = 10
-
-[redis]
-host = "localhost"
-port = 6379
-password = "my-redis-password"
 ```
 
 ---
@@ -673,17 +656,11 @@ password = "my-redis-password"
 ## Deployment
 
 ```bash
-# Start Redis
-redis-server
-
 # Start turnstone servers (one per node)
 turnstone-server --port 8080
 
-# Start bridges (one per server)
-turnstone-bridge --server-url http://localhost:8080 --node-id node-a
-
 # Start cluster console (one instance)
-turnstone-console --redis-host localhost --port 8090 --auth-token "$TURNSTONE_AUTH_TOKEN"
+turnstone-console --port 8090
 ```
 
 Open `http://localhost:8090` for the cluster dashboard. Create workstreams via the "+ new" button. Click any workstream to open the proxied server UI — no direct access to server ports required.

docs/coordinator-api-tour.md

@@ -0,0 +1,372 @@
+# Coordinator API tour
+
+Turnstone's **coordinator workstream** is a session hosted on the
+console whose job is to orchestrate other workstreams.  It runs an LLM
+that can spawn child workstreams on any node, watch their progress,
+wait for them to finish, steer them mid-flight, and tear them down.
+This doc walks the full lifecycle — one request, one response, and the
+relevant SSE events at each step.
+
+Aimed at integrators driving a coordinator from a custom UI or SDK
+without reverse-engineering the built-in console page.  The shapes
+here match the live OpenAPI spec served at `/openapi.json` and
+rendered at `/docs` on every `turnstone-console` process.  Every
+step references the operation id from that spec so doc updates track
+schema changes.
+
+> **Auth throughout.**  Every endpoint below sits behind bearer-token
+> auth and the `admin.coordinator` permission.  A session-scoped JWT
+> is minted per login (see [docs/oidc.md](oidc.md) / [docs/security.md](security.md));
+> a service token may call the read paths but destructive governance
+> paths (`/restrict`, `/stop_cascade`, `/close_all_children`) require
+> the explicit `admin.coordinator` grant — a service-token owner
+> match isn't enough.
+
+---
+
+## The 9 steps
+
+| # | Action                       | Operation                                                   | Operation id                                                |
+|---|------------------------------|-------------------------------------------------------------|-------------------------------------------------------------|
+| 1 | Create                       | `POST /v1/api/coordinator/new`                              | `v1_api_coordinator_new_post`                               |
+| 2 | Subscribe to events          | `GET /v1/api/coordinator/{ws_id}/events` (SSE)              | `v1_api_coordinator_{ws_id}_events_get`                     |
+| 3 | Send a user message          | `POST /v1/api/coordinator/{ws_id}/send`                     | `v1_api_coordinator_{ws_id}_send_post`                      |
+| 4 | Inspect children             | `GET /v1/api/coordinator/{ws_id}/children`                  | `v1_api_coordinator_{ws_id}_children_get`                   |
+| 5 | Inspect one workstream       | `GET /v1/api/cluster/ws/{ws_id}/detail`                     | `v1_api_cluster_ws_{ws_id}_detail_get`                      |
+| 6 | Wait for fan-out             | model-side tool `wait_for_workstream`                       | — (tool call, not HTTP)                                     |
+| 7 | Govern                       | `POST /v1/api/coordinator/{ws_id}/trust`                    | `v1_api_coordinator_{ws_id}_trust_post`                     |
+|   |                              | `POST /v1/api/coordinator/{ws_id}/restrict`                 | `v1_api_coordinator_{ws_id}_restrict_post`                  |
+|   |                              | `POST /v1/api/coordinator/{ws_id}/stop_cascade`             | `v1_api_coordinator_{ws_id}_stop_cascade_post`              |
+|   |                              | `POST /v1/api/coordinator/{ws_id}/close_all_children`       | `v1_api_coordinator_{ws_id}_close_all_children_post`        |
+| 8 | Approve / cancel             | `POST /v1/api/coordinator/{ws_id}/approve`                  | `v1_api_coordinator_{ws_id}_approve_post`                   |
+|   |                              | `POST /v1/api/coordinator/{ws_id}/cancel`                   | `v1_api_coordinator_{ws_id}_cancel_post`                    |
+| 9 | Close                        | `POST /v1/api/coordinator/{ws_id}/close`                    | `v1_api_coordinator_{ws_id}_close_post`                     |
+
+---
+
+## 1. Create a coordinator
+
+```http
+POST /v1/api/coordinator/new
+Content-Type: application/json
+Authorization: Bearer <token>
+
+{
+  "name": "release-coord",
+  "skill": "engineer-orchestrator",
+  "initial_message": "audit /auth for CSRF handling across all active routes"
+}
+```
+
+```http
+HTTP/1.1 201 Created
+Content-Type: application/json
+
+{"ws_id": "a1b2c3d4e5f6...", "name": "release-coord"}
+```
+
+All three body fields are optional — an empty body still creates a
+coordinator with an auto-generated name and no initial message.
+Returns **503** with a remediation message when the cluster isn't
+configured with a coordinator model; see
+[`coordinator.model_alias`](settings.md) to set one.
+
+**SSE implication:** the `ws_created` event fires on the cluster-wide
+stream (`/v1/api/cluster/events`) once the row is committed.  Per-ws
+subscribers (step 2) see the session warm up as token traffic starts.
+
+---
+
+## 2. Subscribe to the per-coordinator event stream
+
+```http
+GET /v1/api/coordinator/{ws_id}/events HTTP/1.1
+Accept: text/event-stream
+Authorization: Bearer <token>
+```
+
+One persistent SSE connection per browser tab / SDK caller — the
+console fans each event out to every listener queue (cap 500 events
+per queue, put_nowait drop on overflow).  Events come in flat JSON
+with a `type` field.  The recurring shapes a UI has to handle:
+
+| `type`              | Emitted when                                                                               | Payload highlights |
+|---------------------|--------------------------------------------------------------------------------------------|--------------------|
+| `thinking_start` / `thinking_stop` | Model has entered / exited a reasoning block                                | — |
+| `reasoning`         | Reasoning-token stream chunk (when the model exposes it)                                   | `text` |
+| `content`           | Assistant-content stream chunk                                                             | `text` |
+| `stream_end`        | End of a single provider stream                                                            | — |
+| `tool_result`       | A tool call completed (success or error)                                                   | `call_id`, `name`, `output`, `is_error?` |
+| `tool_output_chunk` | Streaming tool output (e.g. long bash command)                                             | `call_id`, `chunk` |
+| `approve_request`   | One or more tool calls need operator approval                                              | `items: [{call_id, header, preview, func_name, approval_label, needs_approval}]` |
+| `approval_resolved` | Operator answered the approval prompt                                                      | `approved`, `feedback` |
+| `state_change`      | Worker-thread state transition                                                             | `state` ∈ `running`, `thinking`, `attention`, `idle`, `error` |
+| `status`            | Token usage + context-window snapshot (fires on every streaming tick)                      | `prompt_tokens`, `completion_tokens`, `total_tokens`, `context_window`, `pct`, `effort`, `cache_creation_tokens`, `cache_read_tokens` |
+| `rename`            | Session's display name changed                                                             | `name` |
+| `intent_verdict`    | Intent judge produced a verdict on a pending tool call                                     | `risk_level`, `recommendation`, `reasons` |
+| `output_warning`    | Output guard flagged a tool result                                                         | `call_id`, `risk_level`, `flags` |
+| `child_ws_created`  | A direct child of this coord was just created (fan-out from the cluster bus)              | `child_ws_id`, `node_id`, `name`, `parent_ws_id` (`ws_id` in the envelope is always the coord's own id) |
+| `child_ws_state`    | A direct child transitioned state                                                          | `child_ws_id`, `state` |
+| `child_ws_closed`   | A direct child closed                                                                      | `child_ws_id` |
+| `child_ws_rename`   | A direct child's name changed                                                              | `child_ws_id`, `name` |
+| `wait_started` / `wait_progress` / `wait_ended` | `wait_for_workstream` tool lifecycle (see §6)                  | `call_id`, `ws_ids`, `elapsed`, `results`, `complete` |
+| `batch_started` / `batch_ended` | `spawn_batch` / `close_all_children` tool lifecycle                            | `call_id`, `op`, `total`/`succeeded`/`denied`/`closed`/`failed`/`skipped` |
+| `info` / `error`    | Operational messages                                                                       | `message` |
+
+**Reconnection contract:** a freshly-opened SSE connection receives
+the current snapshot of any pending tool approval (`approve_request`
+is re-sent if unresolved) and any in-flight `wait_*` / `batch_*`
+indicator — so a tab refresh mid-approval doesn't strand the
+operator.
+
+---
+
+## 3. Send the first user message
+
+```http
+POST /v1/api/coordinator/{ws_id}/send
+Content-Type: application/json
+
+{"message": "audit /auth for CSRF handling across all active routes"}
+```
+
+```http
+HTTP/1.1 200 OK
+{"status": "ok"}
+```
+
+The message is queued for the worker thread at its next tool-result
+seam (so you can send follow-ups mid-conversation without corrupting
+the in-progress turn).  On the SSE stream you'll see `state_change`
+→ `thinking_start` → streaming `reasoning` / `content` / `tool_result`
+events, finishing with `state_change → idle` or an
+`approve_request` when the model invokes a gated tool.
+
+---
+
+## 4. Inspect direct children
+
+```http
+GET /v1/api/coordinator/{ws_id}/children HTTP/1.1
+```
+
+```json
+{
+  "items": [
+    {"ws_id": "d4e5f6...", "name": "csrf-audit", "state": "running", "node_id": "gpu-3"},
+    {"ws_id": "e1f2a3...", "name": "xss-audit",  "state": "idle",    "node_id": "gpu-1"}
+  ],
+  "truncated": false
+}
+```
+
+The response key is `items`, not `children` — the endpoint shape
+follows the cluster-wide workstream-list idiom rather than the
+coordinator `list_workstreams` tool's (which uses `children`).
+Rows include every state stored for the parent (`running`, `idle`,
+`closed`, ...); the endpoint does not accept a state query param,
+so clients should inspect each row's `state` field and filter
+locally if they want to hide closed/deleted children.  Nested
+coordinator rows are dropped server-side so only interactive
+descendants appear.
+
+---
+
+## 5. Inspect one workstream (storage + live block + tail)
+
+```http
+GET /v1/api/cluster/ws/{ws_id}/detail?message_limit=20 HTTP/1.1
+```
+
+```json
+{
+  "persisted": { "ws_id": "...", "state": "running", "parent_ws_id": "...", "kind": "interactive", ... },
+  "live":      { "state": "thinking", "tokens": 12843, "activity": "...", "pending_approval": null },
+  "tail":      [ {"role": "assistant", "content": "...", "tokens": 128}, ... ]
+}
+```
+
+Works for any workstream the caller has `admin.cluster.inspect` on,
+not just children of a single coordinator — useful for a cluster
+admin panel watching multiple coordinators at once.  `live` is
+`null` when the owning node is unreachable or has dropped the row
+from its dashboard cache; callers should degrade gracefully, not
+treat it as an error.
+
+For fan-out views, prefer
+[`GET /v1/api/cluster/ws/live?ids=a,b,c`](bulk-endpoints.md) — it
+collapses N per-row round-trips into one, returning the live block
+for every id in a `{results, denied, truncated}` envelope.
+
+---
+
+## 6. Wait for fan-out (`wait_for_workstream`)
+
+`wait_for_workstream` is a **model-side tool**, not an HTTP endpoint
+— the coordinator's LLM invokes it with a list of child ws_ids, the
+session's worker thread blocks inside the tool, and a sequence of
+`wait_started` / `wait_progress` / `wait_ended` SSE events is emitted
+for the UI to drive a "waiting on N children" indicator.
+
+![wait_for_workstream sequence](diagrams/png/27-coordinator-wait-for-workstream.png)
+
+Key properties:
+
+- **Caps** — up to 32 ws_ids per call, up to 600 seconds per call.
+  A coordinator that needs to wait on more children re-invokes the
+  tool with a fresh timeout.
+- **Modes** — `mode="any"` returns as soon as one child reaches a
+  real terminal state (`idle` / `error` / `closed` / `deleted`);
+  `mode="all"` waits for every polled child.
+- **Progress throttling** — the poll loop runs every 500 ms but the
+  SSE emission is diff-on-state-change plus a 5-second heartbeat.  A
+  600 s wait generates O(dozens) of progress events, not 1200.
+- **Denied rows** — an id the caller doesn't own (cross-tenant) or a
+  missing row is reported as a `denied` state in the results dict;
+  `mode="any"` won't satisfy on a pure-denied list (the LLM should
+  treat it as a config error, not a completion).
+
+Prefer `wait_for_workstream` over polling `inspect_workstream` in a
+loop — a wait consumes one assistant turn regardless of how long the
+children take, whereas each `inspect_workstream` poll costs a full
+turn (plus judge, plus tokens).  On a fan-out of 3+ children this
+rounds to a 10× token-efficiency win.
+
+---
+
+## 7. Governance — trust, restrict, stop_cascade, close_all_children
+
+These four endpoints let an operator steer a live coordinator session
+mid-flight.  All four emit an audit event tagged
+`coordinator.<action>` via the dedicated audit executor so a cascade
+burst can't starve audit writes.
+
+### `POST /trust` — auto-approve own-subtree sends
+
+```json
+POST /v1/api/coordinator/{ws_id}/trust
+{"send": true}
+```
+
+Flips `trust_send=true` on the live session.  Subsequent
+`send_to_workstream` calls that target a ws_id in the coordinator's
+own subtree skip the approval prompt; foreign ws_ids and other tool
+calls still go through the normal flow.  Requires both
+`admin.coordinator` AND `coordinator.trust.send` permissions (the
+second grants a service token the opt-in it otherwise wouldn't get).
+
+### `POST /restrict` — revoke tool access mid-session
+
+```json
+POST /v1/api/coordinator/{ws_id}/restrict
+{"revoke": ["spawn_workstream", "delete_workstream"]}
+```
+
+Unions the names into the session's revoked-tools set.  Additive and
+idempotent — calling twice with overlapping lists converges to the
+union.  Revocations don't survive a session close/reopen; operators
+opt in per session.  Cap 256 tool names per request, 128 chars each.
+
+### `POST /stop_cascade` — cancel the subtree
+
+```json
+POST /v1/api/coordinator/{ws_id}/stop_cascade
+{}
+```
+
+Cancels the coordinator's in-flight generation AND dispatches
+`cancel_workstream` through the routing proxy for every direct
+child in the in-memory registry.  Returns:
+
+```json
+{"status": "ok", "cancelled": ["child-1", "child-3"], "failed": [], "skipped": ["child-2"]}
+```
+
+Response uses the [cascade-mutation bulk shape](bulk-endpoints.md):
+`cancelled` = accepted, `failed` = dispatch error worth retrying,
+`skipped` = upstream 404 (already gone — stale registry entry or
+the row was deleted between snapshot and dispatch).  Grandchildren
+aren't touched directly; they sit behind their parent's cancel and
+propagate via the child's SSE stream.
+
+### `POST /close_all_children` — soft-close the direct fan-out
+
+```json
+POST /v1/api/coordinator/{ws_id}/close_all_children
+{"reason": "audit round complete"}
+```
+
+Response:
+
+```json
+{"status": "ok", "closed": ["c-1", "c-2"], "failed": [], "skipped": []}
+```
+
+Soft-close cascade bounded by the same semaphore as `stop_cascade`.
+The `reason` (up to 512 chars) propagates into each closed child's
+audit + `workstream_config` for postmortem.  Unlike `stop_cascade`
+this does NOT recurse into grandchildren — the model-facing tool
+that pairs with this endpoint asks for a bounded teardown of the
+coordinator's own fan-out.  For a full-subtree teardown, use
+`stop_cascade`.
+
+See [bulk-endpoints.md](bulk-endpoints.md) for why both endpoints
+share the cascade-mutation shape and how it differs from the
+`spawn_batch` / `cluster/ws/live` shape.
+
+---
+
+## 8. Approve / cancel
+
+The `approve` endpoint is what resolves an `approve_request` SSE
+event.  The coordinator's worker thread is blocked inside
+`ui.approve_tools` waiting for this POST.
+
+```json
+POST /v1/api/coordinator/{ws_id}/approve
+{"approved": true, "feedback": null, "always": false}
+{"approved": false, "feedback": "spawn count looks too high — try 3 not 10"}
+{"approved": true, "feedback": null, "always": true}    // always-approve this tool name
+```
+
+`cancel` drops the in-flight generation but leaves the coordinator
+idle and open for a fresh `send`:
+
+```json
+POST /v1/api/coordinator/{ws_id}/cancel
+{}
+```
+
+---
+
+## 9. Close
+
+```json
+POST /v1/api/coordinator/{ws_id}/close
+{}
+```
+
+Soft-closes the session — state persists, children keep running (use
+`close_all_children` or `stop_cascade` first to wind them down), the
+worker thread exits, SSE streams send a final `stream_end` and
+disconnect.  The row is reopenable via
+`POST /v1/api/coordinator/{ws_id}/open` so long as it hasn't been
+deleted.
+
+---
+
+## Further reading
+
+- [coordinator-skills.md](coordinator-skills.md) — writing a skill
+  that runs on a coordinator session (orchestrator persona,
+  workflow patterns, `SkillKind` classifier).
+- [bulk-endpoints.md](bulk-endpoints.md) — the two bulk-shape
+  idioms (`{results, denied, truncated}` vs
+  `{<bucket>, failed, skipped}`) used by `cluster/ws/live`,
+  `spawn_batch`, `stop_cascade`, and `close_all_children`.
+- [architecture.md](architecture.md) — cluster-wide architecture
+  including how coordinator sessions fit next to node-hosted
+  interactive workstreams.
+- The live OpenAPI spec (`/openapi.json` on any console process)
+  and Swagger UI (`/docs`) — authoritative schemas for every
+  endpoint above.

docs/coordinator-skills.md

@@ -0,0 +1,321 @@
+# Writing a coordinator-specific skill
+
+Skills are prompt-level personas that steer a Turnstone session
+toward a narrow task.  Most skills target **interactive** sessions —
+the single-workstream "do this thing" surface where the model wields
+`bash`, `edit_file`, `web_fetch`, and the rest of the maker toolset.
+
+A **coordinator skill** is different.  It runs on a session whose job
+is to orchestrate other sessions.  The toolset is smaller and
+narrower, the persona is an orchestrator instead of a maker, and the
+success metric is "did the plan resolve" instead of "did the code
+compile".  This doc covers the differences a skill author has to
+care about.
+
+---
+
+## The two-surface model
+
+A row in `prompt_templates` carries a `kind` column (see
+[`turnstone/core/skill_kind.py`](../turnstone/core/skill_kind.py);
+migration 044 added the column).  Three values:
+
+| `SkillKind` enum     | Stored as                   | Visible in                                                                |
+|----------------------|-----------------------------|---------------------------------------------------------------------------|
+| `SkillKind.INTERACTIVE` | `"interactive"`          | Only the interactive-session activation path.  `list_skills` on a coord won't show it. |
+| `SkillKind.COORDINATOR` | `"coordinator"`          | Only the coordinator's `list_skills` tool.  Hidden from interactive activation pickers. |
+| `SkillKind.ANY`         | `"any"`                  | Both surfaces.  Default for legacy rows predating the classifier.        |
+
+The `kind` field is a `StrEnum` — drop-in ``str`` compatible — so
+DB rows, JSON payloads, and `==` comparisons all work without
+translation at the edge.
+
+When a coordinator calls `list_skills`, the SQL filter narrows to
+`kind IN ('coordinator', 'any')`.  When an interactive session picks
+a skill at activation, the filter narrows to
+`kind IN ('interactive', 'any')`.  A skill author tags once at
+creation; the two surfaces stay partitioned without any
+per-call filtering on the LLM side.
+
+**Tagging a new skill as coordinator-only** — set `kind` to
+`SkillKind.COORDINATOR` (or the literal string `"coordinator"`) when
+you POST to `/v1/api/admin/skills`.  Existing rows default to
+`SkillKind.ANY`; bump them to `COORDINATOR` if you've rewritten the
+prompt around the orchestrator toolset.
+
+---
+
+## Tool surface differences
+
+Coordinator sessions receive a **fixed** tool set, defined in
+`turnstone/core/tools.py` as `COORDINATOR_TOOLS`.  Nothing a skill
+or MCP config can do adds to it.  Current members:
+
+| Tool                      | Category        | Notes                                                               |
+|---------------------------|-----------------|---------------------------------------------------------------------|
+| `spawn_workstream`        | delegate        | Create one child.  Requires approval.                               |
+| `spawn_batch`              | delegate        | Create up to 10 children in one approval.  Partial-success shape.   |
+| `inspect_workstream`      | observe         | Read state + tail of one child.  Auto-approved (no mutation).       |
+| `list_workstreams`        | observe         | List the direct children (same shape as `/children` endpoint).      |
+| `wait_for_workstream`     | block           | Block until one/all listed children hit a terminal state.           |
+| `send_to_workstream`      | steer           | Queue a follow-up message to a running child.                        |
+| `close_workstream`        | wind-down       | Soft-close one child.  Requires approval.                           |
+| `close_all_children`      | wind-down       | Soft-close every direct child in one approval.  Partial-success shape. |
+| `cancel_workstream`       | wind-down       | Drop the in-flight generation; leaves child idle for a fresh send.  |
+| `delete_workstream`       | wind-down       | Hard-delete one child.  Requires approval.                          |
+| `list_nodes`              | discover        | Enumerate live cluster nodes + capabilities.                        |
+| `list_skills`             | discover        | Coordinator-visible skills only (SkillKind filter above).           |
+| `task_list`               | plan            | Orchestrator-only scratchpad.  Children don't see it.               |
+
+Explicitly **not** in the coordinator set:
+
+- `bash` / `edit_file` / `write_file` / `append_file` / `diff_file` — no local FS.
+- `read_file` / `search` — no local FS reads.
+- `web_fetch` / `web_search` — no direct web access.
+- `task_agent` / `plan_agent` — sub-agent tools are zeroed on coord sessions.
+- `memory` / `recall` / `notify` / `watch` / `read_resource` / `use_prompt` / `skill` — the orchestrator's "memory" is its children's outputs; these UX / persistence tools belong to interactive sessions.
+
+If your skill needs a coordinator to "run a command" or "read a
+file", write the delegate pattern instead: spawn a child with an
+appropriate skill, `wait_for_workstream`, then `inspect_workstream`
+for the output.  The coordinator stays the orchestrator.
+
+---
+
+## Persona differences
+
+Interactive skills compose on top of `base_interactive.md` — a
+"maker" persona: get the work done, use the tools, edit the code,
+close the loop.
+
+Coordinator skills compose on top of
+[`base_coordinator.md`](../turnstone/prompts/base_coordinator.md) —
+an "orchestrator" persona: decompose, delegate, monitor, synthesise.
+The base text is short but sets the tone every coordinator skill
+inherits:
+
+> You are a coordinator on a small, focused infrastructure team.
+> Your role is to orchestrate work across the cluster...  You do
+> not edit files, run shell commands, browse the web, or manipulate
+> the codebase directly.  Children do that.
+
+Write your skill's system prompt to *add* task-specific orchestration
+hints on top — don't re-explain the role, don't paste tool JSON,
+don't try to override the "no direct action" contract.  Keep the
+additions to: (a) the specific kind of work this skill delegates;
+(b) the preferred skill tags for children; (c) the synthesis shape
+the skill should end on.
+
+---
+
+## `task_list` integration
+
+`task_list` is the coordinator's scratchpad — a persisted, ordered
+list of rows with fields `{id, title, status, child_ws_id, created,
+updated}` that only this coordinator sees.  Children don't see it;
+the user does via the sidebar.  Five actions: `add`, `update`,
+`remove`, `reorder`, `list` (only `list` is auto-approved; the
+mutators go through the approval flow).
+
+The input schema refers to rows by `task_id`; the persisted row
+object exposes the same id as `id`.  The `child_ws_id` field is a
+free-form label the skill sets to link a task to a spawned
+workstream — it is NOT validated against the workstreams table, so
+a skill can set it to a placeholder before `spawn_workstream`
+returns or keep it pointing at a closed child for later audit.
+
+A skill's initial prompt can seed the task list by calling
+`task_list(action="add", title=...)` as its very first tool calls —
+the user gets a visible plan before any child is spawned, and the
+coordinator's future self has something concrete to iterate on.
+Status transitions (`pending` → `in_progress` → `done` / `blocked`)
+are the skill's main feedback loop: mutate the task when the child
+covering it finishes, not when the child starts.  Use
+`task_list(action="update", task_id=..., child_ws_id=<ws_id>)` to
+link a task to the child that owns it once spawn returns.
+
+A final gotcha: parallel tool dispatch does NOT serialise reads
+after writes in the same batch.  If a skill issues an `update` and
+a `list` in one parallel tool batch, the `list` response may reflect
+the pre-update state.  Dispatch mutate and list serially (one
+tool_use turn each) when the list must observe the mutation.
+
+Keep the tasks coarse-grained — one per child, roughly.  A 20-task
+list for a 3-child fan-out is noise; a 1-task list for a 5-child
+fan-out loses the plan.  The sidebar renders tasks as the operator's
+mental model of "what the coord thinks it's doing".
+
+---
+
+## Referencing children by `ws_id`
+
+Every ws_id returned by `spawn_workstream` / `spawn_batch` is a
+**full 32-char hex string**.  The skill's system prompt must not
+invent ws_ids — a model that hallucinates `"child-1"` or `"ws-abc"`
+hits the tenant guard in `CoordinatorClient._is_own_subtree`, which
+validates ws_id against `parent_ws_id=coord_ws_id` AND
+`user_id=owner` in storage.  The rejection shape varies by tool:
+
+- **Mutating ops** (`send_to_workstream`, `close_workstream`,
+  `cancel_workstream`, `delete_workstream`) return
+  `{"error": "workstream not in coordinator subtree: <ws_id>", "status": 404}`
+  — the skill should treat this as a tool error, not an empty result.
+- **`inspect_workstream`** returns `{"error": "workstream not found: <ws_id>"}`
+  (same shape as a genuinely missing row, so the guard can't be
+  used as an existence oracle).
+- **`wait_for_workstream`** reports the offending id with
+  `state="denied"` in its `results` dict; `mode="any"` won't
+  satisfy on a pure-denied list, so a hallucinated id won't trick
+  the wait into reporting "complete".
+
+Pattern: capture each spawn result in the next tool call's input.
+The JSON tool-result carries `{"ws_id": "...", "name": "...",
+"node_id": "...", "status": 200}`; the model should extract the
+ws_id and pass it to `inspect_workstream` / `wait_for_workstream` /
+`send_to_workstream` / `close_workstream` verbatim.
+
+A UI that wants human-readable identifiers should render the `name`
+field and keep the ws_id as the click-through key.
+
+---
+
+## `wait_for_workstream` vs `inspect_workstream`
+
+Two distinct semantics, different cost profiles:
+
+- **`wait_for_workstream(ws_ids=[...], timeout=60, mode="any")`** —
+  blocks inside a single tool call until one (or all, for `mode="all"`)
+  of the listed children reaches a terminal state (`idle`, `error`,
+  `closed`, `deleted`).  The worker thread blocks up to `timeout`
+  seconds; the assistant turn remains a single round-trip regardless
+  of how long the wait actually takes.  Prefer this for "the plan
+  needs child X to finish before the next step."
+- **`inspect_workstream(ws_id=...)`** — single read of the child's
+  state + tail.  Costs a full assistant turn (judge, tokens, stream).
+  Prefer this for "what does the final message say?" after the child
+  has already resolved (via `wait_for_workstream` or a known
+  transition).
+
+Rule of thumb: wait once for a fan-out, then inspect once per
+child for the content.  A loop of inspect-every-few-seconds is a
+token-burning antipattern — on 3+ children it rounds to a 10×
+efficiency hit over a wait+inspect pair.
+
+---
+
+## Common coordinator patterns
+
+Three patterns cover most coordinator skills.  Pick the one that
+matches the task, or combine them deliberately.
+
+### Pattern 1 — delegate-and-summarise
+
+One specialist child, one focused brief, one synthesis message back
+to the user.  Appropriate when the user's request is "run the thing
+and tell me what happened" and the work fits in one workstream.
+
+```
+task_list(action='add', title='audit /auth for CSRF')
+spawn_workstream(skill='engineer', initial_message='audit /auth ...')
+wait_for_workstream(ws_ids=[<child>], timeout=300)
+inspect_workstream(ws_id=<child>)
+→ synthesise the final message into a user-facing response
+task_list(action='update', task_id='t_01', status='done')
+close_workstream(ws_id=<child>, reason='audit complete')
+```
+
+### Pattern 2 — fan-out-and-synthesise
+
+N children running in parallel, each with a distinct brief, all
+waited-on together, then synthesised.  Appropriate when the user's
+request naturally decomposes into independent subtasks.
+
+```
+task_list seeds:
+  t_01 benchmark Anthropic 4.7 latency on summarisation
+  t_02 benchmark OpenAI GPT-5.2 latency on summarisation
+  t_03 benchmark Gemini 2.5 latency on summarisation
+spawn_batch(children=[...3 briefs...])
+wait_for_workstream(ws_ids=[c1, c2, c3], mode='all', timeout=600)
+inspect_workstream(ws_id=c1); ...(c2); ...(c3)
+→ synthesise head-to-head comparison
+task_list → all done
+close_all_children(reason='benchmark complete')
+```
+
+Prefer `spawn_batch` over 3 individual `spawn_workstream` calls —
+one approval instead of three, one audit trail, deterministic
+sibling ordering.  Pair with `wait_for_workstream(mode='all')` and
+`close_all_children(reason=...)` to wind the fan-out down in one
+approval each.
+
+### Pattern 3 — plan-then-delegate
+
+The coordinator first uses its own reasoning to carve the plan,
+records it in `task_list`, then spawns children that each own one
+task.  Appropriate when the user's request is "figure out how to X"
+and the coordinator's planning step is itself valuable.
+
+```
+→ coord reasons about the shape of the work
+task_list(action='add', title='...') × N   # the plan, visible in the sidebar
+for task in tasks:
+    spawn_workstream(skill=..., initial_message=task.brief)
+    task_list(action='update', task_id=task.id, notes='ws=<child_ws_id>')
+wait_for_workstream(ws_ids=[...], mode='all', timeout=...)
+for child in children:
+    inspect_workstream(ws_id=child)
+    task_list(action='update', task_id=..., status='done', notes='result summary')
+→ synthesise
+```
+
+The key distinction from Pattern 2: the plan is an artifact the user
+can see and interact with (via the sidebar).  If the coordinator's
+reasoning-pass was wrong about the decomposition, the user can
+course-correct before any child runs.
+
+---
+
+## Testing a coordinator skill
+
+Coordinator sessions are hosted on the console, not on a node.
+Integration tests that drive a real coord session live under
+`tests/test_coordinator_end_to_end.py` — they spin a console with
+an in-memory SQLite backend and a fake upstream node, then drive
+the session through its HTTP surface.
+
+For a new coordinator skill:
+
+1. Write the skill prompt as a string and pass it to the
+   `coord_session` fixture's `skill=` kwarg (see
+   `tests/test_coordinator_tools.py` for the pattern).
+2. Build a small fake cluster: one node + two children via
+   `mgr.register_children(coord.id, ["child-1", "child-2"])`.
+3. Drive the session with seeded tool_call dicts matching the
+   provider layer's shape.  The unit-level tests in
+   `tests/test_coordinator_tools.py` show the helper (`_tc(name,
+   args, call_id)`).
+4. Assert the skill's decision shape — which tools fire in what
+   order, what the task_list looks like at the end, which
+   `_error` reasons appear on the denied-path.
+
+A full end-to-end test isn't required for every skill; a
+prepare-step unit test that asserts "given this initial message, the
+first tool call is X with Y args" is usually sufficient to catch
+persona drift without a real LLM in the loop.
+
+---
+
+## Further reading
+
+- [coordinator-api-tour.md](coordinator-api-tour.md) — the HTTP
+  surface every coordinator skill indirectly drives.
+- [bulk-endpoints.md](bulk-endpoints.md) — the response shape
+  `spawn_batch` and `close_all_children` use, so your skill can
+  parse results / denied arrays correctly.
+- [governance.md](governance.md) — the broader governance surface
+  (`/trust`, `/restrict`, `/stop_cascade`, role-based permissions)
+  that wraps every coord session.
+- [settings.md](settings.md) — `coordinator.model_alias` and
+  `coordinator.reasoning_effort` settings that gate which LLM runs
+  the coordinator session at all.

docs/design/consistent-hash-ring.md

@@ -0,0 +1,162 @@
+# Consistent Hash Ring — Reference Design
+
+**Status**: Reference — alternative routing strategy
+
+Live routing uses **rendezvous (HRW) hashing** in
+`turnstone/core/rendezvous.py` and `turnstone/console/router.py`.  This
+document captures a vnode-ring approach as a reference for future
+evaluation if the cluster outgrows rendezvous's O(N)-per-route
+characteristic.
+
+The FNV-1a-32 hash function specified below is bit-identical to the
+hash used by the live rendezvous implementation; cross-language clients
+can rely on these test vectors.
+
+## When the ring approach becomes interesting
+
+The vnode ring becomes preferable to rendezvous hashing when:
+
+- Cluster size grows large (50+ nodes) and the per-route O(N) hash
+  computation becomes visible against downstream HTTP cost.
+- Decentralised routing is needed (each node computes the ring locally,
+  no central console required).
+- A precomputed flat-array lookup is desired so the routing hot path
+  avoids hashing entirely.
+
+## Algorithm
+
+### Hash function: FNV-1a (32-bit)
+
+```python
+def fnv1a_32(data: bytes) -> int:
+    """FNV-1a 32-bit hash.
+
+    Basis: 0x811C9DC5, Prime: 0x01000193.
+    XOR each byte, then multiply by prime (masked to 32 bits).
+    """
+    h = 0x811C9DC5
+    for b in data:
+        h ^= b
+        h = (h * 0x01000193) & 0xFFFFFFFF
+    return h
+```
+
+Known test vectors:
+- `fnv1a_32(b"")` = `0x811C9DC5` (basis value)
+- `fnv1a_32(b"foobar")` = `0xBF9CF968`
+
+Cross-language implementations:
+- **Python**: loop above (no dependencies)
+- **Go**: same algorithm with `uint32` arithmetic
+- **TypeScript**: same algorithm with `>>> 0` for unsigned 32-bit
+
+### Virtual nodes
+
+Each physical node with weight `w` gets `w * 150` virtual positions on a
+16-bit ring (65536 positions). Virtual node `i` of physical node `N` is
+placed at:
+
+```
+position = fnv1a_32(f"{N.node_id}:{i}".encode()) % 65536
+```
+
+With 150 vnodes per unit weight:
+- 2 equal-weight nodes: ~50/50 split (measured: 38-62% range due to
+  hash variance, stddev ~3% with large vnode counts)
+- 3 nodes at weights 2:1:1: ~50/25/25 (within 10% tolerance)
+
+### Lookup
+
+```python
+def owner(bucket: int) -> str:
+    """O(log n) bisect-right walk to find the next virtual node clockwise."""
+    idx = bisect_right(positions, bucket)
+    if idx >= len(positions):
+        idx = 0  # wrap around
+    return vnode_map[positions[idx]]
+```
+
+### Stability properties
+
+The consistent hash ring guarantees:
+- **Node addition**: adding a node moves at most `1/N` of buckets (where N
+  is the new node count). Other nodes' buckets are unaffected.
+- **Node removal**: only the removed node's buckets are reassigned. Buckets
+  owned by surviving nodes don't move.
+- **Determinism**: same membership list always produces the same ring.
+  No coordination needed between processes.
+
+### Full assignment precomputation
+
+```python
+def assignments() -> list[tuple[int, str]]:
+    """Compute all 65536 bucket-to-node mappings."""
+    return [(b, owner(b)) for b in range(65536)]
+```
+
+This produces a complete assignment table that can be loaded into a flat
+array for O(1) request-time lookup. The ring itself is never consulted
+on the hot path.
+
+## Data structures
+
+```python
+@dataclass(frozen=True, slots=True)
+class RingNode:
+    node_id: str
+    url: str
+    weight: int = 1
+
+class HashRing:
+    """Immutable consistent hash ring. Thread-safe (no mutable state)."""
+
+    def __init__(self, nodes: Sequence[RingNode], vnodes_per_unit: int = 150):
+        # Validate no duplicate node_ids
+        # Build sorted array of (position, node_id) tuples
+        # positions[i] = fnv1a_32(f"{node_id}:{i}".encode()) % RING_SIZE
+
+    def owner(self, bucket: int) -> RingNode | None:
+        # bisect_right + wrap
+
+    @property
+    def version(self) -> int:
+        # Deterministic hash of membership: fnv1a_32 of sorted node_id:weight pairs
+
+    def assignments(self) -> list[tuple[int, str]]:
+        # Precompute all 65536 bucket assignments
+```
+
+## Comparison with rendezvous (HRW) hashing
+
+| Aspect | Rendezvous (live) | Consistent hash ring (this doc) |
+|--------|-------------------|---------------------------------|
+| Per-route cost | O(N) hash computes | O(log V) bisect against precomputed array |
+| Seeding | None — pure function | Build vnode array on every membership change |
+| Node addition | Pure function moves ~1/N keys | Ring moves ~1/N buckets |
+| Node removal | Surviving nodes' keys unchanged | Surviving nodes' buckets unchanged |
+| Decentralised | Yes — pure function over services | Yes — each node computes locally |
+| Persistent state | None | None on the hot path; precomputed array in memory |
+| Complexity | ~20 LOC | Virtual-node construction + bisect |
+
+## Test vectors
+
+For cross-language implementation validation:
+
+```json
+{
+  "fnv1a_32": [
+    {"input": "", "output": 2166136261},
+    {"input": "foobar", "output": 3215766888}
+  ],
+  "bucket_of": [
+    {"ws_id": "a3f100000000000000000000000000000", "bucket": 41969},
+    {"ws_id": "00000000000000000000000000000000", "bucket": 0},
+    {"ws_id": "ffff0000000000000000000000000000", "bucket": 65535}
+  ],
+  "ring_single_node": {
+    "nodes": [{"node_id": "n1", "weight": 1}],
+    "vnodes_per_unit": 150,
+    "expected_n1_buckets": 65536
+  }
+}
+```

docs/diagrams/01-system-context.puml

@@ -13,24 +13,22 @@ cloud "LLM Providers" as llm {
     component [OpenAI-compatible API\n(OpenAI, vLLM, llama.cpp)] as llm_openai
     component [Anthropic Messages API] as llm_anthropic
 }
-database "Redis" as redis
 database "SQLite\n(.turnstone.db)" as sqlite
 
 ' Turnstone System Boundary
 package "Turnstone Platform" {
     component [turnstone\n(CLI)] as cli <<entry point>>
     component [turnstone-server\n(HTTP + SSE)] as server <<entry point>>
-    component [turnstone-bridge\n(Queue ↔ HTTP)] as bridge <<service>>
-    component [turnstone-console\n(Dashboard)] as console <<service>>
+    component [turnstone-console\n(Dashboard + Router)] as console <<service>>
     component [turnstone-eval\n(Headless)] as eval <<entry point>>
-    component [turnstone-sim\n(Simulator)] as sim <<service>>
+    component [turnstone-channel\n(Channel Gateway)] as channel <<service>>
 }
 
 ' User connections
 cli_user --> cli : stdin / stdout
 browser_user --> server : HTTP + SSE\n(port 8080)
 browser_user --> console : HTTP + SSE\n(port 8090)
-ext_client --> redis : Redis LIST\n(push commands)
+ext_client --> server : HTTP + SSE\n(SDK / API)
 eval_user --> eval : Python API
 
 ' Internal connections
@@ -43,26 +41,16 @@ server --> sqlite : SQLite
 eval --> llm : LLM Provider API\n(non-streaming)
 eval --> sqlite : SQLite
 
-bridge --> server : HTTP REST\n(POST /v1/api/send, etc.)
-bridge <-- server : SSE\n(GET /v1/api/events)
-bridge --> redis : Redis LIST + PUBSUB\n+ STRING (routing, heartbeats)
+console --> server : HTTP proxy\n(hash-ring bucket lookup,\nproxy /node/{id}/* traffic)
 
-console --> redis : Redis PUBSUB + STRING + LIST\n(cluster events, heartbeats,\nworkstream creation commands)
-console --> server : HTTP polling + reverse proxy\n(GET /v1/api/dashboard,\nproxy /node/{id}/* traffic)
-
-sim --> redis : Redis LIST + PUBSUB\n+ STRING (heartbeats)
+channel --> server : HTTP + SSE\n(POST /v1/api/send,\nGET /v1/api/events)
 
 ' Notes
-note right of sim
-  Simulator replaces Server+Bridge
-  with lightweight SimNodes that
-  publish to the same Redis channels.
-end note
-
-note right of redis
-  Shared message broker:
-  - LIST: command queues
-  - STRING: heartbeats, routing
-  - PUBSUB: event broadcast
+note right of console
+  Multi-node router:
+  - Hash-ring bucket lookup
+  - Proxies create/send/approve
+  - Direct SSE from client to node
+  - HTTP polling for dashboard
 end note
 @enduml

docs/diagrams/02-package-structure.puml

@@ -6,13 +6,12 @@ title Turnstone — Package & Module Structure
 skinparam component {
     BackgroundColor<<entry>> #B8D4E3
     BackgroundColor<<core>> #C8E6C9
-    BackgroundColor<<mq>> #FFE0B2
-    BackgroundColor<<sim>> #E1BEE7
     BackgroundColor<<console>> #B2EBF2
     BackgroundColor<<ui>> #F0F4C3
     BackgroundColor<<artifact>> #ECEFF1
     BackgroundColor<<sdk>> #FFCDD2
     BackgroundColor<<api>> #D1C4E9
+    BackgroundColor<<channel>> #FFE0B2
 }
 
 ' Entry points
@@ -20,13 +19,14 @@ package "Entry Points" <<Rectangle>> {
     component [cli.py\nturnstone] as cli <<entry>>
     component [server.py\nturnstone-server] as server <<entry>>
     component [eval.py\nturnstone-eval] as eval <<entry>>
-    component [chat.py\n(re-exports)] as chat <<entry>>
+    component [admin.py\nturnstone-admin] as admin <<entry>>
+    component [bootstrap.py\nturnstone-bootstrap] as bootstrap <<entry>>
 }
 
 ' Core engine
 package "turnstone/core/" <<Rectangle>> {
     component [session.py\nChatSession, SessionUI] as session <<core>>
-    component [providers/\nLLMProvider, OpenAI, Anthropic] as providers <<core>>
+    component [providers/\nLLMProvider, OpenAI, Anthropic, Google] as providers <<core>>
     component [workstream.py\nWorkstreamManager] as workstream <<core>>
     component [tools.py\nTool loader] as tools <<core>>
     component [memory.py\nPersistence facade] as memory <<core>>
@@ -45,23 +45,12 @@ package "turnstone/core/" <<Rectangle>> {
     component [model_registry.py\nModelRegistry] as registry <<core>>
 }
 
-' MQ subsystem
-package "turnstone/mq/" <<Rectangle>> {
-    component [protocol.py\n28 message types] as protocol <<mq>>
-    component [broker.py\nMessageBroker, RedisBroker] as broker <<mq>>
-    component [bridge.py\nturnstone-bridge] as bridge <<mq>>
-    component [client.py\nTurnstoneClient] as client <<mq>>
-}
-
-' Simulator
-package "turnstone/sim/" <<Rectangle>> {
-    component [cluster.py\nSimCluster] as simcluster <<sim>>
-    component [node.py\nSimNode, SimWorkstream] as simnode <<sim>>
-    component [engine.py\nSimEngine] as simengine <<sim>>
-    component [scenario.py\n5 scenarios] as scenario <<sim>>
-    component [sim/config.py\nSimConfig] as simconfig <<sim>>
-    component [sim/metrics.py\nSim metrics] as simmetrics <<sim>>
-    component [sim/cli.py\nturnstone-sim] as simcli <<sim>>
+' Channels
+package "turnstone/channels/" <<Rectangle>> {
+    component [_routing.py\nChannelRouter] as router <<channel>>
+    component [discord/bot.py\nDiscordBot] as discordbot <<channel>>
+    component [slack/bot.py\nSlackBot (Socket Mode)] as slackbot <<channel>>
+    component [cli.py\nturnstone-channel] as gateway <<channel>>
 }
 
 ' Console
@@ -125,7 +114,8 @@ eval --> memory
 eval --> config
 eval --> tools
 
-chat --> session
+admin --> auth
+bootstrap --> providers
 
 ' Core internal deps
 session --> providers
@@ -146,35 +136,19 @@ mcp --> config
 registry --> config
 tools --> schemas
 
-' MQ dependencies
-bridge --> protocol
-bridge --> broker
-bridge --> config
-client --> protocol
-client --> broker
-
-' Sim dependencies
-simcli --> simcluster
-simcli --> simconfig
-simcli --> scenario
-simcluster --> simnode
-simcluster --> broker
-simcluster --> simmetrics
-simcluster --> simconfig
-simnode --> simengine
-simnode --> protocol
-simnode --> simconfig
-simnode --> simmetrics
-scenario --> broker
-scenario --> protocol
-scenario --> simconfig
-scenario --> simmetrics
+' Channel dependencies
+gateway --> discordbot
+gateway --> slackbot
+gateway --> router
+discordbot --> sdkserver : HTTP + SSE
+slackbot --> sdkserver : HTTP + SSE
+router --> storage : channel_routes
 
 ' Console dependencies
 consoleserver --> collector
 consoleserver --> config
 consoleserver --> auth
-collector --> broker
+collector --> server : HTTP polling
 
 ' API dependencies
 serverspec --> openapi

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

@@ -103,6 +103,18 @@ class "AnthropicProvider" as AnthropicProv {
     core/providers/_anthropic.py
 }
 
+class "GoogleProvider" as GoogleProv {
+    + provider_name: str
+    + get_capabilities(model) -> ModelCapabilities
+    --
+    Extends OpenAIChatCompletionsProvider
+    for Gemini /v1beta/openai/ endpoint.
+    Single default ModelCapabilities
+    (2M context, 65K output).
+    --
+    core/providers/_google.py
+}
+
 ' ModelCapabilities
 class "ModelCapabilities" as ModelCaps <<frozen>> {
     + context_window: int
@@ -283,7 +295,7 @@ class "ModelRegistry" as ModelReg {
     --
     Thread-safe lazy client + provider
     creation. Loaded by load_model_registry()
-    from CLI args + [models.*] config.
+    from DB + [models.*] config + CLI args.
     --
     core/model_registry.py
 }
@@ -294,6 +306,9 @@ class "ModelConfig" as ModelCfg <<frozen>> {
     + base_url: str
     + model: str
     + context_window: int
+    + temperature: float | None
+    + max_tokens: int | None
+    + reasoning_effort: str | None
 }
 
 ' Circuit breaker state
@@ -360,6 +375,7 @@ SessionUI <|.. NullUI
 
 LLMProvider <|.. OpenAIProv
 LLMProvider <|.. AnthropicProv
+OpenAIProv <|-- GoogleProv
 
 ChatSession --> SessionUI : uses
 ChatSession --> LLMProvider : delegates LLM calls

docs/diagrams/06-mq-protocol.puml

@@ -1,265 +0,0 @@
-@startuml
-!theme plain
-title Turnstone — Message Queue Protocol Types
-skinparam classAttributeIconSize 0
-skinparam packageStyle rectangle
-skinparam packageBorderThickness 2
-
-package "Inbound Messages (Client → Bridge)" as InPkg #FFF3E0 {
-
-    abstract class "InboundMessage" as IM {
-        + type: str
-        + correlation_id: str  {auto: uuid4().hex[:12]}
-        + timestamp: float  {auto: time.time()}
-        --
-        + to_json() → str
-        + {static} from_json(raw) → InboundMessage
-    }
-
-    class SendMessage {
-        type = "send"
-        --
-        + ws_id: str
-        + message: str
-        + auto_approve: bool = False
-        + auto_approve_tools: list[str] = []
-        + name: str = ""
-        + target_node: str = ""
-    }
-
-    class ApproveMessage {
-        type = "approve"
-        --
-        + ws_id: str
-        + request_id: str
-        + approved: bool = True
-        + feedback: str | None
-        + always: bool = False
-    }
-
-    class PlanFeedbackMessage {
-        type = "plan_feedback"
-        --
-        + ws_id: str
-        + request_id: str
-        + feedback: str
-    }
-
-    class CommandMessage {
-        type = "command"
-        --
-        + ws_id: str
-        + command: str
-    }
-
-    class CreateWorkstreamMessage {
-        type = "create_workstream"
-        --
-        + name: str = ""
-        + auto_approve: bool = False
-        + auto_approve_tools: list[str] = []
-        + target_node: str = ""
-        + initial_message: str = ""
-        + skill: str = ""
-        + user_id: str = ""
-    }
-
-    class CloseWorkstreamMessage {
-        type = "close_workstream"
-        --
-        + ws_id: str
-    }
-
-    class ListWorkstreamsMessage {
-        type = "list_workstreams"
-    }
-
-    class HealthMessage {
-        type = "health"
-    }
-
-    class ListNodesMessage {
-        type = "list_nodes"
-    }
-
-    class CancelMessage {
-        type = "cancel"
-        --
-        + ws_id: str
-    }
-
-    IM <|-- SendMessage
-    IM <|-- ApproveMessage
-    IM <|-- PlanFeedbackMessage
-    IM <|-- CommandMessage
-    IM <|-- CreateWorkstreamMessage
-    IM <|-- CloseWorkstreamMessage
-    IM <|-- ListWorkstreamsMessage
-    IM <|-- HealthMessage
-    IM <|-- ListNodesMessage
-    IM <|-- CancelMessage
-}
-
-package "Outbound Events (Bridge → Client)" as OutPkg #E3F2FD {
-
-    abstract class "OutboundEvent" as OE {
-        + type: str
-        + ws_id: str
-        + correlation_id: str
-        + timestamp: float
-        --
-        + to_json() → str
-        + {static} from_json(raw) → OutboundEvent
-    }
-
-    package "Streaming" #BBDEFB {
-        class ContentEvent {
-            type = "content"
-            + text: str
-        }
-        class ReasoningEvent {
-            type = "reasoning"
-            + text: str
-        }
-        class StreamEndEvent {
-            type = "stream_end"
-        }
-    }
-
-    package "Tools" #C8E6C9 {
-        class ToolInfoEvent {
-            type = "tool_info"
-            + items: list
-        }
-        class ApprovalRequestEvent {
-            type = "approval_request"
-            + items: list
-            ..
-            correlation_id = request_id
-        }
-        class ToolOutputChunkEvent {
-            type = "tool_output_chunk"
-            + call_id: str
-            + chunk: str
-        }
-        class ToolResultEvent {
-            type = "tool_result"
-            + call_id: str
-            + name: str
-            + output: str
-            + is_error: bool
-        }
-        class PlanReviewEvent {
-            type = "plan_review"
-            + content: str
-        }
-    }
-
-    package "Status" #FFF9C4 {
-        class AckEvent {
-            type = "ack"
-            + status: str
-            + detail: str
-        }
-        class StatusEvent {
-            type = "status"
-            + prompt_tokens: int
-            + completion_tokens: int
-            + total_tokens: int
-            + context_window: int
-            + pct: float
-            + effort: str
-            + cache_creation_tokens: int
-            + cache_read_tokens: int
-        }
-        class StateChangeEvent {
-            type = "state_change"
-            + state: str
-        }
-        class TurnCompleteEvent {
-            type = "turn_complete"
-            + content: str
-        }
-    }
-
-    package "Lifecycle" #F8BBD0 {
-        class WorkstreamCreatedEvent {
-            type = "ws_created"
-            + name: str
-        }
-        class WorkstreamClosedEvent {
-            type = "ws_closed"
-        }
-        class WorkstreamListEvent {
-            type = "ws_list"
-            + workstreams: list
-        }
-        class WorkstreamRenameEvent {
-            type = "ws_rename"
-            + name: str
-        }
-    }
-
-    package "System" #E0E0E0 {
-        class HealthResponseEvent {
-            type = "health_response"
-            + data: dict
-        }
-        class ErrorEvent {
-            type = "error"
-            + message: str
-        }
-        class InfoEvent {
-            type = "info"
-            + message: str
-        }
-        class NodeListEvent {
-            type = "node_list"
-            + nodes: list
-        }
-        class ClusterStateEvent {
-            type = "cluster_state"
-            + state: str
-            + node_id: str
-            + tokens: int
-            + context_ratio: float
-            + activity: str
-            + activity_state: str
-        }
-    }
-
-    OE <|-- ContentEvent
-    OE <|-- ReasoningEvent
-    OE <|-- StreamEndEvent
-    OE <|-- ToolInfoEvent
-    OE <|-- ApprovalRequestEvent
-    OE <|-- ToolResultEvent
-    OE <|-- PlanReviewEvent
-    OE <|-- AckEvent
-    OE <|-- StatusEvent
-    OE <|-- StateChangeEvent
-    OE <|-- TurnCompleteEvent
-    OE <|-- WorkstreamCreatedEvent
-    OE <|-- WorkstreamClosedEvent
-    OE <|-- WorkstreamListEvent
-    OE <|-- WorkstreamRenameEvent
-    OE <|-- HealthResponseEvent
-    OE <|-- ErrorEvent
-    OE <|-- InfoEvent
-    OE <|-- NodeListEvent
-    OE <|-- ClusterStateEvent
-}
-
-SendMessage -[hidden]down- OE
-
-note bottom of IM
-  **Deserialization**: Strict type-dispatch via _INBOUND_REGISTRY.
-  Unknown type raises ValueError.
-end note
-
-note bottom of OE
-  **Deserialization**: Lenient type-dispatch via _OUTBOUND_REGISTRY.
-  Unknown type falls back to base OutboundEvent.
-end note
-
-@enduml

docs/diagrams/07-message-routing.puml

@@ -1,105 +0,0 @@
-@startuml
-!theme plain
-title Turnstone — Multi-Node Message Routing
-
-skinparam sequenceArrowThickness 1.5
-
-participant "TurnstoneClient" as Client
-collections "Redis" as Redis
-participant "Bridge-A\n(node_id: nodeA)" as BridgeA
-participant "Bridge-B\n(node_id: nodeB)" as BridgeB
-participant "Server-A" as ServerA
-
-== Scenario A: New Message — No Workstream Affinity ==
-
-Client -> Redis : RPUSH turnstone:inbound\n{type:"send", message:"...", ws_id:""}
-note right of Redis : Shared queue — any bridge can pick up
-
-BridgeA -> Redis : BLPOP [turnstone:inbound:nodeA,\n         turnstone:inbound]
-Redis --> BridgeA : SendMessage (from shared queue)
-
-BridgeA -> ServerA : POST /v1/api/workstreams/new\n{name:"", auto_approve:false}
-ServerA --> BridgeA : {ws_id:"abc12345", name:"ws-abc1"}
-
-BridgeA -> Redis : SET turnstone:ws:abc12345 "nodeA"
-note right : Register workstream ownership
-
-BridgeA -> ServerA : GET /v1/api/events?ws_id=abc12345
-note right : Start per-WS SSE thread
-
-BridgeA -> Redis : PUBLISH turnstone:events:global\nWorkstreamCreatedEvent
-
-BridgeA -> Redis : PUBLISH turnstone:events:cluster\nClusterStateEvent(ws_id, state:"idle", node_id:"nodeA")
-
-BridgeA -> ServerA : POST /v1/api/send\n{message:"...", ws_id:"abc12345"}
-ServerA --> BridgeA : {status:"ok"}
-
-BridgeA -> Redis : PUBLISH turnstone:events:abc12345\nAckEvent(status:"ok")
-
-... SSE events flow: content, tool_output_chunk, tool_result, status, state_change ...
-
-BridgeA -> Redis : PUBLISH turnstone:events:abc12345\nContentEvent, ToolResultEvent, ...
-BridgeA -> Redis : PUBLISH turnstone:events:global\nStateChangeEvent(state:"idle", content:"...")
-BridgeA -> Redis : PUBLISH turnstone:events:abc12345\nTurnCompleteEvent(content:"...")
-
-== Scenario B: Directed Message to Specific Node ==
-
-Client -> Redis : RPUSH turnstone:inbound:nodeB\n{type:"send", target_node:"nodeB", ...}
-note right : Per-node queue — only nodeB picks up
-
-BridgeB -> Redis : BLPOP [turnstone:inbound:nodeB,\n         turnstone:inbound]
-Redis --> BridgeB : SendMessage (from per-node queue, priority)
-
-note right of BridgeB : Process locally on nodeB
-
-== Scenario C: Re-routing (Lands on Wrong Node) ==
-
-Client -> Redis : RPUSH turnstone:inbound\n{type:"send", ws_id:"abc12345"}
-
-BridgeB -> Redis : BLPOP [..., turnstone:inbound]
-Redis --> BridgeB : SendMessage (ws_id: abc12345)
-
-BridgeB -> Redis : GET turnstone:ws:abc12345
-Redis --> BridgeB : "nodeA"
-
-note right of BridgeB : Owner is nodeA, not me — re-route
-
-BridgeB -> Redis : RPUSH turnstone:inbound:nodeA\n(re-routed message)
-
-BridgeA -> Redis : BLPOP [turnstone:inbound:nodeA, ...]
-Redis --> BridgeA : SendMessage (from per-node queue)
-note right of BridgeA : Process locally — I own this workstream
-
-== Scenario D: Approval via Response Queue ==
-
-BridgeA <- ServerA : SSE: {type:"approve_request", items:[...]}
-
-note right of BridgeA
-  Bridge checks auto-approve:
-  1. _ws_auto_approve[ws_id]? → auto
-  2. All tools in safe set? → auto
-     (read_file, search, man,
-      memory, recall)
-  3. Otherwise → manual approval
-end note
-
-BridgeA -> Redis : PUBLISH turnstone:events:abc12345\nApprovalRequestEvent(correlation_id: req_xyz)
-
-Client <- Redis : (subscribed) ApprovalRequestEvent
-
-Client -> Redis : RPUSH turnstone:resp:req_xyz\nApproveMessage(approved:true)
-note right : Response queue — bypasses inbound queue
-
-BridgeA -> Redis : BLPOP turnstone:resp:req_xyz\n(spawned approval thread, timeout 300s)
-Redis --> BridgeA : ApproveMessage
-
-BridgeA -> ServerA : POST /v1/api/approve\n{approved:true, ws_id:"abc12345"}
-
-== Heartbeat (continuous) ==
-
-BridgeA -> Redis : SET turnstone:node:nodeA\n{server_url, started} EX 60
-note right : Every 30s — TTL 60s
-
-BridgeB -> Redis : SET turnstone:node:nodeB\n{server_url, started} EX 60
-
-@enduml

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

@@ -1,98 +0,0 @@
-@startuml
-!theme plain
-title Turnstone — Redis Key Schema
-
-skinparam component {
-    BackgroundColor<<LIST>> #BBDEFB
-    BackgroundColor<<STRING>> #C8E6C9
-    BackgroundColor<<PUBSUB>> #FFE0B2
-}
-
-skinparam note {
-    BackgroundColor #FAFAFA
-}
-
-package "Queues (Redis LIST)" #E3F2FD {
-    component [**turnstone:inbound**\n\nShared command queue.\nAny bridge can consume.\n\nOps: RPUSH (write), BLPOP (read)] as inbound <<LIST>>
-
-    component [**turnstone:inbound:{node_id}**\n\nPer-node directed queue.\nPriority over shared queue.\n\nOps: RPUSH (write), BLPOP (read)] as inbound_node <<LIST>>
-
-    component [**turnstone:resp:{request_id}**\n\nPer-request response queue.\nFor approval / plan feedback.\nTTL: 600s\n\nOps: RPUSH + EXPIRE (write), BLPOP (read)] as resp <<LIST>>
-}
-
-package "Routing (Redis STRING)" #E8F5E9 {
-    component [**turnstone:ws:{ws_id}**\n\nWorkstream → node ownership.\nValue: node_id string.\nNo TTL.\n\nOps: SET, GET, DEL] as ws_owner <<STRING>>
-
-    component [**turnstone:node:{node_id}**\n\nNode heartbeat + metadata.\nValue: JSON {server_url, started, ...}\nTTL: 60s (refreshed every 30s)\n\nOps: SET with EX, GET, SCAN] as node_hb <<STRING>>
-}
-
-package "Event Channels (Redis PUBSUB)" #FFF3E0 {
-    component [**turnstone:events:global**\n\nGlobal event broadcast.\nAll state changes, ws lifecycle.\n\nOps: PUBLISH, SUBSCRIBE] as evt_global <<PUBSUB>>
-
-    component [**turnstone:events:{ws_id}**\n\nPer-workstream events.\nContent, tools, status.\n\nOps: PUBLISH, SUBSCRIBE] as evt_ws <<PUBSUB>>
-
-    component [**turnstone:events:cluster**\n\nCluster-wide state changes.\nUsed by Console dashboard.\n\nOps: PUBLISH, SUBSCRIBE] as evt_cluster <<PUBSUB>>
-}
-
-' Readers / Writers
-
-actor "TurnstoneClient" as client
-actor "Bridge" as bridge
-actor "SimNode" as sim
-actor "Console\nCollector" as console
-actor "Scenario\n(injector)" as scenario
-
-' Queue interactions
-client --> inbound : RPUSH\n(send commands)
-client --> inbound_node : RPUSH\n(directed)
-scenario --> inbound : RPUSH\n(inject load)
-scenario --> inbound_node : RPUSH\n(directed scenario)
-bridge --> inbound : BLPOP\n(consume)
-bridge --> inbound_node : BLPOP\n(priority)
-bridge --> inbound_node : RPUSH\n(re-route)
-sim --> inbound_node : BLPOP\n(via dispatcher)
-
-client --> resp : RPUSH\n(approval response)
-bridge --> resp : BLPOP\n(wait for approval)
-
-' Routing interactions
-bridge --> ws_owner : SET / GET / DEL
-client --> ws_owner : GET\n(route lookup)
-sim --> ws_owner : SET / DEL
-
-bridge --> node_hb : SET with EX\n(heartbeat)
-sim --> node_hb : SET with EX\n(heartbeat)
-console --> node_hb : SCAN + GET\n(discovery)
-client --> node_hb : SCAN + GET\n(list_nodes)
-
-' Pub/sub interactions
-bridge --> evt_global : PUBLISH
-bridge --> evt_ws : PUBLISH
-bridge --> evt_cluster : PUBLISH
-client --> evt_global : SUBSCRIBE
-client --> evt_ws : SUBSCRIBE
-sim --> evt_global : PUBLISH
-sim --> evt_ws : PUBLISH
-sim --> evt_cluster : PUBLISH
-console --> evt_cluster : SUBSCRIBE
-
-note bottom of inbound
-  **BLPOP priority**: Bridges call
-  BLPOP [per-node, shared] so the
-  per-node queue is always checked first.
-end note
-
-note bottom of resp
-  **Bypasses inbound queue**: Approval
-  responses go directly to the response
-  queue, not through the inbound queue.
-  Auto-cleaned after 600s TTL.
-end note
-
-note bottom of evt_cluster
-  **ClusterStateEvent** includes node_id,
-  tokens, and context_ratio — enriched
-  data not available on the global channel.
-end note
-
-@enduml

docs/diagrams/09-workstream-states.puml

@@ -64,7 +64,7 @@ note right of thinking
 
   **Propagation:**
   • WebUI → global SSE queue (ws_state)
-  • Bridge → PUBLISH to global + cluster channels
+  • Console → HTTP polling picks up state
   • CLI → WorkstreamManager.set_state()
 end note
 
@@ -72,27 +72,8 @@ note left of attention
   **Blocking mechanisms:**
   • TerminalUI: input() prompt
   • WebUI: threading.Event.wait()
-  • Bridge: BLPOP on response queue
+  • ChannelBot: SSE event + Discord button
   • NullUI: auto-approve (never reaches)
 end note
 
-state "SimWorkstream (simplified)" as sim_group {
-    state "sim_idle" as si <<idle>>
-    state "sim_thinking" as st <<thinking>>
-    state "sim_running" as sr <<running>>
-    state "sim_error" as se <<error>>
-
-    [*] --> si
-    si --> st : process_turn() called
-    st --> sr : Tool calls generated
-    sr --> st : More rounds
-    st --> si : No tools / max rounds
-    st --> se : Uncaught exception
-}
-
-note right of sim_group
-  SimWorkstream has no ATTENTION state —
-  tool approval is not simulated.
-end note
-
 @enduml

docs/diagrams/10-simulator-architecture.puml

@@ -1,113 +0,0 @@
-@startuml
-!theme plain
-title Turnstone — Simulator Architecture
-
-skinparam component {
-    BackgroundColor<<cluster>> #E1BEE7
-    BackgroundColor<<node>> #CE93D8
-    BackgroundColor<<engine>> #F3E5F5
-    BackgroundColor<<scenario>> #FFF3E0
-    BackgroundColor<<metrics>> #E8F5E9
-    BackgroundColor<<redis>> #FFCDD2
-}
-
-package "SimCluster" as cluster <<cluster>> {
-
-    component [**ThreadPoolExecutor**\nmax_workers=64\n(blocking Redis ops)] as executor <<cluster>>
-
-    component [**redis.ConnectionPool**\nmax_connections=64\ndecode_responses=True\n(shared across all nodes)] as pool <<redis>>
-
-    package "InboundDispatchers" {
-        component [**Dispatcher 0**\nnodes 0-49] as d0
-        component [**Dispatcher 1**\nnodes 50-99] as d1
-        component [**...**\n(ceil(N/50) total)] as dn
-
-        note bottom of d0
-            Each dispatcher calls BLPOP on a single Redis
-            connection for up to 50 node queues + shared queue.
-            Keys: [prefix:inbound:sim-0000, ..., prefix:inbound]
-            Per-node keys have BLPOP priority over shared.
-        end note
-    }
-
-    package "SimNodes (N instances)" {
-        component [**SimNode sim-0000**] as n0 <<node>>
-        component [**SimNode sim-0001**] as n1 <<node>>
-        component [**...**] as nn <<node>>
-
-        component [**SimEngine**\n(per node, seeded RNG)\n\nLLM simulation:\n  gaussian(μ=2s, σ=0.5s) latency\n  gaussian(μ=200, σ=50) tokens\n  random word content\n  P(tool_calls) = 0.6/0.3\n\nTool simulation:\n  gaussian(μ=0.5s, σ=0.2s) latency\n  P(failure) = 0.02] as engine <<engine>>
-
-        component [**SimWorkstream**\n(0..max_ws per node)\n\nState: idle→thinking→running→idle\nToken accounting: word_count × 3\nContent: 8-chunk streaming] as ws <<node>>
-    }
-
-    component [**MetricsCollector**\n(thread-safe, shared)\n\nTracks: turn latencies,\nthroughput, utilization,\nerrors, node kills] as metrics <<metrics>>
-}
-
-package "Scenarios (5 workload patterns)" <<scenario>> {
-    component [**SteadyState**\nConstant rate:\n1/mps interval\nfor duration secs] as steady <<scenario>>
-
-    component [**Burst**\nburst_size messages\nas fast as possible\nthen wait] as burst <<scenario>>
-
-    component [**NodeFailure**\nSteadyState + periodic\nnode kills (up to N/2)] as failure <<scenario>>
-
-    component [**Directed**\nMessages targeted to\nspecific nodes via\ntarget_node field] as directed <<scenario>>
-
-    component [**Lifecycle**\n3 phases:\n1. Create workstreams\n2. Send messages\n3. Close half] as lifecycle <<scenario>>
-}
-
-database "Redis" as redis <<redis>>
-
-' Scenario -> Redis
-steady --> redis : RPUSH prefix:inbound\n(SendMessage)
-burst --> redis : RPUSH prefix:inbound\n(burst)
-failure --> redis : RPUSH prefix:inbound
-directed --> redis : RPUSH prefix:inbound:{node}\n(directed)
-lifecycle --> redis : RPUSH prefix:inbound\n(Create/Send/Close)
-
-' Dispatchers -> Redis -> Nodes
-d0 --> redis : BLPOP [per-node..., shared]
-d1 --> redis : BLPOP [per-node..., shared]
-d0 --> n0 : handle_message(raw)
-d0 --> n1 : handle_message(raw)
-
-' Nodes internal
-n0 --> engine : simulate_llm_response()\nsimulate_tool_execution()
-n0 --> ws : process_turn()
-
-' Nodes -> Redis (events)
-n0 --> redis : PUBLISH prefix:events:global\n(StateChangeEvent)
-n0 --> redis : PUBLISH prefix:events:{ws_id}\n(ContentEvent, ToolResultEvent, ...)
-n0 --> redis : PUBLISH prefix:events:cluster\n(ClusterStateEvent)
-n0 --> redis : SET prefix:node:sim-0000\nEX 60 (heartbeat)
-n0 --> redis : SET prefix:ws:{ws_id}\n(ownership)
-
-' Shared pool
-n0 ..> pool : PooledBroker\n(shared connection)
-n1 ..> pool : PooledBroker
-d0 ..> pool
-d0 ..> executor : asyncio.to_thread()
-
-' Metrics
-ws --> metrics : record_turn(ws_id, node_id, latency)
-steady --> metrics : record_inject()
-burst --> metrics : record_inject()
-directed --> metrics : record_inject()
-lifecycle --> metrics : record_inject()
-cluster --> metrics : record_node_kill(node_id)
-cluster --> metrics : snapshot_utilization()\n(every metrics_interval)
-
-note bottom of cluster
-    **SimConfig** controls all simulation parameters:
-    num_nodes, max_ws_per_node, redis settings,
-    llm_latency_mean/stddev, tool_failure_rate,
-    scenario, duration, messages_per_second, seed
-end note
-
-note right of redis
-    Simulator uses **real Redis** —
-    not a mock. Console dashboard
-    can monitor a running simulation
-    via the same cluster channel.
-end note
-
-@enduml

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

@@ -7,110 +7,79 @@ skinparam sequenceArrowThickness 1.5
 participant "Browser" as Browser
 participant "Console\nStarlette App" as Server
 participant "ClusterCollector" as CC
-collections "Redis" as Redis
-participant "Node-A Bridge" as BridgeA
-participant "Node-A\n(real server)" as NodeA
-participant "Node-B\n(sim node)" as NodeB
+participant "Node-A\n(server)" as NodeA
+participant "Node-B\n(server)" as NodeB
 
-== Thread 1: Cluster Event Subscriber (real-time) ==
+== Thread 1: Node Discovery (every 60s) ==
 
-CC -> Redis : SUBSCRIBE turnstone:events:cluster
-activate CC #E1BEE7
-
-Redis --> CC : ClusterStateEvent\n{ws_id, state:"thinking",\nnode_id:"nodeA", tokens:500,\ncontext_ratio:0.05}
-CC -> CC : Update NodeSnapshot["nodeA"]\n.workstreams["ws123"].state = "thinking"
-CC -> CC : _fanout(event) → all SSE listeners
-
-Redis --> CC : {"type":"ws_created",\nws_id:"ws456", name:"task-1",\nnode_id:"sim-0003"}
-CC -> CC : Add workstream to\nNodeSnapshot["sim-0003"]
-CC -> CC : _fanout(event)
-
-Redis --> CC : ClusterStateEvent\n{ws_id:"ws456", state:"idle"}
-CC -> CC : Update workstream state
-
-note right of CC
-  Handles: cluster_state,
-  ws_created, ws_closed, ws_rename
-
-  Thread runs continuously.
-  All updates are thread-safe
-  via threading.Lock.
-end note
-
-deactivate CC
-
-== Thread 2: Node Discovery (every 15s) ==
-
-CC -> Redis : SCAN 0 MATCH turnstone:node:*
-activate CC #B2EBF2
-Redis --> CC : [turnstone:node:nodeA, turnstone:node:sim-0003, ...]
-
-loop for each discovered key
-    CC -> Redis : GET turnstone:node:{id}
-    Redis --> CC : JSON: {server_url, started, max_ws, sim:true/false}
-end
-
-CC -> CC : Create new NodeSnapshot\nfor newly discovered nodes
-CC -> CC : Remove NodeSnapshot\nfor disappeared nodes
-
-CC -> CC : _fanout({type: "node_joined", ...})\n_fanout({type: "node_lost", ...})
-
-deactivate CC
-
-== Thread 3: HTTP Polling (every 10s, real nodes only) ==
-
-CC -> CC : Filter nodes where\nserver_url.startswith("http")
+CC -> CC : list_services("server",\nmax_age_seconds=120)
 activate CC #C8E6C9
 
-note right of CC
-  sim:// nodes are SKIPPED.
-  Their data comes exclusively
-  from the cluster event channel.
-end note
-
-CC -> NodeA : GET /v1/api/dashboard
-activate NodeA
-NodeA --> CC : {workstreams: [...],\naggregate: {total_tokens, ...}}
-deactivate NodeA
-
-CC -> NodeA : GET /health
-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)
+CC -> CC : New node? → spawn SSE task\nLost node? → cancel SSE task
+CC -> CC : _fanout(node_joined)\n_fanout(node_lost)
 
 deactivate CC
 
+== Thread 2: SSE Manager (asyncio event loop) ==
+
+note over CC
+  Single asyncio event loop multiplexes
+  one persistent SSE connection per node.
+  Scales to 1000+ nodes.
+end note
+
+CC -> NodeA : GET /v1/api/events/global\n?expected_node_id=nodeA
+activate NodeA
+activate CC #BBDEFB
+
+NodeA --> CC : data: {"type":"node_snapshot",\n"node_id":"nodeA",\n"workstreams":[...],\n"health":{...},\n"aggregate":{...}}
+
+note right of CC
+  Snapshot populates NodeSnapshot
+  in-memory state. Reconciles
+  against stale data (emits
+  ws_created/ws_closed diffs).
+end note
+
+loop real-time delta events
+    NodeA --> CC : data: {"type":"ws_state",\n"ws_id":"ws1","state":"running"}
+    CC -> CC : Update NodeSnapshot\n_fanout(cluster_state)
+end
+
+alt health transition
+    NodeA --> CC : data: {"type":"health_changed",\n"circuit_state":"open"}
+    CC -> CC : Update node.health
+end
+
+alt periodic aggregate (every 10s)
+    NodeA --> CC : data: {"type":"aggregate",\n"total_tokens":50000}
+    CC -> CC : Update node.aggregate
+end
+
+deactivate CC
+deactivate NodeA
+
+alt SSE disconnect
+    CC -> CC : Mark node unreachable\nReconnect with backoff\n(1s → 30s cap)
+end
+
+alt identity mismatch (409 or snapshot node_id differs)
+    CC -> CC : Mark node unreachable\nStop reconnecting to this URL
+end
+
 == Browser SSE Stream ==
 
 Browser -> Server : GET /v1/api/cluster/events
 activate Server
 
-Server -> CC : get_snapshot()
+Server -> CC : get_snapshot_and_register(queue)
+note right : Atomic: snapshot + listener\nregistration under both locks\n→ no event gap
 CC --> Server : ClusterSnapshot\n(full current state)
 
-Server -> CC : register_listener(queue)
-note right : Per-client queue.Queue(maxsize=2000)\nSSE via EventSourceResponse + run_in_executor()
-
 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)
+    CC -> Server : event via listener queue\n(from SSE manager thread)
     Server -> Browser : data: {"type":"cluster_state",...}\n\n
 end
 
@@ -133,20 +102,20 @@ Server --> Browser : JSON response
 
 Browser -> Server : GET /v1/api/cluster/overview
 Server -> CC : get_overview()
-CC --> Server : {nodes: 10, workstreams: 47,\nstates: {running:5, ...},\naggregate: {total_tokens: 50000},\nversion_drift: false, versions: ["0.3.0"]}
+CC --> Server : {nodes: 2, workstreams: 12,\nstates: {running:5, ...},\naggregate: {total_tokens: 50000},\nversion_drift: false, versions: ["0.9.7"]}
 Server --> Browser : JSON response
 
 Browser -> Server : GET /v1/api/cluster/nodes?sort=activity
 Server -> CC : get_nodes(sort_by="activity")
-CC --> Server : {nodes: [...], total: 10}
+CC --> Server : {nodes: [...], total: 2}
 Server --> Browser : JSON response
 
-Browser -> Server : GET /v1/api/cluster/workstreams\n?state=running&node=sim-0003
-Server -> CC : get_workstreams(state="running",\nnode="sim-0003")
+Browser -> Server : GET /v1/api/cluster/workstreams\n?state=running&node=nodeA
+Server -> CC : get_workstreams(state="running",\nnode="nodeA")
 CC --> Server : {workstreams: [...], total: 5,\npage: 1, per_page: 50, pages: 1}
 Server --> Browser : JSON response
 
-== Workstream Creation (via MQ) ==
+== Workstream Creation (via Console proxy) ==
 
 Browser -> Server : POST /v1/api/cluster/workstreams/new\n{node_id:"nodeA", name:"new-task"}
 activate Server #FFECB3
@@ -154,34 +123,22 @@ activate Server #FFECB3
 Server -> CC : _pick_best_node() or\nget_node_detail(node_id)
 CC --> Server : node validated
 
-Server -> Server : Build CreateWorkstreamMessage\n{target_node:"nodeA", name:"new-task",\nuser_id: from auth_result}
+Server -> NodeA : POST http://nodeA:8080/v1/api/workstreams/new\n{name:"new-task", user_id: from auth_result}
+activate NodeA
+NodeA --> Server : {ws_id:"ws789", name:"new-task",\nnode_url:"http://nodeA:8080"}
+deactivate NodeA
 
-Server -> Redis : RPUSH turnstone:inbound:nodeA\n(directed queue)
-Server --> Browser : {status:"ok", correlation_id:"abc",\ntarget_node:"nodeA"}
+Server --> Browser : {status:"ok", ws_id:"ws789",\nnode_url:"http://nodeA:8080"}
 deactivate Server
 
-note right of Redis
-  Bridge on Node-A picks up the
-  message from its directed queue,
-  POSTs to /v1/api/workstreams/new
-  (forwarding user_id in payload),
-  registers ownership, publishes
-  ws_created to cluster channel.
+note right of Server
+  Console proxies the create request
+  directly to the target node via HTTP.
+  The response includes node_url so the
+  client can establish a direct SSE
+  connection for the data plane.
 end note
 
-Redis --> BridgeA : BLPOP turnstone:inbound:nodeA
-activate BridgeA
-BridgeA -> NodeA : POST /v1/api/workstreams/new\n{name:"new-task"}
-NodeA --> BridgeA : {ws_id:"ws789", name:"new-task"}
-BridgeA -> Redis : SET turnstone:ws:ws789 = nodeA
-BridgeA -> Redis : PUBLISH turnstone:events:cluster\n{type:"ws_created", ws_id:"ws789",\nnode_id:"nodeA", name:"new-task"}
-deactivate BridgeA
-
-Redis --> CC : ws_created event
-CC -> CC : Add workstream to\nNodeSnapshot["nodeA"]
-CC -> CC : _fanout(event)
-Server -> Browser : SSE: data: {"type":"ws_created",...}
-
 == Reverse Proxy (server UI through console port) ==
 
 Browser -> Server : GET /node/nodeA/

docs/diagrams/12-deployment.puml

@@ -14,45 +14,25 @@ node "Docker Host" as host {
 
     frame "turnstone-net (bridge network)" as net {
 
-        node "redis" <<redis:7.4-alpine>> as redis_node {
-            component [Redis Server\nport 6379] as redis
-            note bottom of redis
-                Healthcheck: redis-cli ping
-                Volume: redis-data
-            end note
-        }
-
         node "server" <<turnstone image>> as server_node {
             component [turnstone-server\nport 8080] as server
             note bottom of server
                 Command: turnstone-server
                   --host 0.0.0.0
                   --port 8080
-                Depends: redis (healthy)
                 Volume: turnstone-data
                   (/data)
             end note
         }
 
-        node "bridge ×N" <<turnstone image>> as bridge_node {
-            component [turnstone-bridge] as bridge
-            note bottom of bridge
-                Command: turnstone-bridge
-                  --server-url http://server:8080
-                  --redis-host redis
-                Depends: server + redis
-                Scalable: --scale bridge=N
-                node_id: auto from hostname
-            end note
-        }
-
         node "console" <<turnstone image>> as console_node {
             component [turnstone-console\nport 8090] as console
             note bottom of console
                 Command: turnstone-console
-                  --redis-host redis
                   --port 8090
-                Depends: redis
+                Depends: server
+                Hash-ring router for
+                  multi-node clusters
             end note
         }
 
@@ -75,42 +55,21 @@ node "Docker Host" as host {
                 See docs/pgbouncer.md
             end note
         }
-
-        node "sim (profile: sim)" <<turnstone image>> as sim_node {
-            component [turnstone-sim] as sim
-            note bottom of sim
-                Command: turnstone-sim
-                  --redis-host redis
-                  --nodes 100
-                  --scenario steady
-                Depends: redis
-                Optional: only with
-                  --profile sim
-            end note
-        }
     }
 }
 
 actor "Browser\nUser" as browser
-actor "MQ Client" as mqclient
+actor "SDK /\nAPI Client" as apiclient
 
 ' External connections
 browser --> server : HTTP + SSE\nport 8080
 browser --> console : HTTP + SSE\nport 8090
-mqclient --> redis : Redis protocol\nport 6379
+apiclient --> server : HTTP + SSE\nport 8080
 
 ' Internal connections
-server --> redis : Redis protocol\n(6379)
 server --> llm_api : OpenAI API\n(HTTPS/HTTP)
 
-bridge --> server : HTTP REST\n(POST /v1/api/send, etc.)
-bridge <-- server : SSE\n(GET /v1/api/events)
-bridge --> redis : Redis protocol\n(queues + pubsub)
-
-console --> redis : Redis PUBSUB + LIST\n(cluster events,\nws creation commands)
-console --> server : HTTP polling + proxy\n(GET /v1/api/dashboard,\nproxy /node/{id}/*)
-
-sim --> redis : Redis protocol\n(queues + pubsub + keys)
+console --> server : HTTP proxy\n(hash-ring lookup,\nproxy /node/{id}/*)
 
 ' Database connections (production/cluster profiles)
 server ..> pgbouncer : PostgreSQL\n(pool_size=2)
@@ -120,20 +79,17 @@ pgbouncer --> postgres : transaction\npooling
 ' Environment variables
 note right of host
     **Environment Variables:**
-    • LLM_BASE_URL — LLM endpoint
-    • OPENAI_API_KEY — API key
-    • REDIS_PASSWORD — Redis auth
-    • TURNSTONE_AUTH_TOKEN — API auth
-    • TURNSTONE_DB_URL — PostgreSQL URL
-    • POSTGRES_PASSWORD — DB password
+    * LLM_BASE_URL -- LLM endpoint
+    * OPENAI_API_KEY -- API key
+    * TURNSTONE_AUTH_TOKEN -- API auth
+    * TURNSTONE_DB_URL -- PostgreSQL URL
+    * POSTGRES_PASSWORD -- DB password
 end note
 
 ' Volumes
-database "redis-data" as rv
 database "turnstone-data" as tv
 database "postgres-data" as pv
 
-redis_node --> rv
 server_node --> tv
 pg_node --> pv
 

docs/diagrams/14-storage-architecture.puml

@@ -23,7 +23,7 @@ interface "StorageBackend" as SB <<protocol>> {
     +resolve_workstream(alias_or_id) → str | None
     +delete_workstream(ws_id) → bool
     +prune_workstreams(retention_days) → (int, int)
-    +list_workstreams(node_id, limit) → list
+    +list_workstreams(node_id, limit, *, parent_ws_id, kind, user_id) → list
     +save_workstream_config(ws_id, config)
     +load_workstream_config(ws_id) → dict
     +kv_get(key) → str | None

docs/diagrams/16-channel-architecture.puml

@@ -5,8 +5,6 @@ title Turnstone — Channel Integration Architecture
 skinparam class {
     BackgroundColor<<platform>> #E1BEE7
     BackgroundColor<<service>> #E8EAF6
-    BackgroundColor<<mq>> #FFCDD2
-    BackgroundColor<<bridge>> #C8E6C9
     BackgroundColor<<server>> #FFE0B2
     BackgroundColor<<storage>> #B3E5FC
 }
@@ -22,11 +20,14 @@ class "Discord" as Discord <<platform>> {
     asyncio event loop
 }
 
-class "Slack (future)" as Slack <<platform>> {
-    Socket Mode / Events API
+class "Slack" as Slack <<platform>> {
+    Socket Mode WebSocket
     Block Kit messages
+    Slash command (default /turnstone)
+    DM + channel events
     --
-    Planned integration
+    slack-bolt (Python)
+    asyncio event loop
 }
 
 class "Teams (future)" as Teams <<platform>> {
@@ -40,7 +41,7 @@ class "Teams (future)" as Teams <<platform>> {
 class "turnstone-channel" as ChannelService <<service>> {
     entry point: turnstone-channel
     --
-    One process per platform
+    One process — hosts one or more adapters
     asyncio event loop
     Structured logging (structlog)
     --log-level, --log-format
@@ -49,6 +50,19 @@ class "turnstone-channel" as ChannelService <<service>> {
     GET  /health
 }
 
+class "SlackBot" as SlackBot <<service>> {
+    +on_message(event)
+    +on_action(action)  (Block Kit buttons)
+    +send(channel_id, content)
+    +send_notification(channel_id, content, ws_id)
+    +run(bot_token, app_token)
+    --
+    slack-bolt AsyncApp
+    Socket Mode client
+    Per-user channel sessions via slash command
+    DM routing without slash command
+}
+
 class "DiscordBot" as Bot <<service>> {
     +on_message(msg)
     +on_interaction(interaction)
@@ -63,53 +77,23 @@ class "DiscordBot" as Bot <<service>> {
     Renders approval buttons
     escape_mentions() on send
     --
-    _notify_ws_map: msg_id → (ws_id, user_id)
-    _notify_reply_channels: ws_id → (dm, user_id)
+    _notify_ws_map: msg_id -> (ws_id, user_id)
+    _notify_reply_channels: ws_id -> (dm, user_id)
 }
 
 class "ChannelRouter" as Router <<service>> {
     +resolve_route(platform, channel_id)
-        → ws_id | None
+        -> ws_id | None
     +register_route(channel_id, ws_id)
     +resolve_identity(platform, platform_user_id)
-        → user_id | None
+        -> user_id | None
     --
-    Maps channels → workstreams
-    Maps platform users → turnstone users
+    Maps channels -> workstreams
+    Maps platform users -> turnstone users
     Caches routes in memory
 }
 
-class "AsyncRedisBroker" as Broker <<service>> {
-    +push_inbound(msg)
-    +subscribe(ws_id) → AsyncIterator
-    +subscribe_global() → AsyncIterator
-    +push_response(correlation_id, msg)
-    --
-    redis.asyncio client
-    Pub/sub + queue operations
-}
-
-' -- Redis MQ --
-class "Redis MQ" as Redis <<mq>> {
-    turnstone:inbound (LIST)
-    turnstone:events:{ws_id} (PUBSUB)
-    turnstone:events:global (PUBSUB)
-    turnstone:resp:{corr_id} (LIST)
-    --
-    Shared message bus
-    Same queues as bridge protocol
-}
-
-' -- Bridge + Server --
-class "turnstone-bridge" as Bridge <<bridge>> {
-    BLPOP turnstone:inbound
-    Drive server via HTTP
-    Relay SSE → Redis pub/sub
-    --
-    Owns workstream lifecycle
-    Auto-approve / manual approve
-}
-
+' -- Server --
 class "turnstone-server" as Server <<server>> {
     POST /v1/api/send
     POST /v1/api/approve
@@ -128,7 +112,7 @@ class "channel_users" as CU <<storage>> {
     channel_user_id (PK)
     platform: "discord" | "slack"
     platform_user_id
-    user_id → users
+    user_id -> users
     linked_at
     --
     /link command creates row
@@ -161,29 +145,28 @@ class "services" as SVC <<storage>> {
 ' -- Relationships --
 Discord --> Bot : gateway\nevents
 Bot --> Router : on_message\non_interaction
-Router --> Broker : SendMessage\nApproveMessage
 Router --> CU : resolve identity
 Router --> CR : resolve / register route
-Broker --> Redis : RPUSH inbound\nRPUSH resp:{id}
 
-Redis --> Bridge : BLPOP inbound
-Bridge --> Server : HTTP API
-Server --> Bridge : SSE events
-Bridge --> Redis : PUBLISH events:{ws_id}\nPUBLISH events:global
+Router --> Server : POST /v1/api/send\nPOST /v1/api/approve\nPOST /v1/api/workstreams/new
+Bot --> Server : GET /v1/api/events?ws_id=\n(SSE via httpx-sse)
+Server --> Bot : SSE event stream
 
-Redis --> Broker : SUBSCRIBE events:{ws_id}
-Broker --> Bot : event stream
 Bot --> Discord : reply / embed\nbutton callback
 
-Slack .[hidden]. Discord
+Slack --> SlackBot : socket-mode\nevents
+SlackBot --> Router : on_message / on_action
+SlackBot --> Server : POST /v1/api/send\nGET /v1/api/events?ws_id=
+SlackBot --> Slack : post / update\nBlock Kit button callbacks
+
 Teams .[hidden]. Slack
 
 ChannelService --> Bot : creates + runs
+ChannelService --> SlackBot : creates + runs
 ChannelService --> Router : creates
-ChannelService --> Broker : creates
 ChannelService --> SVC : register / heartbeat /\nderegister
 
-' -- Notification path (direct HTTP, bypasses MQ) --
+' -- Notification path (direct HTTP) --
 Server --> ChannelService : POST /v1/api/notify\n(JWT: aud=turnstone-channel)
 Server --> SVC : list_services("channel",\nmax_age_seconds=120)
 
@@ -192,38 +175,36 @@ note right of Bot
   **Inbound Flow**
   1. Discord message arrives via gateway
   2. Bot.on_message() fires
-  3. ChannelRouter resolves channel → ws_id
+  3. ChannelRouter resolves channel -> ws_id
      (or creates new workstream)
-  4. ChannelRouter resolves platform user → user_id
+  4. ChannelRouter resolves platform user -> user_id
      via channel_users table
-  5. Broker.push_inbound(SendMessage)
-  6. Bridge pops from Redis, drives server
+  5. Router sends POST /v1/api/send to server
 
   **Workstream Resume (evicted workstreams)**
-  1. Stale route detected (no MQ owner)
+  1. Stale route detected (no active SSE listener)
   2. Existing ws_id reused directly from route
-  3. CreateWorkstreamMessage sent with
+  3. POST /v1/api/workstreams/new with
      resume_ws=<ws_id>
   4. Server resumes atomically during creation
-  5. Bridge emits WorkstreamResumedEvent → thread
+  5. SSE emits WorkstreamResumedEvent -> thread
 end note
 
-note right of Broker
+note right of Server
   **Outbound Flow**
-  1. Server emits SSE events
-  2. Bridge relays to Redis events:{ws_id}
-  3. Broker.subscribe(ws_id) yields events
-  4. Bot formats and sends to Discord thread
+  1. Server emits SSE events on
+     GET /v1/api/events?ws_id=
+  2. Bot subscribes via httpx-sse
+  3. Bot formats and sends to Discord thread
 end note
 
 note bottom of CR
   **Approval Flow**
-  1. ApprovalRequestEvent arrives via events:{ws_id}
+  1. ApprovalRequestEvent arrives via SSE
   2. Bot renders Discord buttons (Approve / Deny)
-  3. User clicks button → on_interaction()
+  3. User clicks button -> on_interaction()
   4. Router builds ApproveMessage
-  5. Broker.push_response(correlation_id, msg)
-  6. Bridge pops from resp:{id}, calls POST /api/approve
+  5. Router sends POST /v1/api/approve to server
 end note
 
 note bottom of CU
@@ -238,17 +219,17 @@ note bottom of CU
 end note
 
 note bottom of SVC
-  **Notification Flow** (direct HTTP, bypasses MQ)
-  1. LLM calls notify tool → _prepare_notify()
+  **Notification Flow** (direct HTTP)
+  1. LLM calls notify tool -> _prepare_notify()
   2. _exec_notify() checks rate limit (5/turn)
   3. Queries services table for healthy gateways
   4. Mints JWT (aud: turnstone-channel) via
      ServiceTokenManager
   5. POSTs to first healthy gateway (incl. ws_id)
   6. Gateway validates JWT, resolves target
-  7. adapter.send_notification() → Discord API
-     (tracks msg_id → ws_id for reply routing)
-  8. On failure: retry up to 3× (1s, 3s backoff)
+  7. adapter.send_notification() -> Discord API
+     (tracks msg_id -> ws_id for reply routing)
+  8. On failure: retry up to 3x (1s, 3s backoff)
   9. SSRF: only http(s) URLs allowed
 
   **Bidirectional DM Replies**

docs/diagrams/20-mcp-architecture.puml

@@ -152,10 +152,34 @@ MCPMgr -> MCPSrv : prompts/get
 MCPSrv --> MCPMgr : GetPromptResult
 MCPMgr --> Session : messages [{role, content}]
 
+== Resilience: Circuit Breaker & Stream Safety ==
+
+note over MCPMgr
+  **Per-server circuit breaker**
+  CLOSED --(3 failures)--> OPEN
+  OPEN --(cooldown expires)--> half-open probe
+  Probe success --> CLOSED (trip_count decays by 1)
+  Probe failure --> OPEN (cooldown doubles, max 5 min)
+
+  McpError (protocol) does NOT trip breaker.
+  BrokenPipeError / EOFError evicts dead session.
+  All sync methods cancel orphaned futures on timeout.
+  Transport streams pre-closed before stack teardown
+  to avoid anyio cancel-scope CPU busy-loop (SDK #2147).
+end note
+
+Session -> MCPMgr : call_tool_sync()
+MCPMgr -> MCPMgr : _cb_gate(server)\n[reject if circuit open]
+MCPMgr -> MCPMgr : _cb_auto_reconnect()\n[if session gone + cooldown expired]
+MCPMgr -> MCPSrv : tools/call
+MCPSrv --> MCPMgr : result or error
+MCPMgr -> MCPMgr : _cb_record_success()\nor _cb_record_failure()
+
 == Three-Tier Refresh ==
 
-group Push Notifications
+group Push Notifications (debounced 5s per server)
   MCPSrv -> MCPMgr : ToolListChangedNotification
+  MCPMgr -> MCPMgr : debounce check\n(skip if < 5s since last)
   MCPMgr -> MCPMgr : _refresh_server_tools()
 
   MCPSrv -> MCPMgr : ResourceListChangedNotification
@@ -172,6 +196,9 @@ group Periodic Polling (default 4h)
     Only polls capabilities
     without push support.
     Staggered per-server.
+    Disconnected servers get
+    reconnect attempts with
+    exponential backoff (60s-1h).
   end note
 end
 

docs/diagrams/22-judge-architecture.puml

@@ -211,7 +211,7 @@ note over Session, Judge
   **Storage:**
   intent_verdicts table (migration 012), output_assessments table
   (migration 022). Both queryable via admin API endpoints
-  (requires admin.judge permission). Skills store scan_status,
+  (requires admin.judge permission). Skills store risk_level,
   scan_report, scan_version for install-time risk assessment.
 end note
 

docs/diagrams/23-memory-architecture.puml

@@ -61,7 +61,7 @@ end
 
 Session -> Session : _init_system_messages()\nevery conversation turn
 
-Session -> Session : _get_visible_memories(\nlimit=fetch_limit)
+Session -> Session : _list_visible_memories(\nlimit=fetch_limit)
 note right
   **Scope resolution:**
   1. global scope (always)

docs/diagrams/24-settings-architecture.puml

@@ -144,7 +144,7 @@ note over Server, Registry
   **CLI entry point:**
   CLI flag  >  config.toml  >  argparse default
 
-  **Bootstrap settings** (database, Redis, auth, server bind):
+  **Bootstrap settings** (database, auth, server bind):
   Always from config.toml / env vars — never in ConfigStore.
 end note
 

docs/diagrams/27-coordinator-wait-for-workstream.puml

@@ -0,0 +1,89 @@
+@startuml
+title Turnstone - coordinator wait_for_workstream lifecycle
+
+skinparam sequenceArrowThickness 1.5
+skinparam noteBackgroundColor #FDF6E3
+
+participant "Coordinator\nLLM" as LLM
+participant "ChatSession\n(worker thread)" as CS
+participant "CoordinatorClient" as CC
+participant "SessionUI\n(SSE fanout)" as UI
+participant "Console routing\nproxy" as RP
+database "Storage\n(workstreams row)" as DB
+participant "Child\nnode" as NODE
+
+== Spawn ==
+
+LLM -> CS : tool_call spawn_workstream(...)
+activate CS
+CS -> CC : spawn(initial_message=...,\nparent_ws_id=coord, user_id=...)
+CC -> RP : POST /v1/api/route/workstreams/new
+RP -> NODE : dispatch (rendezvous)
+NODE -> DB : insert workstreams row\nstate='running'
+RP --> CC : {ws_id, node_id, name, status: 200}
+CC --> CS : {ws_id, ...}
+CS -> UI : on_tool_result\n("spawn_workstream", ws_id)
+deactivate CS
+
+note right of LLM
+  Model now knows the child ws_id.
+  It can inspect / send / wait, and
+  the parent registry tracks it.
+end note
+
+== Wait (blocking) ==
+
+LLM -> CS : tool_call wait_for_workstream\n(ws_ids=[child], mode="any", timeout=60)
+activate CS
+CS -> CS : _prepare_wait_for_workstream\n(validate ws_ids, timeout, mode)
+CS -> UI : emit wait_started\n{call_id, ws_ids, mode, timeout}
+
+CS -> CC : wait_for_workstream(ws_ids, timeout,\nmode, progress_callback)
+activate CC
+
+loop every 500ms up to timeout
+    CC -> DB : read workstreams row(s)
+    DB --> CC : {state, updated, tokens, ...}
+    alt state in {idle, error, closed, deleted}
+        note over CC
+          real-terminal state ->
+          completion condition met
+        end note
+    else still running / thinking / attention
+        CC -> CS : progress_callback(snap)\n(diff-on-change or 5s heartbeat)
+        CS -> UI : emit wait_progress\n{call_id, elapsed, results?}
+    end
+end
+
+CC --> CS : {complete, elapsed,\nresults: {ws_id: snap}}
+deactivate CC
+
+CS -> UI : emit wait_ended\n{call_id, complete, elapsed, results}
+CS -> UI : on_tool_result\n("wait_for_workstream",\n"complete after Ns (R/N resolved)")
+CS --> LLM : tool_result (full results dict)
+deactivate CS
+
+note left of UI
+  Sidebar "waiting on N children" indicator
+  keys on call_id - started / progress / ended
+  scope to a single wait invocation so
+  nested waits render independent badges.
+end note
+
+== After wait: inspect + close ==
+
+LLM -> CS : tool_call inspect_workstream(ws_id=child)
+CS -> CC : inspect(ws_id)
+CC -> DB : read row + tail
+CC --> CS : {state, messages, tokens, ...}
+CS --> LLM : tool_result (serialised)
+
+LLM -> CS : tool_call close_workstream\n(ws_id=child, reason="...")
+CS -> CC : close_workstream(ws_id, reason)
+CC -> RP : POST /v1/api/route/workstreams/close
+RP -> NODE : dispatch
+NODE -> DB : state='closed',\nclose_reason='...'
+RP --> CC : {status: 200}
+CC --> CS : {closed: true, status: 200, reason: ...}
+CS --> LLM : tool_result
+@enduml

docs/diagrams/architecture-overview.svg

@@ -34,253 +34,214 @@
   <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>
+  <text x="110" y="86" text-anchor="middle" fill="#58a6ff" font-size="9" font-weight="600" letter-spacing="2">CLIENTS</text>
+  <text x="380" y="86" text-anchor="middle" fill="#3fb950" font-size="9" font-weight="600" letter-spacing="2">CONSOLE ROUTER</text>
+  <text x="700" y="86" text-anchor="middle" fill="#f47067" font-size="9" font-weight="600" letter-spacing="2">SERVER NODES</text>
+  <text x="1010" 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>
+    <rect x="40" y="108" width="140" height="46" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="40" y="108" width="140" height="5" rx="5" fill="#58a6ff"/>
+    <rect x="40" y="108" width="140" height="5" fill="#58a6ff"/>
+    <rect x="40" y="111" width="140" height="2" fill="#161b22"/>
+    <text x="110" y="130" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">CLI</text>
+    <text x="110" 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>
+    <rect x="40" y="174" width="140" height="46" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="40" y="174" width="140" height="5" rx="5" fill="#58a6ff"/>
+    <rect x="40" y="174" width="140" height="5" fill="#58a6ff"/>
+    <rect x="40" y="177" width="140" height="2" fill="#161b22"/>
+    <text x="110" y="196" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">Browser UI</text>
+    <text x="110" 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>
+    <rect x="40" y="244" width="140" height="46" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="40" y="244" width="140" height="5" rx="5" fill="#58a6ff"/>
+    <rect x="40" y="244" width="140" height="5" fill="#58a6ff"/>
+    <rect x="40" y="247" width="140" height="2" fill="#161b22"/>
+    <text x="110" y="266" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">SDK / API</text>
+    <text x="110" y="281" text-anchor="middle" fill="#8b949e" font-size="9">programmatic</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>
+    <rect x="40" y="314" width="140" height="46" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="40" y="314" width="140" height="5" rx="5" fill="#58a6ff"/>
+    <rect x="40" y="314" width="140" height="5" fill="#58a6ff"/>
+    <rect x="40" y="317" width="140" height="2" fill="#161b22"/>
+    <text x="110" y="336" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">Channel Gateway</text>
+    <text x="110" y="351" text-anchor="middle" fill="#8b949e" font-size="9">Discord, Slack, ...</text>
   </g>
 
-  <!-- ==================== REDIS MQ ==================== -->
+  <!-- ==================== CONSOLE ROUTER ==================== -->
   <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>
+    <rect x="300" y="148" width="160" height="170" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="300" y="148" width="160" height="5" rx="5" fill="#3fb950"/>
+    <rect x="300" y="148" width="160" height="5" fill="#3fb950"/>
+    <rect x="300" y="151" width="160" height="2" fill="#161b22"/>
+    <text x="380" y="178" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">Console</text>
+    <line x1="318" y1="190" x2="442" y2="190" stroke="#30363d" stroke-width="1"/>
+    <text x="380" y="208" text-anchor="middle" fill="#8b949e" font-size="9">hash-ring router</text>
+    <text x="380" y="223" text-anchor="middle" fill="#8b949e" font-size="9">cluster dashboard</text>
+    <text x="380" y="238" text-anchor="middle" fill="#8b949e" font-size="9">reverse proxy</text>
+    <line x1="318" y1="250" x2="442" y2="250" stroke="#30363d" stroke-width="1"/>
+    <text x="380" y="268" text-anchor="middle" fill="#484f58" font-size="8">control plane:</text>
+    <text x="380" y="282" text-anchor="middle" fill="#484f58" font-size="8">create / send / approve</text>
+    <text x="380" y="296" text-anchor="middle" fill="#484f58" font-size="8">cancel / command / close</text>
+    <text x="380" y="310" text-anchor="middle" fill="#484f58" font-size="8">port 8090</text>
   </g>
 
-  <!-- ==================== CLUSTER NODES ==================== -->
+  <!-- ==================== SERVER 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"/>
+  <rect x="570" y="100" width="260" 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)"/>
+    <rect x="590" y="118" width="220" height="100" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="590" y="118" width="220" height="5" rx="5" fill="#f47067"/>
+    <rect x="590" y="118" width="220" height="5" fill="#f47067"/>
+    <rect x="590" y="121" width="220" height="2" fill="#161b22"/>
+    <text x="700" y="142" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">Server Node A</text>
+    <line x1="608" y1="152" x2="792" y2="152" stroke="#30363d" stroke-width="1"/>
+    <!-- Server process -->
+    <rect x="608" y="162" width="184" height="28" rx="3" fill="#1c2128" stroke="#30363d" stroke-width="1"/>
+    <text x="700" y="180" text-anchor="middle" fill="#8b949e" font-size="9">turnstone-server :8080</text>
     <!-- Tools label -->
-    <text x="699" y="206" text-anchor="middle" fill="#484f58" font-size="8">14 tools + MCP</text>
+    <text x="700" y="206" text-anchor="middle" fill="#484f58" font-size="8">19 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)"/>
+    <rect x="590" y="238" width="220" height="100" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="590" y="238" width="220" height="5" rx="5" fill="#f47067"/>
+    <rect x="590" y="238" width="220" height="5" fill="#f47067"/>
+    <rect x="590" y="241" width="220" height="2" fill="#161b22"/>
+    <text x="700" y="262" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">Server Node B</text>
+    <line x1="608" y1="272" x2="792" y2="272" stroke="#30363d" stroke-width="1"/>
+    <!-- Server process -->
+    <rect x="608" y="282" width="184" height="28" rx="3" fill="#1c2128" stroke="#30363d" stroke-width="1"/>
+    <text x="700" y="300" text-anchor="middle" fill="#8b949e" font-size="9">turnstone-server :8080</text>
     <!-- Tools label -->
-    <text x="699" y="326" text-anchor="middle" fill="#484f58" font-size="8">14 tools + MCP</text>
+    <text x="700" y="326" text-anchor="middle" fill="#484f58" font-size="8">19 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>
+    <rect x="930" y="130" width="160" height="46" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="930" y="130" width="160" height="5" rx="5" fill="#f778ba"/>
+    <rect x="930" y="130" width="160" height="5" fill="#f778ba"/>
+    <rect x="930" y="133" width="160" height="2" fill="#161b22"/>
+    <text x="1010" y="153" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">OpenAI</text>
+    <text x="1010" 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>
+    <rect x="930" y="196" width="160" height="46" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="930" y="196" width="160" height="5" rx="5" fill="#f778ba"/>
+    <rect x="930" y="196" width="160" height="5" fill="#f778ba"/>
+    <rect x="930" y="199" width="160" height="2" fill="#161b22"/>
+    <text x="1010" y="219" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">Anthropic</text>
+    <text x="1010" 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>
+    <rect x="930" y="262" width="160" height="46" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="930" y="262" width="160" height="5" rx="5" fill="#f778ba"/>
+    <rect x="930" y="262" width="160" height="5" fill="#f778ba"/>
+    <rect x="930" y="265" width="160" height="2" fill="#161b22"/>
+    <text x="1010" y="285" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">Local / vLLM</text>
+    <text x="1010" 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>
+    <rect x="590" y="450" width="220" height="52" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="590" y="450" width="220" height="5" rx="5" fill="#bc8cff"/>
+    <rect x="590" y="450" width="220" height="5" fill="#bc8cff"/>
+    <rect x="590" y="453" width="220" height="2" fill="#161b22"/>
+    <text x="700" y="476" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">PostgreSQL / SQLite</text>
+    <text x="700" 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>
+  <text x="700" y="444" text-anchor="middle" fill="#bc8cff" font-size="9" font-weight="600" letter-spacing="2">STORAGE</text>
 
   <!-- ==================== CONNECTION LINES ==================== -->
 
-  <!-- CLIENT -> GATEWAY connections -->
+  <!-- CLIENT -> CONSOLE connections (control plane) -->
   <!-- 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)"/>
+  <line x1="180" y1="197" x2="298" y2="210" stroke="#58a6ff" stroke-width="1.2" stroke-opacity="0.6" marker-end="url(#arrow-blue)"/>
+  <!-- Channel -> Console -->
+  <line x1="180" y1="337" x2="298" y2="290" stroke="#58a6ff" stroke-width="1.2" stroke-opacity="0.6" marker-end="url(#arrow-blue)"/>
+  <!-- SDK -> Console -->
+  <line x1="180" y1="267" x2="298" y2="248" stroke="#58a6ff" stroke-width="1.2" stroke-opacity="0.6" marker-end="url(#arrow-blue)"/>
+  <text x="240" y="238" fill="#484f58" font-size="8" text-anchor="middle">HTTP</text>
 
-  <!-- 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>
+  <!-- CLI -> direct to Node A (single-node mode, above everything) -->
+  <path d="M 180 120 L 588 120" stroke="#58a6ff" stroke-width="1.2" stroke-opacity="0.4" fill="none" stroke-dasharray="6,3" marker-end="url(#arrow-blue)"/>
+  <text x="390" y="114" fill="#484f58" font-size="8" text-anchor="middle">direct (single-node)</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)"/>
+  <!-- CONSOLE -> NODE connections (proxy) -->
+  <!-- Console -> Node A -->
+  <line x1="460" y1="200" x2="588" y2="176" stroke="#3fb950" stroke-width="1.2" stroke-opacity="0.6" marker-end="url(#arrow-green)"/>
+  <!-- Console -> Node B -->
+  <line x1="460" y1="260" x2="588" y2="296" stroke="#3fb950" stroke-width="1.2" stroke-opacity="0.6" marker-end="url(#arrow-green)"/>
+  <text x="520" y="222" fill="#484f58" font-size="8" text-anchor="middle">proxy</text>
 
-  <!-- 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>
+  <!-- CLIENT -> NODE direct SSE (data plane, below console) -->
+  <!-- Browser -> Node A SSE (arc below console) -->
+  <path d="M 180 205 C 240 370, 450 380, 588 330" stroke="#58a6ff" stroke-width="1" stroke-opacity="0.3" fill="none" stroke-dasharray="4,3" marker-end="url(#arrow-blue)"/>
+  <text x="340" y="378" fill="#484f58" font-size="8" text-anchor="middle">SSE (data plane)</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"/>
+  <line x1="810" y1="168" x2="928" y2="155" stroke="#f47067" stroke-width="1.2" stroke-opacity="0.5" marker-end="url(#arrow-coral)"/>
+  <line x1="810" y1="176" x2="928" y2="219" stroke="#f47067" stroke-width="1.2" stroke-opacity="0.3"/>
+  <line x1="810" y1="180" x2="928" 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)"/>
+  <line x1="810" y1="288" x2="928" y2="163" stroke="#f47067" stroke-width="1.2" stroke-opacity="0.2"/>
+  <line x1="810" y1="296" x2="928" y2="222" stroke="#f47067" stroke-width="1.2" stroke-opacity="0.3"/>
+  <line x1="810" y1="300" x2="928" 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>
+  <text x="700" y="392" text-anchor="middle" fill="#30363d" font-size="10">...</text>
 
   <!-- ==================== FLOW LABELS ==================== -->
-  <!-- Interactive flow label -->
+  <!-- Direct / single-node 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>
+  <text x="46" y="404" fill="#8b949e" font-size="9">direct (single-node / SSE)</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>
+  <!-- Control plane label -->
+  <rect x="200" y="395" width="10" height="10" rx="2" fill="none" stroke="#58a6ff" stroke-width="1.5"/>
+  <text x="216" y="404" fill="#8b949e" font-size="9">control plane (HTTP)</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>
+  <!-- Proxy label -->
+  <rect x="340" y="395" width="10" height="10" rx="2" fill="none" stroke="#3fb950" stroke-width="1.5"/>
+  <text x="356" y="404" fill="#8b949e" font-size="9">console proxy</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>
+  <circle cx="44" cy="474" r="3" fill="#3fb950" opacity="0.6"/>
+  <text x="54" y="477" fill="#484f58" font-size="9">control plane: client &#x2192; console &#x2192; server node (hash-ring bucket lookup)</text>
+  <circle cx="44" cy="494" r="3" fill="#58a6ff" opacity="0.6"/>
+  <text x="54" y="497" fill="#484f58" font-size="9">data plane: client &#x2192; server node (direct SSE, node_url from create response)</text>
+  <circle cx="44" cy="514" r="3" fill="#f47067" opacity="0.6"/>
+  <text x="54" y="517" fill="#484f58" font-size="9">single-node: client &#x2192; server (direct HTTP + SSE, no console needed)</text>
+</svg>

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

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:d8ce6d2a43a991655c3f64a20b6e810fdb2f78eb767acc3d3d1b8d2c9f443181
-size 165011
+oid sha256:881a8b9bce67b5af9a52d5e50deaa72351cd99c76f18aad5caeb2b61131ca1af
+size 119798

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

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:2b3ea69f852e93dc1bc7943db0c71d0cdd1afcbcf470a8737189ae56e85b3206
-size 310075
+oid sha256:a3b5c59403a6febd81667fc8fd2a7d22bc59da6130eba0dea5449c42668d0ede
+size 387044

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

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:6471e611beebf647f3a191eb16588571a404cc52a43067883a2b6f06dd936376
-size 594676
+oid sha256:474b900448ec04d1117b48a2b55614524721b2f04ac4bda66170bd0a06aae0f2
+size 624573

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

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

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

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

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

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-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:7bf27afa267d5b8d6da38e83213ed1b8e87639d5105a0a1ccc2e5a4bf4d3b67e
-size 185282
+oid sha256:04d2069a9b5155ad1e7d842147fd78535ad9106d6856520439c33a9868a47499
+size 156694

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

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-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:e3f1ad0fcd55eaca3b8ad9c5abc07432803641c54ede9fc93c79df144cf77d1c
-size 407761
+oid sha256:040f7d9ec7d676da40b9487e0825caf2c1574cbdd9f16d0998d90e0c2e4f8861
+size 360309

docs/diagrams/png/12-deployment.png

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:09065fef028d05e6df425fd8abefaf5a2ca04b66802f2e3975f289fa597f63ed
-size 309656
+oid sha256:a872556d111185f4531d1b68ee892b4ce5042d7ccf277e2cad08beb6932c9803
+size 191144

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

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:6fc99bb8d84d6e9f3dac9d5c12ac7f569a041b29431c57612c24b50f332982ed
-size 462992
+oid sha256:ae4f79fb22600106f8cb0af4ba5586bb26ea5d57e27ef382fdc59b6549fdbd21
+size 415473

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

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:a6b7769aa7e732ffbeb1eb7f5b65273a135fb3a78d9802ec36d3b92801c34f6b
-size 427745
+oid sha256:7623df33be9baf7647ca1c2450640df57e1cd73e8be1f8168aae16e546ad683c
+size 459941

docs/diagrams/png/24-settings-architecture.png

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:83c0e6aad3eb19f6bc475a30a77215e801da3da5930f0462417fe7eb6eda6be2
-size 347144
+oid sha256:06fe076f0835a891e00afc804fd1805196ebde9fc0d34998c7873e87287f982b
+size 346887

docs/diagrams/png/27-coordinator-wait-for-workstream.png

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

docs/docker.md

@@ -1,6 +1,6 @@
 # Docker Deployment
 
-Docker Compose stack for running the full turnstone platform or the simulator.
+Docker Compose stack for running the full turnstone platform.
 
 ## Quick Start
 
@@ -10,9 +10,6 @@ cp .env.example .env
 
 # Full stack (needs an LLM API on the host)
 docker compose up
-
-# Simulator only (no LLM needed)
-docker compose --profile sim up redis console sim
 ```
 
 Console dashboard: http://localhost:8090
@@ -23,18 +20,14 @@ Console dashboard: http://localhost:8090
 
 | Service | Port | Profile | Description |
 |---------|------|---------|-------------|
-| `redis` | 6379 | default | Message broker, pub/sub, node registry |
 | `server` | 8080 | default | Web UI + chat workstreams + LLM |
-| `bridge` | — | default | Redis-to-HTTP bridge (multi-node routing) |
 | `console` | 8090 | default | Cluster dashboard |
-| `channel` | — | production | Channel gateway (Discord, Slack, etc.) |
+| `channel` | — | production | Channel gateway (Discord and/or Slack adapters) |
 | `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
 
-**Default** (no flag) — starts `redis`, `server`, `bridge`, `console`. Requires an OpenAI-compatible LLM API running on the host (default: `http://localhost:8000/v1`).
+**Default** (no flag) — starts `server` and `console`. Requires an OpenAI-compatible LLM API running on the host (default: `http://localhost:8000/v1`).
 
 ```bash
 docker compose up
@@ -46,22 +39,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`:
+**Cluster** — 10-node server fleet sharing PostgreSQL. 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
-# Sim + console (no LLM needed)
-docker compose --profile sim up redis console sim
-
-# Everything including sim
-docker compose --profile sim up
-```
-
 ## Configuration
 
 All configuration is via environment variables in `.env` (copy from `.env.example`):
@@ -74,13 +57,6 @@ All configuration is via environment variables in `.env` (copy from `.env.exampl
 | `OPENAI_API_KEY` | `dummy` | API key (`dummy` for local servers) |
 | `TAVILY_API_KEY` | — | Web search API key (only needed for local/vLLM models; Anthropic and OpenAI search models use native search) |
 
-### Redis
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `REDIS_PASSWORD` | — | Redis auth password (empty = no auth) |
-| `REDIS_PORT` | `6379` | Host port mapping |
-
 ### Server
 
 | Variable | Default | Description |
@@ -93,26 +69,29 @@ All configuration is via environment variables in `.env` (copy from `.env.exampl
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `CONSOLE_PORT` | `8090` | Host port mapping |
-| `CONSOLE_POLL_INTERVAL` | `10` | Node polling interval (seconds) |
 
 ### Auth
 
+Auth is always enabled. `TURNSTONE_JWT_SECRET` is required.
+
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `TURNSTONE_AUTH_ENABLED` | — | Set to `1` to require authentication |
-| `TURNSTONE_AUTH_TOKEN` | — | Config-file token for server/bridge/console (backward compat, works alongside JWT) |
-| `TURNSTONE_JWT_SECRET` | — | Secret key for signing JWTs (required when using user identity / JWT auth) |
+| `TURNSTONE_JWT_SECRET` | — | Secret key for signing JWTs (required) |
 
 ### Database
 
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `TURNSTONE_DB_BACKEND` | `sqlite` | Storage backend: `sqlite` or `postgresql` |
-| `TURNSTONE_DB_URL` | — | Database URL (e.g. `postgresql://user:pass@db:5432/turnstone`). For SQLite, defaults to `/data/.turnstone.db` |
+| `TURNSTONE_DB_URL` | — | Database URL (e.g. `postgresql+psycopg://user:pass@postgres:5432/turnstone`). For SQLite, defaults to `/data/.turnstone.db` |
 | `TURNSTONE_DB_POOL_SIZE` | `2` | PostgreSQL connection pool size per process (default: 2 base + 3 overflow = 5 max) |
+| `POSTGRES_USER` | `turnstone` | PostgreSQL container username (used in default `TURNSTONE_DB_URL` for cluster/channel) |
+| `POSTGRES_PASSWORD` | — | PostgreSQL container password (required for production and cluster profiles) |
 
 The database stores workstream history, user accounts, and API tokens. When using JWT auth, a database backend is required for user storage.
 
+> **Upgrading from <1.3.0a4:** Earlier versions used `DB_BACKEND` and `DATABASE_URL` in `.env`, which `compose.yaml` mapped to the `TURNSTONE_`-prefixed names internally. These short aliases have been removed. Rename `DB_BACKEND` → `TURNSTONE_DB_BACKEND` and `DATABASE_URL` → `TURNSTONE_DB_URL` in your `.env` file.
+
 > **Large clusters:** Each turnstone process maintains a small connection pool (5 max). At hundreds of nodes this adds up — use [PgBouncer](pgbouncer.md) in transaction pooling mode between turnstone and PostgreSQL.
 
 > **First-time setup:** After deploying with auth enabled, create an initial admin user by running `turnstone-admin create-user` inside the container:
@@ -129,30 +108,26 @@ The database stores workstream history, user accounts, and API tokens. When usin
 |----------|---------|-------------|
 | `TURNSTONE_DISCORD_TOKEN` | — | Discord bot token (required to enable Discord adapter) |
 | `TURNSTONE_DISCORD_GUILD` | `0` | Restrict to a single Discord guild (0 = all guilds) |
+| `TURNSTONE_SLACK_TOKEN` | — | Slack Bot User OAuth token `xoxb-…` (required to enable Slack adapter) |
+| `TURNSTONE_SLACK_APP_TOKEN` | — | Slack App-Level token `xapp-…` (required with `TURNSTONE_SLACK_TOKEN`) |
+| `TURNSTONE_SLACK_CHANNELS` | — | Comma-separated Slack channel IDs to allow (empty = all) |
+| `TURNSTONE_SLACK_SLASH_COMMAND` | `/turnstone` | Slash command registered in the Slack app |
 
-The channel service runs in the `production` profile. When `TURNSTONE_DISCORD_TOKEN` is set, the Discord adapter connects to the Discord Gateway and routes messages through Redis MQ to the bridge and server. See [Channel Integrations](channels.md) for full setup instructions including Discord application creation and user account linking.
-
-### Simulator
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `SIM_NODES` | `100` | Number of simulated nodes |
-| `SIM_SCENARIO` | `steady` | Scenario: `steady`, `burst`, `node_failure`, `directed`, `lifecycle` |
-| `SIM_DURATION` | `60` | Duration in seconds |
-| `SIM_MPS` | `5.0` | Messages per second (steady scenario) |
-| `SIM_LOG_LEVEL` | `INFO` | Log verbosity |
-| `SIM_SEED` | — | Random seed for reproducibility |
-| `SIM_METRICS_FILE` | — | Write JSON report to file |
+The channel service runs in the `production` profile. When
+`TURNSTONE_DISCORD_TOKEN` or the Slack pair is set the gateway starts the
+corresponding adapter; both can run in one process. See
+[Channel Integrations](channels.md) for platform app setup and user
+account linking.
 
 ## Scaling
 
-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:
+For multi-node testing, use the `cluster` profile which provides 10 server instances with unique node IDs (`node-1` through `node-10`), resource limits, and shared PostgreSQL:
 
 ```bash
 POSTGRES_PASSWORD=secret docker compose --profile cluster up
 ```
 
-The default `server` and `bridge` also run alongside the cluster nodes (11 total). All nodes are accessible via the console dashboard at `:8090`.
+The default `server` also runs alongside the cluster nodes (11 total). All nodes are accessible via the console dashboard at `:8090`.
 
 For production clusters beyond ~50 nodes, add PgBouncer between turnstone services and PostgreSQL. See [PgBouncer Connection Pooling](pgbouncer.md) for Docker Compose and Helm configuration.
 
@@ -160,7 +135,6 @@ For production clusters beyond ~50 nodes, add PgBouncer between turnstone servic
 
 | Volume | Mount | Purpose |
 |--------|-------|---------|
-| `redis-data` | `/data` | Redis persistence |
 | `turnstone-data` | `/data` | SQLite database (`.turnstone.db`) |
 
 ## Building
@@ -175,7 +149,9 @@ docker compose build
 docker compose build --no-cache
 ```
 
-All entry points are installed in a single image: `turnstone-server`, `turnstone-bridge`, `turnstone-console`, `turnstone-channel`, `turnstone-admin`, `turnstone-sim`, `turnstone-eval`.
+All entry points are installed in a single image: `turnstone`,
+`turnstone-server`, `turnstone-console`, `turnstone-channel`,
+`turnstone-admin`, `turnstone-eval`, and `turnstone-bootstrap`.
 
 ## Cleanup
 

docs/governance.md

@@ -62,14 +62,14 @@ etc.) since workstream templates were merged into the skills system in v0.8.0.
 - **Default skills**: All `is_default=true` skills 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
+- **Explicit selection**: `--skill <name>` CLI flag, `skill` field on
   `POST /v1/api/workstreams/new`, console creation modal dropdown, scheduled task
   config, and channel adapter config. An explicit skill *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.
+- **Runtime switching**: `/skill <name>` to switch, `/skill clear` to revert
+  to defaults, `/skill` to show current. Persisted across resume.
 - **Model-driven loading**: The `skill` built-in tool lets the model
   discover and activate skills mid-conversation. `search` action finds skills
   by query (auto-approved); `load` action activates by name (requires user
@@ -91,7 +91,7 @@ etc.) since workstream templates were merged into the skills system in v0.8.0.
   time. The scanner evaluates four risk axes: content risk (command execution,
   data exfiltration), supply chain risk (pipe-to-shell, transitive installs),
   vulnerability risk (prompt injection, insecure credentials), and declared
-  capability risk (from `allowed-tools` in SKILL.md). Results populate the `scan_status`
+  capability risk (from `allowed-tools` in SKILL.md). Results populate the `risk_level`
   (safe/low/medium/high/critical) and `scan_report` (JSON breakdown) columns.
   These fields are system-managed and cannot be overwritten via the admin API.
 - **Discovery**: External skills can be discovered and installed from registries:
@@ -186,15 +186,21 @@ Full OpenAPI spec at `/openapi.json` and Swagger UI at `/docs`.
 
 ## Admin Console UI
 
-6 new tabs added to the admin panel (11 total):
+Governance-related tabs within the 18-tab admin panel:
 
 - **Roles** — CRUD roles, permission checkbox grid, user role assignment modal
 - **Policies** — CRUD tool policies with colored action badges (green/red/amber)
-- **Skills** — CRUD skills with wide modal, textarea editor
+- **Prompts** — Prompt-policy editor (heuristics for admin guardrails)
+- **Skills** — CRUD skills with wide modal, textarea editor; Discover pill for
+  installing from skills.sh / GitHub; per-row scan badges (safe/low/med/high/critical)
+- **Judge** — Intent validation configuration and verdict history
 - **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.
+See [docs/console.md](console.md) for the full tab list and
+[docs/settings.md](settings.md) for the Settings tab that edits live
+ConfigStore values.
 
 ## SDK
 

docs/judge.md

@@ -41,6 +41,7 @@ confidence_threshold = 0.7   # reserved for v2 smart approvals (not used in v1)
 max_context_ratio = 0.5       # max % of judge context window for history
 timeout = 60.0                # seconds (generous for local models)
 read_only_tools = true        # judge can use read_file/list_directory
+cancel_on_approval = false    # stop judging remaining tool calls once user decides
 ```
 
 All fields are optional. The judge is enabled by default; use `enabled = false`
@@ -72,6 +73,17 @@ CLI flags override `config.toml` values.
 - **Cross-provider**: When both `model` and `provider` are set, the judge
   creates its own LLM client. You can optionally specify `base_url` and
   `api_key` for non-default endpoints.
+- **Google models**: The judge supports `google` as a provider. Note that
+  read-only tools are disabled for Google models (the Gemini API requires
+  `thought_signature` in tool call round-trips which the judge's normalized
+  format does not preserve).
+
+The judge creates a fresh HTTP client for each evaluation run and closes it
+when done, avoiding stale connection issues across runs.
+
+If the LLM judge fails or returns no verdict, a fallback verdict with tier
+`llm_fallback` is delivered via the callback, ensuring the UI always receives
+a result.
 
 ---
 
@@ -303,7 +315,7 @@ four independent risk axes:
    `Bash(*)` (unrestricted shell) is high risk. `Bash(git:*)` is low.
    Read-only tools are safe.
 
-Results are stored in `scan_status` (tier: safe/low/medium/high/critical) and
+Results are stored in `risk_level` (tier: safe/low/medium/high/critical) and
 `scan_report` (JSON breakdown) on the `prompt_templates` table. These fields are
 system-managed and not editable via the admin API.
 
@@ -379,7 +391,7 @@ emitted to the frontend:
 ```
 
 The web UI renders this as an inline warning after the tool result. The CLI
-shows a colored terminal warning. The MQ bridge forwards it as an
+shows a colored terminal warning. The server forwards it as an
 `OutputWarningEvent` for console subscribers.
 
 Assessments are persisted to the `output_assessments` table for v2
@@ -388,11 +400,11 @@ level, annotations, output length, redaction status).
 
 ### Session-level skill scan warning
 
-When a skill with `scan_status` of `high` or `critical` is loaded into a
+When a skill with `risk_level` of `high` or `critical` is loaded into a
 session, a warning is emitted via `on_info`:
 
 ```
-⚠ Skill 'my-skill' has scan status: high.
+⚠ Skill 'my-skill' has risk level: high.
 Review scan report in admin panel before enabling in production.
 ```
 
@@ -409,7 +421,7 @@ All three evaluation systems persist their assessments for future calibration:
 |-------|--------|-------------|
 | `intent_verdicts` | Intent judge (heuristic + LLM) | `func_name`, `risk_level`, `confidence`, `user_decision` |
 | `output_assessments` | Output guard | `func_name`, `risk_level`, `flags`, `redacted` |
-| `prompt_templates` | Skill scanner | `scan_status`, `scan_report`, `scan_version` |
+| `prompt_templates` | Skill scanner | `risk_level`, `scan_report`, `scan_version` |
 
 Run v1 with all tools requiring manual approval to build a local dataset.
 In v2, calibration tooling will analyze this data to:

docs/mcp-registry.md

@@ -146,7 +146,7 @@ with TurnstoneConsole("http://localhost:8081", token="...") as client:
 ### TypeScript
 
 ```typescript
-import { TurnstoneConsole } from "@anthropic/turnstone-sdk";
+import { TurnstoneConsole } from "@turnstone/sdk";
 
 const client = new TurnstoneConsole({
   baseUrl: "http://localhost:8081",

docs/oidc.md

@@ -38,7 +38,7 @@ are set.
 | `TURNSTONE_OIDC_PROVIDER_NAME` | No | `SSO` | Display name for the login button (e.g. "Google", "Okta") |
 | `TURNSTONE_OIDC_ROLE_CLAIM` | No | — | ID token claim containing role/group values (see [Role Mapping](#role-mapping)) |
 | `TURNSTONE_OIDC_ROLE_MAP` | No | — | Mapping from claim values to Turnstone role IDs (see [Role Mapping](#role-mapping)) |
-| `TURNSTONE_OIDC_PASSWORD_ENABLED` | No | `true` | Set to `false` to hide the password form and block all username/password logins (including admin). API tokens and config-file tokens still work. |
+| `TURNSTONE_OIDC_PASSWORD_ENABLED` | No | `true` | Set to `false` to hide the password form and block all username/password logins (including admin). API tokens continue to work. |
 | `TURNSTONE_OIDC_REDIRECT_BASE` | No | — | Externally-reachable origin for the OIDC redirect URI (e.g. `https://app.example.com`). Recommended when running behind a reverse proxy. When unset, derived from the request Host header. |
 
 OIDC is enabled when all three required fields (issuer, client ID, client
@@ -246,10 +246,10 @@ password) before OIDC is enabled. The setup wizard always works
 regardless of this setting because it is only available when zero users
 exist in the database.
 
-API token login (`POST /v1/api/auth/login` with a `ts_` token) and
-config-file tokens (`Authorization: Bearer tok_xxx`) continue to work
-regardless of this setting. OIDC-only mode affects password-based
-authentication only.
+API token login (`POST /v1/api/auth/login` with a `ts_` token)
+continues to work regardless of this setting. JWTs and API tokens are
+the supported authentication methods. OIDC-only mode affects
+password-based authentication only.
 
 ---
 

docs/openshell.md

@@ -98,7 +98,6 @@ cannot bypass the proxy.
 | `skills_registry` | `skills.sh` | Skill discovery |
 | `github_api` | `api.github.com` (read-only L7), `raw.githubusercontent.com` | Skill fetch, GitHub API |
 | `mcp_registry` | `registry.modelcontextprotocol.io` (read-only L7) | MCP server discovery |
-| `redis` | `127.0.0.1:6379` | Message queue |
 | `web_fetch_common` | readthedocs, python docs, GitHub Pages, PyPI, npm, Stack Overflow, Wikipedia | Curated web_fetch domains |
 | `bash_network_tools` | Same as `web_fetch_common` | curl/wget from bash tool |
 | `package_registries` | `pypi.org`, `files.pythonhosted.org` | pip/uv package installs |
@@ -283,6 +282,5 @@ For production deployments:
 - [ ] Review and trim `web_fetch_common` domains to your actual needs
 - [ ] Remove `package_registries` policy if pip/uv installs are not needed
 - [ ] Add your OIDC provider endpoint if using SSO
-- [ ] Set Redis `allowed_ips` to your actual Redis host if not localhost
 - [ ] Consider removing `bash_network_tools` entirely if bash should not have
       network access

docs/pgbouncer.md

@@ -1,7 +1,7 @@
 # PgBouncer Connection Pooling
 
 Turnstone cluster deployments share a single PostgreSQL instance across
-all server nodes, bridge processes, and the console. Each process
+all server nodes and the console. Each process
 maintains a small connection pool (2 base + 3 overflow = 5 max). At
 scale this adds up — a 100-node cluster opens up to 500 connections,
 and a 1000-node cluster up to 5,000.
@@ -40,18 +40,20 @@ Add PgBouncer between turnstone services and PostgreSQL:
 ```yaml
 services:
   pgbouncer:
-    image: bitnami/pgbouncer:latest
+    image: edoburu/pgbouncer:latest
     environment:
-      POSTGRESQL_HOST: postgres
-      POSTGRESQL_PORT: "5432"
-      POSTGRESQL_DATABASE: turnstone
-      POSTGRESQL_USERNAME: ${POSTGRES_USER:-turnstone}
-      POSTGRESQL_PASSWORD: ${POSTGRES_PASSWORD:?}
-      PGBOUNCER_POOL_MODE: transaction
-      PGBOUNCER_DEFAULT_POOL_SIZE: "40"
-      PGBOUNCER_MAX_CLIENT_CONN: "5000"
-      PGBOUNCER_MAX_DB_CONNECTIONS: "80"
-      PGBOUNCER_SERVER_IDLE_TIMEOUT: "300"
+      DB_HOST: postgres
+      DB_PORT: "5432"
+      DB_NAME: ${POSTGRES_DB:-turnstone}
+      DB_USER: ${POSTGRES_USER:-turnstone}
+      DB_PASSWORD: ${POSTGRES_PASSWORD:?}
+      LISTEN_PORT: "6432"
+      AUTH_TYPE: ${POSTGRES_AUTH_TYPE:-scram-sha-256}
+      POOL_MODE: transaction
+      DEFAULT_POOL_SIZE: "40"
+      MAX_CLIENT_CONN: "5000"
+      MAX_DB_CONNECTIONS: "80"
+      SERVER_IDLE_TIMEOUT: "300"
     ports:
       - "6432:6432"
     networks:
@@ -67,7 +69,7 @@ services:
 ```
 
 Then point turnstone services at PgBouncer instead of PostgreSQL
-directly by changing the `DATABASE_URL` (or `TURNSTONE_DB_URL`):
+directly by changing `TURNSTONE_DB_URL`:
 
 ```bash
 # Before (direct)
@@ -82,7 +84,7 @@ TURNSTONE_DB_URL=postgresql://turnstone:secret@pgbouncer:6432/turnstone
 ## Helm / Kubernetes
 
 Add a PgBouncer deployment or use a Helm chart like
-[bitnami/pgbouncer](https://github.com/bitnami/charts/tree/main/bitnami/pgbouncer).
+[edoburu/pgbouncer](https://github.com/edoburu/docker-pgbouncer/tree/master/examples/kubernetes).
 
 In `values.yaml`, point the database at PgBouncer:
 
@@ -106,7 +108,7 @@ pgbouncer:
   maxClientConn: 5000
   maxDbConnections: 80
 ```
-
+:
 ---
 
 ## Configuration reference

docs/releasing.md

@@ -0,0 +1,89 @@
+# Release Process
+
+Turnstone ships several parallel release tracks from a single PyPI package.
+
+## Release Tracks
+
+| Track | Versions | Branch | Docker tags | PyPI install |
+|-------|----------|--------|-------------|--------------|
+| **Legacy 1.0** | `1.0.x` | `stable/1.0` | `:1.0.x`, `:1.0` | `pip install 'turnstone==1.0.*'` |
+| **Stable 1.3** | `1.3.x` | `stable/1.3` | `:1.3.x`, `:1.3` | `pip install 'turnstone==1.3.*'` |
+| **Stable 1.4** | `1.4.x` | `stable/1.4` | `:1.4.x`, `:1.4`, `:stable`, `:latest` | `pip install turnstone` |
+| **Experimental** | `1.5.0aN` | `main` | `:1.5.0aN`, `:experimental` | `pip install turnstone --pre` |
+
+- **Stable** tracks receive bugfixes only.  The most-recent stable minor
+  owns the `:stable` / `:latest` Docker tags and the default PyPI
+  install.
+- **Experimental** (always on `main`) receives new features. May be
+  rough around the edges.
+- When experimental matures, it is promoted to a new stable minor via
+  a `stable/X.Y` branch; older stable branches continue to receive
+  security fixes until explicitly retired.
+
+## Version Scheme
+
+[PEP 440](https://peps.python.org/pep-0440/) pre-release suffixes on a single package:
+
+- `1.0.0` — stable release
+- `1.1.0a1` — alpha (experimental)
+- `1.1.0b1` — beta (experimental, more stable)
+- `1.1.0rc1` — release candidate (experimental, nearly stable)
+- `1.1.0` — promoted to stable
+
+## Releasing an Experimental Version (from main)
+
+```bash
+scripts/release.sh 1.5.0a2 --push
+```
+
+This bumps `pyproject.toml` + `turnstone/__init__.py`, regenerates `uv.lock`, commits, tags `v1.5.0a2`, and pushes. CI runs, then publish + Docker workflows fire automatically.
+
+## Releasing a Stable Patch (from stable/X.Y)
+
+```bash
+git checkout stable/1.4
+git cherry-pick <commit-hash>    # bugfix from main
+scripts/release.sh 1.4.1 --push
+```
+
+## Promoting Experimental to Stable
+
+When `main` is ready for a stable release:
+
+```bash
+# 1. Tag the stable release on main
+scripts/release.sh 1.5.0 --push
+
+# 2. Create the stable maintenance branch from that tag
+git branch stable/1.5 v1.5.0
+git push origin stable/1.5
+
+# 3. Start the next experimental cycle on main
+scripts/release.sh 1.6.0a1 --push
+```
+
+The previous stable branch (`stable/1.4`) continues to receive
+security-only patches; older tracks (`stable/1.0`, `stable/1.3`) are
+retired when they fall out of support.
+
+## CI/CD Pipeline
+
+All releases are gated on CI success:
+
+1. `git push` with `v*` tag triggers **CI** (lint, typecheck, test, test-postgres, lock-check, security audit)
+2. On CI success, **Publish to PyPI** fires via `workflow_run`
+3. On CI success, **Publish Docker Image** fires via `workflow_run`
+
+Pre-release tags (`a`, `b`, `rc` suffixes) produce:
+- PyPI: pre-release version (not installed by default)
+- GitHub Release: marked as pre-release
+- Docker: `:experimental` alias + exact version tag
+
+Stable tags produce:
+- PyPI: stable version (default `pip install`)
+- GitHub Release: full release
+- Docker: `:stable`, `:latest`, `:X.Y`, `:X.Y.Z` tags
+
+## Dependency Updates
+
+Renovate targets `main` (experimental) only. Stable branches receive manual dependency updates via cherry-pick when security-relevant.

docs/sdk.md

@@ -69,8 +69,12 @@ Both `TurnstoneServer` (sync) and `AsyncTurnstoneServer` (async) expose:
 |----------|--------|---------|
 | **Workstreams** | `list_workstreams()` | `ListWorkstreamsResponse` |
 | | `dashboard()` | `DashboardResponse` |
-| | `create_workstream(*, name, model, auto_approve, skill)` | `CreateWorkstreamResponse` |
+| | `create_workstream(*, name, model, auto_approve, skill, initial_message, attachments)` | `CreateWorkstreamResponse` |
 | | `close_workstream(ws_id)` | `StatusResponse` |
+| **Attachments** | `upload_attachment(ws_id, filename, data, *, mime_type=...)` | `UploadAttachmentResponse` |
+| | `list_attachments(ws_id)` | `ListAttachmentsResponse` |
+| | `get_attachment_content(ws_id, attachment_id)` | `bytes` |
+| | `delete_attachment(ws_id, attachment_id)` | `StatusResponse` |
 | **Chat** | `send(message, ws_id)` | `SendResponse` |
 | | `approve(*, ws_id, approved, feedback, always)` | `StatusResponse` |
 | | `plan_feedback(*, ws_id, feedback)` | `StatusResponse` |
@@ -171,6 +175,36 @@ result.ok           # True if no errors and not timed out
 result.timed_out    # True if timeout expired
 ```
 
+### Attachments
+
+Upload files to a workstream and attach them to the next user turn:
+
+```python
+# Upload separately, then send a message — attachments auto-attach
+with open("screenshot.png", "rb") as f:
+    att = client.upload_attachment(ws.ws_id, "screenshot.png",
+                                   f.read(),
+                                   mime_type="image/png")
+client.send("What's wrong in this screenshot?", ws.ws_id)
+
+# Or attach at workstream-creation time (multipart upload)
+from turnstone.sdk import AttachmentUpload
+
+with open("notes.txt", "rb") as f:
+    ws = client.create_workstream(
+        name="triage",
+        initial_message="Summarize the notes",
+        attachments=[AttachmentUpload(data=f.read(),
+                                      filename="notes.txt",
+                                      mime_type="text/plain")],
+    )
+```
+
+Limits: images ≤ 4 MiB (png/jpeg/gif/webp), text ≤ 512 KiB (UTF-8),
+10 pending per (workstream, user). The SDK auto-generates `ws_id` on the
+client so cluster-routed callers bind attachments to the owning node
+before the request lands.
+
 ### Error Handling
 
 Non-2xx responses raise `TurnstoneAPIError`:
@@ -284,7 +318,7 @@ turnstone/sdk/               Python SDK (sub-package)
   _base.py                   Shared httpx async client, auth, error handling
   _sync.py                   Background event loop for sync wrappers
   _types.py                  TurnResult + TurnstoneAPIError
-  events.py                  27 SSE event dataclasses with type registry
+  events.py                  38 SSE event dataclasses with type registry
   server.py                  AsyncTurnstoneServer + TurnstoneServer
   console.py                 AsyncTurnstoneConsole + TurnstoneConsole
 
@@ -332,6 +366,6 @@ client.login(token="ts_abc123...")
 - `client.logout()` clears the stored JWT from the client.
 - If a request returns 401, the SDK raises `TurnstoneAPIError` — the caller is responsible for re-authenticating.
 
-### Backward Compatibility
+### Token Types
 
-The config-file token (`TURNSTONE_AUTH_TOKEN`) still works as a simple Bearer token for environments that do not use the user/JWT system. When the server receives a non-JWT Bearer token, it falls back to the legacy token check.
+The SDK accepts any Bearer token — JWTs (from `ServiceTokenManager` or login) and API tokens (`ts_` prefix) are both supported. Use `token_factory` for auto-rotating JWTs or a static `token` for API tokens.

docs/security.md

@@ -1,30 +1,15 @@
 # Security and Authentication
 
-Turnstone uses a layered authentication system with three token types,
-hierarchical scopes, and a split architecture where the console manages
-credentials while individual server nodes validate JWTs locally.
+Turnstone uses a layered authentication system with two token types
+(database-backed API tokens + HMAC-SHA256 JWTs), hierarchical scopes,
+and a split architecture where the console manages credentials while
+individual server nodes validate JWTs locally.  Inter-service traffic
+uses short-lived service JWTs minted by `ServiceTokenManager`.
 
 ---
 
 ## Token Types
 
-### Config-file tokens
-
-Static tokens defined in `config.toml` or the `TURNSTONE_AUTH_TOKEN`
-environment variable. Validated in-memory using `hmac.compare_digest`
-(timing-safe). Each token maps to a role that determines its scopes.
-
-```toml
-[[auth.tokens]]
-value = "tok_legacy"
-role = "full"     # full → {read, write, approve}
-```
-
-Role mappings: `"read"` → `{read}`, `"full"` → `{read, write, approve}`.
-
-Config tokens are sent directly as `Authorization: Bearer tok_legacy`
-on every request. No JWT exchange is needed.
-
 ### API tokens
 
 Database-backed tokens prefixed with `ts_`. Created via the admin CLI
@@ -54,7 +39,7 @@ Claims:
 |-------|-------------|
 | `sub` | User ID |
 | `scopes` | Comma-separated scope list (`read,write,approve`) |
-| `src` | Token source (`password`, `api_token`, `config`, `oidc`) |
+| `src` | Token source (`password`, `database`, `oidc`, or a service origin like `console`, `cli`, or `channel`) |
 | `iss` | Issuer — always `turnstone` |
 | `aud` | Audience — `turnstone-server` or `turnstone-console` |
 | `iat` | Issued-at timestamp |
@@ -149,15 +134,6 @@ The API token is hashed, looked up in the database, and exchanged for a
 JWT with the token's scopes. This is the recommended flow for SDKs and
 automated clients that need cookie-based sessions.
 
-### Config-file tokens (direct)
-
-Config tokens are validated per-request via `hmac.compare_digest`. No
-login exchange is needed — include the token as a `Bearer` header:
-
-```
-Authorization: Bearer tok_legacy
-```
-
 ### First-time setup
 
 When no users exist in the database:
@@ -276,7 +252,7 @@ Setting `TURNSTONE_OIDC_PASSWORD_ENABLED=false` hides the password
 form on the login page and blocks password-based login at the API
 level. The setup wizard always works regardless of this setting — the
 first admin user is created with a password before OIDC is relevant.
-API tokens and config-file tokens are unaffected by this setting.
+API tokens are unaffected by this setting.
 
 #### Known limitations
 
@@ -297,8 +273,6 @@ and classifies the token:
 
 1. **Contains `.`** → JWT → validate HS256 signature and expiry
 2. **Starts with `ts_`** → API token → SHA-256 hash, database lookup
-3. **Otherwise** → config-file token → `hmac.compare_digest` against
-   each configured token
 
 If a session cookie is present and no `Authorization` header is sent,
 the cookie value is treated as a JWT (step 1).
@@ -332,17 +306,10 @@ deployments.
 | Signing secret | `[auth] jwt_secret` | `TURNSTONE_JWT_SECRET` | Auto-generated ephemeral (warning logged) |
 | Expiry | `[auth] jwt_expiry_hours` | — | 24 hours |
 | Algorithm | — | — | HS256 (not configurable) |
-| Minimum secret length | — | — | 32 characters (warning if shorter) |
+| Minimum secret length | — | — | 32 characters (exits if shorter) |
 
-All service nodes that need to validate JWTs must share the same signing
-secret. If no secret is configured, an ephemeral key is generated at
-startup and a warning is logged — JWTs will not survive restarts or work
-across nodes.
-
-The bridge and console **require** `TURNSTONE_JWT_SECRET` when no
-`--auth-token` is provided. They exit with an error if the secret is
-missing, since ephemeral secrets would silently break inter-service
-communication.
+All services require `TURNSTONE_JWT_SECRET` and exit at startup if it is
+missing or shorter than 32 characters.
 
 ---
 
@@ -443,16 +410,15 @@ Console (cluster-wide)              Server (per-node)
 ┌──────────────────────┐           ┌──────────────────────┐
 │ User/Token CRUD (DB) │           │ JWT validation only  │
 │ Login: creds → JWT   │           │ (shared signing key) │
-│ Admin API endpoints  │           │ Config tokens: hmac  │
-│ Storage: users,      │           │ No auth DB needed    │
+│ Admin API endpoints  │           │ No auth DB needed    │
+│ Storage: users,      │           │                      │
 │   api_tokens tables  │           │                      │
 └──────────────────────┘           └──────────────────────┘
 ```
 
 The console owns the credential database and handles all user/token
 CRUD.  Individual server nodes only need the JWT signing secret to
-validate session tokens.  Config-file tokens are validated locally
-without any database.
+validate session tokens.
 
 ### Proxy auth forwarding
 
@@ -479,35 +445,30 @@ distinguish proxied requests from direct logins in audit logs.
 
 When no user context is available (auth disabled, or internal requests),
 the proxy falls back to a `ServiceTokenManager` with service identity
-`console-proxy` and full scopes.  If `--auth-token` is provided, that
-static token is used as a final fallback.
+`console-proxy` and full scopes.
 
 ### Service-to-service authentication
 
-The bridge and console collector use `ServiceTokenManager` for
-auto-rotating JWTs when communicating with server nodes:
+The console collector uses `ServiceTokenManager` for auto-rotating
+JWTs when communicating with server nodes:
 
 | Service | Identity | Scope | Audience | Purpose |
 |---------|----------|-------|----------|---------|
-| Bridge | `bridge` | `approve` | `turnstone-server` | Tool approval proxy, message relay |
 | Console collector | `console-collector` | `read` | `turnstone-server` | Node health polling |
 | Console proxy (fallback) | `console-proxy` | `approve` | `turnstone-server` | Proxied API calls when no user context |
 | Channel notify | `system` | `write` | `turnstone-channel` | Notification delivery to channel gateway |
 
 Service tokens use 1-hour expiry with automatic refresh via
-`ServiceTokenManager`.  The bridge injects auth headers per-request via
-httpx event hooks to ensure rotated tokens are picked up on SSE
-reconnects.
+`ServiceTokenManager`.
 
 ### User identity in MQ-dispatched workstreams
 
-When the console creates a workstream via MQ (the normal path), the
-authenticated user's `user_id` is embedded in the
-`CreateWorkstreamMessage`.  The bridge forwards this `user_id` in the
-HTTP payload when calling the server's `POST /v1/api/workstreams/new`.
-The server accepts a `user_id` from the request body **only when the
-caller is a trusted service** — identified by `token_source` matching
-`bridge`, `console-proxy`, or `console`.  Regular API callers cannot
+When the console creates a workstream (the normal path), the
+authenticated user's `user_id` is forwarded in the HTTP payload when
+calling the server's `POST /v1/api/workstreams/new`.  The server
+accepts a `user_id` from the request body **only when the caller is a
+trusted service** — identified by `token_source` matching
+`console-proxy` or `console`.  Regular API callers cannot
 override `user_id`; the server always uses their JWT identity.
 
 Note that the channel gateway uses a distinct JWT audience
@@ -523,22 +484,17 @@ channel gateway endpoint, and vice versa.
 
 ```toml
 [auth]
-enabled = true
 jwt_secret = "your-secret-key-here"
 jwt_expiry_hours = 24
-
-[[auth.tokens]]
-value = "tok_legacy"
-role = "full"
 ```
 
 ### Environment variables
 
+Auth is always enabled. `TURNSTONE_JWT_SECRET` is required.
+
 | Variable | Description |
 |----------|-------------|
-| `TURNSTONE_AUTH_ENABLED=1` | Enable authentication |
-| `TURNSTONE_AUTH_TOKEN=tok_xxx` | Register a config-file token with `full` access |
-| `TURNSTONE_JWT_SECRET=xxx` | JWT signing secret (must match across nodes) |
+| `TURNSTONE_JWT_SECRET=xxx` | JWT signing secret (required, must match across nodes) |
 | `TURNSTONE_CORS_ORIGINS=` | CORS allowed origins (comma-separated; empty = same-origin only) |
 
 ---
@@ -576,8 +532,6 @@ and browsers enforce same-origin policy.
 
 ## Security Properties
 
-- **Timing-safe comparison** for config-file tokens via
-  `hmac.compare_digest` — no timing side-channel.
 - **Hash-based lookup** for API tokens — the database stores only
   SHA-256 hashes, eliminating timing attacks on token comparison.
 - **Local JWT validation** — no network call or database query needed

docs/settings.md

@@ -27,7 +27,7 @@ Settings resolution differs between entry points:
 
 | Entry point | Chain |
 |-------------|-------|
-| **Server** (`turnstone-server`, `turnstone-bridge`) | CLI flag > ConfigStore > registry default |
+| **Server** (`turnstone-server`) | CLI flag > ConfigStore > registry default |
 | **CLI** (`turnstone`) | CLI flag > config.toml > argparse default |
 
 The server's `apply_config()` ignores config.toml sections that overlap with
@@ -36,6 +36,47 @@ users to the admin Settings API.
 
 ---
 
+## Per-Model Sampling Overrides
+
+The global `model.temperature`, `model.max_tokens`, and `model.reasoning_effort`
+settings serve as cluster-wide defaults. Individual models can override these
+via per-model settings in the `model_definitions` table (admin Models tab).
+
+Resolution order for sampling parameters:
+
+| Priority | Source |
+|----------|--------|
+| 1 (highest) | Per-model override (set in Models tab) |
+| 2 | Global default (set in Settings tab) |
+| 3 | Registry default (code) |
+
+When a per-model override is `NULL` (empty in the UI), the global default is
+used. Switching models via `/model <alias>` re-resolves sampling parameters
+from the new model's overrides or global defaults.
+
+**Removed settings:** `model.name` and `model.context_window` have been removed
+from ConfigStore. Model names and context windows are now configured per-model
+in the Models tab. A startup warning is logged if these keys appear in
+`config.toml`.
+
+### Plan / task agent overrides
+
+`plan_agent` and `task_agent` sub-sessions resolve independently from the
+conversation model so operators can pick a cheaper/faster model for
+autonomous loops:
+
+| Setting | Purpose |
+|---------|---------|
+| `model.plan_alias` | Alias used for `plan_agent` sub-sessions. Falls back to `[model].plan_model` in config.toml, then `[model].agent_model`, then the session's active model. |
+| `model.task_alias` | Alias used for `task_agent` sub-sessions. Same fallback chain as `plan_alias`. |
+| `model.plan_effort` | Reasoning effort for `plan_agent` (`none` / `minimal` / `low` / `medium` / `high` / `xhigh` / `max`). Defaults to `high`. |
+| `model.task_effort` | Reasoning effort for `task_agent`. Empty string means "inherit from the session". |
+
+All four are live-editable from the Settings tab and take effect on the
+next sub-agent invocation — no restart required.
+
+---
+
 ## Bootstrap vs ConfigStore
 
 **Bootstrap settings** are required before storage is available (database
@@ -46,17 +87,15 @@ connection, Redis, auth secrets, server bind address). These stay in
 |----------|---------|-------|
 | API credentials | `[api]` | config.toml / env |
 | Database | `[database]` | config.toml / env |
-| Redis | `[redis]` | config.toml / env |
 | Auth | `[auth]` | config.toml / env |
-| Bridge identity | `[bridge]` | config.toml / env |
 | Console bind | `[console]` | config.toml / env |
 
-**ConfigStore settings** (48 settings) are loaded from the database after
-storage initialization:
+**ConfigStore settings** are loaded from the database after storage
+initialization:
 
 | Section | Settings |
 |---------|----------|
-| `model` | name, temperature, max_tokens, reasoning_effort, context_window |
+| `model` | default_alias, temperature, max_tokens, reasoning_effort, plan_alias, task_alias, plan_effort, task_effort |
 | `session` | instructions, retention_days, compact_max_tokens, auto_compact_pct |
 | `tools` | timeout, truncation, agent_max_turns, skip_permissions, search, search_threshold, search_max_results |
 | `server` | workstream_idle_timeout, max_workstreams |
@@ -64,7 +103,8 @@ storage initialization:
 | `mcp` | config_path, refresh_interval, registry_url |
 | `ratelimit` | enabled, requests_per_second, burst, trusted_proxies |
 | `health` | backend_probe_interval, backend_probe_timeout, circuit_breaker_threshold, circuit_breaker_cooldown |
-| `judge` | enabled, model, provider, base_url, api_key, confidence_threshold, max_context_ratio, timeout, read_only_tools, output_guard, redact_secrets |
+| `judge` | enabled, model, provider, base_url, api_key, confidence_threshold, max_context_ratio, timeout, read_only_tools, output_guard, redact_secrets, cancel_on_approval |
+| `interface` | close_tab_action, theme |
 | `skills` | discovery_url |
 | `memory` | relevance_k, fetch_limit, max_content, nudge_cooldown, nudges |
 

docs/simulator.md

@@ -1,204 +0,0 @@
-# Cluster Simulator
-
-The simulator (`turnstone-sim`) creates lightweight simulated nodes that talk to a real Redis instance using the standard turnstone protocol. External observers — `TurnstoneClient`, `turnstone-console`, real bridges — see identical behavior. No LLM backend is needed.
-
-## Quick Start
-
-```bash
-pip install turnstone[sim]
-
-# 10 nodes, steady load, 60 seconds
-turnstone-sim --nodes 10 --scenario steady --duration 60 --mps 5
-
-# 100 nodes via Docker
-docker compose --profile sim up redis console sim
-```
-
-## How It Works
-
-Each simulated node is an asyncio coroutine (not a thread or process), so 1000 nodes run efficiently on a single event loop. The simulator:
-
-1. Registers nodes via Redis heartbeats (same keys as real bridges)
-2. Accepts messages from per-node and shared inbound queues
-3. Simulates LLM responses with configurable latency and token generation
-4. Simulates tool execution with configurable latency and failure rates
-5. Publishes real protocol events (`ContentEvent`, `StateChangeEvent`, `TurnCompleteEvent`, etc.)
-6. Reports latency, throughput, and utilization metrics at completion
-
-```
-TurnstoneClient → Redis Queue → SimNode → Redis Pub/Sub → TurnstoneClient
-                                  ↓
-                            turnstone-console (cluster dashboard)
-```
-
-## Scenarios
-
-| Scenario | Description |
-|----------|-------------|
-| `steady` | Inject messages at a constant rate (`--mps`) for `--duration` seconds |
-| `burst` | Push `--burst-size` messages instantly, then wait for completion |
-| `node_failure` | Steady load + periodically kill nodes to test redistribution |
-| `directed` | Send messages to specific nodes via `target_node` routing |
-| `lifecycle` | Create, use, and close workstreams across nodes |
-
-## CLI Reference
-
-```
-turnstone-sim [options]
-```
-
-### Cluster
-
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--nodes` | `10` | Number of simulated nodes |
-
-### Scenario
-
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--scenario` | `steady` | Scenario name |
-| `--duration` | `60` | Duration in seconds |
-| `--mps` | `5.0` | Messages per second (steady) |
-| `--burst-size` | `100` | Messages to send (burst) |
-| `--node-kill-interval` | `15` | Seconds between kills (node_failure) |
-| `--node-kill-count` | `1` | Nodes per kill cycle |
-
-### Simulation
-
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--llm-latency` | `2.0` | Mean LLM response latency (seconds) |
-| `--tool-latency` | `0.5` | Mean tool execution latency (seconds) |
-| `--tool-failure-rate` | `0.02` | Tool failure probability (0.0–1.0) |
-| `--seed` | — | Random seed for reproducibility |
-
-### Redis
-
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--redis-host` | `localhost` | Redis host |
-| `--redis-port` | `6379` | Redis port |
-| `--redis-password` | — | Redis password |
-| `--prefix` | `turnstone` | Redis key prefix |
-
-### Output
-
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--metrics-file` | — | Write JSON report to file |
-| `--log-level` | `INFO` | Log verbosity |
-
-## Example: Load Testing
-
-```bash
-# 100 nodes, high throughput, 2 minutes
-turnstone-sim --nodes 100 --scenario steady --duration 120 --mps 50
-
-# Burst of 500 messages across 50 nodes
-turnstone-sim --nodes 50 --scenario burst --burst-size 500 --duration 60
-
-# Node failure resilience (kill 2 nodes every 10 seconds)
-turnstone-sim --nodes 20 --scenario node_failure --duration 120 \
-  --node-kill-interval 10 --node-kill-count 2
-
-# Fast simulation (low latency, no failures)
-turnstone-sim --nodes 10 --scenario steady --duration 30 \
-  --llm-latency 0.1 --tool-latency 0.05 --tool-failure-rate 0 --mps 10
-```
-
-## Metrics Report
-
-The simulator prints a summary at completion:
-
-```
-============================================================
-  SIMULATION REPORT
-============================================================
-  Scenario:       steady
-  Nodes:          100
-  Duration:       60.2s
-  Total turns:    295
-  Total errors:   5
-  Node kills:     0
-------------------------------------------------------------
-  THROUGHPUT
-    Messages/sec: 4.97
-    Turns/sec:    4.89
-------------------------------------------------------------
-  LATENCY (seconds)
-    p50:          3.21
-    p90:          5.44
-    p99:          8.12
-    mean:         3.56
-    max:          12.1
-------------------------------------------------------------
-  UTILIZATION
-    Mean ws/node: 2.3
-    Max ws/node:  8
-    Idle nodes:   12
-============================================================
-```
-
-Use `--metrics-file report.json` to write the full report as JSON.
-
-## Console Integration
-
-The simulator's nodes appear in `turnstone-console` exactly like real nodes. Run them together to see the dashboard populate with simulated workstreams:
-
-```bash
-# Terminal 1: start Redis and console
-docker compose up redis console
-
-# Terminal 2: run simulator
-docker compose --profile sim up sim
-```
-
-Or all at once:
-
-```bash
-SIM_NODES=50 SIM_DURATION=120 docker compose --profile sim up redis console sim
-```
-
-Open http://localhost:8090 to see simulated nodes, workstream states, token counts, and load bars updating in real time.
-
-## Architecture
-
-> See also: [Simulator Architecture diagram](diagrams/png/10-simulator-architecture.png)
-
-```
-turnstone/sim/
-├── __init__.py     # Public API: SimCluster, SimConfig
-├── config.py       # SimConfig — all simulation parameters
-├── engine.py       # SimEngine — LLM + tool execution simulation
-├── node.py         # SimNode + SimWorkstream — protocol-compatible node
-├── cluster.py      # SimCluster + InboundDispatcher + PooledBroker
-├── scenario.py     # 5 scenario classes
-├── metrics.py      # MetricsCollector — latency, throughput, utilization
-└── cli.py          # CLI entry point
-```
-
-**Key design:** The `InboundDispatcher` batches ~50 node queues into a single Redis `BLPOP` call, keeping connection count bounded at ~20 regardless of node count. All nodes share a single `ConnectionPool(max_connections=64)`.
-
-## Programmatic Use
-
-```python
-import asyncio
-from turnstone.sim import SimCluster, SimConfig
-
-async def main():
-    config = SimConfig(
-        num_nodes=10,
-        scenario="steady",
-        duration=30,
-        messages_per_second=2.0,
-        llm_latency_mean=0.5,
-    )
-    cluster = SimCluster(config)
-    await cluster.start()
-    await cluster.run_scenario()
-    print(cluster.report())
-    await cluster.stop()
-
-asyncio.run(main())
-```

docs/tls.md

@@ -12,7 +12,7 @@ docker compose -f compose.yaml -f deploy/docker-compose.tls.yml up
 ```
 
 This:
-1. Bootstraps an internal CA and issues certs for Redis/PostgreSQL
+1. Bootstraps an internal CA and issues certs for PostgreSQL
 2. Starts the console with TLS enabled (internal CA + ACME server)
 3. Server nodes auto-provision certs via the console's ACME endpoint
 4. All inter-service communication uses mTLS
@@ -30,9 +30,9 @@ Console (CA + ACME Server)
                   | ACME protocol (auto-approve, no challenge validation)
       +-----------+-----------+
       |           |           |
-  Server(s)    Bridge    Channel GW
-  (auto-cert    (mTLS     (mTLS
-   + renewal)   client)    client)
+  Server(s)       Channel GW
+  (auto-cert       (mTLS
+   + renewal)       client)
 ```
 
 **Two cert paths on the console:**
@@ -57,12 +57,6 @@ Console (CA + ACME Server)
 These are needed before storage is available:
 
 ```toml
-[redis]
-tls = false
-tls_ca = ""      # path to CA cert
-tls_cert = ""    # path to client cert
-tls_key = ""     # path to client key
-
 [database]
 sslmode = "prefer"   # disable, allow, prefer, require, verify-full
 sslrootcert = ""     # path to CA cert
@@ -89,12 +83,11 @@ sslkey = ""          # path to client key
 Create a CA and infrastructure certs without a running console:
 
 ```bash
-# Bootstrap CA + Redis + PostgreSQL certs
-turnstone-admin tls-bootstrap --out /certs --issue redis --issue postgres
+# Bootstrap CA + PostgreSQL certs
+turnstone-admin tls-bootstrap --out /certs --issue postgres
 
 # Output:
 #   /certs/ca.pem              (CA root certificate)
-#   /certs/certs/redis/        (Redis cert + key)
 #   /certs/certs/postgres/     (PostgreSQL cert + key)
 ```
 
@@ -112,7 +105,7 @@ turnstone-admin tls-ca-cert --out ca.pem --console-url http://console:8080
 turnstone-admin tls-issue worker-1.internal --out /certs --console-url http://console:8080
 
 # List issued certs
-turnstone-admin tls-list --console-url http://console:8080 --auth-token $TOKEN
+turnstone-admin tls-list --console-url http://console:8080
 ```
 
 ### Console URL Discovery

docs/tools.md

@@ -169,8 +169,8 @@ Every tool defines a `primary_key`. The mapping is:
 | `man`        | `page`      |
 | `web_fetch`  | `url`       |
 | `web_search` | `query`     |
-| `task`       | `prompt`    |
-| `plan`       | `prompt`    |
+| `task_agent` | `prompt`    |
+| `plan_agent` | `goal`      |
 | `memory`     | `name`      |
 | `recall`     | `query`     |
 | `notify`     | `message`   |
@@ -357,7 +357,10 @@ Search the web using a text query.
 
 ## Agent
 
-### task
+Tool names use the `_agent` suffix — bare `plan` / `task` collide with
+chat-template channel names on some local models.
+
+### task_agent
 
 Delegate a general-purpose task to an autonomous sub-agent.
 
@@ -371,7 +374,7 @@ Delegate a general-purpose task to an autonomous sub-agent.
 
 ---
 
-### plan
+### plan_agent
 
 Plan before implementing -- an autonomous agent explores the codebase and writes a structured plan.
 
@@ -543,11 +546,11 @@ pre-configure skills at workstream creation.
 - `load` — Activate a skill by name. Calls `set_skill()` which handles content
   rendering with `{{model}}`/`{{ws_id}}`/`{{node_id}}` variables, system message
   reinitialization, and config persistence. Returns the skill name, description,
-  and security scan tier. Warns on high/critical scan status.
+  and security risk level. Warns on high/critical risk level.
 - `search` — Find available skills by query. Uses BM25 relevance ranking over
   name, description, tags, and category (same `BM25Index` used by memory
   relevance and tool search). Returns up to 10 results with name, description,
-  category, scan status, and activation type.
+  category, risk level, and activation type.
 
 - **Auto-approve**: `load` requires approval (changes session behavior); `search`
   is auto-approved (read-only).
@@ -568,8 +571,8 @@ pre-configure skills at workstream creation.
 | `man`        | Info       | Yes          | Yes   | Yes        | `page`      |
 | `web_fetch`  | Info       | No           | Yes   | Yes        | `url`       |
 | `web_search` | Info       | No           | Yes   | Yes        | `query`     |
-| `task`       | Agent      | No           | No    | No         | `prompt`    |
-| `plan`       | Agent      | No           | No    | No         | `prompt`    |
+| `task_agent` | Agent      | No           | No    | No         | `prompt`    |
+| `plan_agent` | Agent      | No           | No    | No         | `goal`      |
 | `memory`     | Memory     | Yes          | No    | No         | `name`      |
 | `recall`     | Memory     | Yes          | No    | No         | `query`     |
 | `notify`     | Notify     | Yes          | Yes   | Yes        | `message`   |
@@ -593,7 +596,7 @@ current turn and letting it search for them on demand.
 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
+   on deferred tool definitions plus the `tool_search_tool_bm25` server-side
    search tool. Anthropic's API handles search and expansion transparently.
 
 2. **OpenAI GPT-5.4+ (native)** -- Models with hosted tool search receive
@@ -690,7 +693,7 @@ that external tools are read-only. However, global overrides such as
 `--skip-permissions` will auto-approve all tools, including MCP tools. The
 interactive "Always" button adds specific tool types to the per-tool auto-approve
 set. The web UI and server use `approval_label` for MCP tools, giving
-per-prompt/per-resource granularity. The CLI and bridge use `func_name`, which
+per-prompt/per-resource granularity. The CLI uses `func_name`, which
 gives per-tool-type granularity (e.g., all `use_prompt` calls).
 
 ### Sub-agent availability

examples/mcp-cluster-ops/README.md

@@ -1,10 +1,51 @@
 # MCP Cluster Ops
 
-An MCP server that exposes tools for executing commands across a [Turnstone](https://github.com/turnstonelabs/turnstone) cluster. Serves as a reference implementation for both MCP server patterns and Turnstone MQ client SDK usage.
+An MCP server that exposes tools for executing commands across a Turnstone cluster. Serves as a reference implementation for both MCP server patterns and Turnstone SDK usage.
+
+> [!NOTE]
+> **Superseded by the built-in coordinator workstream in Turnstone 1.5.**
+>
+> This MCP side-car is the pre-1.5 pattern for cluster-wide orchestration.
+> Turnstone 1.5 promotes coordinator behaviour to a first-class workstream
+> kind hosted inside `turnstone-console` — no external MCP server to
+> install or operate, proper per-user audit attribution, and a dedicated
+> UI at `/coordinator/{ws_id}`.
+>
+> The extension continues to work for 1.4-and-earlier clusters. On 1.5+:
+> grant the `admin.coordinator` permission, set `coordinator.model_alias`
+> in the admin Settings tab, and create sessions via the dashboard's
+> "new coordinator" button or `POST /v1/api/coordinator/new`. Full
+> removal of this example (including docker / compose references) is
+> planned once 1.5 is confirmed in production.
+>
+> | Concern | Built-in coordinator (1.5+) | This MCP extension (1.4-and-earlier) |
+> |---|---|---|
+> | Install | None — shipped in-tree | `pip install -e examples/mcp-cluster-ops` + MCP client config |
+> | Auth | Real creator's `user_id` + `admin.coordinator` permission | Shared service token |
+> | Audit | `coordinator.create` / `close` / `cancel` events on the console; `src="coordinator"` preserved on upstream hops | Service identity only |
+> | UI | `/coordinator/{ws_id}` one-pane HTML | No UI — model-only |
+> | Tool approvals | Inline approval bar in the coordinator pane | MCP approval flow |
+> | Configuration | `coordinator.model_alias`, `coordinator.max_active`, `coordinator.reasoning_effort`, `coordinator.session_jwt_ttl_seconds` | MCP server config file |
+>
+> Minimal 1.5 migration:
+>
+> ```bash
+> curl -X POST https://console.example/v1/api/coordinator/new \
+>   -H "Authorization: Bearer $TOKEN" \
+>   -H "Content-Type: application/json" \
+>   -d '{"name":"planner","initial_message":"Spawn a worker to check the build"}'
+> ```
+>
+> The response carries `ws_id`; open
+> `https://console.example/coordinator/{ws_id}` to watch the session.
 
 ## How it works
 
-This server uses Turnstone's MQ client (`TurnstoneClient`) to dispatch shell commands to specific nodes via Redis. Remote agents execute the command and the raw bash output is captured directly from the `ToolResultEvent` stream — bypassing the costly "agent reads output → re-generates output as completion tokens" round-trip.
+This server uses the Turnstone console SDK (`TurnstoneConsole`) for node discovery and routing, and `TurnstoneServer` for per-node SSE streaming. The dispatch flow for each command is:
+
+1. **Route** — `TurnstoneConsole.route_create_workstream(target_node=..., auto_approve=True)` creates a workstream pinned to the target node via the console's rendezvous routing proxy, returning `ws_id` and `node_url`.
+2. **Execute** — `TurnstoneServer(node_url, token=...)` connects directly to the node's SSE stream using the same `TURNSTONE_API_TOKEN`. `send_and_wait(prompt, ws_id)` runs the command and the raw bash output is captured from the `ToolResultEvent` — bypassing the costly "agent reads output then re-generates output as completion tokens" round-trip.
+3. **Cleanup** — `TurnstoneConsole.route_close(ws_id)` closes the workstream.
 
 Multi-node dispatches run in parallel via `asyncio.gather`, so total wall time is bounded by the slowest node rather than the sum.
 
@@ -19,8 +60,7 @@ Multi-node dispatches run in parallel via `asyncio.gather`, so total wall time i
 
 ## Prerequisites
 
-- A running Turnstone cluster (at least one `turnstone-server` + `turnstone-bridge`)
-- Redis accessible from wherever this MCP server runs
+- A running Turnstone cluster with at least one `turnstone-server` and a `turnstone-console`
 - Python 3.11+
 
 ## Installation
@@ -28,10 +68,6 @@ Multi-node dispatches run in parallel via `asyncio.gather`, so total wall time i
 ```bash
 # From the turnstone repo root:
 pip install -e ./examples/mcp-cluster-ops
-
-# Or install turnstone with MQ support first, then the example:
-pip install -e ".[mq]"
-pip install -e ./examples/mcp-cluster-ops
 ```
 
 ## Configuration
@@ -40,9 +76,8 @@ pip install -e ./examples/mcp-cluster-ops
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `REDIS_HOST` | `localhost` | Redis host |
-| `REDIS_PORT` | `6379` | Redis port |
-| `REDIS_PASSWORD` | _(none)_ | Redis password (use env vars, not config files) |
+| `TURNSTONE_CONSOLE_URL` | `http://localhost:8090` | Console URL for node discovery and routing |
+| `TURNSTONE_API_TOKEN` | _(none)_ | API token / JWT for authentication |
 | `MCP_CLUSTER_OPS_TIMEOUT` | `120` | Default command timeout (seconds, clamped 5-3600) |
 | `MCP_CLUSTER_OPS_MAX_OUTPUT` | `8192` | Max output bytes per node (0 = unlimited) |
 | `MCP_CLUSTER_OPS_MAX_NODES` | `32` | Max concurrent node dispatches |
@@ -57,7 +92,7 @@ pip install -e ./examples/mcp-cluster-ops
 command = "mcp-cluster-ops"
 
 [mcp.servers.cluster-ops.env]
-REDIS_HOST = "redis.example.com"
+TURNSTONE_CONSOLE_URL = "http://console.example.com:8090"
 ```
 
 **JSON** (via `--mcp-config`):
@@ -68,7 +103,7 @@ REDIS_HOST = "redis.example.com"
     "cluster-ops": {
       "command": "mcp-cluster-ops",
       "env": {
-        "REDIS_HOST": "redis.example.com"
+        "TURNSTONE_CONSOLE_URL": "http://console.example.com:8090"
       }
     }
   }
@@ -90,10 +125,6 @@ node-2: /dev/sda1  500G  410G   90G  82%  /
 node-3: /dev/sda1  1.0T  200G  800G  20%  /
 ```
 
-## Why MQ client instead of HTTP SDK?
-
-The HTTP SDK (`TurnstoneServer`) talks to a single server instance. The MQ client (`TurnstoneClient`) routes through Redis with `target_node` support, which is the entire point of cross-node cluster operations.
-
 ## Security Considerations
 
 **This MCP server grants the calling agent shell access to cluster nodes.**
@@ -104,8 +135,8 @@ The HTTP SDK (`TurnstoneServer`) talks to a single server instance. The MQ clien
   is returned through the MCP tool result and becomes part of the LLM context.
 - The security boundary is at the MCP host layer -- use Turnstone's tool
   policy system to restrict which agents can invoke these tools.
-- Set `REDIS_PASSWORD` via your environment or a secrets manager -- avoid
-  hardcoding passwords in config files.
+- Set `TURNSTONE_API_TOKEN` via your environment or a secrets manager -- avoid
+  hardcoding tokens in config files.
 
 ## Development
 

examples/mcp-cluster-ops/mcp_cluster_ops/server.py

@@ -1,7 +1,8 @@
 """MCP server for Turnstone cluster operations.
 
 Exposes tools to execute commands on specific nodes in a Turnstone cluster.
-Uses the MQ client (``TurnstoneClient``) for direct node targeting via Redis.
+Uses the SDK console client (``TurnstoneConsole``) for node discovery and
+routing, and ``TurnstoneServer`` for per-node SSE streaming.
 
 Usage::
 
@@ -14,22 +15,20 @@ Configure in ``~/.config/turnstone/config.toml``::
     command = "mcp-cluster-ops"
 
     [mcp.servers.cluster-ops.env]
-    REDIS_HOST = "redis.example.com"
+    TURNSTONE_CONSOLE_URL = "http://localhost:8090"
 
 Environment variables
 ---------------------
-REDIS_HOST              Redis host (default: localhost)
-REDIS_PORT              Redis port (default: 6379)
-REDIS_PASSWORD          Redis password (default: none)
+TURNSTONE_CONSOLE_URL       Console URL (default: http://localhost:8090)
+TURNSTONE_API_TOKEN         API token / JWT for authentication (default: none)
 MCP_CLUSTER_OPS_TIMEOUT     Default command timeout in seconds (default: 120)
 MCP_CLUSTER_OPS_MAX_OUTPUT  Max output bytes per node (default: 8192, 0=unlimited)
 
 Performance notes
 -----------------
 Remote agents are told to reply with only "ok" or "failed" — the raw bash
-output is captured directly from the ToolResultEvent that already flows
-through Redis, bypassing the costly "agent reads output then re-generates
-output as completion tokens" round-trip.
+output is captured directly from the ToolResultEvent, bypassing the costly
+"agent reads output then re-generates output as completion tokens" round-trip.
 
 All multi-node dispatches run in parallel via ``asyncio.gather`` so total
 wall time is bounded by the slowest node, not the sum of all nodes.
@@ -45,7 +44,7 @@ from contextlib import asynccontextmanager
 from typing import TYPE_CHECKING, Any
 
 from mcp.server.fastmcp import Context, FastMCP
-from turnstone.mq.client import TurnResult, TurnstoneClient
+from turnstone.sdk import TurnResult, TurnstoneConsole, TurnstoneServer
 
 if TYPE_CHECKING:
     from collections.abc import AsyncIterator
@@ -68,20 +67,12 @@ _MAX_TIMEOUT = 3600
 # ---------------------------------------------------------------------------
 
 
-def _redis_kwargs() -> dict[str, Any]:
-    """Build Redis connection kwargs from environment variables.
-
-    Follows the same env var convention as ``turnstone.mq.broker.add_redis_args``:
-    ``REDIS_HOST``, ``REDIS_PORT``, ``REDIS_PASSWORD``.
-    """
-    kwargs: dict[str, Any] = {"host": os.environ.get("REDIS_HOST", "localhost")}
-    port = os.environ.get("REDIS_PORT")
-    if port is not None:
-        kwargs["port"] = int(port)
-    password = os.environ.get("REDIS_PASSWORD")
-    if password:
-        kwargs["password"] = password
-    return kwargs
+def _console_kwargs() -> dict[str, Any]:
+    """Build TurnstoneConsole connection kwargs from environment variables."""
+    return {
+        "base_url": os.environ.get("TURNSTONE_CONSOLE_URL", "http://localhost:8090"),
+        "token": os.environ.get("TURNSTONE_API_TOKEN", ""),
+    }
 
 
 def _exec_prompt(command: str) -> str:
@@ -148,6 +139,11 @@ def _validate_command(command: str) -> str | None:
     return None
 
 
+def _extract_node_ids(nodes: list[dict[str, Any]]) -> list[str]:
+    """Extract unique, non-empty node IDs from a list of node dicts."""
+    return list(dict.fromkeys(n["node_id"].strip() for n in nodes if n.get("node_id", "").strip()))
+
+
 def _format_node_result(
     node_id: str,
     result: TurnResult,
@@ -172,12 +168,12 @@ def _format_node_result(
 
 
 # ---------------------------------------------------------------------------
-# Core dispatch functions (testable with mocked TurnstoneClient)
+# Core dispatch functions (testable with mocked SDK clients)
 # ---------------------------------------------------------------------------
 
 
 def _exec_on_node_sync(
-    redis_kw: dict[str, Any],
+    console_kw: dict[str, Any],
     node_id: str,
     command: str,
     timeout: float,
@@ -185,22 +181,35 @@ def _exec_on_node_sync(
     """Dispatch *command* to *node_id* and block until complete.
 
     Runs inside ``asyncio.to_thread`` so it does not block the event loop.
-    Each call creates its own ``TurnstoneClient`` to avoid Redis pub/sub
-    subscription conflicts between concurrent dispatches.
+
+    Flow:
+      1. Create a workstream on the target node via the console routing proxy
+      2. Connect directly to the node's SSE stream to send + collect output
+      3. Close the workstream via the routing proxy
     """
     prompt = _exec_prompt(command)
-    with TurnstoneClient(**redis_kw) as client:
-        result = client.send_and_wait(
-            message=prompt,
-            target_node=node_id,
-            auto_approve=True,
-            timeout=timeout,
-        )
+    ws_id = ""
+    with TurnstoneConsole(**console_kw) as console:
+        try:
+            route_resp = console.route_create_workstream(
+                target_node=node_id,
+                auto_approve=True,
+            )
+            ws_id = route_resp["ws_id"]
+            node_url: str = route_resp["node_url"]
+            with TurnstoneServer(
+                base_url=node_url,
+                token=console_kw["token"],
+            ) as server:
+                result = server.send_and_wait(prompt, ws_id, timeout=timeout)
+        finally:
+            if ws_id:
+                console.route_close(ws_id)
     return node_id, result
 
 
 async def _dispatch_parallel(
-    redis_kw: dict[str, Any],
+    console_kw: dict[str, Any],
     node_ids: list[str],
     command: str,
     timeout: float,
@@ -211,7 +220,7 @@ async def _dispatch_parallel(
     Total wall time is bounded by the slowest node.
     """
     tasks = [
-        asyncio.to_thread(_exec_on_node_sync, redis_kw, nid, command, timeout) for nid in node_ids
+        asyncio.to_thread(_exec_on_node_sync, console_kw, nid, command, timeout) for nid in node_ids
     ]
     outcomes = await asyncio.gather(*tasks, return_exceptions=True)
 
@@ -227,16 +236,22 @@ async def _dispatch_parallel(
     return results
 
 
-def _list_nodes_sync(redis_kw: dict[str, Any]) -> list[dict[str, Any]]:
-    """List active cluster nodes (blocking)."""
-    with TurnstoneClient(**redis_kw) as client:
-        nodes: list[dict[str, Any]] = client.list_nodes()
-        return nodes
+def _list_nodes_sync(console_kw: dict[str, Any]) -> list[dict[str, Any]]:
+    """List active cluster nodes (blocking), paginating if needed."""
+    page_size = 100
+    nodes: list[dict[str, Any]] = []
+    with TurnstoneConsole(**console_kw) as console:
+        while True:
+            resp = console.nodes(limit=page_size, offset=len(nodes))
+            nodes.extend(n.model_dump() for n in resp.nodes)
+            if len(nodes) >= resp.total or not resp.nodes:
+                break
+    return nodes
 
 
-async def _list_nodes_impl(redis_kw: dict[str, Any]) -> list[dict[str, Any]]:
+async def _list_nodes_impl(console_kw: dict[str, Any]) -> list[dict[str, Any]]:
     """List active cluster nodes."""
-    return await asyncio.to_thread(_list_nodes_sync, redis_kw)
+    return await asyncio.to_thread(_list_nodes_sync, console_kw)
 
 
 # ---------------------------------------------------------------------------
@@ -246,9 +261,9 @@ async def _list_nodes_impl(redis_kw: dict[str, Any]) -> list[dict[str, Any]]:
 
 @asynccontextmanager
 async def _lifespan(server: FastMCP[dict[str, Any]]) -> AsyncIterator[dict[str, Any]]:
-    """Lifespan context — stores Redis kwargs for tool handlers."""
-    kw = _redis_kwargs()
-    yield {"redis_kwargs": kw}
+    """Lifespan context — stores console connection kwargs for tool handlers."""
+    kw = _console_kwargs()
+    yield {"console_kwargs": kw}
 
 
 mcp = FastMCP(
@@ -270,8 +285,8 @@ async def list_nodes(ctx: Context[Any, Any, Any]) -> str:
     Call this before dispatching work to discover available node IDs.
     Returns a JSON array of node metadata objects.
     """
-    redis_kw: dict[str, Any] = ctx.request_context.lifespan_context["redis_kwargs"]
-    nodes = await _list_nodes_impl(redis_kw)
+    console_kw: dict[str, Any] = ctx.request_context.lifespan_context["console_kwargs"]
+    nodes = await _list_nodes_impl(console_kw)
     return json.dumps(nodes, indent=2)
 
 
@@ -298,13 +313,16 @@ async def run_on_node(
     if cmd_err:
         return json.dumps({"error": cmd_err})
 
-    redis_kw: dict[str, Any] = ctx.request_context.lifespan_context["redis_kwargs"]
+    console_kw: dict[str, Any] = ctx.request_context.lifespan_context["console_kwargs"]
     max_output = _DEFAULT_MAX_OUTPUT
 
     log.info("run_on_node node=%s cmd=%r", node_id, command)
-    _, result = await asyncio.to_thread(
-        _exec_on_node_sync, redis_kw, node_id, command, _clamp_timeout(timeout)
-    )
+    try:
+        _, result = await asyncio.to_thread(
+            _exec_on_node_sync, console_kw, node_id, command, _clamp_timeout(timeout)
+        )
+    except Exception as exc:
+        return json.dumps({"node": node_id, "ok": False, "error": str(exc)}, indent=2)
     formatted = _format_node_result(node_id, result, max_output)
     return json.dumps(formatted, indent=2)
 
@@ -330,7 +348,7 @@ async def run_on_nodes(
     if cmd_err:
         return json.dumps({"error": cmd_err})
 
-    redis_kw: dict[str, Any] = ctx.request_context.lifespan_context["redis_kwargs"]
+    console_kw: dict[str, Any] = ctx.request_context.lifespan_context["console_kwargs"]
     max_output = _DEFAULT_MAX_OUTPUT
 
     clean_ids = list(dict.fromkeys(nid.strip() for nid in node_ids if nid.strip()))
@@ -343,7 +361,7 @@ async def run_on_nodes(
 
     log.info("run_on_nodes nodes=%s cmd=%r", clean_ids, command)
     results = await _dispatch_parallel(
-        redis_kw, clean_ids, command, _clamp_timeout(timeout), max_output
+        console_kw, clean_ids, command, _clamp_timeout(timeout), max_output
     )
     return json.dumps(results, indent=2)
 
@@ -368,18 +386,14 @@ async def run_on_all_nodes(
     if cmd_err:
         return json.dumps({"error": cmd_err})
 
-    redis_kw: dict[str, Any] = ctx.request_context.lifespan_context["redis_kwargs"]
+    console_kw: dict[str, Any] = ctx.request_context.lifespan_context["console_kwargs"]
     max_output = _DEFAULT_MAX_OUTPUT
 
-    nodes = await _list_nodes_impl(redis_kw)
+    nodes = await _list_nodes_impl(console_kw)
     if not nodes:
         return json.dumps({"error": "No active nodes found in cluster"})
 
-    node_ids = list(
-        dict.fromkeys(
-            nid.strip() for n in nodes if (nid := n.get("node_id") or n.get("id")) and nid.strip()
-        )
-    )
+    node_ids = _extract_node_ids(nodes)
     if not node_ids:
         return json.dumps({"error": "No nodes with identifiable IDs found"})
     if len(node_ids) > _MAX_CONCURRENT_NODES:
@@ -388,7 +402,7 @@ async def run_on_all_nodes(
         )
     log.info("run_on_all_nodes nodes=%s cmd=%r", node_ids, command)
     results = await _dispatch_parallel(
-        redis_kw, node_ids, command, _clamp_timeout(timeout), max_output
+        console_kw, node_ids, command, _clamp_timeout(timeout), max_output
     )
     return json.dumps(results, indent=2)
 

examples/mcp-cluster-ops/pyproject.toml

@@ -9,7 +9,7 @@ description = "MCP server for Turnstone cluster operations — reference impleme
 requires-python = ">=3.11"
 license = "BUSL-1.1"
 dependencies = [
-    "turnstone[mq]",
+    "turnstone",
     "mcp>=1.6",
 ]
 
@@ -18,7 +18,7 @@ mcp-cluster-ops = "mcp_cluster_ops.server:main"
 
 [project.optional-dependencies]
 test = ["pytest>=9.0"]
-dev = ["ruff>=0.9", "mypy>=1.14", "types-redis>=4.6"]
+dev = ["ruff>=0.9", "mypy>=1.14"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

examples/mcp-cluster-ops/tests/test_helpers.py

@@ -2,11 +2,12 @@
 
 from __future__ import annotations
 
-from turnstone.mq.client import TurnResult
+from turnstone.sdk import TurnResult
 
 from mcp_cluster_ops.server import (
     _clamp_timeout,
     _exec_prompt,
+    _extract_node_ids,
     _extract_output,
     _format_node_result,
     _truncate,
@@ -190,3 +191,53 @@ class TestClampTimeout:
 
     def test_negative(self):
         assert _clamp_timeout(-1) == 5.0
+
+
+# ---------------------------------------------------------------------------
+# _extract_node_ids
+# ---------------------------------------------------------------------------
+
+
+class TestExtractNodeIds:
+    def test_normal(self):
+        nodes = [
+            {"node_id": "a", "server_url": "http://a:8080"},
+            {"node_id": "b", "server_url": "http://b:8080"},
+        ]
+        assert _extract_node_ids(nodes) == ["a", "b"]
+
+    def test_deduplicates(self):
+        nodes = [
+            {"node_id": "a"},
+            {"node_id": "a"},
+            {"node_id": "b"},
+        ]
+        assert _extract_node_ids(nodes) == ["a", "b"]
+
+    def test_strips_whitespace(self):
+        nodes = [{"node_id": "  a  "}, {"node_id": "b "}]
+        assert _extract_node_ids(nodes) == ["a", "b"]
+
+    def test_skips_empty(self):
+        nodes = [
+            {"node_id": "a"},
+            {"node_id": ""},
+            {"node_id": "  "},
+            {"node_id": "b"},
+        ]
+        assert _extract_node_ids(nodes) == ["a", "b"]
+
+    def test_skips_missing_key(self):
+        nodes = [
+            {"node_id": "a"},
+            {"server_url": "http://orphan:8080"},
+            {"node_id": "b"},
+        ]
+        assert _extract_node_ids(nodes) == ["a", "b"]
+
+    def test_empty_list(self):
+        assert _extract_node_ids([]) == []
+
+    def test_all_empty_ids(self):
+        nodes = [{"node_id": ""}, {"node_id": "  "}]
+        assert _extract_node_ids(nodes) == []

examples/mcp-cluster-ops/tests/test_tools.py

@@ -1,12 +1,14 @@
-"""Tests for MCP tool handlers with mocked TurnstoneClient."""
+"""Tests for MCP tool handlers with mocked SDK clients."""
 
 from __future__ import annotations
 
 import asyncio
+import contextlib
 from typing import Any
 from unittest.mock import MagicMock, patch
 
-from turnstone.mq.client import TurnResult
+import pytest
+from turnstone.sdk import TurnResult
 
 from mcp_cluster_ops.server import (
     _dispatch_parallel,
@@ -14,6 +16,22 @@ from mcp_cluster_ops.server import (
     _list_nodes_impl,
 )
 
+_CONSOLE_KW: dict[str, Any] = {"base_url": "http://localhost:8090", "token": ""}
+_CONSOLE_KW_AUTH: dict[str, Any] = {"base_url": "http://localhost:8090", "token": "tok_test"}
+
+
+def _mock_console_ctx(mock_cls: MagicMock, mock_client: MagicMock) -> None:
+    """Wire up a TurnstoneConsole mock as a context manager."""
+    mock_cls.return_value.__enter__ = MagicMock(return_value=mock_client)
+    mock_cls.return_value.__exit__ = MagicMock(return_value=False)
+
+
+def _mock_server_ctx(mock_cls: MagicMock, mock_server: MagicMock) -> None:
+    """Wire up a TurnstoneServer mock as a context manager."""
+    mock_cls.return_value.__enter__ = MagicMock(return_value=mock_server)
+    mock_cls.return_value.__exit__ = MagicMock(return_value=False)
+
+
 # ---------------------------------------------------------------------------
 # _list_nodes_impl
 # ---------------------------------------------------------------------------
@@ -21,26 +39,71 @@ from mcp_cluster_ops.server import (
 
 class TestListNodesImpl:
     def test_returns_nodes(self):
-        nodes = [{"node_id": "a", "model": "gpt-5"}, {"node_id": "b", "model": "gpt-5"}]
-        with patch("mcp_cluster_ops.server.TurnstoneClient") as mock_cls:
-            mock_client = MagicMock()
-            mock_client.list_nodes.return_value = nodes
-            mock_cls.return_value.__enter__ = MagicMock(return_value=mock_client)
-            mock_cls.return_value.__exit__ = MagicMock(return_value=False)
+        mock_node_a = MagicMock()
+        mock_node_a.model_dump.return_value = {"node_id": "a", "server_url": "http://a:8080"}
+        mock_node_b = MagicMock()
+        mock_node_b.model_dump.return_value = {"node_id": "b", "server_url": "http://b:8080"}
 
-            result = asyncio.run(_list_nodes_impl({"host": "localhost"}))
-            assert result == nodes
+        mock_resp = MagicMock()
+        mock_resp.nodes = [mock_node_a, mock_node_b]
+        mock_resp.total = 2
+
+        with patch("mcp_cluster_ops.server.TurnstoneConsole") as mock_cls:
+            mock_client = MagicMock()
+            mock_client.nodes.return_value = mock_resp
+            _mock_console_ctx(mock_cls, mock_client)
+
+            result = asyncio.run(_list_nodes_impl(_CONSOLE_KW))
+            assert len(result) == 2
+            assert result[0]["node_id"] == "a"
+            assert result[1]["node_id"] == "b"
 
     def test_empty_cluster(self):
-        with patch("mcp_cluster_ops.server.TurnstoneClient") as mock_cls:
-            mock_client = MagicMock()
-            mock_client.list_nodes.return_value = []
-            mock_cls.return_value.__enter__ = MagicMock(return_value=mock_client)
-            mock_cls.return_value.__exit__ = MagicMock(return_value=False)
+        mock_resp = MagicMock()
+        mock_resp.nodes = []
+        mock_resp.total = 0
 
-            result = asyncio.run(_list_nodes_impl({"host": "localhost"}))
+        with patch("mcp_cluster_ops.server.TurnstoneConsole") as mock_cls:
+            mock_client = MagicMock()
+            mock_client.nodes.return_value = mock_resp
+            _mock_console_ctx(mock_cls, mock_client)
+
+            result = asyncio.run(_list_nodes_impl(_CONSOLE_KW))
             assert result == []
 
+    def test_paginates_large_clusters(self):
+        """Clusters with >100 nodes are fetched across multiple pages."""
+
+        def _make_node(nid: str) -> MagicMock:
+            m = MagicMock()
+            m.model_dump.return_value = {"node_id": nid}
+            return m
+
+        page1_nodes = [_make_node(f"n-{i}") for i in range(100)]
+        page2_nodes = [_make_node(f"n-{i}") for i in range(100, 150)]
+
+        page1_resp = MagicMock()
+        page1_resp.nodes = page1_nodes
+        page1_resp.total = 150
+
+        page2_resp = MagicMock()
+        page2_resp.nodes = page2_nodes
+        page2_resp.total = 150
+
+        with patch("mcp_cluster_ops.server.TurnstoneConsole") as mock_cls:
+            mock_client = MagicMock()
+            mock_client.nodes.side_effect = [page1_resp, page2_resp]
+            _mock_console_ctx(mock_cls, mock_client)
+
+            result = asyncio.run(_list_nodes_impl(_CONSOLE_KW))
+            assert len(result) == 150
+            assert result[0]["node_id"] == "n-0"
+            assert result[149]["node_id"] == "n-149"
+            assert mock_client.nodes.call_count == 2
+            # Verify offset was passed correctly
+            mock_client.nodes.assert_any_call(limit=100, offset=0)
+            mock_client.nodes.assert_any_call(limit=100, offset=100)
+
 
 # ---------------------------------------------------------------------------
 # _exec_on_node_sync
@@ -50,35 +113,111 @@ class TestListNodesImpl:
 class TestExecOnNodeSync:
     def test_success(self):
         turn_result = TurnResult(
+            ws_id="ws-123",
             tool_results=[("bash", "hello world")],
         )
-        with patch("mcp_cluster_ops.server.TurnstoneClient") as mock_cls:
-            mock_client = MagicMock()
-            mock_client.send_and_wait.return_value = turn_result
-            mock_cls.return_value.__enter__ = MagicMock(return_value=mock_client)
-            mock_cls.return_value.__exit__ = MagicMock(return_value=False)
+        with (
+            patch("mcp_cluster_ops.server.TurnstoneConsole") as mock_console_cls,
+            patch("mcp_cluster_ops.server.TurnstoneServer") as mock_server_cls,
+        ):
+            mock_console = MagicMock()
+            mock_console.route_create_workstream.return_value = {
+                "ws_id": "ws-123",
+                "node_url": "http://node-1:8080",
+                "node_id": "node-1",
+                "name": "ws-123",
+            }
+            _mock_console_ctx(mock_console_cls, mock_console)
 
-            node_id, result = _exec_on_node_sync(
-                {"host": "localhost"}, "node-1", "echo hello", 60.0
-            )
+            mock_server = MagicMock()
+            mock_server.send_and_wait.return_value = turn_result
+            _mock_server_ctx(mock_server_cls, mock_server)
+
+            node_id, result = _exec_on_node_sync(_CONSOLE_KW_AUTH, "node-1", "echo hello", 60.0)
             assert node_id == "node-1"
             assert result.ok
-            mock_client.send_and_wait.assert_called_once()
-            call_kwargs = mock_client.send_and_wait.call_args
-            assert call_kwargs.kwargs["target_node"] == "node-1"
-            assert call_kwargs.kwargs["auto_approve"] is True
+
+            # Verify console created ws on the right node
+            mock_console.route_create_workstream.assert_called_once_with(
+                target_node="node-1",
+                auto_approve=True,
+            )
+
+            # Verify server connected to the node URL with the token
+            mock_server_cls.assert_called_once_with(
+                base_url="http://node-1:8080",
+                token="tok_test",
+            )
+
+            # Verify send_and_wait got the right ws_id
+            call_kwargs = mock_server.send_and_wait.call_args
+            assert call_kwargs.args[1] == "ws-123"
+
+            # Verify workstream was closed
+            mock_console.route_close.assert_called_once_with("ws-123")
 
     def test_timeout(self):
-        turn_result = TurnResult(timed_out=True)
-        with patch("mcp_cluster_ops.server.TurnstoneClient") as mock_cls:
-            mock_client = MagicMock()
-            mock_client.send_and_wait.return_value = turn_result
-            mock_cls.return_value.__enter__ = MagicMock(return_value=mock_client)
-            mock_cls.return_value.__exit__ = MagicMock(return_value=False)
+        turn_result = TurnResult(ws_id="ws-456", timed_out=True)
+        with (
+            patch("mcp_cluster_ops.server.TurnstoneConsole") as mock_console_cls,
+            patch("mcp_cluster_ops.server.TurnstoneServer") as mock_server_cls,
+        ):
+            mock_console = MagicMock()
+            mock_console.route_create_workstream.return_value = {
+                "ws_id": "ws-456",
+                "node_url": "http://node-1:8080",
+                "node_id": "node-1",
+            }
+            _mock_console_ctx(mock_console_cls, mock_console)
 
-            _, result = _exec_on_node_sync({"host": "localhost"}, "node-1", "sleep 9999", 1.0)
+            mock_server = MagicMock()
+            mock_server.send_and_wait.return_value = turn_result
+            _mock_server_ctx(mock_server_cls, mock_server)
+
+            _, result = _exec_on_node_sync(_CONSOLE_KW, "node-1", "sleep 9999", 1.0)
             assert result.timed_out
             assert not result.ok
+            # Workstream still closed even on timeout
+            mock_console.route_close.assert_called_once_with("ws-456")
+
+    def test_send_failure_still_closes_workstream(self):
+        """Workstream must be closed even if send_and_wait raises."""
+        with (
+            patch("mcp_cluster_ops.server.TurnstoneConsole") as mock_console_cls,
+            patch("mcp_cluster_ops.server.TurnstoneServer") as mock_server_cls,
+        ):
+            mock_console = MagicMock()
+            mock_console.route_create_workstream.return_value = {
+                "ws_id": "ws-789",
+                "node_url": "http://node-1:8080",
+                "node_id": "node-1",
+            }
+            _mock_console_ctx(mock_console_cls, mock_console)
+
+            mock_server = MagicMock()
+            mock_server.send_and_wait.side_effect = ConnectionError("lost connection")
+            _mock_server_ctx(mock_server_cls, mock_server)
+
+            with contextlib.suppress(ConnectionError):
+                _exec_on_node_sync(_CONSOLE_KW, "node-1", "echo hi", 60.0)
+
+            mock_console.route_close.assert_called_once_with("ws-789")
+
+    def test_malformed_route_response_no_leak(self):
+        """If route response is missing ws_id, no route_close is attempted."""
+        with patch("mcp_cluster_ops.server.TurnstoneConsole") as mock_console_cls:
+            mock_console = MagicMock()
+            mock_console.route_create_workstream.return_value = {
+                # Missing "ws_id" and "node_url"
+                "node_id": "node-1",
+            }
+            _mock_console_ctx(mock_console_cls, mock_console)
+
+            with pytest.raises(KeyError):
+                _exec_on_node_sync(_CONSOLE_KW, "node-1", "echo hi", 60.0)
+
+            # route_close must NOT be called — ws_id was never assigned
+            mock_console.route_close.assert_not_called()
 
 
 # ---------------------------------------------------------------------------
@@ -88,61 +227,47 @@ class TestExecOnNodeSync:
 
 class TestDispatchParallel:
     def test_parallel_success(self):
-        def fake_exec(redis_kw: Any, node_id: str, command: str, timeout: float) -> Any:
-            return (node_id, TurnResult(tool_results=[("bash", f"output-{node_id}")]))
+        def fake_exec(console_kw: Any, node_id: str, command: str, timeout: float) -> Any:
+            return (
+                node_id,
+                TurnResult(tool_results=[("bash", f"output-{node_id}")]),
+            )
 
         with patch("mcp_cluster_ops.server._exec_on_node_sync", side_effect=fake_exec):
             results = asyncio.run(
-                _dispatch_parallel(
-                    {"host": "localhost"},
-                    ["a", "b", "c"],
-                    "echo hi",
-                    60.0,
-                    8192,
-                )
+                _dispatch_parallel(_CONSOLE_KW, ["a", "b", "c"], "echo hi", 60.0, 8192)
             )
             assert len(results) == 3
             assert all(r["ok"] for r in results)
             outputs = {r["node"]: r["output"] for r in results}
             assert outputs["a"] == "output-a"
             assert outputs["b"] == "output-b"
+            assert outputs["c"] == "output-c"
 
     def test_partial_failure(self):
-        def fake_exec(redis_kw: Any, node_id: str, command: str, timeout: float) -> Any:
+        def fake_exec(console_kw: Any, node_id: str, command: str, timeout: float) -> Any:
             if node_id == "bad":
-                raise ConnectionError("Redis down")
+                raise ConnectionError("connection refused")
             return (node_id, TurnResult(tool_results=[("bash", "ok")]))
 
         with patch("mcp_cluster_ops.server._exec_on_node_sync", side_effect=fake_exec):
             results = asyncio.run(
-                _dispatch_parallel(
-                    {"host": "localhost"},
-                    ["good", "bad"],
-                    "echo hi",
-                    60.0,
-                    8192,
-                )
+                _dispatch_parallel(_CONSOLE_KW, ["good", "bad"], "echo hi", 60.0, 8192)
             )
             assert len(results) == 2
             good = next(r for r in results if r["node"] == "good")
             bad = next(r for r in results if r["node"] == "bad")
             assert good["ok"] is True
             assert bad["ok"] is False
-            assert "Redis down" in bad["error"]
+            assert "connection refused" in bad["error"]
 
     def test_all_fail(self):
-        def fake_exec(redis_kw: Any, node_id: str, command: str, timeout: float) -> Any:
+        def fake_exec(console_kw: Any, node_id: str, command: str, timeout: float) -> Any:
             raise RuntimeError(f"fail-{node_id}")
 
         with patch("mcp_cluster_ops.server._exec_on_node_sync", side_effect=fake_exec):
             results = asyncio.run(
-                _dispatch_parallel(
-                    {"host": "localhost"},
-                    ["a", "b"],
-                    "echo hi",
-                    60.0,
-                    8192,
-                )
+                _dispatch_parallel(_CONSOLE_KW, ["a", "b"], "echo hi", 60.0, 8192)
             )
             assert all(not r["ok"] for r in results)
             assert "fail-a" in results[0]["error"]

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "turnstone"
-version = "0.9.5"
+version = "1.5.0a4"
 description = "Multi-node AI orchestration platform with tool use, agent routing, and cluster simulation."
 readme = "README.md"
 license = "BUSL-1.1"
@@ -12,7 +12,7 @@ requires-python = ">=3.11"
 authors = [{name = "Patrick Buckley", email = "buckleypm@gmail.com"}]
 keywords = ["ai", "chat", "llm", "agent", "tools", "openai"]
 classifiers = [
-    "Development Status :: 4 - Beta",
+    "Development Status :: 5 - Production/Stable",
     "Environment :: Console",
     "Intended Audience :: Developers",
     "Programming Language :: Python :: 3",
@@ -44,26 +44,23 @@ Repository = "https://github.com/turnstonelabs/turnstone"
 Issues = "https://github.com/turnstonelabs/turnstone/issues"
 
 [project.optional-dependencies]
-test = ["pytest>=9.0", "pytest-cov>=6.0", "croniter>=3.0"]
-dev = ["ruff>=0.9", "mypy>=1.14", "types-redis>=4.6"]
-mq = ["redis>=7.2"]
-console = ["redis>=7.2", "croniter>=3.0"]
-sim = ["redis>=7.2"]
+test = ["pytest>=9.0", "pytest-cov>=6.0", "croniter>=3.0", "slack-bolt>=1.18", "aiohttp>=3.9"]
+dev = ["ruff>=0.9", "mypy>=1.14"]
+console = ["croniter>=3.0"]
 anthropic = ["anthropic>=0.39"]
 postgres = ["psycopg[binary]>=3.2"]
 ddg = ["ddgs>=9.0"]
-discord = ["discord.py>=2.4", "redis>=7.2"]
-tls = ["lacme>=1.0.4"]
+discord = ["discord.py>=2.4"]
+tls = ["lacme>=1.0.5"]
 sandbox = ["sympy>=1.13", "numpy>=2.0", "scipy>=1.14", "pytest>=9.0"]
-all = ["turnstone[mq,console,sim,anthropic,postgres,discord,ddg,tls,sandbox]"]
+slack = ["slack-bolt>=1.18", "aiohttp>=3.9"]
+all = ["turnstone[console,anthropic,postgres,discord,ddg,tls,sandbox,slack]"]
 
 [project.scripts]
 turnstone = "turnstone.cli:main"
 turnstone-eval = "turnstone.eval:main"
 turnstone-server = "turnstone.server:main"
-turnstone-bridge = "turnstone.mq.bridge:main"
 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"
@@ -71,6 +68,7 @@ turnstone-bootstrap = "turnstone.bootstrap:main"
 [tool.hatch.build.targets.wheel]
 include = [
   "turnstone/**/*.py",
+  "turnstone/prompts/**/*.md",
   "turnstone/tools/*.json",
   "turnstone/ui/static/*.html",
   "turnstone/ui/static/*.css",
@@ -78,12 +76,17 @@ include = [
   "turnstone/console/static/*.html",
   "turnstone/console/static/*.css",
   "turnstone/console/static/*.js",
+  "turnstone/console/static/coordinator/*.html",
+  "turnstone/console/static/coordinator/*.js",
   "turnstone/shared_static/*.css",
   "turnstone/shared_static/*.js",
-  "turnstone/shared_static/katex-0.16.44/**/*",
+  "turnstone/shared_static/design/**/*",
+  "turnstone/shared_static/katex-0.16.45/**/*",
   "turnstone/shared_static/hljs-11.11.1/**/*",
-  "turnstone/shared_static/mermaid-11.13.0/**/*",
+  "turnstone/shared_static/mermaid-11.14.0/**/*",
+  "turnstone/shared_static/hls-1.6.16/**/*",
   "turnstone/sdk/py.typed",
+  "turnstone/deploy/*.yaml",
 ]
 
 [tool.pytest.ini_options]
@@ -182,5 +185,6 @@ disallow_untyped_decorators = false
 warn_unused_ignores = false
 
 [[tool.mypy.overrides]]
-module = "tests.*"
-disallow_untyped_defs = false
+module = ["slack_bolt", "slack_bolt.*", "slack_sdk", "slack_sdk.*"]
+ignore_missing_imports = true
+disallow_untyped_calls = false

scripts/release.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+#
+# Bump version, regenerate lockfile, commit, and tag.
+#
+# Usage:
+#   scripts/release.sh 1.0.0          # stable release
+#   scripts/release.sh 1.1.0a1        # experimental pre-release
+#   scripts/release.sh 1.0.1 --push   # bump + push tag to origin
+#
+set -euo pipefail
+
+VERSION="${1:?Usage: scripts/release.sh VERSION [--push]}"
+PUSH="${2:-}"
+
+# Validate PEP 440 version
+if ! echo "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+(a[0-9]+|b[0-9]+|rc[0-9]+)?$'; then
+    echo "error: invalid PEP 440 version: $VERSION" >&2
+    echo "  examples: 1.0.0, 1.1.0a1, 1.0.1rc2" >&2
+    exit 1
+fi
+
+TAG="v${VERSION}"
+
+# Check for clean working tree
+if ! git diff --quiet || ! git diff --cached --quiet; then
+    echo "error: working tree is dirty — commit or stash first" >&2
+    exit 1
+fi
+
+# Check tag doesn't already exist
+if git rev-parse "$TAG" >/dev/null 2>&1; then
+    echo "error: tag $TAG already exists" >&2
+    exit 1
+fi
+
+# Detect current version
+CURRENT=$(grep -oP '(?<=^version = ")[^"]+' pyproject.toml)
+echo "Bumping $CURRENT → $VERSION"
+
+# Update version in both files
+sed -i "s/^version = \".*\"/version = \"$VERSION\"/" pyproject.toml
+sed -i "s/^__version__ = \".*\"/__version__ = \"$VERSION\"/" turnstone/__init__.py
+
+# Regenerate lockfile
+echo "Regenerating uv.lock..."
+uv lock
+
+# Commit and tag
+git add pyproject.toml turnstone/__init__.py uv.lock
+git commit -m "chore: bump version to $VERSION"
+git tag "$TAG"
+
+echo ""
+echo "Created commit and tag $TAG"
+
+if [ "$PUSH" = "--push" ]; then
+    BRANCH=$(git rev-parse --abbrev-ref HEAD)
+    echo "Pushing $BRANCH + $TAG to origin..."
+    git push origin "$BRANCH" "$TAG"
+else
+    echo "Run 'git push origin <branch> $TAG' to publish"
+fi