Bump version to 0.4.3

new high level arch abstract
Add 10-node cluster profile to Docker Compose
2026-08-14 07:52:25 -06:00 · 2026-03-07 13:11:42 -08:00 · 2026-03-07 13:01:19 -08:00 · 2026-03-07 12:54:41 -08:00 · 2026-03-07 12:49:07 -08:00 · 2026-03-05 20:18:46 -08:00
128 changed files with 18959 additions and 1665 deletions
@@ -22,6 +22,7 @@ OPENAI_API_KEY=sk-...
 # -- Authentication ------------------------------------------------------------
 # TURNSTONE_AUTH_ENABLED=true
 # TURNSTONE_AUTH_TOKEN=your-secret-token
+# TURNSTONE_JWT_SECRET=python -c "import secrets; print(secrets.token_hex(32))"

 # -- Ports ---------------------------------------------------------------------
 # SERVER_PORT=8080
@@ -17,3 +17,5 @@ venv/
 .plan.md
 .plan-*.md
 .hypothesis/
+PROGRESS.md
+.coverage
@@ -34,7 +34,7 @@ RUN useradd --create-home --shell /bin/bash turnstone

 # Install the wheel with all optional extras
 COPY --from=builder /build/wheels/*.whl /tmp/wheels/
-RUN pip install --no-cache-dir "$(ls /tmp/wheels/*.whl)[mq,console,sim,postgres]" \
+RUN pip install --no-cache-dir "$(ls /tmp/wheels/*.whl)[mq,console,sim,postgres,discord]" \
    && rm -rf /tmp/wheels

 # Health check script (stdlib only, no pip deps needed)
@@ -19,13 +19,9 @@ Turnstone gives LLMs tools — shell, files, search, web, planning — and orche
 - **Cluster dashboard** — real-time view of all nodes and workstreams, workstream creation with node targeting, reverse proxy for server UIs (only the console port needs network access)
 - **Cluster simulator** — test the stack at scale (up to 1000 nodes) without an LLM backend

-```
-External System → Message Queue → Bridge (per node) → Turnstone Server → LLM + Tools
-                                      ↓
-                                 Pub/Sub → Progress Events → External System
-                                      ↓
-                                 turnstone-console → Cluster Dashboard (browser)
-```
+<p align="center">
+  <img src="docs/diagrams/architecture-overview.svg" alt="Turnstone system architecture — data flow from clients through gateways, Redis MQ, cluster nodes, to LLM providers" width="960"/>
+</p>

 ## Quickstart

@@ -111,69 +107,7 @@ All frontends connect to any OpenAI-compatible API (vLLM, NVIDIA NIM/NGC, llama.

 ## Architecture

-```
-turnstone/
-├── core/              # UI-agnostic engine
-│   ├── session.py     # ChatSession — multi-turn loop, tool dispatch, agents
-│   ├── providers/     # LLM provider adapters (OpenAI, Anthropic)
-│   │   ├── _protocol.py   # LLMProvider protocol, ModelCapabilities, StreamChunk
-│   │   ├── _openai.py     # OpenAI-compatible (OpenAI, vLLM, llama.cpp)
-│   │   └── _anthropic.py  # Anthropic Messages API (native streaming, thinking)
-│   ├── tools.py       # Tool definitions (auto-loaded from JSON)
-│   ├── workstream.py  # WorkstreamManager — parallel independent sessions
-│   ├── mcp_client.py  # MCP client manager (external tool servers)
-│   ├── model_registry.py # ModelRegistry — named models, fallback routing, per-workstream selection
-│   ├── config.py      # Unified TOML config (~/.config/turnstone/config.toml)
-│   ├── memory.py      # Persistence facade (delegates to storage/)
-│   ├── storage/       # Pluggable storage backend (SQLite + PostgreSQL)
-│   ├── metrics.py     # Prometheus-compatible metrics collector
-│   ├── healthcheck.py # Backend health monitor + circuit breaker
-│   ├── ratelimit.py   # Per-IP token-bucket rate limiter
-│   ├── edit.py        # File editing (fuzzy match, indentation)
-│   ├── safety.py      # Path validation, sandbox checks
-│   ├── sandbox.py     # Command sandboxing
-│   └── web.py         # Web fetch/search helpers
-├── mq/                # Message queue integration
-│   ├── protocol.py    # Typed message dataclasses (JSON serialization)
-│   ├── broker.py      # Abstract MessageBroker + RedisBroker
-│   ├── bridge.py      # Bridge service (queue ↔ HTTP API, multi-node routing)
-│   └── client.py      # TurnstoneClient — Python API for external systems
-├── console/           # Cluster dashboard
-│   ├── collector.py   # ClusterCollector — aggregates all nodes via Redis + HTTP
-│   ├── server.py      # Dashboard Starlette/ASGI server + SSE
-│   └── static/        # Cluster dashboard web UI
-├── tools/             # Tool schemas (one JSON file per tool)
-├── ui/                # Frontend assets and terminal rendering
-│   └── static/        # Web UI (HTML, CSS, JS)
-├── sim/               # Cluster simulator
-│   ├── cluster.py     # SimCluster — orchestrates N nodes + dispatchers
-│   ├── node.py        # SimNode + SimWorkstream — protocol-compatible node
-│   ├── engine.py      # LLM + tool execution simulation
-│   ├── scenario.py    # 5 workload scenarios (steady, burst, node_failure, …)
-│   ├── metrics.py     # Latency, throughput, utilization collection
-│   └── cli.py         # CLI entry point (turnstone-sim)
-├── cli.py             # Terminal frontend (+ /cluster commands for console)
-├── server.py          # Web frontend (Starlette/ASGI + SSE)
-└── eval.py            # Evaluation and prompt optimization harness
-├── api/               # OpenAPI spec generation (Pydantic v2 models)
-├── sdk/               # Client SDKs (sync + async, Python)
-docs/
-├── architecture.md    # System architecture and threading model
-├── api-reference.md   # Web server API and SSE event reference
-├── sdk.md             # Client SDK reference (Python + TypeScript)
-├── console.md         # Cluster dashboard service (turnstone-console)
-├── docker.md          # Docker Compose deployment and configuration
-├── simulator.md       # Cluster simulator usage and scenarios
-├── tools.md           # Tool schemas, execution pipeline, approval flow
-├── eval.md            # Evaluation harness internals
-└── diagrams/          # UML architecture diagrams (PlantUML sources + PNGs)
-    └── png/           # Pre-rendered diagram images
-deploy/
-├── helm/turnstone/    # Helm chart for Kubernetes
-└── terraform/         # Terraform modules (AWS ECS/Fargate)
-```
-
-### Architecture Diagrams
+### Diagrams

 Detailed UML diagrams are available in [`docs/diagrams/`](docs/diagrams/):

@@ -412,6 +346,7 @@ Per-workstream metrics are labeled by `ws_id` (bounded to 10 max workstreams).
 - Redis (for message queue bridge — `pip install turnstone[mq]`)
 - Anthropic provider (optional — `pip install turnstone[anthropic]`)
 - PostgreSQL (optional, for production — `pip install turnstone[postgres]`)
+- [Git LFS](https://git-lfs.com/) (for cloning — diagram PNGs are stored in LFS)

 ## License

@@ -5,8 +5,8 @@
 #   Default (SQLite):     docker compose up
 #   Production (PG):      DB_BACKEND=postgresql docker compose --profile production up
 #                         (or set DB_BACKEND=postgresql in .env)
+#   10-node cluster:      docker compose --profile cluster up
 #   With simulator:       docker compose --profile sim up
-#   Scale bridges:        docker compose up --scale bridge=3
 # =============================================================================

 name: turnstone
@@ -28,6 +28,7 @@ services:
    image: postgres:17-alpine
    profiles:
      - production
+      - cluster
    environment:
      POSTGRES_DB: turnstone
      POSTGRES_USER: ${POSTGRES_USER:-turnstone}
@@ -109,9 +110,11 @@ services:
      - SKIP_PERMISSIONS=${SKIP_PERMISSIONS:-}
      - TURNSTONE_AUTH_ENABLED=${TURNSTONE_AUTH_ENABLED:-}
      - TURNSTONE_AUTH_TOKEN=${TURNSTONE_AUTH_TOKEN:-}
+      - TURNSTONE_JWT_SECRET=${TURNSTONE_JWT_SECRET:-}
      - MODEL=${MODEL:-}
      - TURNSTONE_DB_BACKEND=${DB_BACKEND:-sqlite}
      - TURNSTONE_DB_URL=${DATABASE_URL:-}
+      - TURNSTONE_NODE_ID=${TURNSTONE_NODE_ID:-}
    extra_hosts:
      - "host.docker.internal:host-gateway"
    networks:
@@ -148,6 +151,7 @@ services:
    environment:
      - REDIS_PASSWORD=${REDIS_PASSWORD:-}
      - TURNSTONE_AUTH_TOKEN=${TURNSTONE_AUTH_TOKEN:-}
+      - TURNSTONE_JWT_SECRET=${TURNSTONE_JWT_SECRET:-}
    networks:
      - turnstone-net
    depends_on:
@@ -177,6 +181,9 @@ services:
      - REDIS_PASSWORD=${REDIS_PASSWORD:-}
      - TURNSTONE_AUTH_ENABLED=${TURNSTONE_AUTH_ENABLED:-}
      - TURNSTONE_AUTH_TOKEN=${TURNSTONE_AUTH_TOKEN:-}
+      - TURNSTONE_JWT_SECRET=${TURNSTONE_JWT_SECRET:-}
+      - TURNSTONE_DB_BACKEND=${DB_BACKEND:-sqlite}
+      - TURNSTONE_DB_URL=${DATABASE_URL:-}
    networks:
      - turnstone-net
    depends_on:
@@ -190,6 +197,43 @@ services:
      start_period: 10s
    restart: unless-stopped

+  # -------------------------------------------------------------------
+  # turnstone-channel — Channel gateway (Discord, Slack, etc.)
+  # Requires TURNSTONE_DISCORD_TOKEN to enable Discord adapter
+  # -------------------------------------------------------------------
+  channel:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    profiles:
+      - production
+    command:
+      - sh
+      - -c
+      - >-
+        turnstone-channel
+        --redis-host=redis
+        --redis-port=6379
+        --http-host=0.0.0.0
+        $${TURNSTONE_DISCORD_GUILD:+--discord-guild $$TURNSTONE_DISCORD_GUILD}
+    environment:
+      - TURNSTONE_DISCORD_TOKEN=${TURNSTONE_DISCORD_TOKEN:-}
+      - TURNSTONE_DISCORD_GUILD=${TURNSTONE_DISCORD_GUILD:-0}
+      - REDIS_PASSWORD=${REDIS_PASSWORD:-}
+      - TURNSTONE_JWT_SECRET=${TURNSTONE_JWT_SECRET:-}
+      - TURNSTONE_DB_BACKEND=${DB_BACKEND:-sqlite}
+      - TURNSTONE_DB_URL=${DATABASE_URL:-}
+      - TURNSTONE_CHANNEL_ADVERTISE_URL=http://channel:8091
+    networks:
+      - turnstone-net
+    depends_on:
+      redis:
+        condition: service_healthy
+      postgres:
+        condition: service_healthy
+        required: false
+    restart: unless-stopped
+
  # -------------------------------------------------------------------
  # turnstone-sim — Multi-node cluster simulator (no LLM needed)
  # Start with: docker compose --profile sim up
@@ -229,3 +273,219 @@ services:
      redis:
        condition: service_healthy
    restart: "no"
+
+  # ===================================================================
+  # 10-node cluster (profile: cluster)
+  #
+  # Each node is a server + bridge pair.  All share the same PostgreSQL
+  # and Redis instances.  Access via console at :8090.
+  #
+  # Start:  docker compose --profile cluster up
+  # ===================================================================
+
+  # -- cluster servers ------------------------------------------------
+
+  server-1: &cluster-server
+    build: { context: ., dockerfile: Dockerfile }
+    profiles: [cluster]
+    command: &cluster-server-cmd
+      - sh
+      - -c
+      - >-
+        turnstone-server
+        --host 0.0.0.0
+        --port 8080
+        --base-url "$${LLM_BASE_URL}"
+        --api-key "$${OPENAI_API_KEY}"
+        $${MODEL:+--model $$MODEL}
+        $${SKIP_PERMISSIONS:+--skip-permissions}
+    volumes: [turnstone-data:/data]
+    environment: &cluster-server-env
+      LLM_BASE_URL: ${LLM_BASE_URL:-http://host.docker.internal:8000/v1}
+      OPENAI_API_KEY: ${OPENAI_API_KEY:-dummy}
+      TAVILY_API_KEY: ${TAVILY_API_KEY:-}
+      SKIP_PERMISSIONS: ${SKIP_PERMISSIONS:-}
+      TURNSTONE_AUTH_ENABLED: ${TURNSTONE_AUTH_ENABLED:-}
+      TURNSTONE_AUTH_TOKEN: ${TURNSTONE_AUTH_TOKEN:-}
+      TURNSTONE_JWT_SECRET: ${TURNSTONE_JWT_SECRET:-}
+      MODEL: ${MODEL:-}
+      TURNSTONE_DB_BACKEND: ${DB_BACKEND:-postgresql}
+      TURNSTONE_DB_URL: ${DATABASE_URL:-postgresql://${POSTGRES_USER:-turnstone}:${POSTGRES_PASSWORD:?}@postgres:5432/turnstone}
+      TURNSTONE_NODE_ID: node-1
+    extra_hosts: ["host.docker.internal:host-gateway"]
+    networks: [turnstone-net]
+    depends_on:
+      redis: { condition: service_healthy }
+      postgres: { condition: service_healthy }
+    healthcheck:
+      test: ["CMD", "python", "/usr/local/bin/healthcheck.py", "http://127.0.0.1:8080/health"]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+      start_period: 15s
+    deploy:
+      resources:
+        limits: { memory: 384M, cpus: '0.5' }
+    restart: unless-stopped
+
+  server-2:
+    <<: *cluster-server
+    environment: { <<: *cluster-server-env, TURNSTONE_NODE_ID: node-2 }
+  server-3:
+    <<: *cluster-server
+    environment: { <<: *cluster-server-env, TURNSTONE_NODE_ID: node-3 }
+  server-4:
+    <<: *cluster-server
+    environment: { <<: *cluster-server-env, TURNSTONE_NODE_ID: node-4 }
+  server-5:
+    <<: *cluster-server
+    environment: { <<: *cluster-server-env, TURNSTONE_NODE_ID: node-5 }
+  server-6:
+    <<: *cluster-server
+    environment: { <<: *cluster-server-env, TURNSTONE_NODE_ID: node-6 }
+  server-7:
+    <<: *cluster-server
+    environment: { <<: *cluster-server-env, TURNSTONE_NODE_ID: node-7 }
+  server-8:
+    <<: *cluster-server
+    environment: { <<: *cluster-server-env, TURNSTONE_NODE_ID: node-8 }
+  server-9:
+    <<: *cluster-server
+    environment: { <<: *cluster-server-env, TURNSTONE_NODE_ID: node-9 }
+  server-10:
+    <<: *cluster-server
+    environment: { <<: *cluster-server-env, TURNSTONE_NODE_ID: node-10 }
+
+  # -- cluster bridges ------------------------------------------------
+
+  bridge-1: &cluster-bridge
+    build: { context: ., dockerfile: Dockerfile }
+    profiles: [cluster]
+    command:
+      - turnstone-bridge
+      - --server-url=http://server-1:8080
+      - --redis-host=redis
+      - --redis-port=6379
+      - --heartbeat-ttl=${HEARTBEAT_TTL:-60}
+      - --approval-timeout=${APPROVAL_TIMEOUT:-3600}
+    environment: &cluster-bridge-env
+      REDIS_PASSWORD: ${REDIS_PASSWORD:-}
+      TURNSTONE_AUTH_TOKEN: ${TURNSTONE_AUTH_TOKEN:-}
+      TURNSTONE_JWT_SECRET: ${TURNSTONE_JWT_SECRET:-}
+    networks: [turnstone-net]
+    depends_on:
+      server-1: { condition: service_healthy }
+      redis: { condition: service_healthy }
+    deploy:
+      resources:
+        limits: { memory: 256M, cpus: '0.25' }
+    restart: unless-stopped
+
+  bridge-2:
+    <<: *cluster-bridge
+    command:
+      - turnstone-bridge
+      - --server-url=http://server-2:8080
+      - --redis-host=redis
+      - --redis-port=6379
+      - --heartbeat-ttl=${HEARTBEAT_TTL:-60}
+      - --approval-timeout=${APPROVAL_TIMEOUT:-3600}
+    depends_on:
+      server-2: { condition: service_healthy }
+      redis: { condition: service_healthy }
+  bridge-3:
+    <<: *cluster-bridge
+    command:
+      - turnstone-bridge
+      - --server-url=http://server-3:8080
+      - --redis-host=redis
+      - --redis-port=6379
+      - --heartbeat-ttl=${HEARTBEAT_TTL:-60}
+      - --approval-timeout=${APPROVAL_TIMEOUT:-3600}
+    depends_on:
+      server-3: { condition: service_healthy }
+      redis: { condition: service_healthy }
+  bridge-4:
+    <<: *cluster-bridge
+    command:
+      - turnstone-bridge
+      - --server-url=http://server-4:8080
+      - --redis-host=redis
+      - --redis-port=6379
+      - --heartbeat-ttl=${HEARTBEAT_TTL:-60}
+      - --approval-timeout=${APPROVAL_TIMEOUT:-3600}
+    depends_on:
+      server-4: { condition: service_healthy }
+      redis: { condition: service_healthy }
+  bridge-5:
+    <<: *cluster-bridge
+    command:
+      - turnstone-bridge
+      - --server-url=http://server-5:8080
+      - --redis-host=redis
+      - --redis-port=6379
+      - --heartbeat-ttl=${HEARTBEAT_TTL:-60}
+      - --approval-timeout=${APPROVAL_TIMEOUT:-3600}
+    depends_on:
+      server-5: { condition: service_healthy }
+      redis: { condition: service_healthy }
+  bridge-6:
+    <<: *cluster-bridge
+    command:
+      - turnstone-bridge
+      - --server-url=http://server-6:8080
+      - --redis-host=redis
+      - --redis-port=6379
+      - --heartbeat-ttl=${HEARTBEAT_TTL:-60}
+      - --approval-timeout=${APPROVAL_TIMEOUT:-3600}
+    depends_on:
+      server-6: { condition: service_healthy }
+      redis: { condition: service_healthy }
+  bridge-7:
+    <<: *cluster-bridge
+    command:
+      - turnstone-bridge
+      - --server-url=http://server-7:8080
+      - --redis-host=redis
+      - --redis-port=6379
+      - --heartbeat-ttl=${HEARTBEAT_TTL:-60}
+      - --approval-timeout=${APPROVAL_TIMEOUT:-3600}
+    depends_on:
+      server-7: { condition: service_healthy }
+      redis: { condition: service_healthy }
+  bridge-8:
+    <<: *cluster-bridge
+    command:
+      - turnstone-bridge
+      - --server-url=http://server-8:8080
+      - --redis-host=redis
+      - --redis-port=6379
+      - --heartbeat-ttl=${HEARTBEAT_TTL:-60}
+      - --approval-timeout=${APPROVAL_TIMEOUT:-3600}
+    depends_on:
+      server-8: { condition: service_healthy }
+      redis: { condition: service_healthy }
+  bridge-9:
+    <<: *cluster-bridge
+    command:
+      - turnstone-bridge
+      - --server-url=http://server-9:8080
+      - --redis-host=redis
+      - --redis-port=6379
+      - --heartbeat-ttl=${HEARTBEAT_TTL:-60}
+      - --approval-timeout=${APPROVAL_TIMEOUT:-3600}
+    depends_on:
+      server-9: { condition: service_healthy }
+      redis: { condition: service_healthy }
+  bridge-10:
+    <<: *cluster-bridge
+    command:
+      - turnstone-bridge
+      - --server-url=http://server-10:8080
+      - --redis-host=redis
+      - --redis-port=6379
+      - --heartbeat-ttl=${HEARTBEAT_TTL:-60}
+      - --approval-timeout=${APPROVAL_TIMEOUT:-3600}
+    depends_on:
+      server-10: { condition: service_healthy }
+      redis: { condition: service_healthy }
@@ -56,6 +56,170 @@ 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.
+
+### Sending Credentials
+
+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:
+
+| 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.
+
+### `POST /v1/api/auth/login`
+
+Authenticate with credentials and receive a JWT. Accepts two credential formats:
+
+**Username + password:**
+
+```json
+{"username": "alice", "password": "hunter2"}
+```
+
+**API token:**
+
+```json
+{"token": "ts_a1b2c3d4e5f6..."}
+```
+
+**Response (success):** `200`
+
+```json
+{
+  "status": "ok",
+  "role": "full",
+  "scopes": "approve,read,write",
+  "jwt": "eyJhbGciOiJIUzI1NiIs...",
+  "user_id": "u_abc123"
+}
+```
+
+The response also sets a `turnstone_auth` HttpOnly cookie containing the JWT.
+
+**Response (failure):** `401`
+
+```json
+{"error": "Invalid credentials"}
+```
+
+---
+
+### `POST /v1/api/auth/logout`
+
+Clears the `turnstone_auth` cookie. No request body required.
+
+**Response:** `200`
+
+```json
+{"status": "ok"}
+```
+
+The response includes a `Set-Cookie` header that expires the auth cookie.
+
+---
+
+### `GET /v1/api/auth/status`
+
+Returns the current authentication state. Works with or without a valid token.
+
+**Response (authenticated):** `200`
+
+```json
+{
+  "authenticated": true,
+  "user_id": "u_abc123",
+  "scopes": ["approve", "read", "write"],
+  "source": "jwt"
+}
+```
+
+**Response (not authenticated):** `200`
+
+```json
+{
+  "authenticated": false,
+  "user_id": null,
+  "scopes": [],
+  "source": null
+}
+```
+
+**Response (auth disabled):** `200`
+
+```json
+{
+  "authenticated": false,
+  "auth_enabled": false
+}
+```
+
+---
+
+### `POST /v1/api/auth/setup`
+
+Creates the first admin user when no users exist in the database. This is a
+public endpoint (no authentication required) that only succeeds when auth is
+enabled and the user database is empty. Both the server and console expose
+this endpoint.
+
+**Request body:**
+
+```json
+{
+  "username": "admin",
+  "display_name": "Admin",
+  "password": "strongpass"
+}
+```
+
+| Field          | Type   | Required | Validation                  |
+|----------------|--------|----------|-----------------------------|
+| `username`     | string | yes      | 1-64 ASCII characters       |
+| `display_name` | string | yes      | Non-empty                   |
+| `password`     | string | yes      | Minimum 8 characters        |
+
+**Response (success):** `200`
+
+```json
+{
+  "status": "ok",
+  "user_id": "u_abc123",
+  "username": "admin",
+  "role": "full",
+  "scopes": "approve,read,write",
+  "jwt": "eyJhbGciOiJIUzI1NiIs..."
+}
+```
+
+The response also sets a `turnstone_auth` HttpOnly cookie containing the JWT.
+
+**Response (already set up):** `409`
+
+```json
+{"error": "Setup already completed"}
+```
+
+Returned when one or more users already exist in the database.
+
+**Response (auth disabled):** `400`
+
+```json
+{"error": "Auth is not enabled"}
+```
+
+---
+
 ## Endpoints

 ### `GET /`
@@ -351,8 +515,8 @@ Returns a list of all active workstreams.
 ```json
 {
  "workstreams": [
-    {"id": "abc123", "name": "default", "state": "idle", "session_id": "a1b2c3d4e5f6"},
-    {"id": "def456", "name": "hacker-news", "state": "thinking", "session_id": "c5d6e7f8a9b0"}
+    {"id": "abc123", "name": "default", "state": "idle"},
+    {"id": "def456", "name": "hacker-news", "state": "thinking"}
  ]
 }
 ```
@@ -364,22 +528,21 @@ Each workstream object:
 | `id`         | string      | Unique workstream routing identifier                   |
 | `name`       | string      | Display name (alias if set, otherwise `ws-xxxx`)       |
 | `state`      | string      | Current state (see state values above)                 |
-| `session_id` | string/null | Session ID of the workstream's `ChatSession`, used for deduplication against `/v1/api/sessions` |

 ---

-### `GET /v1/api/sessions`
+### `GET /v1/api/workstreams/saved`

-Returns a list of saved sessions from the database, ordered by most recently
+Returns a list of saved workstreams from the database, ordered by most recently
 updated.

 **Response:**

 ```json
 {
-  "sessions": [
+  "workstreams": [
    {
-      "session_id": "a1b2c3d4e5f6",
+      "ws_id": "a1b2c3d4e5f6",
      "alias": "refactor",
      "title": "JWT Authentication Refactor",
      "created": "2026-03-01 10:00:00",
@@ -390,16 +553,16 @@ updated.
 }
 ```

-Each session object:
+Each saved workstream object:

 | Field           | Type        | Description                                |
 |-----------------|-------------|--------------------------------------------|
-| `session_id`    | string      | Unique 12-char hex session identifier      |
+| `ws_id`         | string      | Unique workstream identifier               |
 | `alias`         | string/null | User-assigned short name                   |
 | `title`         | string/null | LLM-generated title                        |
-| `created`       | string      | ISO timestamp of session creation          |
+| `created`       | string      | ISO timestamp of workstream creation       |
 | `updated`       | string      | ISO timestamp of last message              |
-| `message_count` | int         | Number of messages in the session          |
+| `message_count` | int         | Number of messages in the workstream       |

 ---

@@ -550,22 +713,25 @@ Creates a new workstream. The server supports up to 10 concurrent workstreams.

 All fields are optional. The body can be empty or an empty JSON object.

-| Field          | Type   | Default | Description                                    |
-|----------------|--------|---------|------------------------------------------------|
-| `name`         | string | auto    | Workstream display name                        |
-| `model`        | string | default | Model alias from the registry (`[models.*]`)   |
-| `auto_approve` | bool   | false   | Auto-approve all tool calls for this workstream |
+| Field            | Type   | Default | Description                                                    |
+|------------------|--------|---------|----------------------------------------------------------------|
+| `name`           | string | auto    | Workstream display name                                        |
+| `model`          | string | default | Model alias from the registry (`[models.*]`)                   |
+| `auto_approve`   | bool   | false   | Auto-approve all tool calls for this workstream                |
+| `resume_ws`      | string | ""      | Workstream ID to resume atomically during creation (empty = fresh)|

 **Response (success):**

 ```json
-{"ws_id": "ghi789", "name": "ws-3"}
+{"ws_id": "ghi789", "name": "ws-3", "resumed": false, "message_count": 0}
 ```

-| Field   | Type   | Description                        |
-|---------|--------|------------------------------------|
-| `ws_id` | string | Unique ID of the new workstream    |
-| `name`  | string | Auto-generated workstream name     |
+| Field           | Type   | Description                                         |
+|-----------------|--------|-----------------------------------------------------|
+| `ws_id`         | string | Unique ID of the new workstream                     |
+| `name`          | string | Auto-generated workstream name                      |
+| `resumed`       | bool   | Whether a previous session was successfully resumed |
+| `message_count` | int    | Number of messages in the resumed session (0 if fresh) |

 **Error (limit reached):**

@@ -692,7 +858,8 @@ liveness probes.
 ```json
 {
  "status": "ok",
-  "version": "0.3.0",
+  "version": "0.4.0",
+  "node_id": "worker-01_a3f2",
  "uptime_seconds": 3614.72,
  "model": "llama-3.1-70b-instruct",
  "workstreams": {
@@ -714,6 +881,7 @@ liveness probes.
 |-------|------|-------------|
 | `status` | string | `"ok"` or `"degraded"` (degraded when backend unreachable) |
 | `version` | string | turnstone server version |
+| `node_id` | string | Server-generated node identity (`{hostname}_{4hex}`) |
 | `uptime_seconds` | number | Seconds since the server process started |
 | `model` | string | Model name detected or configured at startup |
 | `workstreams.total` | integer | Total active workstreams |
@@ -21,6 +21,8 @@ plugs in.
 | `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 |

 ---

@@ -73,8 +75,15 @@ turnstone/
    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
    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
+    _config.py        Base ChannelConfig dataclass
+    discord/          Discord adapter (bot, cog, views, streaming, config)
  shared_static/      Shared design system (base.css, auth.js, theme.js, toast.js, utils.js, kb.js)
  ui/
    colors.py         ANSI color constants with NO_COLOR support
@@ -463,7 +472,7 @@ independently, then returns the final content as the tool result.

 - **task**: uses `self._task_tools` (`TASK_AGENT_TOOLS` + MCP tools)
 - **plan**: uses `self._agent_tools` (`AGENT_TOOLS` + MCP tools). Writes output
-  to `.plan-<session_id>.md` — unique per `ChatSession` so concurrent workstreams
+  to `.plan-<ws_id>.md` — unique per `ChatSession` so concurrent workstreams
  don't collide. On repeat invocations the prior `plan` tool call and its result
  are forwarded from `self.messages` so the agent refines the existing plan rather
  than starting over. Planning instructions are injected as a developer message
@@ -679,8 +688,11 @@ memories
  created  TEXT NOT NULL
  updated  TEXT NOT NULL

-sessions
-  session_id  TEXT PRIMARY KEY
+workstreams
+  ws_id       TEXT PRIMARY KEY
+  node_id     TEXT NOT NULL
+  name        TEXT NOT NULL
+  state       TEXT NOT NULL DEFAULT 'idle'
  alias       TEXT UNIQUE            -- user-assigned short name (nullable)
  title       TEXT                   -- LLM-generated title (nullable)
  created     TEXT NOT NULL
@@ -688,7 +700,7 @@ sessions

 conversations
  id            INTEGER PRIMARY KEY AUTOINCREMENT
-  session_id    TEXT NOT NULL
+  ws_id         TEXT NOT NULL
  timestamp     TEXT NOT NULL
  role          TEXT NOT NULL        -- user | assistant | tool_call | tool_result
  content       TEXT
@@ -697,8 +709,8 @@ conversations
  tool_call_id  TEXT                 -- links tool_call ↔ tool_result for resume
  provider_data TEXT                 -- raw provider content (e.g. Anthropic encrypted)

-session_config
-  session_id  TEXT NOT NULL          -- composite PK with key
+workstream_config
+  ws_id       TEXT NOT NULL          -- composite PK with key
  key         TEXT NOT NULL
  value       TEXT

@@ -713,18 +725,21 @@ and are the single source of truth for both backends and Alembic migrations.

 | Method | Purpose |
 |--------|---------|
-| `register_session(session_id, title)` | Create a sessions row (no-op if exists) |
-| `save_message(session_id, role, content, ...)` | Log a message to conversations |
-| `load_session_messages(session_id)` | Reconstruct OpenAI message format from DB rows |
-| `list_sessions(limit)` | List sessions with >=1 message, ordered by updated DESC |
-| `delete_session(session_id)` | Delete session and all its messages |
-| `prune_sessions(retention_days)` | Remove empty sessions and old unnamed sessions |
-| `resolve_session(alias_or_id)` | Resolve alias, exact id, or id prefix to full session_id |
-| `save_session_config(session_id, config)` | Persist session configuration key/value pairs |
-| `load_session_config(session_id)` | Retrieve session configuration |
-| `set_session_alias(session_id, alias)` | Set user-friendly alias (returns False if taken) |
-| `get_session_name(session_id)` | Return alias if set, else title, else None |
-| `update_session_title(session_id, title)` | Set/update LLM-generated title |
+| `register_workstream(ws_id, node_id, name, state)` | Create a workstreams row (no-op if exists) |
+| `save_message(ws_id, role, content, ...)` | Log a message to conversations |
+| `load_messages(ws_id)` | Reconstruct OpenAI message format from DB rows |
+| `list_workstreams_with_history(limit)` | List workstreams with >=1 message, ordered by updated DESC |
+| `delete_workstream(ws_id)` | Delete workstream and cascade conversations + config |
+| `prune_workstreams(retention_days)` | Remove empty workstreams and old unnamed workstreams |
+| `resolve_workstream(alias_or_id)` | Resolve alias, exact id, or id prefix to full ws_id |
+| `save_workstream_config(ws_id, config)` | Persist workstream configuration key/value pairs |
+| `load_workstream_config(ws_id)` | Retrieve workstream configuration |
+| `set_workstream_alias(ws_id, alias)` | Set user-friendly alias (returns False if taken) |
+| `get_workstream_display_name(ws_id)` | Return alias if set, else title, else None |
+| `update_workstream_title(ws_id, title)` | Set/update LLM-generated title |
+| `update_workstream_state(ws_id, state)` | Update workstream state and bump timestamp |
+| `update_workstream_name(ws_id, name)` | Update workstream display name |
+| `list_workstreams(node_id, limit)` | List workstreams, optionally by node |
 | `kv_get(key)` / `kv_set(key, value)` / `kv_delete(key)` | Generic key-value store (backs memories table) |
 | `kv_list()` / `kv_search(query)` | List or search key-value pairs |
 | `search_history(query, limit)` | Full-text search (FTS5 on SQLite, tsvector on PostgreSQL) |
@@ -743,57 +758,59 @@ pool_size = 5                       # PostgreSQL connection pool size

 Environment variables: `TURNSTONE_DB_BACKEND`, `TURNSTONE_DB_URL`, `TURNSTONE_DB_PATH`.

-### Session Persistence and Resume
+### Persistence and Resume

-Each `ChatSession` generates a 12-char hex `_session_id` on creation and
-registers it in the `sessions` table. Messages are saved to `conversations`
-as they happen via `save_message()`.
+`ws_id` is the sole persistent identity for both routing and conversation
+history. There is no separate `session_id` — the `workstreams` table holds
+alias, title, and state alongside the routing fields (`node_id`, `name`).
+Messages are saved to `conversations` (keyed by `ws_id`) as they happen
+via `save_message()`. Workstream state changes are tracked via
+`update_workstream_state()`.

 **Auto-titling:** After the first complete exchange (user message + assistant
 response), a background thread calls the LLM with a title-generation prompt
 (`reasoning_effort: "low"`, `max_completion_tokens: 200`). The generated
-title (3-8 words) is stored in `sessions.title`.
+title (3-8 words) is stored in `workstreams.title`.

-**Resume flow:** `ChatSession.resume_session(session_id)` calls
-`load_session_messages()` which reconstructs the OpenAI message format from
-database rows:
+**Resume flow:** `ChatSession.resume(ws_id)` calls `load_messages()` which
+reconstructs the OpenAI message format from database rows:

 - `user` and `assistant` rows map directly
 - Consecutive `tool_call` rows are grouped into one assistant message's
  `tool_calls` array, paired with subsequent `tool_result` rows via
  `tool_call_id` (or positional matching for legacy data)
- **Interrupted session repair:** If the last assistant message has
-  `tool_calls` but fewer tool results than expected (session was
+- **Interrupted conversation repair:** If the last assistant message has
+  `tool_calls` but fewer tool results than expected (conversation was
  interrupted mid-execution), the incomplete turn is stripped so the
  LLM can re-generate cleanly
- The session adopts the old `_session_id`, so new messages continue in
-  the same session
+- The `ChatSession` adopts the resumed `_ws_id`, so new messages continue
+  in the same workstream

 **Config persistence:** LLM-affecting parameters (`temperature`,
 `reasoning_effort`, `max_tokens`, `instructions`, `creative_mode`) are
-persisted to the `session_config` table on creation and whenever changed
-via slash commands. `resume_session()` restores these values so resumed
-sessions behave identically to the original.
+persisted to the `workstream_config` table on creation and whenever changed
+via slash commands. `resume()` restores these values so resumed workstreams
+behave identically to the original.

 **`/clear` vs `/new`:** `/clear` wipes in-memory context but preserves
-messages in the database for future resume. `/new` starts a fresh session
-(new `_session_id`), leaving the old session resumable.
+messages in the database for future resume. `/new` starts a fresh workstream
+(new `_ws_id`), leaving the old workstream resumable.

-**Resolution:** `resolve_session()` accepts aliases, exact session IDs, or
-session ID prefixes, enabling `turnstone --resume refactor` or `/resume abc12`.
+**Resolution:** `resolve_workstream()` accepts aliases, exact workstream IDs,
+or ID prefixes, enabling `turnstone --resume refactor` or `/resume abc12`.

-**Session listing:** `list_sessions()` only returns sessions that have at
-least one saved message (`WHERE EXISTS` on `conversations`). Sessions
-registered but never used (e.g., from process startup) are invisible until
-a message is sent.
+**Workstream listing:** `list_workstreams_with_history()` only returns
+workstreams that have at least one saved message (`WHERE EXISTS` on
+`conversations`). Workstreams registered but never used (e.g., from process
+startup) are invisible until a message is sent.

-**Session pruning:** `prune_sessions(retention_days, log_fn)` runs once at
-startup (CLI and server). It removes:
- Sessions with no messages (orphaned registrations)
- Unnamed sessions (`alias IS NULL`) older than `retention_days` days (default 90)
+**Workstream pruning:** `prune_workstreams(retention_days, log_fn)` runs once
+at startup (CLI and server). It removes:
+- Workstreams with no messages (orphaned registrations)
+- Unnamed workstreams (`alias IS NULL`) older than `retention_days` days (default 90)

-Named (aliased) sessions are never age-pruned. Configure with
-`--session-retention-days N` (0 = disable age pruning).
+Named (aliased) workstreams are never age-pruned. Configure with
+`--retention-days N` (0 = disable age pruning).

 ---

@@ -910,6 +927,98 @@ limits using a token-bucket algorithm. Each IP gets a `TokenBucket` with

 ---

+## User Identity and Authentication
+
+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
+   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
+   successful credential validation. Contain `sub` (user_id), `scopes`, and
+   `src` (origin) in claims.
+
+### Scope Model
+
+Three hierarchical scopes control endpoint access:
+
+| Scope | Grants | Endpoints |
+|-------|--------|-----------|
+| `read` | SSE streams, workstream listing, history | GET endpoints |
+| `write` | `read` + send, command, workstream create/close | POST to `/api/send`, `/api/command`, etc. |
+| `approve` | `write` + tool approval, admin operations | POST to `/api/approve`, `/api/admin/*` |
+
+### Middleware Flow
+
+`AuthMiddleware` (ASGI) intercepts every request:
+
+1. **Public path check** — `/`, `/static/*`, `/shared/*`, `/health`,
+   `/metrics`, `/openapi.json`, `/docs`, `/api/auth/*`, and `/api/auth/setup`
+   are always allowed.
+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.
+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
+   logging includes the authenticated identity on every log event.
+
+### Architecture Split
+
+- **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** (Users and Tokens tabs) for managing
+  credentials 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).
+- **First-time setup** — both server and console expose
+  `POST /v1/api/auth/setup`, a public endpoint that creates the initial admin
+  user when no users exist. This avoids the chicken-and-egg problem of needing
+  `approve` scope to create the first user via `/api/admin/users`.
+
+### Auth Storage Tables
+
+Three tables in `storage/_schema.py` support identity:
+
+```sql
+users
+  user_id        TEXT PRIMARY KEY
+  username       TEXT NOT NULL UNIQUE
+  display_name   TEXT NOT NULL
+  password_hash  TEXT NOT NULL       -- bcrypt
+  created        TEXT NOT NULL
+
+api_tokens
+  token_id       TEXT PRIMARY KEY
+  token_hash     TEXT NOT NULL UNIQUE  -- SHA-256 of raw token
+  token_prefix   TEXT NOT NULL         -- first 8 chars for display
+  user_id        TEXT NOT NULL
+  name           TEXT NOT NULL         -- human-readable label
+  scopes         TEXT NOT NULL         -- comma-separated
+  created        TEXT NOT NULL
+  expires        TEXT                  -- optional expiry timestamp
+
+channel_users
+  channel_type      TEXT NOT NULL      -- e.g. "slack", "discord"
+  channel_user_id   TEXT NOT NULL      -- platform-specific user ID
+  user_id           TEXT NOT NULL      -- FK to users
+  PRIMARY KEY (channel_type, channel_user_id)
+```
+
+See [docs/security.md](security.md) for full security details including token
+lifecycle, password hashing, and deployment hardening.
+
+---
+
 ## Threading Model

 ### CLI
@@ -1037,7 +1146,10 @@ a response or the approval timeout (default 3600s / 1 hour) expires.
 `ws_id` for active sends. When the global SSE reports `ws_state → idle` for a tracked
 workstream, the bridge emits a synthetic `TurnCompleteEvent` with the correlation ID.

-**Multi-node routing:** Each bridge has a `node_id` (defaults to hostname) and BLPOPs
+**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.
@@ -1128,7 +1240,7 @@ typed event dataclasses.

 **Two client pairs** (sync + async):

- `TurnstoneServer` / `AsyncTurnstoneServer` — server API (workstreams, chat, streaming, sessions)
+- `TurnstoneServer` / `AsyncTurnstoneServer` — server API (workstreams, chat, streaming)
 - `TurnstoneConsole` / `AsyncTurnstoneConsole` — console API (cluster overview, nodes, workstreams)

 **Design**: async-first with thin sync wrappers. `_BaseClient` provides httpx
@@ -1152,3 +1264,42 @@ with TurnstoneServer("http://localhost:8080", token="tok_xxx") as client:
    result = client.send_and_wait("Hello!", ws.ws_id)
    print(result.content)
 ```
+
+---
+
+## Channel Integrations
+
+> 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
+platform adapter implements the `ChannelAdapter` protocol and translates
+between platform-native events and turnstone MQ messages.
+
+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
+the old workstream's conversation during creation in a single HTTP
+request, eliminating ordering fragility. The bridge emits a
+`WorkstreamResumedEvent` to confirm success.
+
+Discord ships as the first adapter. See [channels.md](channels.md) for
+setup instructions, configuration reference, and the adapter development
+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
+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`),
+and POSTs to `POST /v1/api/notify` on the first healthy gateway. The
+gateway validates the JWT, resolves the target (username lookup via
+`channel_users` or direct `channel_type`+`channel_id`), and delegates to
+the appropriate `ChannelAdapter.send()`. Delivery retries up to 3 times
+with backoff, re-querying the service registry on each attempt. See
+[Notification Flow diagram](diagrams/png/17-notify-flow.png).
@@ -0,0 +1,346 @@
+# Channel Integrations
+
+The `turnstone-channel` gateway connects external messaging platforms to
+turnstone workstreams via Redis MQ. Each platform adapter translates
+platform-native events (messages, button clicks, slash commands) into
+turnstone MQ messages, 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.
+
+---
+
+## Architecture
+
+```
+Discord Gateway
+      |
+      v
+turnstone-channel  (Discord adapter)
+      |
+      v
+  Redis MQ
+      |
+      v
+turnstone-bridge  ──>  turnstone-server
+```
+
+Key components:
+
+- **ChannelAdapter protocol** (`turnstone/channels/_protocol.py`) — generic
+  interface for any messaging platform. Defines `start()`, `stop()`,
+  `send()`, `edit_message()`, `send_approval_request()`,
+  `send_plan_review()`, and `create_thread()`.
+- **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.
+- **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.
+  Survives bot restarts. Stale routes (evicted workstreams) are detected
+  and refreshed on the next message.
+
+---
+
+## Discord Setup
+
+### 1. Create a Discord Application
+
+1. Go to https://discord.com/developers/applications
+2. Click **New Application** and give it a name
+3. Navigate to the **Bot** tab and click **Reset Token** to generate a
+   bot token. Copy it immediately — it is shown only once.
+4. On the same **Bot** tab, scroll down to **Privileged Gateway Intents**
+   and enable **MESSAGE CONTENT INTENT**
+5. Navigate to **OAuth2 > URL Generator**
+6. Under **Scopes**, check `bot` and `applications.commands`
+7. Under **Bot Permissions**, check:
+   - View Channels
+   - Send Messages
+   - Send Messages in Threads
+   - Create Public Threads
+   - Read Message History
+   - Add Reactions
+   - Embed Links
+8. Copy the generated URL, open it in a browser, and add the bot to your
+   Discord server
+
+### 2. Configure Turnstone
+
+**Environment variables** (recommended for Docker):
+
+```bash
+TURNSTONE_DISCORD_TOKEN=your-bot-token-here
+TURNSTONE_DISCORD_GUILD=123456789  # optional, restrict to one guild
+```
+
+**CLI flags** (bare-metal):
+
+```bash
+turnstone-channel \
+  --discord-token "your-bot-token" \
+  --discord-guild 123456789 \
+  --redis-host localhost \
+  --redis-port 6379
+```
+
+**Docker Compose** (production profile):
+
+```bash
+# In .env file:
+TURNSTONE_DISCORD_TOKEN=your-bot-token
+TURNSTONE_DISCORD_GUILD=123456789
+```
+
+Then start the stack:
+
+```bash
+docker compose --profile production up
+```
+
+The `channel` service starts automatically when
+`TURNSTONE_DISCORD_TOKEN` is set.
+
+### 3. Link User Accounts
+
+Discord users must link their account to a turnstone user before they can
+interact with the bot. Unlinked users' messages are silently ignored.
+
+1. The user must have a turnstone API token — created via the admin panel
+   or `turnstone-admin create-token`
+2. In Discord, the user runs `/link`. A modal appears prompting for the
+   API token (the token is never visible in Discord audit logs because it
+   is submitted via modal, not as a slash command argument).
+3. The token is validated against the database. If valid, a
+   `channel_users` mapping is created.
+4. The user can now @mention the bot or use slash commands.
+
+An admin can also force-link or unlink users via the console admin panel
+(Admin > Channels tab).
+
+---
+
+## Usage
+
+### Conversations
+
+- **@mention** the bot in any allowed channel to start a new conversation.
+  The bot creates a Discord thread from the message and a turnstone
+  workstream behind it.
+- All subsequent messages in the thread are routed to the same workstream.
+- The bot streams responses via message edits, updated approximately every
+  1.5 seconds.
+- If the workstream is evicted for capacity, the next message in the
+  thread auto-creates a new workstream and atomically resumes the
+  previous workstream via the `resume_ws` field on
+  `CreateWorkstreamMessage`. The server resumes the workstream during
+  creation (same HTTP request), and the bridge emits a
+  `WorkstreamResumedEvent` back to the channel. The thread receives a
+  *"Resumed: {name} ({count} messages restored)"* confirmation.
+
+### Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/link` | Link Discord account to turnstone (opens modal for API token) |
+| `/unlink` | Unlink Discord account |
+| `/ask <message>` | Create a new thread and workstream with an initial message |
+| `/status` | Show workstream info for the current thread (ephemeral) |
+| `/close` | Close the workstream, delete the route, and archive the thread |
+
+### Tool Approvals
+
+When manual approval is enabled (the default), tool calls are displayed as
+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
+
+Buttons use static `custom_id` values so they survive bot restarts.
+Correlation data (`ws_id`, `correlation_id`) is stored in the embed footer.
+
+**Auto-approval:** When `auto_approve` is true (via `--auto-approve`), or when
+all tools in the request match the `auto_approve_tools` list in the adapter
+config, the bot auto-responds with approval and posts a
+"*Tool auto-approved.*" notice to the thread instead of showing buttons. The
+`auto_approve_tools` list is set via the `ChannelConfig.auto_approve_tools`
+field (useful for allowing specific tools like `bash` or `read_file` while
+still requiring manual approval for others).
+
+### Plan Reviews
+
+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`
+
+---
+
+## Configuration Reference
+
+| CLI Flag | Env Var | Default | Description |
+|----------|---------|---------|-------------|
+| `--discord-token` | `TURNSTONE_DISCORD_TOKEN` | — | 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 |
+| `--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`) |
+
+---
+
+## User Identity
+
+- The `channel_users` table maps `(channel_type, channel_user_id)` to a
+  turnstone `user_id`
+- Self-service linking via the `/link` slash command (modal input, not
+  visible in Discord audit logs)
+- Admin can force-link or unlink via the console admin panel (Admin >
+  Channels tab). Unlinking uses a styled confirmation modal.
+- Unlinked users' messages are silently dropped
+- A user can be linked across multiple platforms (e.g. Discord + Slack)
+
+See [Security: Database Schema](security.md#database-schema) for the
+`channel_users` table definition.
+
+---
+
+## Workstream Lifecycle
+
+1. **Creation** — @mention or `/ask` creates a Discord thread and a
+   turnstone workstream. The `ChannelRouter` persists the mapping in the
+   `channel_routes` table.
+2. **Active** — messages are routed bidirectionally. The bot streams
+   responses via message edits (updated every ~1.5 seconds).
+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
+   the workstream during creation (no separate command or reverse lookup
+   needed). The bridge emits a `WorkstreamResumedEvent` to the channel, and
+   the thread displays *"Resumed: {name} ({count} messages restored)"*.
+   If the old workstream was pruned, a fresh one starts with no error.
+5. **Close** — `/close` command closes the workstream via MQ, deletes the
+   route, unsubscribes from events, and archives the Discord thread.
+
+---
+
+## Notifications
+
+> See also: [Notification Flow diagram](diagrams/png/17-notify-flow.png)
+
+The `notify` tool allows the LLM to proactively send notifications to
+users or channels on external platforms. This is useful for alerting
+people about task completion, errors, or important updates without
+waiting for them to check in.
+
+### Targeting
+
+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).
+- **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
+gateway directly over HTTP:
+
+1. The LLM calls the `notify` tool with a message and target
+2. `_exec_notify()` queries the `services` table for healthy channel
+   gateways (heartbeat within the last 120 seconds)
+3. The server mints a service JWT (`aud: turnstone-channel`) via
+   `ServiceTokenManager` and POSTs to the first healthy gateway
+4. The gateway validates the JWT, resolves the target, and calls
+   `adapter.send()` on the appropriate platform adapter
+5. On failure, the server tries the next gateway. If all fail, it
+   retries up to 2 more times (delays: 1s, 3s), re-querying the
+   service registry on each attempt
+
+### Service Registry
+
+The channel gateway registers itself in the `services` database table
+on startup and sends a heartbeat every 30 seconds. On shutdown it
+deregisters. Services are considered stale after 120 seconds (4 missed
+heartbeats) and are excluded from `list_services()` queries.
+
+The `services` table schema:
+
+| Column | Description |
+|--------|-------------|
+| `service_type` | Service category (e.g. `"channel"`) |
+| `service_id` | Unique instance ID (`channel-<hostname>-<random>`) |
+| `url` | HTTP base URL for the service |
+| `last_heartbeat` | ISO 8601 timestamp of last heartbeat |
+| `created` | ISO 8601 timestamp of initial registration |
+
+### 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.
+- **Rate limit** — maximum 5 notifications per turn. The counter only
+  increments on successful delivery, so failures don't consume the
+  budget.
+- **SSRF protection** — only `http://` and `https://` service URLs
+  are allowed. Other schemes are silently skipped.
+- **Mention sanitization** — `discord.utils.escape_mentions()` is
+  applied before sending, preventing `@everyone` / `@here` abuse.
+- **Error redaction** — generic error messages are returned to the
+  LLM. Internal details (service IDs, URLs, exception messages) are
+  logged server-side only.
+
+---
+
+## Adding New Adapters
+
+The `ChannelAdapter` protocol defines the interface any platform adapter
+must implement:
+
+```python
+class ChannelAdapter(Protocol):
+    channel_type: str
+
+    async def start(self) -> None: ...
+    async def stop(self) -> None: ...
+    async def send(self, channel_id: str, content: 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: ...
+```
+
+To add a new platform:
+
+1. Create `turnstone/channels/<platform>/` package
+2. Implement the `ChannelAdapter` protocol
+3. Add a `--<platform>-token` flag and detection logic in
+   `turnstone/channels/cli.py`
+4. Add the optional dependency in `pyproject.toml` (e.g.
+   `turnstone[slack]`)
+
+See `turnstone/channels/discord/` as a reference implementation.
@@ -148,7 +148,7 @@ Single node detail with all its workstreams.

 ### `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 `"full"` auth role.
+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.

 Request:

@@ -207,6 +207,96 @@ Keepalive comments (`: keepalive\n\n`) are sent every 5 seconds. Clients should
 }
 ```

+### Admin API
+
+User and token management endpoints. All admin endpoints require `approve` scope, except for the setup endpoint which is public.
+
+#### `POST /v1/api/auth/setup`
+
+Creates the first admin user when no users exist. Public endpoint (no auth required). Returns a JWT and sets a session cookie. Returns `409` if users already exist. See [Security: First-time setup](security.md#first-time-setup) for full details.
+
+#### `POST /v1/api/admin/users`
+
+Create a new user.
+
+```json
+{
+  "username": "alice",
+  "password": "s3cret",
+  "scopes": ["read", "write"]
+}
+```
+
+#### `GET /v1/api/admin/users`
+
+List all users.
+
+```json
+{
+  "users": [
+    {"user_id": "u_abc123", "username": "alice", "scopes": ["read", "write"], "created": "2026-03-01T12:00:00Z"}
+  ]
+}
+```
+
+#### `DELETE /v1/api/admin/users/{user_id}`
+
+Delete a user and revoke all their tokens.
+
+#### `POST /v1/api/admin/users/{user_id}/tokens`
+
+Create an API token for the given user. Returns a `ts_`-prefixed token string that can be used for Bearer auth or passed to `client.login(token="ts_xxx")`.
+
+```json
+{
+  "name": "CI pipeline",
+  "scopes": ["read", "write"]
+}
+```
+
+#### `GET /v1/api/admin/users/{user_id}/tokens`
+
+List active tokens for a user (token strings are not returned, only metadata).
+
+#### `DELETE /v1/api/admin/tokens/{token_id}`
+
+Revoke a specific API token.
+
+### Channel links
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/v1/api/admin/users/{user_id}/channels` | List channel links for a user |
+| POST | `/v1/api/admin/users/{user_id}/channels` | Link a channel account (channel_type, channel_user_id) |
+| DELETE | `/v1/api/admin/channels/{channel_type}/{channel_user_id}` | Unlink a channel account |
+
+These endpoints manage the `channel_users` table mappings that connect external platform identities (e.g. Discord user IDs) to turnstone users. See [Channel Integrations](channels.md) for details on the linking flow.
+
+#### `GET /v1/api/auth/status`
+
+Public endpoint for login UI state detection. Returns auth configuration, not
+current-user identity.
+
+```json
+{
+  "auth_enabled": true,
+  "has_users": true,
+  "setup_required": false
+}
+```
+
+### Auth Scopes
+
+The auth system uses three scopes instead of the earlier read/full role model:
+
+| Scope | Grants |
+|-------|--------|
+| `read` | Read-only access: dashboards, workstream lists, SSE streams, health |
+| `write` | Send messages, create/close workstreams, approve tool calls |
+| `approve` | Admin operations: manage users and API tokens |
+
+Scopes are cumulative — a user with `approve` scope can also perform `write` and `read` operations.
+
 ---

 ## Reverse Proxy
@@ -240,13 +330,13 @@ SSE streams (`/v1/api/events`, `/v1/api/events/global`) are proxied by creating

 ### Authentication

-The proxy forwards requests to server nodes using the console's `--auth-token`. The console's own auth middleware also checks proxy routes — `POST` requests to proxy write endpoints (`/v1/api/send`, `/v1/api/approve`, etc.) require the `"full"` auth role, preventing read-only tokens from escalating to write operations.
+The proxy forwards the user's JWT to upstream server nodes — it extracts the token from the incoming request's cookie (or `Authorization` header) and adds it as a `Bearer` header on the proxied request.  Since all services share the same `TURNSTONE_JWT_SECRET`, the user's JWT is valid on every node without re-authentication.  The console's own auth middleware also checks proxy routes — `POST` requests to proxy write endpoints (`/v1/api/send`, `/v1/api/approve`, etc.) require `write` scope, preventing read-only tokens from escalating via proxy.  The static `--auth-token` / `proxy_auth_token` is used as a fallback when no user JWT is present.

 ---

 ## Browser Dashboard

-The web UI has four views, toggled client-side:
+The web UI has five views, toggled client-side:

 ### 1. Cluster Overview (landing)

@@ -276,7 +366,204 @@ Triggered by the "+ new" header button. A modal dialog with:

 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.

-All four views receive live updates via SSE — state cards update counts, node rows update metrics, workstream rows update state indicators.
+All five views receive live updates via SSE — state cards update counts, node rows update metrics, workstream rows update state indicators.
+
+### 5. Admin Panel
+
+Accessed via the "admin" button in the header (visible when authenticated
+with `approve` scope). Provides user, API token, and channel link management
+with three tabs:
+
+**Users tab:**
+
+- Grid table listing all users (username, display name, role, creation date)
+- "Create User" button opens a modal with fields for username, display name,
+  and password (validated: username 1-64 ASCII, password min 8 characters)
+- Delete button on each row opens a styled confirmation modal before
+  removing the user and cascading to revoke all their tokens
+
+**Tokens tab:**
+
+- User selector dropdown to pick which user's tokens to manage
+- Grid table listing tokens for the selected user (name, prefix, scopes,
+  creation date)
+- Scope badges rendered as colored pills for visual clarity
+- "Create Token" button opens a modal with fields for token name and scope
+  checkboxes
+- On creation, a "Token Created" modal displays the raw `ts_`-prefixed
+  token with a copy button. The token is shown once and cannot be retrieved
+  again.
+- Revoke button on each row opens a styled confirmation modal before
+  deleting the token
+
+**Channels tab:**
+
+- User selector dropdown to pick which user's channel links to manage
+- Grid table listing linked channel accounts for the selected user
+  (channel type, channel user ID, creation date)
+- "Link Channel" button opens a modal with fields for channel type
+  (e.g. `discord`) and the platform user ID
+- Unlink button on each row opens a styled confirmation modal before
+  removing the channel mapping
+- Admins can force-link users who have not self-linked via `/link` in
+  Discord
+
+**Accessibility:**
+
+- Full keyboard navigation: focus traps in modals, Escape to close, arrow
+  keys for tab switching
+- Responsive layout with column hiding at 700px breakpoint
+
+**First-time setup:**
+
+The console also exposes `POST /v1/api/auth/setup` for first-time
+bootstrap. When no users exist, the setup wizard calls this public endpoint
+to create the initial admin user and receive a JWT in one step. See
+[Security: First-time setup](security.md#first-time-setup) for details.
+
+---
+
+## 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.
+
+### 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)
+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
+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)
+
+Run history is automatically pruned (runs older than 90 days) approximately once per hour.
+
+### Schedule Types
+
+| Type | Field | Behavior |
+|------|-------|----------|
+| `cron` | `cron_expr` | Recurring schedule using standard 5-field cron syntax. Requires `croniter`. |
+| `at` | `at_time` | One-shot: fires once at the given ISO 8601 timestamp (must include timezone), then auto-disables. |
+
+### Target Modes
+
+| Mode | Behavior |
+|------|----------|
+| `auto` | Picks the reachable node with the most available capacity |
+| `pool` | Pushes to the shared inbound queue (any bridge picks it up) |
+| `all` | Fan-out to all reachable nodes (capped at `max_fan_out`, default 20) |
+| `<node_id>` | Targets a specific node by ID |
+
+### Configuration
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `check_interval` | `15.0` | Seconds between scheduler ticks |
+| `lock_ttl` | `60` | Distributed lock TTL in seconds |
+| `max_fan_out` | `20` | Maximum nodes for `all` target mode |
+
+Dependency: `croniter` (installed with turnstone).
+
+### Schedule API
+
+All schedule endpoints require `approve` scope. Maximum 200 schedules.
+
+#### `GET /v1/api/admin/schedules`
+
+List all scheduled tasks.
+
+```json
+{
+  "schedules": [
+    {
+      "task_id": "a1b2c3d4",
+      "name": "nightly-checks",
+      "description": "Run nightly health checks",
+      "schedule_type": "cron",
+      "cron_expr": "0 2 * * *",
+      "at_time": "",
+      "target_mode": "auto",
+      "model": "",
+      "initial_message": "Run the nightly health check suite.",
+      "auto_approve": false,
+      "auto_approve_tools": [],
+      "enabled": true,
+      "created_by": "u_admin",
+      "last_run": "2026-03-05T02:00:00Z",
+      "next_run": "2026-03-06T02:00:00Z",
+      "created": "2026-03-01T12:00:00Z",
+      "updated": "2026-03-05T02:00:01Z"
+    }
+  ]
+}
+```
+
+#### `POST /v1/api/admin/schedules`
+
+Create a scheduled task.
+
+Request:
+
+```json
+{
+  "name": "nightly-checks",
+  "description": "Run nightly health checks",
+  "schedule_type": "cron",
+  "cron_expr": "0 2 * * *",
+  "target_mode": "auto",
+  "initial_message": "Run the nightly health check suite.",
+  "auto_approve": false,
+  "enabled": true
+}
+```
+
+Required fields: `name`, `schedule_type`, `initial_message`. For `cron` schedules provide `cron_expr`; for `at` schedules provide `at_time` (ISO 8601 with timezone, must be in the future).
+
+Response: `ScheduleInfo` (same shape as list items above). Returns `400` for invalid cron syntax, naive timestamps, or past `at_time`. Returns `409` if the 200-schedule cap is reached.
+
+#### `GET /v1/api/admin/schedules/{task_id}`
+
+Get a single scheduled task. Returns `ScheduleInfo` or `404`.
+
+#### `PUT /v1/api/admin/schedules/{task_id}`
+
+Partial update — only include fields to change. If `schedule_type`, `cron_expr`, or `at_time` change, `next_run` is recomputed automatically.
+
+```json
+{
+  "enabled": false
+}
+```
+
+Response: updated `ScheduleInfo`. Returns `400` for validation errors, `404` if not found.
+
+#### `DELETE /v1/api/admin/schedules/{task_id}`
+
+Delete a scheduled task and all its run history. Returns `{"status": "ok"}` or `404`.
+
+#### `GET /v1/api/admin/schedules/{task_id}/runs?limit=50`
+
+List execution history for a task (most recent first). `limit` defaults to 50, max 200.
+
+```json
+{
+  "runs": [
+    {
+      "run_id": "r_abc123",
+      "task_id": "a1b2c3d4",
+      "node_id": "db-west-04",
+      "ws_id": "ws_xyz",
+      "correlation_id": "corr_789",
+      "started": "2026-03-05T02:00:00Z",
+      "status": "dispatched",
+      "error": ""
+    }
+  ]
+}
+```
+
+Status is `dispatched` on success or `failed` with an `error` message (e.g. no reachable nodes). Failed runs do not advance `next_run`.

 ---

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:d5a2bd1c55ac8cf3b777a8decb6f3bb3d063c10c8f3a9e63457079830e48f456
-size 162310
@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:09cee5819bb7820641a466ed29a53f1b479bc2ded83079fc798c7410bf741a62
-size 329703
@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:b3f76042c8046560502fa3132351821d56e8526b13d38d7be8b839fcf3d5f648
-size 373463
@@ -118,7 +118,7 @@ class "ChatSession" as ChatSession {
    - ui: SessionUI
    - messages: list[dict]
    - _msg_tokens: list[int]
-    - _session_id: str
+    - _ws_id: str
    - _mcp_client: MCPClientManager | None
    - _registry: ModelRegistry | None
    + model_alias: str | None {property}
@@ -130,7 +130,7 @@ class "ChatSession" as ChatSession {
    --
    + send(user_input: str)
    + handle_command(command: str)
-    + resume_session(session_id: str)
+    + resume(ws_id: str)
    - _save_config()
    - _stream_response(stream) → dict
    - _create_stream_with_retry(msgs) → Stream (+ fallback)
@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:fca0957b54101ce5c2b2e06d639b04dc5fff733f2641af0d732c49ea86883882
-size 279397
@@ -18,7 +18,7 @@ User -> CS : send(user_input)
 activate CS

 CS -> CS : messages.append({role: "user", content: input})
-CS -> DB : save_message(session_id, "user", input)
+CS -> DB : save_message(ws_id, "user", input)

 == LLM Call Loop ==

@@ -65,8 +65,8 @@ group loop [while tool_calls present]

    CS -> CS : _update_token_table()\ncalibrate chars_per_token ratio
    CS -> CS : messages.append(assistant_msg)
-    CS -> DB : save_message(session_id, "assistant", content)
-    CS -> DB : save_message(session_id, "tool_call", ...) ×N
+    CS -> DB : save_message(ws_id, "assistant", content)
+    CS -> DB : save_message(ws_id, "tool_call", ...) ×N

    == Tool Dispatch (if tool_calls) ==

@@ -136,7 +136,7 @@ group loop [while tool_calls present]

        loop for each result
            CS -> CS : messages.append({role: "tool", ...})
-            CS -> DB : save_message(session_id, "tool_result", ...)
+            CS -> DB : save_message(ws_id, "tool_result", ...)
        end

        opt user_feedback from approval
@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:06fb9faa29c11395c6fc54ebddc79994b000dee78d56e0c13cb689fd6a82e37a
-size 237255
@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:13b2da77312e5abb44c81aabb7f0addccab31d9bc7e8ef2f1c3563ef985ed503
-size 186941
@@ -35,7 +35,7 @@ package "turnstone/sdk/ (Python)" {
        + stream_events(ws_id)
        + stream_global_events()
        + send_and_wait()
-        + list_sessions()
+        + list_saved_workstreams()
        + login() / logout()
        + health()
    }
@@ -13,18 +13,19 @@ skinparam class {

 ' -- Protocol --
 interface "StorageBackend" as SB <<protocol>> {
-    +register_session(session_id, title)
-    +save_message(session_id, role, content, ...)
-    +load_session_messages(session_id) → list[dict]
-    +list_sessions(limit) → list
-    +delete_session(session_id) → bool
-    +prune_sessions(retention_days) → (int, int)
-    +resolve_session(alias_or_id) → str | None
-    +save_session_config(session_id, config)
-    +load_session_config(session_id) → dict
-    +set_session_alias(session_id, alias) → bool
-    +get_session_name(session_id) → str | None
-    +update_session_title(session_id, title)
+    +save_message(ws_id, role, content, ...)
+    +load_messages(ws_id) → list[dict]
+    +register_workstream(ws_id, node_id, name, state)
+    +update_workstream_state(ws_id, state)
+    +update_workstream_name(ws_id, name)
+    +set_workstream_alias(ws_id, alias) → bool
+    +update_workstream_title(ws_id, title)
+    +resolve_workstream(alias_or_id) → str | None
+    +delete_workstream(ws_id) → bool
+    +prune_workstreams(retention_days) → (int, int)
+    +list_workstreams(node_id, limit) → list
+    +save_workstream_config(ws_id, config)
+    +load_workstream_config(ws_id) → dict
    +kv_get(key) → str | None
    +kv_set(key, value) → str | None
    +kv_delete(key) → bool
@@ -32,6 +33,11 @@ interface "StorageBackend" as SB <<protocol>> {
    +kv_search(query) → list[(str, str)]
    +search_history(query, limit) → list
    +search_history_recent(limit) → list
+    +create_user(user_id, username, display_name, pw_hash)
+    +get_user(user_id) / get_user_by_username(username)
+    +list_users() / delete_user(user_id)
+    +create_api_token(...) / get_api_token_by_hash(hash)
+    +list_api_tokens(user_id) / delete_api_token(id)
    +close()
 }

@@ -58,8 +64,11 @@ class "_schema.py" as Schema <<schema>> {
    +metadata: MetaData
    +memories: Table
    +conversations: Table
-    +sessions: Table
-    +session_config: Table
+    +workstreams: Table (node_id, alias, title, state)
+    +workstream_config: Table
+    +users: Table (username, password_hash)
+    +api_tokens: Table (token_hash, scopes)
+    +channel_users: Table (channel_type)
    --
    SQLAlchemy Core
    Single source of truth
@@ -76,6 +85,7 @@ class "_migrate.py" as Migrate <<migration>> {

 class "migrations/" as Versions <<migration>> {
    001_initial_schema.py
+    002_user_identity.py
 }

 ' -- Registry --
@@ -91,12 +101,14 @@ class "_registry.py" as Registry {

 ' -- Facade --
 class "memory.py" as Facade <<facade>> {
-    +register_session()
    +save_message()
-    +load_session_messages()
+    +load_messages()
+    +register_workstream()
+    +update_workstream_state()
+    +save_workstream_config()
    +save_memory() / delete_memory()
    +search_memories()
-    +... (all 18 functions)
+    +... (all delegated functions)
    --
    Thin delegation to
    get_storage()
@@ -0,0 +1,179 @@
+@startuml
+!theme plain
+title Turnstone — Authentication Architecture
+
+skinparam class {
+    BackgroundColor<<core>> #E8EAF6
+    BackgroundColor<<jwt>> #C8E6C9
+    BackgroundColor<<storage>> #B3E5FC
+    BackgroundColor<<endpoint>> #FFE0B2
+    BackgroundColor<<scope>> #F3E5F5
+}
+
+' -- Core Auth --
+class "AuthConfig" as AC <<core>> {
+    +enabled: bool
+    +tokens: dict[str, str]
+    +check(token) → role | None
+    --
+    Static config-file tokens
+    hmac.compare_digest
+}
+
+class "AuthResult" as AR <<core>> {
+    +user_id: str
+    +scopes: frozenset[str]
+    +token_source: str
+    +has_scope(scope) → bool
+}
+
+class "check_request()" as CR <<core>> {
+    auth_config, method, path,
+    auth_header, cookie_header,
+    jwt_secret, storage
+    → (allowed, status, msg, AuthResult)
+    --
+    1. Auth disabled → allow
+    2. Public path → allow
+    3. Extract Bearer / cookie
+    4. Detect token type
+    5. Validate → AuthResult
+    6. Check scope vs path
+}
+
+' -- Token Types --
+class "JWT (HS256)" as JWT <<jwt>> {
+    sub: user_id
+    scopes: "read,write,approve"
+    src: "password" | "database"
+    iat, exp (24h default)
+    --
+    Detected by: contains "."
+    Validated locally
+    No DB call
+}
+
+class "API Token" as AT <<jwt>> {
+    Format: ts_ + 64 hex
+    Stored: SHA-256 hash
+    --
+    Detected by: starts with "ts_"
+    Lookup by hash in DB
+    Expiry check
+}
+
+class "Config Token" as CT <<core>> {
+    Raw value in memory
+    Role: "read" | "full"
+    --
+    Detected by: fallback
+    hmac.compare_digest
+    No DB needed
+}
+
+' -- Scopes --
+class "Scope Hierarchy" as SH <<scope>> {
+    read: {read}
+    write: {read, write}
+    approve: {read, write, approve}
+    --
+    GET → read
+    POST write paths → write
+    POST /api/approve → approve
+    /api/admin/* → approve
+}
+
+' -- Storage --
+class "users" as UT <<storage>> {
+    user_id (PK)
+    username (unique)
+    display_name
+    password_hash (bcrypt)
+    created
+}
+
+class "api_tokens" as TT <<storage>> {
+    token_id (PK)
+    token_hash (SHA-256, unique)
+    token_prefix
+    user_id → users
+    name, scopes
+    created, expires
+}
+
+' -- Endpoints --
+class "POST /api/auth/login" as Login <<endpoint>> {
+    {username, password}
+    OR {token: "ts_xxx"}
+    → {jwt, role, scopes, user_id}
+    --
+    Sets HttpOnly cookie
+}
+
+class "GET /api/auth/status" as Status <<endpoint>> {
+    → {auth_enabled, has_users,
+       setup_required}
+    --
+    Public (no auth)
+    Drives UI setup wizard
+}
+
+class "POST /api/auth/setup" as Setup <<endpoint>> {
+    {username, display_name, password}
+    → {jwt, user_id, scopes}
+    --
+    Public (no auth)
+    Only when zero users exist
+    Returns 409 if already set up
+}
+
+class "Admin API (Console)" as Admin <<endpoint>> {
+    POST/GET/DELETE users
+    POST/GET tokens
+    DELETE tokens/{id}
+    --
+    Requires approve scope
+}
+
+' -- Relationships --
+CR --> AC : config tokens
+CR --> JWT : validate
+CR --> AT : hash lookup
+CR --> CT : hmac check
+CR --> AR : returns
+CR --> SH : checks
+
+Login --> JWT : issues
+Login --> UT : verify password
+Login --> TT : verify API token
+
+Setup --> UT : create first user
+Setup --> JWT : issues
+
+AT --> TT : lookup by hash
+Admin --> UT : CRUD
+Admin --> TT : CRUD
+
+AR --> SH : scopes from
+
+JWT ..> AR : produces
+AT ..> AR : produces
+CT ..> AR : produces
+
+note right of CR
+  **Middleware Flow**
+  AuthMiddleware on every request:
+  1. Extract token from header/cookie
+  2. Detect type (JWT / ts_ / config)
+  3. Validate → AuthResult
+  4. Set ctx_user_id for logging
+  5. Store auth_result in scope state
+end note
+
+note bottom of SH
+  **Console** owns admin endpoints
+  **Server** validates JWT + config only
+  Both share JWT signing secret
+end note
+
+@enduml
@@ -0,0 +1,250 @@
+@startuml
+!theme plain
+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
+}
+
+' -- External Platforms --
+class "Discord" as Discord <<platform>> {
+    Gateway WebSocket (v10)
+    Message events
+    Interaction callbacks (buttons)
+    Thread-per-workstream
+    --
+    discord.py 2.x
+    asyncio event loop
+}
+
+class "Slack (future)" as Slack <<platform>> {
+    Socket Mode / Events API
+    Block Kit messages
+    --
+    Planned integration
+}
+
+class "Teams (future)" as Teams <<platform>> {
+    Bot Framework
+    Adaptive Cards
+    --
+    Planned integration
+}
+
+' -- Channel Service --
+class "turnstone-channel" as ChannelService <<service>> {
+    entry point: turnstone-channel
+    --
+    One process per platform
+    asyncio event loop
+    Structured logging (structlog)
+    --log-level, --log-format
+    --
+    POST /v1/api/notify (HTTP)
+    GET  /health
+}
+
+class "DiscordBot" as Bot <<service>> {
+    +on_message(msg)
+    +on_interaction(interaction)
+    +send(channel_id, content)
+    +run(token)
+    --
+    discord.py Client
+    Receives message events
+    Sends replies + embeds
+    Creates threads for workstreams
+    Renders approval buttons
+    escape_mentions() on send
+}
+
+class "ChannelRouter" as Router <<service>> {
+    +resolve_route(platform, channel_id)
+        → ws_id | None
+    +register_route(channel_id, ws_id)
+    +resolve_identity(platform, platform_user_id)
+        → user_id | None
+    --
+    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
+}
+
+class "turnstone-server" as Server <<server>> {
+    POST /v1/api/send
+    POST /v1/api/approve
+    POST /v1/api/workstreams/new
+    GET  /v1/api/events?ws_id=
+    --
+    LLM execution + tool use
+    SSE event stream
+    --
+    notify tool: _exec_notify()
+    ServiceTokenManager (JWT)
+}
+
+' -- Storage --
+class "channel_users" as CU <<storage>> {
+    channel_user_id (PK)
+    platform: "discord" | "slack"
+    platform_user_id
+    user_id → users
+    linked_at
+    --
+    /link command creates row
+    Resolved on each inbound message
+}
+
+class "channel_routes" as CR <<storage>> {
+    channel_type (PK)
+    channel_id (PK)
+    ws_id
+    node_id
+    created
+    --
+    Maps platform channels
+    to turnstone workstreams
+}
+
+class "services" as SVC <<storage>> {
+    service_type (PK)
+    service_id (PK)
+    url
+    last_heartbeat
+    created
+    --
+    Heartbeat every 30s
+    Stale after 120s
+    ON CONFLICT DO UPDATE
+}
+
+' -- 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
+
+Redis --> Broker : SUBSCRIBE events:{ws_id}
+Broker --> Bot : event stream
+Bot --> Discord : reply / embed\nbutton callback
+
+Slack .[hidden]. Discord
+Teams .[hidden]. Slack
+
+ChannelService --> Bot : creates + runs
+ChannelService --> Router : creates
+ChannelService --> Broker : creates
+ChannelService --> SVC : register / heartbeat /\nderegister
+
+' -- Notification path (direct HTTP, bypasses MQ) --
+Server --> ChannelService : POST /v1/api/notify\n(JWT: aud=turnstone-channel)
+Server --> SVC : list_services("channel",\nmax_age_seconds=120)
+
+' -- Notes --
+note right of Bot
+  **Inbound Flow**
+  1. Discord message arrives via gateway
+  2. Bot.on_message() fires
+  3. ChannelRouter resolves channel → ws_id
+     (or creates new workstream)
+  4. ChannelRouter resolves platform user → user_id
+     via channel_users table
+  5. Broker.push_inbound(SendMessage)
+  6. Bridge pops from Redis, drives server
+
+  **Workstream Resume (evicted workstreams)**
+  1. Stale route detected (no MQ owner)
+  2. Existing ws_id reused directly from route
+  3. CreateWorkstreamMessage sent with
+     resume_ws=<ws_id>
+  4. Server resumes atomically during creation
+  5. Bridge emits WorkstreamResumedEvent → thread
+end note
+
+note right of Broker
+  **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
+end note
+
+note bottom of CR
+  **Approval Flow**
+  1. ApprovalRequestEvent arrives via events:{ws_id}
+  2. Bot renders Discord buttons (Approve / Deny)
+  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
+end note
+
+note bottom of CU
+  **Identity Linking**
+  1. User runs /link in Discord
+  2. Bot opens modal requesting API token
+  3. User submits ts_... API token
+  4. Bot validates token against storage
+  5. On success, inserts channel_users row
+  6. Subsequent messages carry user_id
+  7. AuthResult scopes applied by server
+end note
+
+note bottom of SVC
+  **Notification Flow** (direct HTTP, bypasses MQ)
+  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
+  6. Gateway validates JWT, resolves target
+  7. adapter.send() → Discord API
+  8. On failure: retry up to 3× (1s, 3s backoff)
+  9. SSRF: only http(s) URLs allowed
+end note
+
+@enduml
@@ -0,0 +1,116 @@
+@startuml
+!theme plain
+title Turnstone — Notification Delivery Flow
+
+skinparam participant {
+    BackgroundColor<<server>> #FFE0B2
+    BackgroundColor<<storage>> #B3E5FC
+    BackgroundColor<<service>> #E8EAF6
+    BackgroundColor<<platform>> #E1BEE7
+}
+
+participant "ChatSession\n(turnstone-server)" as Session <<server>>
+participant "StorageBackend" as Storage <<storage>>
+participant "ServiceTokenManager" as STM <<server>>
+participant "Channel Gateway\n(_http.py)" as Gateway <<service>>
+participant "ChannelAdapter\n(Discord bot)" as Adapter <<service>>
+participant "Discord API" as Discord <<platform>>
+
+== Prepare Phase ==
+
+Session -> Session : _prepare_notify(call_id, args)
+note right
+  Validates:
+  - message (required, ≤2000 chars)
+  - target: username OR channel_type+channel_id
+  - no ambiguous targeting (both set)
+  - partial targeting errors
+end note
+
+== Execute Phase ==
+
+Session -> Session : _exec_notify(item)
+Session -> Session : check rate limit\n(≥5 per turn?)
+
+alt rate limit exceeded
+    Session --> Session : "Error: rate limit exceeded"
+end
+
+loop up to 3 attempts (retry delays: 1s, 3s)
+
+    Session -> Storage : list_services("channel",\nmax_age_seconds=120)
+    Storage --> Session : services[] (sorted by\nlast_heartbeat DESC)
+
+    alt no healthy services
+        Session -> Session : log.warning("notify.no_services")
+        Session -> Session : sleep(delay)
+    else services available
+
+        Session -> STM : bearer_header
+        note right
+          Lazy-init ServiceTokenManager
+          aud: turnstone-channel
+          scope: write
+          Auto-rotates 1h JWTs
+        end note
+        STM --> Session : Authorization: Bearer <jwt>
+
+        loop for each gateway (first-healthy)
+            Session -> Session : SSRF check:\nurl.startswith("http://"|"https://")
+
+            Session -> Gateway : POST /v1/api/notify\n+ Authorization header
+            Gateway -> Gateway : _check_auth()\nvalidate JWT (aud=turnstone-channel)\nor static token
+
+            alt auth failed
+                Gateway --> Session : 401 Unauthorized
+            else auth ok
+
+                alt username target
+                    Gateway -> Storage : get_user_by_username()
+                    Storage --> Gateway : user
+                    Gateway -> Storage : list_channel_users_by_user()
+                    Storage --> Gateway : linked channels
+                else direct target
+                    Gateway -> Gateway : use channel_type + channel_id
+                end
+
+                Gateway -> Adapter : send(channel_id, content)
+                note right
+                  escape_mentions() applied
+                  Chunked for 2000-char limit
+                end note
+                Adapter -> Discord : POST message
+                Discord --> Adapter : message_id
+                Adapter --> Gateway : message_id
+                Gateway --> Session : 200 {results: [{status: "sent"}]}
+
+                Session -> Session : _notify_count += 1
+                Session --> Session : "Notification sent successfully"
+                note right : Return — no further\ngateways tried
+            end
+        end
+
+        alt all gateways failed
+            Session -> Session : log.warning(\n"notify.all_gateways_failed")
+            Session -> Session : sleep(delay)
+        end
+
+    end
+end
+
+alt all retries exhausted
+    Session -> Session : log.warning("notify.delivery_failed")
+    Session --> Session : "Error: notification delivery failed"
+end
+
+== Service Registry (Background) ==
+
+note over Gateway, Storage
+  **Heartbeat Lifecycle**
+  1. Gateway startup: register_service("channel", id, url)
+  2. Every 30s: heartbeat_service("channel", id)
+  3. Shutdown: deregister_service("channel", id)
+  4. Stale after 120s (4 missed heartbeats)
+end note
+
+@enduml
@@ -0,0 +1,286 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 540" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif">
+  <defs>
+    <!-- Arrowhead markers -->
+    <marker id="arrow" viewBox="0 0 10 7" refX="10" refY="3.5" markerWidth="8" markerHeight="6" orient="auto-start-auto">
+      <path d="M 0 0 L 10 3.5 L 0 7 z" fill="#484f58"/>
+    </marker>
+    <marker id="arrow-blue" viewBox="0 0 10 7" refX="10" refY="3.5" markerWidth="8" markerHeight="6" orient="auto-start-auto">
+      <path d="M 0 0 L 10 3.5 L 0 7 z" fill="#58a6ff"/>
+    </marker>
+    <marker id="arrow-green" viewBox="0 0 10 7" refX="10" refY="3.5" markerWidth="8" markerHeight="6" orient="auto-start-auto">
+      <path d="M 0 0 L 10 3.5 L 0 7 z" fill="#3fb950"/>
+    </marker>
+    <marker id="arrow-orange" viewBox="0 0 10 7" refX="10" refY="3.5" markerWidth="8" markerHeight="6" orient="auto-start-auto">
+      <path d="M 0 0 L 10 3.5 L 0 7 z" fill="#f0883e"/>
+    </marker>
+    <marker id="arrow-coral" viewBox="0 0 10 7" refX="10" refY="3.5" markerWidth="8" markerHeight="6" orient="auto-start-auto">
+      <path d="M 0 0 L 10 3.5 L 0 7 z" fill="#f47067"/>
+    </marker>
+    <marker id="arrow-muted" viewBox="0 0 10 7" refX="10" refY="3.5" markerWidth="8" markerHeight="6" orient="auto-start-auto">
+      <path d="M 0 0 L 10 3.5 L 0 7 z" fill="#8b949e"/>
+    </marker>
+
+    <!-- Card shadow filter -->
+    <filter id="shadow" x="-4%" y="-4%" width="108%" height="112%">
+      <feDropShadow dx="0" dy="1" stdDeviation="2" flood-color="#000" flood-opacity="0.4"/>
+    </filter>
+  </defs>
+
+  <!-- Background -->
+  <rect width="1200" height="540" rx="8" fill="#0d1117"/>
+
+  <!-- Title -->
+  <text x="600" y="36" text-anchor="middle" fill="#e6edf3" font-size="15" font-weight="700" letter-spacing="3">TURNSTONE</text>
+  <text x="600" y="54" text-anchor="middle" fill="#8b949e" font-size="11" letter-spacing="1">SYSTEM ARCHITECTURE</text>
+
+  <!-- ==================== COLUMN HEADERS ==================== -->
+  <text x="90" y="86" text-anchor="middle" fill="#58a6ff" font-size="9" font-weight="600" letter-spacing="2">CLIENTS</text>
+  <text x="276" y="86" text-anchor="middle" fill="#3fb950" font-size="9" font-weight="600" letter-spacing="2">GATEWAYS</text>
+  <text x="480" y="86" text-anchor="middle" fill="#f0883e" font-size="9" font-weight="600" letter-spacing="2">MESSAGE QUEUE</text>
+  <text x="700" y="86" text-anchor="middle" fill="#f47067" font-size="9" font-weight="600" letter-spacing="2">CLUSTER NODES</text>
+  <text x="940" y="86" text-anchor="middle" fill="#f778ba" font-size="9" font-weight="600" letter-spacing="2">LLM PROVIDERS</text>
+
+  <!-- ==================== CLIENT BOXES ==================== -->
+  <!-- CLI -->
+  <g filter="url(#shadow)">
+    <rect x="30" y="108" width="120" height="46" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="30" y="108" width="120" height="5" rx="5" fill="#58a6ff"/>
+    <rect x="30" y="108" width="120" height="5" fill="#58a6ff"/>
+    <rect x="30" y="111" width="120" height="2" fill="#161b22"/>
+    <text x="90" y="130" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">CLI</text>
+    <text x="90" y="145" text-anchor="middle" fill="#8b949e" font-size="9">terminal REPL</text>
+  </g>
+
+  <!-- Browser UI -->
+  <g filter="url(#shadow)">
+    <rect x="30" y="174" width="120" height="46" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="30" y="174" width="120" height="5" rx="5" fill="#58a6ff"/>
+    <rect x="30" y="174" width="120" height="5" fill="#58a6ff"/>
+    <rect x="30" y="177" width="120" height="2" fill="#161b22"/>
+    <text x="90" y="196" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">Browser UI</text>
+    <text x="90" y="211" text-anchor="middle" fill="#8b949e" font-size="9">HTTP + SSE</text>
+  </g>
+
+  <!-- SDK / API -->
+  <g filter="url(#shadow)">
+    <rect x="30" y="244" width="120" height="46" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="30" y="244" width="120" height="5" rx="5" fill="#58a6ff"/>
+    <rect x="30" y="244" width="120" height="5" fill="#58a6ff"/>
+    <rect x="30" y="247" width="120" height="2" fill="#161b22"/>
+    <text x="90" y="266" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">SDK / API</text>
+    <text x="90" y="281" text-anchor="middle" fill="#8b949e" font-size="9">programmatic</text>
+  </g>
+
+  <!-- Discord / Slack -->
+  <g filter="url(#shadow)">
+    <rect x="30" y="314" width="120" height="46" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="30" y="314" width="120" height="5" rx="5" fill="#58a6ff"/>
+    <rect x="30" y="314" width="120" height="5" fill="#58a6ff"/>
+    <rect x="30" y="317" width="120" height="2" fill="#161b22"/>
+    <text x="90" y="336" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">Discord / Slack</text>
+    <text x="90" y="351" text-anchor="middle" fill="#8b949e" font-size="9">chat platforms</text>
+  </g>
+
+  <!-- ==================== GATEWAY BOXES ==================== -->
+  <!-- Console -->
+  <g filter="url(#shadow)">
+    <rect x="216" y="118" width="120" height="58" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="216" y="118" width="120" height="5" rx="5" fill="#3fb950"/>
+    <rect x="216" y="118" width="120" height="5" fill="#3fb950"/>
+    <rect x="216" y="121" width="120" height="2" fill="#161b22"/>
+    <text x="276" y="142" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">Console</text>
+    <text x="276" y="157" text-anchor="middle" fill="#8b949e" font-size="9">dashboard + proxy</text>
+    <text x="276" y="169" text-anchor="middle" fill="#8b949e" font-size="9">cluster management</text>
+  </g>
+
+  <!-- Channel Gateway -->
+  <g filter="url(#shadow)">
+    <rect x="216" y="292" width="120" height="58" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="216" y="292" width="120" height="5" rx="5" fill="#3fb950"/>
+    <rect x="216" y="292" width="120" height="5" fill="#3fb950"/>
+    <rect x="216" y="295" width="120" height="2" fill="#161b22"/>
+    <text x="276" y="316" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">Channel Gateway</text>
+    <text x="276" y="331" text-anchor="middle" fill="#8b949e" font-size="9">platform adapter</text>
+    <text x="276" y="343" text-anchor="middle" fill="#8b949e" font-size="9">Discord, Slack, ...</text>
+  </g>
+
+  <!-- ==================== REDIS MQ ==================== -->
+  <g filter="url(#shadow)">
+    <rect x="420" y="168" width="120" height="132" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="420" y="168" width="120" height="5" rx="5" fill="#f0883e"/>
+    <rect x="420" y="168" width="120" height="5" fill="#f0883e"/>
+    <rect x="420" y="171" width="120" height="2" fill="#161b22"/>
+    <text x="480" y="198" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">Redis MQ</text>
+    <line x1="438" y1="210" x2="522" y2="210" stroke="#30363d" stroke-width="1"/>
+    <text x="480" y="228" text-anchor="middle" fill="#8b949e" font-size="9">inbound queues</text>
+    <text x="480" y="243" text-anchor="middle" fill="#8b949e" font-size="9">event pub/sub</text>
+    <text x="480" y="258" text-anchor="middle" fill="#8b949e" font-size="9">node heartbeats</text>
+    <text x="480" y="273" text-anchor="middle" fill="#8b949e" font-size="9">workstream routing</text>
+    <text x="480" y="288" text-anchor="middle" fill="#8b949e" font-size="9">cluster state</text>
+  </g>
+
+  <!-- ==================== CLUSTER NODES ==================== -->
+  <!-- Cluster outline -->
+  <rect x="598" y="100" width="204" height="310" rx="8" fill="none" stroke="#30363d" stroke-width="1" stroke-dasharray="4,3"/>
+  <text x="700" y="422" text-anchor="middle" fill="#30363d" font-size="9" letter-spacing="1">CLUSTER</text>
+
+  <!-- Node A -->
+  <g filter="url(#shadow)">
+    <rect x="614" y="118" width="170" height="100" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="614" y="118" width="170" height="5" rx="5" fill="#f47067"/>
+    <rect x="614" y="118" width="170" height="5" fill="#f47067"/>
+    <rect x="614" y="121" width="170" height="2" fill="#161b22"/>
+    <text x="699" y="142" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">Node A</text>
+    <line x1="632" y1="152" x2="766" y2="152" stroke="#30363d" stroke-width="1"/>
+    <!-- Bridge -->
+    <rect x="626" y="162" width="70" height="28" rx="3" fill="#1c2128" stroke="#30363d" stroke-width="1"/>
+    <text x="661" y="180" text-anchor="middle" fill="#8b949e" font-size="9">bridge</text>
+    <!-- Server -->
+    <rect x="704" y="162" width="70" height="28" rx="3" fill="#1c2128" stroke="#30363d" stroke-width="1"/>
+    <text x="739" y="180" text-anchor="middle" fill="#8b949e" font-size="9">server</text>
+    <!-- Arrow bridge to server -->
+    <line x1="696" y1="176" x2="702" y2="176" stroke="#484f58" stroke-width="1" marker-end="url(#arrow)"/>
+    <!-- Tools label -->
+    <text x="699" y="206" text-anchor="middle" fill="#484f58" font-size="8">14 tools + MCP</text>
+  </g>
+
+  <!-- Node B -->
+  <g filter="url(#shadow)">
+    <rect x="614" y="238" width="170" height="100" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="614" y="238" width="170" height="5" rx="5" fill="#f47067"/>
+    <rect x="614" y="238" width="170" height="5" fill="#f47067"/>
+    <rect x="614" y="241" width="170" height="2" fill="#161b22"/>
+    <text x="699" y="262" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">Node B</text>
+    <line x1="632" y1="272" x2="766" y2="272" stroke="#30363d" stroke-width="1"/>
+    <!-- Bridge -->
+    <rect x="626" y="282" width="70" height="28" rx="3" fill="#1c2128" stroke="#30363d" stroke-width="1"/>
+    <text x="661" y="300" text-anchor="middle" fill="#8b949e" font-size="9">bridge</text>
+    <!-- Server -->
+    <rect x="704" y="282" width="70" height="28" rx="3" fill="#1c2128" stroke="#30363d" stroke-width="1"/>
+    <text x="739" y="300" text-anchor="middle" fill="#8b949e" font-size="9">server</text>
+    <!-- Arrow bridge to server -->
+    <line x1="696" y1="296" x2="702" y2="296" stroke="#484f58" stroke-width="1" marker-end="url(#arrow)"/>
+    <!-- Tools label -->
+    <text x="699" y="326" text-anchor="middle" fill="#484f58" font-size="8">14 tools + MCP</text>
+  </g>
+
+  <!-- ==================== LLM PROVIDERS ==================== -->
+  <!-- OpenAI -->
+  <g filter="url(#shadow)">
+    <rect x="870" y="130" width="140" height="46" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="870" y="130" width="140" height="5" rx="5" fill="#f778ba"/>
+    <rect x="870" y="130" width="140" height="5" fill="#f778ba"/>
+    <rect x="870" y="133" width="140" height="2" fill="#161b22"/>
+    <text x="940" y="153" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">OpenAI</text>
+    <text x="940" y="167" text-anchor="middle" fill="#8b949e" font-size="9">GPT-5, o-series</text>
+  </g>
+
+  <!-- Anthropic -->
+  <g filter="url(#shadow)">
+    <rect x="870" y="196" width="140" height="46" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="870" y="196" width="140" height="5" rx="5" fill="#f778ba"/>
+    <rect x="870" y="196" width="140" height="5" fill="#f778ba"/>
+    <rect x="870" y="199" width="140" height="2" fill="#161b22"/>
+    <text x="940" y="219" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">Anthropic</text>
+    <text x="940" y="233" text-anchor="middle" fill="#8b949e" font-size="9">Claude 4.5 / 4.6</text>
+  </g>
+
+  <!-- Local / vLLM -->
+  <g filter="url(#shadow)">
+    <rect x="870" y="262" width="140" height="46" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="870" y="262" width="140" height="5" rx="5" fill="#f778ba"/>
+    <rect x="870" y="262" width="140" height="5" fill="#f778ba"/>
+    <rect x="870" y="265" width="140" height="2" fill="#161b22"/>
+    <text x="940" y="285" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">Local / vLLM</text>
+    <text x="940" y="299" text-anchor="middle" fill="#8b949e" font-size="9">llama.cpp, NIM</text>
+  </g>
+
+  <!-- ==================== STORAGE ==================== -->
+  <g filter="url(#shadow)">
+    <rect x="614" y="450" width="170" height="52" rx="5" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+    <rect x="614" y="450" width="170" height="5" rx="5" fill="#bc8cff"/>
+    <rect x="614" y="450" width="170" height="5" fill="#bc8cff"/>
+    <rect x="614" y="453" width="170" height="2" fill="#161b22"/>
+    <text x="699" y="476" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">PostgreSQL / SQLite</text>
+    <text x="699" y="492" text-anchor="middle" fill="#8b949e" font-size="9">conversations, memory, auth</text>
+  </g>
+  <text x="699" y="444" text-anchor="middle" fill="#bc8cff" font-size="9" font-weight="600" letter-spacing="2">STORAGE</text>
+
+  <!-- ==================== CONNECTION LINES ==================== -->
+
+  <!-- CLIENT -> GATEWAY connections -->
+  <!-- Browser -> Console -->
+  <line x1="150" y1="197" x2="214" y2="155" stroke="#58a6ff" stroke-width="1.2" stroke-opacity="0.6" marker-end="url(#arrow-blue)"/>
+  <!-- Discord -> Channel -->
+  <line x1="150" y1="337" x2="214" y2="325" stroke="#58a6ff" stroke-width="1.2" stroke-opacity="0.6" marker-end="url(#arrow-blue)"/>
+
+  <!-- CLI -> direct to Node A server (top path, curved) -->
+  <path d="M 150 131 C 200 131, 200 100, 400 100 L 400 100 C 500 100, 570 140, 612 168" stroke="#58a6ff" stroke-width="1.2" stroke-opacity="0.5" fill="none" stroke-dasharray="6,3" marker-end="url(#arrow-blue)"/>
+  <text x="370" y="96" fill="#484f58" font-size="8" text-anchor="middle">direct</text>
+
+  <!-- SDK -> Redis (direct push) -->
+  <line x1="150" y1="267" x2="418" y2="240" stroke="#58a6ff" stroke-width="1.2" stroke-opacity="0.6" marker-end="url(#arrow-blue)"/>
+
+  <!-- GATEWAY -> REDIS connections -->
+  <!-- Console -> Redis -->
+  <line x1="336" y1="160" x2="418" y2="200" stroke="#3fb950" stroke-width="1.2" stroke-opacity="0.6" marker-end="url(#arrow-green)"/>
+  <!-- Channel -> Redis -->
+  <line x1="336" y1="318" x2="418" y2="272" stroke="#3fb950" stroke-width="1.2" stroke-opacity="0.6" marker-end="url(#arrow-green)"/>
+
+  <!-- REDIS -> NODE connections -->
+  <!-- Redis -> Node A bridge -->
+  <line x1="540" y1="210" x2="624" y2="176" stroke="#f0883e" stroke-width="1.2" stroke-opacity="0.6" marker-end="url(#arrow-orange)"/>
+  <!-- Redis -> Node B bridge -->
+  <line x1="540" y1="260" x2="624" y2="296" stroke="#f0883e" stroke-width="1.2" stroke-opacity="0.6" marker-end="url(#arrow-orange)"/>
+
+  <!-- Console -> Node (proxy, dashed) -->
+  <path d="M 336 147 C 380 130, 500 108, 612 145" stroke="#3fb950" stroke-width="1" stroke-opacity="0.4" fill="none" stroke-dasharray="4,3" marker-end="url(#arrow-green)"/>
+  <text x="468" y="120" fill="#484f58" font-size="8" text-anchor="middle">proxy</text>
+
+  <!-- NODE -> LLM connections -->
+  <!-- Node A -> LLM providers -->
+  <line x1="784" y1="168" x2="868" y2="155" stroke="#f47067" stroke-width="1.2" stroke-opacity="0.5" marker-end="url(#arrow-coral)"/>
+  <line x1="784" y1="176" x2="868" y2="219" stroke="#f47067" stroke-width="1.2" stroke-opacity="0.3"/>
+  <line x1="784" y1="180" x2="868" y2="282" stroke="#f47067" stroke-width="1.2" stroke-opacity="0.2"/>
+
+  <!-- Node B -> LLM providers -->
+  <line x1="784" y1="288" x2="868" y2="163" stroke="#f47067" stroke-width="1.2" stroke-opacity="0.2"/>
+  <line x1="784" y1="296" x2="868" y2="222" stroke="#f47067" stroke-width="1.2" stroke-opacity="0.3"/>
+  <line x1="784" y1="300" x2="868" y2="288" stroke="#f47067" stroke-width="1.2" stroke-opacity="0.5" marker-end="url(#arrow-coral)"/>
+
+  <!-- NODE -> STORAGE connections -->
+  <line x1="680" y1="338" x2="680" y2="448" stroke="#bc8cff" stroke-width="1.2" stroke-opacity="0.4" stroke-dasharray="4,3" marker-end="url(#arrow-muted)"/>
+  <line x1="718" y1="218" x2="718" y2="236" stroke="#484f58" stroke-width="1" stroke-opacity="0.3" stroke-dasharray="2,2"/>
+
+  <!-- Extensibility hint -->
+  <text x="699" y="392" text-anchor="middle" fill="#30363d" font-size="10">...</text>
+
+  <!-- Event flow: Bridges -> Redis (dashed, bidirectional feel) -->
+  <line x1="624" y1="186" x2="542" y2="220" stroke="#f0883e" stroke-width="1" stroke-opacity="0.3" stroke-dasharray="3,3"/>
+  <line x1="624" y1="286" x2="542" y2="250" stroke="#f0883e" stroke-width="1" stroke-opacity="0.3" stroke-dasharray="3,3"/>
+  <text x="574" y="242" fill="#484f58" font-size="7" text-anchor="middle">events</text>
+
+  <!-- ==================== FLOW LABELS ==================== -->
+  <!-- Interactive flow label -->
+  <rect x="30" y="395" width="10" height="10" rx="2" fill="none" stroke="#58a6ff" stroke-width="1.5" stroke-dasharray="3,2"/>
+  <text x="46" y="404" fill="#8b949e" font-size="9">interactive (direct)</text>
+
+  <!-- Queue flow label -->
+  <rect x="160" y="395" width="10" height="10" rx="2" fill="none" stroke="#f0883e" stroke-width="1.5"/>
+  <text x="176" y="404" fill="#8b949e" font-size="9">queue-driven</text>
+
+  <!-- Proxy/event label -->
+  <rect x="275" y="395" width="10" height="10" rx="2" fill="none" stroke="#3fb950" stroke-width="1.5" stroke-dasharray="3,2"/>
+  <text x="291" y="404" fill="#8b949e" font-size="9">proxy / events</text>
+
+  <!-- ==================== BOTTOM DETAILS ==================== -->
+  <line x1="30" y1="430" x2="1170" y2="430" stroke="#21262d" stroke-width="1"/>
+
+  <!-- Routing rules at bottom, left-aligned -->
+  <text x="44" y="456" fill="#30363d" font-size="9" font-weight="600" letter-spacing="1">ROUTING</text>
+  <circle cx="44" cy="474" r="3" fill="#f47067" opacity="0.6"/>
+  <text x="54" y="477" fill="#484f58" font-size="9">target_node set  &#x2192;  route to specific node queue</text>
+  <circle cx="44" cy="494" r="3" fill="#f0883e" opacity="0.6"/>
+  <text x="54" y="497" fill="#484f58" font-size="9">ws_id set  &#x2192;  route to owning node</text>
+  <circle cx="44" cy="514" r="3" fill="#58a6ff" opacity="0.6"/>
+  <text x="54" y="517" fill="#484f58" font-size="9">neither  &#x2192;  shared queue, any node picks up</text></svg>
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:0c615984373b4893b6cc5755604f137541e9d391862122746a4fcbae63543563
-size 201041
+oid sha256:733aa17cbfdab60a601cac6adf439c657dd3535e3d6c33c69c2ef93ba8ec5989
+size 251042
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f4b2a2010335f986511c8dabaf49ec046ac02e577f9bc9924897e045f860bb13
+size 248808
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6049cc0b07480df88d0d93aa977a1e97f64b41588325ff41d98be0e39431fc5c
+size 431712
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f55e177e0838a16d9bc4f07b162b4b6a966cc596c9d0a022d35a3c84f23e7b02
+size 221452
@@ -27,6 +27,9 @@ Console dashboard: http://localhost:8090
 | `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.) |
+| `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
@@ -37,6 +40,18 @@ Console dashboard: http://localhost:8090
 docker compose up
 ```

+**Production** — adds PostgreSQL and the channel gateway. Requires `POSTGRES_PASSWORD` and (for Discord) `TURNSTONE_DISCORD_TOKEN`:
+
+```bash
+docker compose --profile production up
+```
+
+**Cluster** — 10-node server/bridge fleet sharing PostgreSQL and Redis. Access all nodes via the console at `:8090`. Requires `POSTGRES_PASSWORD`:
+
+```bash
+docker compose --profile cluster up
+```
+
 **Sim** — adds the simulator. Can run alongside the full stack or standalone with just Redis and the console:

 ```bash
@@ -84,8 +99,35 @@ All configuration is via environment variables in `.env` (copy from `.env.exampl

 | Variable | Default | Description |
 |----------|---------|-------------|
-| `TURNSTONE_AUTH_ENABLED` | — | Set to `1` to require Bearer token auth |
-| `TURNSTONE_AUTH_TOKEN` | — | Shared auth token for server/bridge/console |
+| `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) |
+
+### 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` |
+
+The database stores workstream history, user accounts, and API tokens. When using JWT auth, a database backend is required for user storage.
+
+> **First-time setup:** After deploying with auth enabled, create an initial admin user by running `turnstone-admin create-user` inside the container:
+>
+> ```bash
+> docker compose exec server turnstone-admin create-user --username admin --name "Admin"
+> ```
+>
+> You will be prompted to set a password. Use it to log in via the UI or SDK, then create additional users through the admin API. Pass `--token --scopes read,write,approve` to also generate an initial API token.
+
+### Channel Gateway
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `TURNSTONE_DISCORD_TOKEN` | — | Discord bot token (required to enable Discord adapter) |
+| `TURNSTONE_DISCORD_GUILD` | `0` | Restrict to a single Discord guild (0 = all guilds) |
+
+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

@@ -101,13 +143,13 @@ All configuration is via environment variables in `.env` (copy from `.env.exampl

 ## Scaling

-Scale to multiple server/bridge pairs:
+For multi-node testing, use the `cluster` profile which provides 10 dedicated server+bridge pairs with unique node IDs (`node-1` through `node-10`), resource limits, and shared PostgreSQL:

 ```bash
-docker compose up --scale server=3 --scale bridge=3
+POSTGRES_PASSWORD=secret docker compose --profile cluster up
 ```

-Each bridge auto-generates a unique node ID from its container hostname. When scaling `server`, remove the host port mapping (or use a reverse proxy) to avoid port conflicts.
+The default `server` and `bridge` also run alongside the cluster nodes (11 total). All nodes are accessible via the console dashboard at `:8090`.

 ## Volumes

@@ -128,7 +170,7 @@ docker compose build
 docker compose build --no-cache
 ```

-All five entry points are installed in a single image: `turnstone-server`, `turnstone-bridge`, `turnstone-console`, `turnstone-sim`, `turnstone-eval`.
+All entry points are installed in a single image: `turnstone-server`, `turnstone-bridge`, `turnstone-console`, `turnstone-channel`, `turnstone-admin`, `turnstone-sim`, `turnstone-eval`.

 ## Cleanup

@@ -15,8 +15,10 @@ The Python SDK is included in the `turnstone` package — no extra install requi
 ```python
 from turnstone.sdk import TurnstoneServer

-# Synchronous client
-with TurnstoneServer("http://localhost:8080", token="tok_xxx") as client:
+# Synchronous client — login with username/password
+with TurnstoneServer("http://localhost:8080") as client:
+    client.login(username="alice", password="s3cret")
+
    # Create a workstream
    ws = client.create_workstream(name="Analysis")

@@ -33,6 +35,15 @@ with TurnstoneServer("http://localhost:8080", token="tok_xxx") as client:
    client.close_workstream(ws.ws_id)
 ```

+Alternatively, authenticate with an API token:
+
+```python
+with TurnstoneServer("http://localhost:8080") as client:
+    client.login(token="ts_abc123...")
+    ws = client.create_workstream(name="CI run")
+    result = client.send_and_wait("Run the test suite.", ws.ws_id)
+```
+
 ### Async Client

 ```python
@@ -40,7 +51,8 @@ import asyncio
 from turnstone.sdk import AsyncTurnstoneServer

 async def main():
-    async with AsyncTurnstoneServer("http://localhost:8080", token="tok_xxx") as client:
+    async with AsyncTurnstoneServer("http://localhost:8080") as client:
+        await client.login(username="alice", password="s3cret")
        ws = await client.create_workstream(name="demo")
        async for event in client.stream_events(ws.ws_id):
            if event.type == "content":
@@ -66,9 +78,11 @@ Both `TurnstoneServer` (sync) and `AsyncTurnstoneServer` (async) expose:
 | **Streaming** | `stream_events(ws_id)` | `Iterator[ServerEvent]` |
 | | `stream_global_events()` | `Iterator[ServerEvent]` |
 | **High-level** | `send_and_wait(message, ws_id, *, timeout, on_event)` | `TurnResult` |
-| **Sessions** | `list_sessions()` | `ListSessionsResponse` |
-| **Auth** | `login(token)` | `AuthLoginResponse` |
+| **Saved** | `list_saved_workstreams()` | `ListSavedWorkstreamsResponse` |
+| **Auth** | `login(username=..., password=...)` | `AuthLoginResponse` |
+| | `login(token="ts_xxx")` | `AuthLoginResponse` |
 | | `logout()` | `StatusResponse` |
+| | `auth_status()` | `AuthStatusResponse` |
 | **Health** | `health()` | `HealthResponse` |

 ### Console Client API
@@ -82,8 +96,15 @@ Both `TurnstoneConsole` (sync) and `AsyncTurnstoneConsole` (async) expose:
 | | `workstreams(*, state, node, search, sort, page, per_page)` | `ClusterWorkstreamsResponse` |
 | | `node_detail(node_id)` | `NodeDetailResponse` |
 | | `create_workstream(*, node_id, name, model, initial_message)` | `ConsoleCreateWsResponse` |
+| **Schedules** | `list_schedules()` | `ListSchedulesResponse` |
+| | `create_schedule(*, name, schedule_type, initial_message, ...)` | `ScheduleInfo` |
+| | `get_schedule(task_id)` | `ScheduleInfo` |
+| | `update_schedule(task_id, *, name=..., enabled=..., ...)` | `ScheduleInfo` |
+| | `delete_schedule(task_id)` | `StatusResponse` |
+| | `list_schedule_runs(task_id, *, limit=50)` | `ListScheduleRunsResponse` |
 | **Streaming** | `stream_cluster_events()` | `Iterator[ClusterEvent]` |
-| **Auth** | `login(token)` / `logout()` | `AuthLoginResponse` / `StatusResponse` |
+| **Auth** | `login(username=..., password=...)` / `login(token="ts_xxx")` | `AuthLoginResponse` |
+| | `logout()` | `StatusResponse` |
 | **Health** | `health()` | `ConsoleHealthResponse` |

 ### Event Types
@@ -165,10 +186,11 @@ Located at `sdk/typescript/`. Zero runtime dependencies for browsers; uses nativ
 ```typescript
 import { TurnstoneServer } from "@turnstone/sdk";

-const client = new TurnstoneServer({
-  baseUrl: "http://localhost:8080",
-  token: "tok_xxx",
-});
+const client = new TurnstoneServer({ baseUrl: "http://localhost:8080" });
+
+// Login with username/password or API token
+await client.login({ username: "alice", password: "s3cret" });
+// or: await client.login({ token: "ts_abc123..." });

 // Create workstream and send message
 const ws = await client.createWorkstream({ name: "demo" });
@@ -188,16 +210,14 @@ for await (const event of client.streamEvents(ws.ws_id)) {
 ```typescript
 import { TurnstoneConsole } from "@turnstone/sdk";

-const console = new TurnstoneConsole({
-  baseUrl: "http://localhost:8081",
-  token: "tok_xxx",
-});
+const client = new TurnstoneConsole({ baseUrl: "http://localhost:8090" });
+await client.login({ username: "alice", password: "s3cret" });

-const overview = await console.overview();
+const overview = await client.overview();
 console.log(`Nodes: ${overview.nodes}, Workstreams: ${overview.workstreams}`);

 // Stream cluster events
-for await (const event of console.clusterEvents()) {
+for await (const event of client.clusterEvents()) {
  console.log(event.type, event);
 }
 ```
@@ -256,3 +276,38 @@ sdk/typescript/              TypeScript SDK (npm package)
 The Python SDK reuses Pydantic models from `turnstone/api/` directly — no schema duplication. The TypeScript SDK has hand-written interfaces matching those models.

 Both SDKs follow the same design: typed methods for REST endpoints, async iterators for SSE streams, and a high-level `send_and_wait` method for simple request-response patterns.
+
+---
+
+## Authentication
+
+When auth is enabled on the server, the SDK handles JWT-based authentication automatically.
+
+### Login Flow
+
+There are two ways to authenticate:
+
+1. **Username + password** — calls `POST /v1/api/auth/login` with credentials. The server validates against the user database and returns a JWT.
+
+2. **API token** — calls `POST /v1/api/auth/login` with a `ts_`-prefixed token string. The server looks up the token, resolves the associated user, and returns a JWT.
+
+In both cases the server returns the JWT in the response body and as a `Set-Cookie` header. The SDK extracts the JWT and includes it as a `Bearer` token in the `Authorization` header on all subsequent requests.
+
+```python
+# Username + password
+client.login(username="alice", password="s3cret")
+
+# API token (created via admin API or turnstone-admin CLI)
+client.login(token="ts_abc123...")
+```
+
+### Token Lifecycle
+
+- JWTs have a configurable expiry (default: 24 hours).
+- `client.auth_status()` returns the current user identity and scopes without refreshing the token.
+- `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
+
+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.
@@ -0,0 +1,457 @@
+# 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.
+
+---
+
+## 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
+(`turnstone-admin create-token`) or the console admin API. Stored as
+SHA-256 hashes — the raw token is shown exactly once at creation and
+never persisted in plaintext.
+
+```
+$ turnstone-admin create-token --user abc123 --scopes read,write --name "CI bot"
+Token created: ts_a1b2c3d4e5f6...
+(save this — it will not be shown again)
+```
+
+API tokens can be used directly as `Bearer ts_xxx` headers or exchanged
+for a JWT via the login endpoint.
+
+### JWTs
+
+Short-lived session tokens (24 hours by default). Issued after
+authenticating with username/password or by exchanging an API token.
+HS256-signed with a shared secret. Validated locally on every service
+node — no database call per request.
+
+Claims:
+
+| Claim | Description |
+|-------|-------------|
+| `sub` | User ID |
+| `scopes` | Comma-separated scope list (`read,write,approve`) |
+| `src` | Token source (`password`, `api_token`, `config`) |
+| `iss` | Issuer — always `turnstone` |
+| `aud` | Audience — `turnstone-server` or `turnstone-console` |
+| `iat` | Issued-at timestamp |
+| `exp` | Expiry timestamp |
+
+The `aud` claim prevents cross-service token reuse — a JWT issued for the
+console cannot be used to authenticate against a server node, and vice versa.
+Tokens without an `aud` claim are accepted during the rollout window when
+`audience` validation is not specified.
+
+---
+
+## Scope Model
+
+Scopes are hierarchical — higher scopes imply all lower ones.
+
+| Scope | Grants | Implies |
+|-------|--------|---------|
+| `read` | View workstreams, saved workstreams, history | — |
+| `write` | Send messages, create/close workstreams | `read` |
+| `approve` | Approve tool calls, admin endpoints | `read`, `write` |
+
+### Path-to-scope mapping
+
+| Method | Path pattern | Required scope |
+|--------|-------------|----------------|
+| GET | Any protected path | `read` |
+| POST | `/api/send`, `/api/plan`, `/api/command` | `write` |
+| POST | `/api/workstreams/new`, `/api/workstreams/close` | `write` |
+| POST | `/api/cluster/workstreams/new` | `write` |
+| POST | `/api/approve` | `approve` |
+| Any | `/api/admin/*` | `approve` |
+
+Public paths bypass authentication entirely: `/`, `/health`, `/metrics`,
+`/static/*`, `/shared/*`, `/docs`, `/openapi.json`, `/api/auth/login`,
+`/api/auth/logout`, `/api/auth/status`, `/api/auth/setup`.
+
+---
+
+## Login Flows
+
+### Username and password
+
+```
+POST /v1/api/auth/login
+Content-Type: application/json
+
+{"username": "admin", "password": "s3cret"}
+```
+
+Returns a JWT in the response body and sets an `HttpOnly` session cookie.
+
+### API token exchange
+
+```
+POST /v1/api/auth/login
+Content-Type: application/json
+
+{"token": "ts_a1b2c3d4e5f6..."}
+```
+
+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:
+
+1. `GET /v1/api/auth/status` returns `{"setup_required": true}`
+2. The UI presents a setup wizard
+3. `POST /v1/api/auth/setup` creates the first admin user and returns a
+   JWT in one atomic step (no auth required — this is a public endpoint)
+4. The endpoint returns `409 Conflict` if setup has already been completed
+   (i.e. users already exist in the database)
+5. Subsequent admin requests require `approve` scope
+
+The `/api/auth/setup` endpoint is available on both the server and
+console. It validates input before creating the user:
+
+- **username**: 1-64 ASCII characters
+- **display_name**: required (non-empty)
+- **password**: minimum 8 characters
+
+```
+POST /v1/api/auth/setup
+Content-Type: application/json
+
+{"username": "admin", "display_name": "Admin", "password": "strongpass"}
+```
+
+Response:
+
+```json
+{
+  "status": "ok",
+  "user_id": "u_abc123",
+  "username": "admin",
+  "role": "full",
+  "scopes": "approve,read,write",
+  "jwt": "eyJhbGciOiJIUzI1NiIs..."
+}
+```
+
+The response also sets an `HttpOnly` session cookie containing the JWT,
+so the browser is immediately authenticated after setup completes.
+
+---
+
+## Token Detection Order
+
+The auth middleware inspects the `Authorization: Bearer <token>` header
+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).
+
+---
+
+## Password Storage
+
+Passwords are hashed with **bcrypt** using a random salt per password.
+Plaintext passwords are only accepted over HTTPS in production
+deployments.
+
+---
+
+## Cookie Security
+
+| Attribute | Value | Purpose |
+|-----------|-------|---------|
+| `HttpOnly` | `true` | Prevents JavaScript access |
+| `SameSite` | `Lax` | CSRF protection |
+| `Path` | `/` | Available to all routes |
+| `Max-Age` | 24 hours | Matches JWT expiry |
+| `Secure` | `true` (default) | Always set unless explicitly disabled for dev |
+
+---
+
+## JWT Configuration
+
+| Setting | Config key | Env var | Default |
+|---------|-----------|---------|---------|
+| 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) |
+
+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.
+
+---
+
+## Admin API Endpoints
+
+All admin endpoints require `approve` scope.
+
+### Users
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/v1/api/admin/users` | Create user (username, display_name, password) |
+| GET | `/v1/api/admin/users` | List all users |
+| DELETE | `/v1/api/admin/users/{user_id}` | Delete user and cascade tokens |
+
+### API tokens
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/v1/api/admin/users/{user_id}/tokens` | Create API token (returns raw value once) |
+| GET | `/v1/api/admin/users/{user_id}/tokens` | List tokens (prefix only, no hashes) |
+| DELETE | `/v1/api/admin/tokens/{token_id}` | Revoke token |
+
+---
+
+## CLI Administration
+
+The `turnstone-admin` command provides offline user and token management:
+
+```
+turnstone-admin create-user --username admin --name "Admin" [--password] [--token]
+turnstone-admin create-token --user <user_id> --scopes read,write --name "CI bot"
+turnstone-admin list-users
+turnstone-admin list-tokens
+turnstone-admin revoke-token <token_id>
+```
+
+When `--password` is omitted, the CLI prompts interactively. When
+`--token` is passed to `create-user`, an API token is created alongside
+the user and printed to stdout.
+
+---
+
+## Database Schema
+
+```sql
+CREATE TABLE users (
+    user_id    TEXT PRIMARY KEY,
+    username   TEXT NOT NULL UNIQUE,
+    display_name TEXT NOT NULL,
+    password_hash TEXT NOT NULL,
+    created    TEXT NOT NULL
+);
+
+CREATE TABLE api_tokens (
+    token_id     TEXT PRIMARY KEY,
+    token_hash   TEXT NOT NULL,       -- SHA-256 of raw token
+    token_prefix TEXT NOT NULL,       -- first 8 chars for display
+    user_id      TEXT NOT NULL REFERENCES users(user_id),
+    name         TEXT NOT NULL,
+    scopes       TEXT NOT NULL,       -- comma-separated
+    created      TEXT NOT NULL,
+    expires      TEXT                 -- nullable, ISO 8601
+);
+
+CREATE UNIQUE INDEX ix_api_tokens_hash ON api_tokens(token_hash);
+
+CREATE TABLE channel_users (
+    channel_type    TEXT NOT NULL,
+    channel_user_id TEXT NOT NULL,
+    user_id         TEXT NOT NULL REFERENCES users(user_id),
+    created         TEXT NOT NULL,
+    PRIMARY KEY (channel_type, channel_user_id)
+);
+```
+
+The `sessions` and `workstreams` tables have a nullable `user_id`
+column for attribution when auth is enabled.
+
+---
+
+## Revocation
+
+- **API tokens**: Deleting a token via the admin API or CLI prevents new
+  JWTs from being issued with that token. Existing JWTs derived from the
+  token remain valid until they expire (at most 24 hours).
+- **Config-file tokens**: Remove the token from `config.toml` and
+  restart the service. No JWTs are involved, so revocation is immediate.
+- **JWTs**: Cannot be individually revoked. Rely on short expiry (24h)
+  and revoke the underlying credential to prevent renewal.
+
+---
+
+## Architecture
+
+```
+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    │
+│   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.
+
+### Proxy auth forwarding
+
+When the console proxies requests to server nodes (via `/node/{id}/...`
+routes), it uses a dedicated **service proxy token** with
+`aud: turnstone-server` and `write` scope.  The user's console JWT
+(which has `aud: turnstone-console`) is **not** forwarded — it would be
+rejected by the server's audience validation.
+
+The proxy token is managed by a `ServiceTokenManager` that auto-rotates
+1-hour JWTs, refreshing at 80% of lifetime.  If `--auth-token` is
+provided, that static token is used instead.
+
+### Service-to-service authentication
+
+The bridge and console collector use `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 | `console-proxy` | `write` | `turnstone-server` | Proxied API calls |
+| 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.
+
+Note that the channel gateway uses a distinct JWT audience
+(`turnstone-channel`) from the server (`turnstone-server`) and console
+(`turnstone-console`).  A server-scoped JWT cannot authenticate to the
+channel gateway endpoint, and vice versa.
+
+---
+
+## Configuration Reference
+
+### config.toml
+
+```toml
+[auth]
+enabled = true
+jwt_secret = "your-secret-key-here"
+jwt_expiry_hours = 24
+
+[[auth.tokens]]
+value = "tok_legacy"
+role = "full"
+```
+
+### Environment variables
+
+| 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_CORS_ORIGINS=` | CORS allowed origins (comma-separated; empty = same-origin only) |
+
+---
+
+## Login Rate Limiting
+
+The `/api/auth/login` endpoint is protected by a dedicated
+`LoginRateLimiter` (separate from the general API rate limiter).
+Limits are enforced per-IP and per-username with a sliding window:
+
+- **5 attempts** per **5-minute window** per key
+- Failed logins record against both `ip:{client_ip}` and `user:{username}`
+- Returns `429 Too Many Requests` with `Retry-After` header when exceeded
+- Successful logins do not consume the budget
+
+---
+
+## CORS Policy
+
+By default, no CORS headers are sent (same-origin only). To allow
+cross-origin requests, set `TURNSTONE_CORS_ORIGINS`:
+
+```bash
+# Allow specific origins
+TURNSTONE_CORS_ORIGINS=https://app.example.com,https://admin.example.com
+
+# Allow all origins (development only)
+TURNSTONE_CORS_ORIGINS=*
+```
+
+When the variable is empty or unset, the CORS middleware is not added
+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
+  per request on server nodes.
+- **One-time display** of raw API tokens at creation. The plaintext is
+  never stored; `token_hash` never appears in API responses or logs.
+- **Structured logging audit trail** — `ctx_user_id` is set on every
+  authenticated request and injected into all log events.
+- **Scope enforcement** at the middleware layer before any handler
+  executes. Path-to-scope mapping is defined statically.
+- **JWT audience isolation** — server and console JWTs have distinct
+  `aud` claims, preventing cross-service token reuse.
+- **Login brute-force protection** — per-IP and per-username rate
+  limiting on the login endpoint.
+- **Secure cookies by default** — `Secure` flag set unconditionally;
+  24-hour max-age matches JWT expiry.
+- **CORS restriction** — no CORS headers by default (same-origin only).
+- **Service JWT auto-rotation** — 1-hour expiry with transparent
+  refresh, eliminating long-lived static tokens for inter-service auth.
+- **Secret strength validation** — warning logged when JWT secret is
+  shorter than 32 characters.
@@ -1,6 +1,6 @@
 # Tools Reference

-turnstone exposes 14 built-in tools plus any number of external MCP tools to the
+turnstone exposes 15 built-in tools plus any number of external MCP tools to the
 LLM via the OpenAI function-calling interface. Built-in tools are defined as JSON
 files under `turnstone/tools/` and loaded at startup by `turnstone/core/tools.py`.
 MCP tools are discovered from configured MCP servers at startup by
@@ -46,7 +46,7 @@ schema plus turnstone-specific metadata keys:

 | Name                | Description |
 |---------------------|-------------|
-| `TOOLS`             | All 14 tool definitions (sent to the model). |
+| `TOOLS`             | All 15 tool definitions (sent to the model). |
 | `AGENT_TOOLS`       | Tools with `agent: true` -- available to plan sub-agents. Read-only tools. |
 | `TASK_AGENT_TOOLS`  | Tools with `task_agent: true` -- available to task sub-agents. Includes write operations. |
 | `AGENT_AUTO_TOOLS`  | Set of tool names with `auto_approve: true` -- no user confirmation needed. |
@@ -113,6 +113,7 @@ Each item's `execute` callable is invoked:
 - `remember` -- writes to persistent memory database (lightweight, always auto-approved)
 - `recall` -- reads from persistent memory database
 - `forget` -- deletes from persistent memory database (lightweight, always auto-approved)
+- `notify` -- sends notifications to linked channels (time-sensitive, auto-approved for urgency)

 **Requires user confirmation** (write operations, network access, side effects):
 - `bash` -- arbitrary command execution
@@ -162,6 +163,7 @@ Every tool defines a `primary_key`. The mapping is:
 | `remember`   | `key`       |
 | `recall`     | `query`     |
 | `forget`     | `key`       |
+| `notify`     | `message`   |

 ---

@@ -335,7 +337,7 @@ Plan before implementing -- an autonomous agent explores the codebase and writes
 |-----------|--------|----------|-------------|
 | `prompt`  | string | yes      | What to plan -- the goal, constraints, and scope. |

- **What it does**: Spawns a planning sub-agent with `AGENT_TOOLS` (read-only tools: `read_file`, `search`, `math`, `man`, `web_fetch`, `web_search`). The agent explores the codebase and writes a structured plan to `.plan-<session_id>.md` (unique per session, so concurrent workstreams never collide). If the `plan` tool has been called before in the same session, the prior plan is passed to the agent as context so it refines rather than restarts. After completion, the user is prompted to review and can accept, reject, or annotate the plan.
+- **What it does**: Spawns a planning sub-agent with `AGENT_TOOLS` (read-only tools: `read_file`, `search`, `math`, `man`, `web_fetch`, `web_search`). The agent explores the codebase and writes a structured plan to `.plan-<ws_id>.md` (unique per workstream, so concurrent workstreams never collide). If the `plan` tool has been called before in the same session, the prior plan is passed to the agent as context so it refines rather than restarts. After completion, the user is prompted to review and can accept, reject, or annotate the plan.
 - **Auto-approve**: No -- requires user confirmation, plus post-execution review gate.
 - **Agent availability**: Not available to sub-agents (top-level only).

@@ -387,6 +389,33 @@ Remove a persistent memory by key.

 ---

+## Notifications
+
+### notify
+
+Send a notification to a user or channel on an external platform.
+
+| Parameter      | Type   | Required | Description |
+|----------------|--------|----------|-------------|
+| `message`      | string | yes      | Notification content (plain text, max 2000 chars). |
+| `username`     | string | no       | Turnstone username — sends to all linked channels. |
+| `channel_type` | string | no       | Platform for direct targeting (`discord`). |
+| `channel_id`   | string | no       | Platform-specific channel or user ID for direct targeting. |
+| `title`        | string | no       | Optional short title (rendered as bold prefix). |
+
+Provide either `username` for user-based targeting or `channel_type` +
+`channel_id` for direct targeting. Do not combine both.
+
+- **What it does**: Sends a notification via the channel gateway's HTTP endpoint (`POST /v1/api/notify`). The server queries the `services` table for healthy channel gateways, authenticates with a service JWT (`aud: turnstone-channel`), and delivers to the first healthy gateway. On failure, retries up to 2 additional times with backoff (1s, 3s). Rate-limited to 5 notifications per turn (counter only increments on success).
+- **Auto-approve**: Yes — notifications are time-sensitive and auto-approved so the model can alert users urgently.
+- **Agent availability**: `agent` and `task_agent`.
+
+> See [Channel Integrations: Notifications](channels.md#notifications)
+> for the full delivery flow, service registry details, and security
+> measures.
+
+---
+
 ## Summary Table

 | Tool         | Category   | Auto-approve | agent | task_agent | primary_key |
@@ -405,6 +434,7 @@ Remove a persistent memory by key.
 | `remember`   | Memory     | Yes          | No    | No         | `key`       |
 | `recall`     | Memory     | Yes          | No    | No         | `query`     |
 | `forget`     | Memory     | Yes          | No    | No         | `key`       |
+| `notify`     | Notify     | Yes          | Yes   | Yes        | `message`   |

 ---

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"

 [project]
 name = "turnstone"
-version = "0.3.5"
+version = "0.4.3"
 description = "Multi-node AI orchestration platform with tool use, agent routing, and cluster simulation."
 readme = "README.md"
 license = "BUSL-1.1"
@@ -32,6 +32,9 @@ dependencies = [
    "pydantic>=2.0",
    "sqlalchemy>=2.0",
    "alembic>=1.14",
+    "structlog>=24.1",
+    "PyJWT>=2.8",
+    "bcrypt>=4.0",
 ]

 [project.urls]
@@ -40,13 +43,14 @@ Repository = "https://github.com/turnstonelabs/turnstone"
 Issues = "https://github.com/turnstonelabs/turnstone/issues"

 [project.optional-dependencies]
-test = ["pytest>=9.0", "pytest-cov>=6.0"]
+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"]
+console = ["redis>=7.2", "croniter>=3.0"]
 sim = ["redis>=7.2"]
 anthropic = ["anthropic>=0.39"]
 postgres = ["psycopg[binary]>=3.2"]
+discord = ["discord.py>=2.4", "redis>=7.2"]


 [project.scripts]
@@ -56,6 +60,8 @@ 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"

 [tool.hatch.build.targets.wheel]
 include = [
@@ -128,10 +134,32 @@ ignore_missing_imports = true
 module = ["sqlalchemy", "sqlalchemy.*", "alembic", "alembic.*"]
 ignore_missing_imports = true

+[[tool.mypy.overrides]]
+module = ["structlog", "structlog.*"]
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = ["jwt", "jwt.*"]
+ignore_missing_imports = true
+
 [[tool.mypy.overrides]]
 module = ["anthropic", "anthropic.*"]
 ignore_missing_imports = true

+[[tool.mypy.overrides]]
+module = ["discord", "discord.*"]
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = ["croniter", "croniter.*"]
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = ["turnstone.channels.discord.*"]
+disallow_subclassing_any = false
+disallow_untyped_decorators = false
+warn_unused_ignores = false
+
 [[tool.mypy.overrides]]
 module = "tests.*"
 disallow_untyped_defs = false
@@ -2,7 +2,7 @@
  "openapi": "3.1.0",
  "info": {
    "title": "turnstone Server API",
-    "version": "0.3.0",
+    "version": "0.4.2",
    "description": "Single-node workstream management, chat interaction, and real-time streaming."
  },
  "paths": {
@@ -365,12 +365,12 @@
        }
      }
    },
-    "/v1/api/sessions": {
+    "/v1/api/workstreams/saved": {
      "get": {
-        "summary": "List saved sessions",
-        "operationId": "v1_api_sessions_get",
+        "summary": "List saved workstreams",
+        "operationId": "v1_api_workstreams_saved_get",
        "tags": [
-          "Sessions"
+          "Workstreams"
        ],
        "responses": {
          "200": {
@@ -378,7 +378,7 @@
            "content": {
              "application/json": {
                "schema": {
-                  "$ref": "#/components/schemas/ListSessionsResponse"
+                  "$ref": "#/components/schemas/ListSavedWorkstreamsResponse"
                }
              }
            }
@@ -427,6 +427,88 @@
        }
      }
    },
+    "/v1/api/auth/setup": {
+      "post": {
+        "summary": "Create first admin user",
+        "operationId": "v1_api_auth_setup_post",
+        "tags": [
+          "Auth"
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AuthSetupRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AuthSetupResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Error 400",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "Error 409",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Error 503",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/api/auth/status": {
+      "get": {
+        "summary": "Return auth state",
+        "operationId": "v1_api_auth_status_get",
+        "tags": [
+          "Auth"
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AuthStatusResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
    "/v1/api/auth/logout": {
      "post": {
        "summary": "Clear auth cookie",
@@ -503,17 +585,27 @@
        "type": "object"
      },
      "AuthLoginRequest": {
-        "description": "POST /v1/api/auth/login request body.",
+        "description": "POST /v1/api/auth/login request body.\n\nEither username+password or token must be provided.",
        "properties": {
+          "username": {
+            "default": "",
+            "description": "Login username",
+            "title": "Username",
+            "type": "string"
+          },
+          "password": {
+            "default": "",
+            "description": "Login password",
+            "title": "Password",
+            "type": "string"
+          },
          "token": {
-            "description": "Bearer token to authenticate",
+            "default": "",
+            "description": "Legacy: bearer token to authenticate",
            "title": "Token",
            "type": "string"
          }
        },
-        "required": [
-          "token"
-        ],
        "title": "AuthLoginRequest",
        "type": "object"
      },
@@ -525,14 +617,35 @@
            "title": "Status",
            "type": "string"
          },
+          "user_id": {
+            "default": "",
+            "description": "Authenticated user ID",
+            "title": "User Id",
+            "type": "string"
+          },
          "role": {
-            "description": "Assigned role",
+            "description": "Legacy role",
            "examples": [
              "full",
              "read"
            ],
            "title": "Role",
            "type": "string"
+          },
+          "scopes": {
+            "default": "",
+            "description": "Comma-separated scopes",
+            "examples": [
+              "read,write,approve"
+            ],
+            "title": "Scopes",
+            "type": "string"
+          },
+          "jwt": {
+            "default": "",
+            "description": "JWT session token (if JWT auth is configured)",
+            "title": "Jwt",
+            "type": "string"
          }
        },
        "required": [
@@ -541,6 +654,97 @@
        "title": "AuthLoginResponse",
        "type": "object"
      },
+      "AuthSetupRequest": {
+        "description": "POST /v1/api/auth/setup request body.",
+        "properties": {
+          "username": {
+            "description": "Login username (1-64 ASCII characters)",
+            "title": "Username",
+            "type": "string"
+          },
+          "display_name": {
+            "description": "Display name",
+            "title": "Display Name",
+            "type": "string"
+          },
+          "password": {
+            "description": "Password (minimum 8 characters)",
+            "title": "Password",
+            "type": "string"
+          }
+        },
+        "required": [
+          "username",
+          "display_name",
+          "password"
+        ],
+        "title": "AuthSetupRequest",
+        "type": "object"
+      },
+      "AuthSetupResponse": {
+        "description": "POST /v1/api/auth/setup success response.",
+        "properties": {
+          "status": {
+            "default": "ok",
+            "title": "Status",
+            "type": "string"
+          },
+          "user_id": {
+            "title": "User Id",
+            "type": "string"
+          },
+          "username": {
+            "title": "Username",
+            "type": "string"
+          },
+          "role": {
+            "default": "full",
+            "title": "Role",
+            "type": "string"
+          },
+          "scopes": {
+            "default": "approve,read,write",
+            "title": "Scopes",
+            "type": "string"
+          },
+          "jwt": {
+            "default": "",
+            "description": "JWT session token",
+            "title": "Jwt",
+            "type": "string"
+          }
+        },
+        "required": [
+          "user_id",
+          "username"
+        ],
+        "title": "AuthSetupResponse",
+        "type": "object"
+      },
+      "AuthStatusResponse": {
+        "description": "GET /v1/api/auth/status response.",
+        "properties": {
+          "auth_enabled": {
+            "title": "Auth Enabled",
+            "type": "boolean"
+          },
+          "has_users": {
+            "title": "Has Users",
+            "type": "boolean"
+          },
+          "setup_required": {
+            "title": "Setup Required",
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "auth_enabled",
+          "has_users",
+          "setup_required"
+        ],
+        "title": "AuthStatusResponse",
+        "type": "object"
+      },
      "SendRequest": {
        "properties": {
          "message": {
@@ -677,6 +881,12 @@
            "description": "Auto-approve all tool calls",
            "title": "Auto Approve",
            "type": "boolean"
+          },
+          "resume_ws": {
+            "default": "",
+            "description": "Workstream ID to resume atomically during creation (empty = fresh start)",
+            "title": "Resume Ws",
+            "type": "string"
          }
        },
        "title": "CreateWorkstreamRequest",
@@ -693,6 +903,18 @@
            "description": "Assigned workstream name",
            "title": "Name",
            "type": "string"
+          },
+          "resumed": {
+            "default": false,
+            "description": "Whether a previous workstream was resumed",
+            "title": "Resumed",
+            "type": "boolean"
+          },
+          "message_count": {
+            "default": 0,
+            "description": "Number of messages in the resumed workstream",
+            "title": "Message Count",
+            "type": "integer"
          }
        },
        "required": [
@@ -745,18 +967,6 @@
          "state": {
            "title": "State",
            "type": "string"
-          },
-          "session_id": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "default": null,
-            "title": "Session Id"
          }
        },
        "required": [
@@ -837,18 +1047,6 @@
            "title": "State",
            "type": "string"
          },
-          "session_id": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "default": null,
-            "title": "Session Id"
-          },
          "title": {
            "default": "",
            "title": "Title",
@@ -903,26 +1101,26 @@
        "title": "DashboardWorkstream",
        "type": "object"
      },
-      "ListSessionsResponse": {
+      "ListSavedWorkstreamsResponse": {
        "properties": {
-          "sessions": {
+          "workstreams": {
            "items": {
-              "$ref": "#/components/schemas/SessionInfo"
+              "$ref": "#/components/schemas/SavedWorkstreamInfo"
            },
-            "title": "Sessions",
+            "title": "Workstreams",
            "type": "array"
          }
        },
        "required": [
-          "sessions"
+          "workstreams"
        ],
-        "title": "ListSessionsResponse",
+        "title": "ListSavedWorkstreamsResponse",
        "type": "object"
      },
-      "SessionInfo": {
+      "SavedWorkstreamInfo": {
        "properties": {
-          "session_id": {
-            "title": "Session Id",
+          "ws_id": {
+            "title": "Ws Id",
            "type": "string"
          },
          "alias": {
@@ -963,12 +1161,12 @@
          }
        },
        "required": [
-          "session_id",
+          "ws_id",
          "created",
          "updated",
          "message_count"
        ],
-        "title": "SessionInfo",
+        "title": "SavedWorkstreamInfo",
        "type": "object"
      },
      "HealthResponse": {
@@ -2,15 +2,22 @@ import { BaseClient, type ClientOptions } from "./base.js";
 import type { ClusterEvent } from "./events.js";
 import type {
  AuthLoginResponse,
+  AuthSetupResponse,
+  AuthStatusResponse,
  ClusterNodesResponse,
  ClusterOverviewResponse,
  ClusterWorkstreamsResponse,
  ConsoleCreateWsRequest,
  ConsoleCreateWsResponse,
  ConsoleHealthResponse,
+  CreateScheduleRequest,
+  ListScheduleRunsResponse,
+  ListSchedulesResponse,
  NodeDetailResponse,
  NodesOptions,
+  ScheduleInfo,
  StatusResponse,
+  UpdateScheduleRequest,
  WorkstreamsOptions,
 } from "./types.js";

@@ -70,9 +77,33 @@ export class TurnstoneConsole extends BaseClient {

  // -- Auth -----------------------------------------------------------------

-  async login(token: string): Promise<AuthLoginResponse> {
-    return this.request("POST", "/v1/api/auth/login", {
-      json: { token },
+  async login(opts: {
+    token?: string;
+    username?: string;
+    password?: string;
+  }): Promise<AuthLoginResponse> {
+    const body =
+      opts.username && opts.password
+        ? { username: opts.username, password: opts.password }
+        : { token: opts.token ?? "" };
+    return this.request("POST", "/v1/api/auth/login", { json: body });
+  }
+
+  async authStatus(): Promise<AuthStatusResponse> {
+    return this.request("GET", "/v1/api/auth/status");
+  }
+
+  async setup(opts: {
+    username: string;
+    displayName: string;
+    password: string;
+  }): Promise<AuthSetupResponse> {
+    return this.request("POST", "/v1/api/auth/setup", {
+      json: {
+        username: opts.username,
+        display_name: opts.displayName,
+        password: opts.password,
+      },
    });
  }

@@ -85,4 +116,40 @@ export class TurnstoneConsole extends BaseClient {
  async health(): Promise<ConsoleHealthResponse> {
    return this.request("GET", "/health");
  }
+
+  // -- Schedules ------------------------------------------------------------
+
+  async listSchedules(): Promise<ListSchedulesResponse> {
+    return this.request("GET", "/v1/api/admin/schedules");
+  }
+
+  async createSchedule(opts: CreateScheduleRequest): Promise<ScheduleInfo> {
+    return this.request("POST", "/v1/api/admin/schedules", { json: opts });
+  }
+
+  async getSchedule(taskId: string): Promise<ScheduleInfo> {
+    return this.request("GET", `/v1/api/admin/schedules/${taskId}`);
+  }
+
+  async updateSchedule(
+    taskId: string,
+    opts: UpdateScheduleRequest,
+  ): Promise<ScheduleInfo> {
+    return this.request("PUT", `/v1/api/admin/schedules/${taskId}`, {
+      json: opts,
+    });
+  }
+
+  async deleteSchedule(taskId: string): Promise<StatusResponse> {
+    return this.request("DELETE", `/v1/api/admin/schedules/${taskId}`);
+  }
+
+  async listScheduleRuns(
+    taskId: string,
+    opts?: { limit?: number },
+  ): Promise<ListScheduleRunsResponse> {
+    return this.request("GET", `/v1/api/admin/schedules/${taskId}/runs`, {
+      params: { limit: opts?.limit ?? 50 },
+    });
+  }
 }
@@ -83,13 +83,15 @@ export type {
  DashboardWorkstream,
  DashboardAggregate,
  DashboardResponse,
-  SessionInfo,
-  ListSessionsResponse,
+  SavedWorkstreamInfo,
+  ListSavedWorkstreamsResponse,
  BackendStatus,
  WorkstreamCounts,
  HealthResponse,
  AuthLoginRequest,
  AuthLoginResponse,
+  AuthStatusResponse,
+  AuthSetupResponse,
  StatusResponse,
  ErrorResponse,
  ClusterOverviewResponse,
@@ -101,6 +103,12 @@ export type {
  ConsoleCreateWsRequest,
  ConsoleCreateWsResponse,
  ConsoleHealthResponse,
+  CreateScheduleRequest,
+  UpdateScheduleRequest,
+  ScheduleInfo,
+  ScheduleRunInfo,
+  ListSchedulesResponse,
+  ListScheduleRunsResponse,
  TurnResult,
  SendAndWaitOptions,
  NodesOptions,
@@ -2,11 +2,13 @@ import { BaseClient, type ClientOptions } from "./base.js";
 import type { ServerEvent } from "./events.js";
 import type {
  AuthLoginResponse,
+  AuthSetupResponse,
+  AuthStatusResponse,
  CreateWorkstreamRequest,
  CreateWorkstreamResponse,
  DashboardResponse,
  HealthResponse,
-  ListSessionsResponse,
+  ListSavedWorkstreamsResponse,
  ListWorkstreamsResponse,
  SendAndWaitOptions,
  SendResponse,
@@ -176,17 +178,41 @@ export class TurnstoneServer extends BaseClient {
    return result;
  }

-  // -- Sessions -------------------------------------------------------------
+  // -- Saved workstreams ----------------------------------------------------

-  async listSessions(): Promise<ListSessionsResponse> {
-    return this.request("GET", "/v1/api/sessions");
+  async listSavedWorkstreams(): Promise<ListSavedWorkstreamsResponse> {
+    return this.request("GET", "/v1/api/workstreams/saved");
  }

  // -- Auth -----------------------------------------------------------------

-  async login(token: string): Promise<AuthLoginResponse> {
-    return this.request("POST", "/v1/api/auth/login", {
-      json: { token },
+  async login(opts: {
+    token?: string;
+    username?: string;
+    password?: string;
+  }): Promise<AuthLoginResponse> {
+    const body =
+      opts.username && opts.password
+        ? { username: opts.username, password: opts.password }
+        : { token: opts.token ?? "" };
+    return this.request("POST", "/v1/api/auth/login", { json: body });
+  }
+
+  async authStatus(): Promise<AuthStatusResponse> {
+    return this.request("GET", "/v1/api/auth/status");
+  }
+
+  async setup(opts: {
+    username: string;
+    displayName: string;
+    password: string;
+  }): Promise<AuthSetupResponse> {
+    return this.request("POST", "/v1/api/auth/setup", {
+      json: {
+        username: opts.username,
+        display_name: opts.displayName,
+        password: opts.password,
+      },
    });
  }

@@ -17,6 +17,24 @@ export interface AuthLoginRequest {
 export interface AuthLoginResponse {
  status: string;
  role: string;
+  scopes?: string;
+  jwt?: string;
+  user_id?: string;
+}
+
+export interface AuthStatusResponse {
+  auth_enabled: boolean;
+  has_users: boolean;
+  setup_required: boolean;
+}
+
+export interface AuthSetupResponse {
+  status: string;
+  user_id: string;
+  username: string;
+  role: string;
+  scopes: string;
+  jwt?: string;
 }

 // ---------------------------------------------------------------------------
@@ -53,11 +71,14 @@ export interface CreateWorkstreamRequest {
  name?: string;
  model?: string;
  auto_approve?: boolean;
+  resume_ws?: string;
 }

 export interface CreateWorkstreamResponse {
  ws_id: string;
  name: string;
+  resumed?: boolean;
+  message_count?: number;
 }

 export interface CloseWorkstreamRequest {
@@ -68,7 +89,6 @@ export interface WorkstreamInfo {
  id: string;
  name: string;
  state: string;
-  session_id?: string | null;
 }

 export interface ListWorkstreamsResponse {
@@ -79,7 +99,6 @@ export interface DashboardWorkstream {
  id: string;
  name: string;
  state: string;
-  session_id?: string | null;
  title?: string;
  tokens?: number;
  context_ratio?: number;
@@ -106,11 +125,11 @@ export interface DashboardResponse {
 }

 // ---------------------------------------------------------------------------
-// Server API — Sessions
+// Server API — Saved workstreams
 // ---------------------------------------------------------------------------

-export interface SessionInfo {
-  session_id: string;
+export interface SavedWorkstreamInfo {
+  ws_id: string;
  alias?: string | null;
  title?: string | null;
  created: string;
@@ -118,8 +137,8 @@ export interface SessionInfo {
  message_count: number;
 }

-export interface ListSessionsResponse {
-  sessions: SessionInfo[];
+export interface ListSavedWorkstreamsResponse {
+  workstreams: SavedWorkstreamInfo[];
 }

 // ---------------------------------------------------------------------------
@@ -247,6 +266,77 @@ export interface ConsoleHealthResponse {
  versions: string[];
 }

+// ---------------------------------------------------------------------------
+// Console API — Schedules
+// ---------------------------------------------------------------------------
+
+export interface CreateScheduleRequest {
+  name: string;
+  schedule_type: string;
+  initial_message: string;
+  description?: string;
+  cron_expr?: string;
+  at_time?: string;
+  target_mode?: string;
+  model?: string;
+  auto_approve?: boolean;
+  auto_approve_tools?: string[];
+  enabled?: boolean;
+}
+
+export interface UpdateScheduleRequest {
+  name?: string;
+  description?: string;
+  schedule_type?: string;
+  cron_expr?: string;
+  at_time?: string;
+  target_mode?: string;
+  model?: string;
+  initial_message?: string;
+  auto_approve?: boolean;
+  auto_approve_tools?: string[];
+  enabled?: boolean;
+}
+
+export interface ScheduleInfo {
+  task_id: string;
+  name: string;
+  description: string;
+  schedule_type: string;
+  cron_expr: string;
+  at_time: string;
+  target_mode: string;
+  model: string;
+  initial_message: string;
+  auto_approve: boolean;
+  auto_approve_tools: string[];
+  enabled: boolean;
+  created_by: string;
+  last_run: string | null;
+  next_run: string | null;
+  created: string;
+  updated: string;
+}
+
+export interface ListSchedulesResponse {
+  schedules: ScheduleInfo[];
+}
+
+export interface ScheduleRunInfo {
+  run_id: string;
+  task_id: string;
+  node_id: string;
+  ws_id: string;
+  correlation_id: string;
+  started: string;
+  status: string;
+  error: string;
+}
+
+export interface ListScheduleRunsResponse {
+  runs: ScheduleRunInfo[];
+}
+
 // ---------------------------------------------------------------------------
 // SDK-specific types
 // ---------------------------------------------------------------------------
@@ -0,0 +1,181 @@
+"""Tests for turnstone.mq.async_broker.AsyncRedisBroker."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from turnstone.mq.async_broker import AsyncRedisBroker
+
+
+@pytest.fixture
+def broker() -> AsyncRedisBroker:
+    return AsyncRedisBroker(host="localhost", port=6379, db=0, prefix="test", response_ttl=120)
+
+
+@pytest.fixture
+def mock_redis() -> AsyncMock:
+    """Return a mock Redis client with common async methods."""
+    r = AsyncMock()
+    r.rpush = AsyncMock()
+    r.publish = AsyncMock()
+    r.expire = AsyncMock()
+    r.get = AsyncMock(return_value=None)
+    r.set = AsyncMock()
+    r.delete = AsyncMock()
+    r.blpop = AsyncMock(return_value=None)
+    ps = AsyncMock()
+    ps.subscribe = AsyncMock()
+    ps.unsubscribe = AsyncMock()
+    ps.close = AsyncMock()
+    ps.get_message = AsyncMock(return_value=None)
+    r.pubsub = MagicMock(return_value=ps)
+    return r
+
+
+def _inject_redis(broker: AsyncRedisBroker, mock_redis: AsyncMock) -> None:
+    """Inject a mock Redis client into the broker, simulating connect()."""
+    broker._redis = mock_redis
+    broker._pubsub = mock_redis.pubsub()
+
+
+class TestConstructor:
+    def test_stores_config(self) -> None:
+        b = AsyncRedisBroker(host="h", port=1234, db=2, prefix="pfx", password="pw")
+        assert b._host == "h"
+        assert b._port == 1234
+        assert b._db == 2
+        assert b._prefix == "pfx"
+        assert b._password == "pw"
+        assert b._redis is None
+
+    def test_defaults(self) -> None:
+        b = AsyncRedisBroker()
+        assert b._host == "localhost"
+        assert b._port == 6379
+        assert b._prefix == "turnstone"
+
+
+class TestConnect:
+    @pytest.mark.anyio
+    async def test_creates_connection(self) -> None:
+        b = AsyncRedisBroker()
+        mock_r = AsyncMock()
+        mock_r.pubsub = MagicMock(return_value=AsyncMock())
+        with patch("redis.asyncio.Redis", return_value=mock_r):
+            await b.connect()
+            assert b._redis is mock_r
+            assert b._pubsub is not None
+
+    @pytest.mark.anyio
+    async def test_connect_idempotent(
+        self, broker: AsyncRedisBroker, mock_redis: AsyncMock
+    ) -> None:
+        _inject_redis(broker, mock_redis)
+        old = broker._redis
+        await broker.connect()
+        assert broker._redis is old
+
+
+class TestPushInbound:
+    @pytest.mark.anyio
+    async def test_shared_queue(self, broker: AsyncRedisBroker, mock_redis: AsyncMock) -> None:
+        _inject_redis(broker, mock_redis)
+        await broker.push_inbound('{"type":"send"}')
+        mock_redis.rpush.assert_awaited_once_with("test:inbound", '{"type":"send"}')
+
+    @pytest.mark.anyio
+    async def test_per_node_queue(self, broker: AsyncRedisBroker, mock_redis: AsyncMock) -> None:
+        _inject_redis(broker, mock_redis)
+        await broker.push_inbound('{"type":"send"}', node_id="node-1")
+        mock_redis.rpush.assert_awaited_once_with("test:inbound:node-1", '{"type":"send"}')
+
+
+class TestPublishOutbound:
+    @pytest.mark.anyio
+    async def test_publishes(self, broker: AsyncRedisBroker, mock_redis: AsyncMock) -> None:
+        _inject_redis(broker, mock_redis)
+        await broker.publish_outbound("test:events:global", '{"event":"data"}')
+        mock_redis.publish.assert_awaited_once_with("test:events:global", '{"event":"data"}')
+
+
+class TestPushResponse:
+    @pytest.mark.anyio
+    async def test_rpush_and_expire(self, broker: AsyncRedisBroker, mock_redis: AsyncMock) -> None:
+        _inject_redis(broker, mock_redis)
+        await broker.push_response("req-123", '{"ok":true}')
+        mock_redis.rpush.assert_awaited_once_with("test:resp:req-123", '{"ok":true}')
+        mock_redis.expire.assert_awaited_once_with("test:resp:req-123", 120)
+
+
+class TestSubscribe:
+    @pytest.mark.anyio
+    async def test_creates_task(self, broker: AsyncRedisBroker, mock_redis: AsyncMock) -> None:
+        _inject_redis(broker, mock_redis)
+        await broker.subscribe("test:events:global", lambda msg: None)
+        assert "test:events:global" in broker._callbacks
+        assert broker._listener_task is not None
+        assert isinstance(broker._listener_task, asyncio.Task)
+        # Clean up.
+        broker._listener_task.cancel()
+        with contextlib.suppress(asyncio.CancelledError):
+            await broker._listener_task
+
+
+class TestUnsubscribe:
+    @pytest.mark.anyio
+    async def test_cancels_task(self, broker: AsyncRedisBroker, mock_redis: AsyncMock) -> None:
+        _inject_redis(broker, mock_redis)
+        await broker.subscribe("test:events:ch", lambda msg: None)
+        assert "test:events:ch" in broker._callbacks
+        await broker.unsubscribe("test:events:ch")
+        assert "test:events:ch" not in broker._callbacks
+
+
+class TestRoutingPrimitives:
+    @pytest.mark.anyio
+    async def test_get_ws_owner(self, broker: AsyncRedisBroker, mock_redis: AsyncMock) -> None:
+        _inject_redis(broker, mock_redis)
+        mock_redis.get.return_value = "node-1"
+        result = await broker.get_ws_owner("ws-abc")
+        mock_redis.get.assert_awaited_once_with("test:ws:ws-abc")
+        assert result == "node-1"
+
+    @pytest.mark.anyio
+    async def test_set_ws_owner(self, broker: AsyncRedisBroker, mock_redis: AsyncMock) -> None:
+        _inject_redis(broker, mock_redis)
+        await broker.set_ws_owner("ws-abc", "node-2")
+        mock_redis.set.assert_awaited_once_with("test:ws:ws-abc", "node-2")
+
+    @pytest.mark.anyio
+    async def test_set_ws_owner_with_ttl(
+        self, broker: AsyncRedisBroker, mock_redis: AsyncMock
+    ) -> None:
+        _inject_redis(broker, mock_redis)
+        await broker.set_ws_owner("ws-abc", "node-2", ttl=300)
+        mock_redis.set.assert_awaited_once_with("test:ws:ws-abc", "node-2", ex=300)
+
+    @pytest.mark.anyio
+    async def test_del_ws_owner(self, broker: AsyncRedisBroker, mock_redis: AsyncMock) -> None:
+        _inject_redis(broker, mock_redis)
+        await broker.del_ws_owner("ws-abc")
+        mock_redis.delete.assert_awaited_once_with("test:ws:ws-abc")
+
+
+class TestClose:
+    @pytest.mark.anyio
+    async def test_cancels_tasks_and_closes(
+        self, broker: AsyncRedisBroker, mock_redis: AsyncMock
+    ) -> None:
+        _inject_redis(broker, mock_redis)
+        await broker.subscribe("ch1", lambda m: None)
+        assert len(broker._callbacks) == 1
+        assert broker._listener_task is not None
+        await broker.close()
+        assert len(broker._callbacks) == 0
+        assert broker._listener_task is None
+        assert broker._redis is None
+        assert broker._pubsub is None
@@ -1,7 +1,9 @@
 """Tests for turnstone.core.auth — bearer token authentication and cookies."""

 import os
-from unittest.mock import patch
+import queue
+import threading
+from unittest.mock import MagicMock, patch

 import pytest

@@ -15,7 +17,7 @@ from turnstone.core.auth import (
    load_auth_config,
    make_clear_cookie,
    make_set_cookie,
-    required_role,
+    required_scope,
 )

 # ---------------------------------------------------------------------------
@@ -87,69 +89,59 @@ class TestIsPublicPath:
 # ---------------------------------------------------------------------------


-class TestRequiredRole:
+class TestRequiredScope:
    def test_get_api_needs_read(self):
-        assert required_role("GET", "/api/workstreams") == "read"
+        assert required_scope("GET", "/api/workstreams") == "read"

    def test_get_events_needs_read(self):
-        assert required_role("GET", "/api/events") == "read"
+        assert required_scope("GET", "/api/events") == "read"

-    def test_get_dashboard_needs_read(self):
-        assert required_role("GET", "/api/dashboard") == "read"
+    def test_post_send_needs_write(self):
+        assert required_scope("POST", "/api/send") == "write"

-    def test_post_send_needs_full(self):
-        assert required_role("POST", "/api/send") == "full"
+    def test_post_approve_needs_approve(self):
+        assert required_scope("POST", "/api/approve") == "approve"

-    def test_post_approve_needs_full(self):
-        assert required_role("POST", "/api/approve") == "full"
+    def test_post_plan_needs_write(self):
+        assert required_scope("POST", "/api/plan") == "write"

-    def test_post_plan_needs_full(self):
-        assert required_role("POST", "/api/plan") == "full"
+    def test_post_command_needs_write(self):
+        assert required_scope("POST", "/api/command") == "write"

-    def test_post_command_needs_full(self):
-        assert required_role("POST", "/api/command") == "full"
+    def test_post_workstreams_new_needs_write(self):
+        assert required_scope("POST", "/api/workstreams/new") == "write"

-    def test_post_workstreams_new_needs_full(self):
-        assert required_role("POST", "/api/workstreams/new") == "full"
+    def test_post_workstreams_close_needs_write(self):
+        assert required_scope("POST", "/api/workstreams/close") == "write"

-    def test_post_workstreams_close_needs_full(self):
-        assert required_role("POST", "/api/workstreams/close") == "full"
-
-    def test_all_write_paths_need_full(self):
+    def test_all_write_paths_need_write(self):
        for path in WRITE_PATHS:
-            assert required_role("POST", path) == "full"
+            scope = required_scope("POST", path)
+            assert scope in ("write", "approve"), f"{path} should need write or approve"

    def test_post_unknown_path_needs_read(self):
-        assert required_role("POST", "/api/unknown") == "read"
+        assert required_scope("POST", "/api/unknown") == "read"

-    def test_v1_post_send_needs_full(self):
-        assert required_role("POST", "/v1/api/send") == "full"
+    def test_v1_post_send_needs_write(self):
+        assert required_scope("POST", "/v1/api/send") == "write"

-    def test_v1_post_approve_needs_full(self):
-        assert required_role("POST", "/v1/api/approve") == "full"
+    def test_v1_post_approve_needs_approve(self):
+        assert required_scope("POST", "/v1/api/approve") == "approve"

    def test_v1_get_workstreams_needs_read(self):
-        assert required_role("GET", "/v1/api/workstreams") == "read"
+        assert required_scope("GET", "/v1/api/workstreams") == "read"

-    def test_v1_post_cluster_ws_new_needs_full(self):
-        assert required_role("POST", "/v1/api/cluster/workstreams/new") == "full"
+    def test_v1_post_cluster_ws_new_needs_write(self):
+        assert required_scope("POST", "/v1/api/cluster/workstreams/new") == "write"

-    def test_v1_all_write_paths_need_full(self):
-        for path in WRITE_PATHS:
-            v1_path = "/v1" + path
-            assert required_role("POST", v1_path) == "full", f"{v1_path} should need full"
+    def test_proxy_v1_send_needs_write(self):
+        assert required_scope("POST", "/node/node-a/v1/api/send") == "write"

-    def test_proxy_v1_send_needs_full(self):
-        assert required_role("POST", "/node/node-a/v1/api/send") == "full"
-
-    def test_proxy_v1_approve_needs_full(self):
-        assert required_role("POST", "/node/node-a/v1/api/approve") == "full"
-
-    def test_proxy_v1_cluster_ws_new_needs_full(self):
-        assert required_role("POST", "/node/node-a/v1/api/cluster/workstreams/new") == "full"
+    def test_proxy_v1_approve_needs_approve(self):
+        assert required_scope("POST", "/node/node-a/v1/api/approve") == "approve"

    def test_proxy_v1_read_endpoint_needs_read(self):
-        assert required_role("GET", "/node/node-a/v1/api/workstreams") == "read"
+        assert required_scope("GET", "/node/node-a/v1/api/workstreams") == "read"


 # ---------------------------------------------------------------------------
@@ -268,12 +260,24 @@ class TestMakeSetCookie:

    def test_max_age_default(self):
        val = make_set_cookie("tok_abc")
-        assert "Max-Age=2592000" in val  # 30 days
+        assert "Max-Age=86400" in val  # 24 hours (matches JWT expiry)

    def test_max_age_custom(self):
        val = make_set_cookie("tok_abc", max_age=3600)
        assert "Max-Age=3600" in val

+    def test_secure_default(self):
+        val = make_set_cookie("tok_abc")
+        assert "; Secure" in val
+
+    def test_secure_false(self):
+        val = make_set_cookie("tok_abc", secure=False)
+        assert "; Secure" not in val
+
+    def test_secure_true(self):
+        val = make_set_cookie("tok_abc", secure=True)
+        assert "; Secure" in val
+

 class TestMakeClearCookie:
    def test_max_age_zero(self):
@@ -306,68 +310,78 @@ class TestCheckRequest:
        )

    def test_disabled_allows_all(self, disabled):
-        allowed, status, msg = check_request(disabled, "POST", "/api/send", None)
+        allowed, status, msg, _result = check_request(disabled, "POST", "/api/send", None)
        assert allowed is True
        assert status == 200

    def test_disabled_allows_no_header(self, disabled):
-        allowed, status, msg = check_request(disabled, "GET", "/api/workstreams", None)
+        allowed, status, msg, _result = check_request(disabled, "GET", "/api/workstreams", None)
        assert allowed is True

    def test_public_path_no_token_ok(self, enabled):
-        allowed, status, msg = check_request(enabled, "GET", "/health", None)
+        allowed, status, msg, _result = check_request(enabled, "GET", "/health", None)
        assert allowed is True
        assert status == 200

    def test_public_root_no_token_ok(self, enabled):
-        allowed, status, msg = check_request(enabled, "GET", "/", None)
+        allowed, status, msg, _result = check_request(enabled, "GET", "/", None)
        assert allowed is True

    def test_public_static_no_token_ok(self, enabled):
-        allowed, status, msg = check_request(enabled, "GET", "/static/style.css", None)
+        allowed, status, msg, _result = check_request(enabled, "GET", "/static/style.css", None)
        assert allowed is True

    def test_api_no_token_401(self, enabled):
-        allowed, status, msg = check_request(enabled, "GET", "/api/workstreams", None)
+        allowed, status, msg, _result = check_request(enabled, "GET", "/api/workstreams", None)
        assert allowed is False
        assert status == 401
        assert "Unauthorized" in msg

    def test_api_invalid_token_401(self, enabled):
-        allowed, status, msg = check_request(
+        allowed, status, msg, _result = check_request(
            enabled, "GET", "/api/workstreams", "Bearer wrong_token"
        )
        assert allowed is False
        assert status == 401

    def test_api_read_token_ok(self, enabled):
-        allowed, status, msg = check_request(enabled, "GET", "/api/workstreams", "Bearer tok_read")
+        allowed, status, msg, _result = check_request(
+            enabled, "GET", "/api/workstreams", "Bearer tok_read"
+        )
        assert allowed is True
        assert status == 200

    def test_api_full_token_ok(self, enabled):
-        allowed, status, msg = check_request(enabled, "GET", "/api/workstreams", "Bearer tok_full")
+        allowed, status, msg, _result = check_request(
+            enabled, "GET", "/api/workstreams", "Bearer tok_full"
+        )
        assert allowed is True

    def test_write_read_token_403(self, enabled):
-        allowed, status, msg = check_request(enabled, "POST", "/api/send", "Bearer tok_read")
+        allowed, status, msg, _result = check_request(
+            enabled, "POST", "/api/send", "Bearer tok_read"
+        )
        assert allowed is False
        assert status == 403
        assert "Forbidden" in msg

    def test_write_full_token_ok(self, enabled):
-        allowed, status, msg = check_request(enabled, "POST", "/api/send", "Bearer tok_full")
+        allowed, status, msg, _result = check_request(
+            enabled, "POST", "/api/send", "Bearer tok_full"
+        )
        assert allowed is True
        assert status == 200

    def test_approve_read_token_403(self, enabled):
-        allowed, status, msg = check_request(enabled, "POST", "/api/approve", "Bearer tok_read")
+        allowed, status, msg, _result = check_request(
+            enabled, "POST", "/api/approve", "Bearer tok_read"
+        )
        assert allowed is False
        assert status == 403

    def test_proxy_write_read_token_403(self, enabled):
        """Read tokens cannot escalate to write ops via proxy routes."""
-        allowed, status, msg = check_request(
+        allowed, status, msg, _result = check_request(
            enabled, "POST", "/node/node-a/api/send", "Bearer tok_read"
        )
        assert allowed is False
@@ -375,7 +389,7 @@ class TestCheckRequest:

    def test_proxy_write_trailing_slash_read_token_403(self, enabled):
        """Trailing slash must not bypass write-role check on proxy routes."""
-        allowed, status, msg = check_request(
+        allowed, status, msg, _result = check_request(
            enabled, "POST", "/node/node-a/api/send/", "Bearer tok_read"
        )
        assert allowed is False
@@ -383,20 +397,22 @@ class TestCheckRequest:

    def test_direct_write_trailing_slash_read_token_403(self, enabled):
        """Trailing slash must not bypass write-role check on direct routes."""
-        allowed, status, msg = check_request(enabled, "POST", "/api/send/", "Bearer tok_read")
+        allowed, status, msg, _result = check_request(
+            enabled, "POST", "/api/send/", "Bearer tok_read"
+        )
        assert allowed is False
        assert status == 403

    def test_proxy_write_full_token_ok(self, enabled):
        """Full tokens pass through proxy write routes."""
-        allowed, status, msg = check_request(
+        allowed, status, msg, _result = check_request(
            enabled, "POST", "/node/node-a/api/send", "Bearer tok_full"
        )
        assert allowed is True

    def test_proxy_v1_write_read_token_403(self, enabled):
        """Read tokens cannot escalate to write ops via v1 proxy routes."""
-        allowed, status, msg = check_request(
+        allowed, status, msg, _result = check_request(
            enabled, "POST", "/node/node-a/v1/api/send", "Bearer tok_read"
        )
        assert allowed is False
@@ -404,14 +420,14 @@ class TestCheckRequest:

    def test_proxy_v1_write_full_token_ok(self, enabled):
        """Full tokens pass through v1 proxy write routes."""
-        allowed, status, msg = check_request(
+        allowed, status, msg, _result = check_request(
            enabled, "POST", "/node/node-a/v1/api/send", "Bearer tok_full"
        )
        assert allowed is True

    def test_proxy_v1_cluster_ws_new_read_403(self, enabled):
        """Read tokens cannot create workstreams via v1 proxy."""
-        allowed, status, msg = check_request(
+        allowed, status, msg, _result = check_request(
            enabled,
            "POST",
            "/node/node-a/v1/api/cluster/workstreams/new",
@@ -422,25 +438,27 @@ class TestCheckRequest:

    def test_proxy_read_endpoint_read_token_ok(self, enabled):
        """Read tokens can access proxy read endpoints."""
-        allowed, status, msg = check_request(
+        allowed, status, msg, _result = check_request(
            enabled, "GET", "/node/node-a/api/workstreams", "Bearer tok_read"
        )
        assert allowed is True

    def test_console_create_ws_read_token_403(self, enabled):
        """Read tokens cannot create workstreams."""
-        allowed, status, msg = check_request(
+        allowed, status, msg, _result = check_request(
            enabled, "POST", "/api/cluster/workstreams/new", "Bearer tok_read"
        )
        assert allowed is False
        assert status == 403

    def test_approve_full_token_ok(self, enabled):
-        allowed, status, msg = check_request(enabled, "POST", "/api/approve", "Bearer tok_full")
+        allowed, status, msg, _result = check_request(
+            enabled, "POST", "/api/approve", "Bearer tok_full"
+        )
        assert allowed is True

    def test_no_auth_header_string(self, enabled):
-        allowed, status, msg = check_request(enabled, "GET", "/api/dashboard", "")
+        allowed, status, msg, _result = check_request(enabled, "GET", "/api/dashboard", "")
        assert allowed is False
        assert status == 401

@@ -461,7 +479,7 @@ class TestCheckRequestWithCookie:
        )

    def test_cookie_fallback_when_no_bearer(self, enabled):
-        allowed, status, _ = check_request(
+        allowed, status, _, _r = check_request(
            enabled,
            "GET",
            "/api/workstreams",
@@ -473,7 +491,7 @@ class TestCheckRequestWithCookie:

    def test_bearer_takes_precedence_over_cookie(self, enabled):
        # Bearer is full, cookie is read — Bearer should win
-        allowed, status, _ = check_request(
+        allowed, status, _, _r = check_request(
            enabled,
            "POST",
            "/api/send",
@@ -483,7 +501,7 @@ class TestCheckRequestWithCookie:
        assert allowed is True

    def test_invalid_cookie_401(self, enabled):
-        allowed, status, _ = check_request(
+        allowed, status, _, _r = check_request(
            enabled,
            "GET",
            "/api/workstreams",
@@ -494,7 +512,7 @@ class TestCheckRequestWithCookie:
        assert status == 401

    def test_cookie_read_on_write_403(self, enabled):
-        allowed, status, _ = check_request(
+        allowed, status, _, _r = check_request(
            enabled,
            "POST",
            "/api/send",
@@ -505,7 +523,7 @@ class TestCheckRequestWithCookie:
        assert status == 403

    def test_cookie_full_on_write_ok(self, enabled):
-        allowed, status, _ = check_request(
+        allowed, status, _, _r = check_request(
            enabled,
            "POST",
            "/api/send",
@@ -515,7 +533,7 @@ class TestCheckRequestWithCookie:
        assert allowed is True

    def test_no_cookie_no_bearer_401(self, enabled):
-        allowed, status, _ = check_request(
+        allowed, status, _, _r = check_request(
            enabled,
            "GET",
            "/api/workstreams",
@@ -526,7 +544,7 @@ class TestCheckRequestWithCookie:
        assert status == 401

    def test_login_path_public(self, enabled):
-        allowed, status, _ = check_request(
+        allowed, status, _, _r = check_request(
            enabled,
            "POST",
            "/api/auth/login",
@@ -535,7 +553,7 @@ class TestCheckRequestWithCookie:
        assert allowed is True

    def test_logout_path_public(self, enabled):
-        allowed, status, _ = check_request(
+        allowed, status, _, _r = check_request(
            enabled,
            "POST",
            "/api/auth/logout",
@@ -552,12 +570,28 @@ class TestCheckRequestWithCookie:
 class TestLoadAuthConfig:
    """Tests for load_auth_config with mocked config + env vars."""

-    def test_default_disabled(self):
+    def test_default_enabled(self):
        with patch("turnstone.core.config.load_config", return_value={}):
            cfg = load_auth_config()
-        assert cfg.enabled is False
+        assert cfg.enabled is True
        assert cfg.tokens == {}

+    def test_explicit_disable(self):
+        with (
+            patch("turnstone.core.config.load_config", return_value={"enabled": False}),
+            patch.dict(os.environ, {}, clear=True),
+        ):
+            cfg = load_auth_config()
+        assert cfg.enabled is False
+
+    def test_env_disable(self):
+        with (
+            patch("turnstone.core.config.load_config", return_value={}),
+            patch.dict(os.environ, {"TURNSTONE_AUTH_ENABLED": "0"}, clear=True),
+        ):
+            cfg = load_auth_config()
+        assert cfg.enabled is False
+
    def test_config_file_tokens(self):
        mock_cfg = {
            "enabled": True,
@@ -685,7 +719,7 @@ class TestServerAuth:
        srv_mod._metrics.model = "test-model"

        mock_session = MagicMock()
-        mock_session.session_id = "test-session-id"
+        mock_session.ws_id = "test-session-id"

        mock_ws = MagicMock()
        mock_ws.id = "test-ws"
@@ -705,6 +739,7 @@ class TestServerAuth:
                enabled=True,
                tokens={"tok_full": "full", "tok_read": "read"},
            ),
+            cors_origins=["*"],
        )
        cls.client = TestClient(app, raise_server_exceptions=False)

@@ -902,7 +937,7 @@ class TestServerLogin:
        srv_mod._metrics.model = "test-model"

        mock_session = MagicMock()
-        mock_session.session_id = "test-session-id"
+        mock_session.ws_id = "test-session-id"

        mock_ws = MagicMock()
        mock_ws.id = "test-ws"
@@ -1040,3 +1075,277 @@ class TestConsoleLogin:
        self.test_client.post("/v1/api/auth/logout")
        resp = self.test_client.get("/v1/api/cluster/overview")
        assert resp.status_code == 401
+
+
+# ---------------------------------------------------------------------------
+# Security hardening tests
+# ---------------------------------------------------------------------------
+
+
+class TestLoginRateLimiter:
+    def test_allows_under_limit(self):
+        from turnstone.core.auth import LoginRateLimiter
+
+        limiter = LoginRateLimiter(max_attempts=3, window_seconds=60)
+        for _ in range(3):
+            ok, _ = limiter.check("ip:1.2.3.4")
+            assert ok
+            limiter.record("ip:1.2.3.4")
+        # 4th should be blocked (3 recorded)
+        ok, retry = limiter.check("ip:1.2.3.4")
+        assert not ok
+        assert retry > 0
+
+    def test_different_keys_independent(self):
+        from turnstone.core.auth import LoginRateLimiter
+
+        limiter = LoginRateLimiter(max_attempts=2, window_seconds=60)
+        limiter.record("ip:a")
+        limiter.record("ip:a")
+        ok_a, _ = limiter.check("ip:a")
+        ok_b, _ = limiter.check("ip:b")
+        assert not ok_a
+        assert ok_b
+
+    def test_cleanup(self):
+        from turnstone.core.auth import LoginRateLimiter
+
+        limiter = LoginRateLimiter(max_attempts=1, window_seconds=60)
+        limiter.record("ip:old")
+        removed = limiter.cleanup(max_age=0.0)
+        assert removed == 1
+        ok, _ = limiter.check("ip:old")
+        assert ok
+
+    def test_max_keys_protection(self):
+        from turnstone.core.auth import LoginRateLimiter
+
+        limiter = LoginRateLimiter(max_attempts=5, window_seconds=60)
+        limiter.MAX_KEYS = 2
+        limiter.record("a")
+        limiter.record("b")
+        limiter.record("c")  # should be silently dropped (at capacity)
+        assert "c" not in limiter._attempts
+
+
+class TestJWTAudienceIssuer:
+    SECRET = "test-secret-that-is-at-least-32-chars"
+
+    def test_create_jwt_includes_iss(self):
+        import jwt as pyjwt
+
+        from turnstone.core.auth import JWT_ISSUER, create_jwt
+
+        token = create_jwt("user1", frozenset({"read"}), "test", self.SECRET)
+        payload = pyjwt.decode(
+            token, self.SECRET, algorithms=["HS256"], options={"verify_aud": False}
+        )
+        assert payload["iss"] == JWT_ISSUER
+
+    def test_create_jwt_with_audience(self):
+        import jwt as pyjwt
+
+        from turnstone.core.auth import JWT_AUD_SERVER, create_jwt
+
+        token = create_jwt(
+            "user1", frozenset({"read"}), "test", self.SECRET, audience=JWT_AUD_SERVER
+        )
+        payload = pyjwt.decode(token, self.SECRET, algorithms=["HS256"], audience=JWT_AUD_SERVER)
+        assert payload["aud"] == JWT_AUD_SERVER
+
+    def test_validate_jwt_wrong_audience_rejected(self):
+        from turnstone.core.auth import JWT_AUD_CONSOLE, JWT_AUD_SERVER, create_jwt, validate_jwt
+
+        token = create_jwt(
+            "user1", frozenset({"read"}), "test", self.SECRET, audience=JWT_AUD_SERVER
+        )
+        result = validate_jwt(token, self.SECRET, audience=JWT_AUD_CONSOLE)
+        assert result is None
+
+    def test_validate_jwt_correct_audience_accepted(self):
+        from turnstone.core.auth import JWT_AUD_SERVER, create_jwt, validate_jwt
+
+        token = create_jwt(
+            "user1", frozenset({"read"}), "test", self.SECRET, audience=JWT_AUD_SERVER
+        )
+        result = validate_jwt(token, self.SECRET, audience=JWT_AUD_SERVER)
+        assert result is not None
+        assert result.user_id == "user1"
+
+    def test_validate_jwt_no_audience_backward_compat(self):
+        from turnstone.core.auth import create_jwt, validate_jwt
+
+        # Token without aud claim should be accepted when audience="" (backward compat)
+        token = create_jwt("user1", frozenset({"read"}), "test", self.SECRET)
+        result = validate_jwt(token, self.SECRET, audience="")
+        assert result is not None
+
+
+class TestServiceTokenManager:
+    SECRET = "test-secret-that-is-at-least-32-chars"
+
+    def test_auto_mints_on_first_access(self):
+        from turnstone.core.auth import ServiceTokenManager
+
+        mgr = ServiceTokenManager(
+            user_id="svc",
+            scopes=frozenset({"read"}),
+            source="test",
+            secret=self.SECRET,
+        )
+        token = mgr.token
+        assert token  # non-empty
+        assert isinstance(token, str)
+
+    def test_bearer_header_format(self):
+        from turnstone.core.auth import ServiceTokenManager
+
+        mgr = ServiceTokenManager(
+            user_id="svc",
+            scopes=frozenset({"read"}),
+            source="test",
+            secret=self.SECRET,
+        )
+        header = mgr.bearer_header
+        assert "Authorization" in header
+        assert header["Authorization"].startswith("Bearer ")
+
+    def test_token_stable_within_window(self):
+        from turnstone.core.auth import ServiceTokenManager
+
+        mgr = ServiceTokenManager(
+            user_id="svc",
+            scopes=frozenset({"read"}),
+            source="test",
+            secret=self.SECRET,
+            expiry_hours=1,
+        )
+        t1 = mgr.token
+        t2 = mgr.token
+        assert t1 == t2
+
+    def test_token_rotates_near_expiry(self):
+        from turnstone.core.auth import ServiceTokenManager
+
+        mgr = ServiceTokenManager(
+            user_id="svc",
+            scopes=frozenset({"read"}),
+            source="test",
+            secret=self.SECRET,
+            expiry_hours=1,
+        )
+        _ = mgr.token  # initial mint
+        # Simulate expiry by backdating _expires_at
+        mgr._expires_at = 0.0
+        t2 = mgr.token
+        # Token was re-minted (even if payload matches within same second,
+        # the internal state was refreshed)
+        assert t2  # non-empty, valid token
+        assert mgr._expires_at > 0.0  # was refreshed
+
+    def test_audience_included(self):
+        import jwt as pyjwt
+
+        from turnstone.core.auth import JWT_AUD_SERVER, ServiceTokenManager
+
+        mgr = ServiceTokenManager(
+            user_id="svc",
+            scopes=frozenset({"read"}),
+            source="test",
+            secret=self.SECRET,
+            audience=JWT_AUD_SERVER,
+        )
+        payload = pyjwt.decode(
+            mgr.token, self.SECRET, algorithms=["HS256"], audience=JWT_AUD_SERVER
+        )
+        assert payload["aud"] == JWT_AUD_SERVER
+
+
+class TestIsSecureRequest:
+    def test_https_scheme(self):
+        from turnstone.core.auth import is_secure_request
+
+        assert is_secure_request({}, scheme="https") is True
+
+    def test_http_scheme(self):
+        from turnstone.core.auth import is_secure_request
+
+        assert is_secure_request({}, scheme="http") is False
+
+    def test_x_forwarded_proto_https(self):
+        from turnstone.core.auth import is_secure_request
+
+        assert is_secure_request({"x-forwarded-proto": "https"}, scheme="http") is True
+
+    def test_x_forwarded_proto_http(self):
+        from turnstone.core.auth import is_secure_request
+
+        assert is_secure_request({"x-forwarded-proto": "http"}, scheme="http") is False
+
+
+class TestSecretStrength:
+    def test_short_secret_warns(self, caplog):
+        import logging
+
+        from turnstone.core.auth import _MIN_SECRET_LENGTH
+
+        with caplog.at_level(logging.WARNING, logger="turnstone.core.auth"):
+            import turnstone.core.auth as auth_mod
+
+            old = os.environ.get("TURNSTONE_JWT_SECRET", "")
+            os.environ["TURNSTONE_JWT_SECRET"] = "short"
+            try:
+                secret = auth_mod.load_jwt_secret()
+                assert secret == "short"
+                assert any(str(_MIN_SECRET_LENGTH) in r.message for r in caplog.records)
+            finally:
+                if old:
+                    os.environ["TURNSTONE_JWT_SECRET"] = old
+                else:
+                    os.environ.pop("TURNSTONE_JWT_SECRET", None)
+
+
+class TestCorsConfigurable:
+    """Verify CORS middleware is only added when origins are configured."""
+
+    def test_no_cors_origins_no_cors_headers(self):
+        """Without cors_origins, no Access-Control headers."""
+        from starlette.testclient import TestClient
+
+        import turnstone.server as srv_mod
+
+        app = srv_mod.create_app(
+            workstreams=MagicMock(),
+            global_queue=queue.Queue(),
+            global_listeners=[],
+            global_listeners_lock=threading.Lock(),
+            skip_permissions=False,
+            auth_config=AuthConfig(enabled=False),
+        )
+        client = TestClient(app)
+        resp = client.get("/health", headers={"Origin": "http://evil.com"})
+        assert "Access-Control-Allow-Origin" not in resp.headers
+        client.close()
+
+    def test_cors_origins_set(self):
+        """With cors_origins, CORS headers are present."""
+        from starlette.testclient import TestClient
+
+        import turnstone.server as srv_mod
+
+        app = srv_mod.create_app(
+            workstreams=MagicMock(),
+            global_queue=queue.Queue(),
+            global_listeners=[],
+            global_listeners_lock=threading.Lock(),
+            skip_permissions=False,
+            auth_config=AuthConfig(enabled=False),
+            cors_origins=["http://example.com"],
+        )
+        client = TestClient(app)
+        resp = client.get(
+            "/health",
+            headers={"Origin": "http://example.com"},
+        )
+        assert resp.headers.get("Access-Control-Allow-Origin") == "http://example.com"
+        client.close()
@@ -0,0 +1,357 @@
+"""Tests for user identity, API tokens, JWT, and scoped auth."""
+
+from __future__ import annotations
+
+import time
+
+import pytest
+
+from turnstone.core.auth import (
+    AuthConfig,
+    AuthResult,
+    _authenticate_token,
+    check_request,
+    create_jwt,
+    generate_token,
+    hash_password,
+    hash_token,
+    parse_scopes,
+    required_scope,
+    token_prefix,
+    validate_jwt,
+    verify_password,
+)
+
+# ---------------------------------------------------------------------------
+# AuthResult
+# ---------------------------------------------------------------------------
+
+
+class TestAuthResult:
+    def test_frozen(self):
+        r = AuthResult(user_id="u1", scopes=frozenset({"read"}), token_source="config")
+        with pytest.raises(AttributeError):
+            r.user_id = "u2"  # type: ignore[misc]
+
+    def test_has_scope(self):
+        r = AuthResult(user_id="", scopes=frozenset({"read", "write"}), token_source="config")
+        assert r.has_scope("read")
+        assert r.has_scope("write")
+        assert not r.has_scope("approve")
+
+    def test_empty_scopes(self):
+        r = AuthResult(user_id="", scopes=frozenset(), token_source="config")
+        assert not r.has_scope("read")
+
+
+# ---------------------------------------------------------------------------
+# Token generation and hashing
+# ---------------------------------------------------------------------------
+
+
+class TestTokenHelpers:
+    def test_generate_token_format(self):
+        tok = generate_token()
+        assert tok.startswith("ts_")
+        assert len(tok) == 3 + 64  # ts_ + 64 hex chars
+
+    def test_generate_token_unique(self):
+        tokens = {generate_token() for _ in range(10)}
+        assert len(tokens) == 10
+
+    def test_hash_token_deterministic(self):
+        assert hash_token("ts_abc") == hash_token("ts_abc")
+
+    def test_hash_token_hex(self):
+        h = hash_token("test")
+        assert len(h) == 64  # SHA-256 hex
+        int(h, 16)  # valid hex
+
+    def test_token_prefix(self):
+        assert token_prefix("ts_abcdefgh1234") == "ts_abcde"
+
+
+# ---------------------------------------------------------------------------
+# Password hashing (bcrypt)
+# ---------------------------------------------------------------------------
+
+
+class TestPasswordHashing:
+    def test_hash_and_verify(self):
+        pw = "hunter2"
+        hashed = hash_password(pw)
+        assert verify_password(pw, hashed)
+
+    def test_wrong_password(self):
+        hashed = hash_password("correct")
+        assert not verify_password("wrong", hashed)
+
+    def test_hash_is_different_each_time(self):
+        h1 = hash_password("same")
+        h2 = hash_password("same")
+        assert h1 != h2  # different salts
+
+
+# ---------------------------------------------------------------------------
+# Scope parsing
+# ---------------------------------------------------------------------------
+
+
+class TestParseScopes:
+    def test_single_scope(self):
+        assert parse_scopes("read") == frozenset({"read"})
+
+    def test_hierarchy_write(self):
+        assert parse_scopes("write") == frozenset({"read", "write"})
+
+    def test_hierarchy_approve(self):
+        assert parse_scopes("approve") == frozenset({"read", "write", "approve"})
+
+    def test_comma_separated(self):
+        assert parse_scopes("read,write") == frozenset({"read", "write"})
+
+    def test_redundant_scopes(self):
+        # approve already includes read,write
+        assert parse_scopes("read,approve") == frozenset({"read", "write", "approve"})
+
+    def test_empty_string(self):
+        assert parse_scopes("") == frozenset()
+
+    def test_invalid_scope_filtered(self):
+        assert parse_scopes("bogus") == frozenset()
+
+    def test_mixed_valid_invalid(self):
+        assert parse_scopes("read,bogus,approve") == frozenset({"read", "write", "approve"})
+
+
+# ---------------------------------------------------------------------------
+# JWT create / validate
+# ---------------------------------------------------------------------------
+
+
+class TestJWT:
+    SECRET = "test-secret-key-for-jwt"
+
+    def test_round_trip(self):
+        scopes = frozenset({"read", "write"})
+        token = create_jwt("user123", scopes, "database", self.SECRET, expiry_hours=1)
+        result = validate_jwt(token, self.SECRET)
+        assert result is not None
+        assert result.user_id == "user123"
+        assert result.scopes == frozenset({"read", "write"})
+
+    def test_expired_token(self):
+        import jwt
+
+        payload = {
+            "sub": "user1",
+            "scopes": "read",
+            "src": "database",
+            "iat": int(time.time()) - 7200,
+            "exp": int(time.time()) - 3600,
+        }
+        token = jwt.encode(payload, self.SECRET, algorithm="HS256")
+        assert validate_jwt(token, self.SECRET) is None
+
+    def test_invalid_signature(self):
+        token = create_jwt("user1", frozenset({"read"}), "db", self.SECRET)
+        assert validate_jwt(token, "wrong-secret") is None
+
+    def test_malformed_token(self):
+        assert validate_jwt("not.a.jwt", self.SECRET) is None
+
+    def test_contains_dots(self):
+        """JWTs contain dots, used for detection."""
+        token = create_jwt("u1", frozenset({"read"}), "db", self.SECRET)
+        assert "." in token
+
+
+# ---------------------------------------------------------------------------
+# required_scope
+# ---------------------------------------------------------------------------
+
+
+class TestRequiredScope:
+    def test_get_read(self):
+        assert required_scope("GET", "/api/workstreams") == "read"
+
+    def test_post_write(self):
+        assert required_scope("POST", "/api/send") == "write"
+
+    def test_post_approve(self):
+        assert required_scope("POST", "/api/approve") == "approve"
+
+    def test_admin_prefix(self):
+        assert required_scope("GET", "/api/admin/users") == "approve"
+        assert required_scope("POST", "/api/admin/users") == "approve"
+        assert required_scope("DELETE", "/api/admin/users/abc") == "approve"
+
+    def test_versioned_path(self):
+        assert required_scope("POST", "/v1/api/send") == "write"
+        assert required_scope("POST", "/v1/api/approve") == "approve"
+
+    def test_proxy_write(self):
+        assert required_scope("POST", "/node/n1/api/send") == "write"
+
+    def test_proxy_approve(self):
+        assert required_scope("POST", "/node/n1/api/approve") == "approve"
+
+
+# ---------------------------------------------------------------------------
+# _authenticate_token
+# ---------------------------------------------------------------------------
+
+
+class TestAuthenticateToken:
+    def test_config_token_read(self):
+        cfg = AuthConfig(enabled=True, tokens={"tok_read": "read"})
+        result = _authenticate_token("tok_read", cfg)
+        assert result is not None
+        assert result.scopes == frozenset({"read"})
+        assert result.token_source == "config"
+
+    def test_config_token_full(self):
+        cfg = AuthConfig(enabled=True, tokens={"tok_full": "full"})
+        result = _authenticate_token("tok_full", cfg)
+        assert result is not None
+        assert result.scopes == frozenset({"read", "write", "approve"})
+
+    def test_jwt_token(self):
+        secret = "test-secret"
+        jwt_tok = create_jwt("user1", frozenset({"read", "write"}), "db", secret)
+        cfg = AuthConfig(enabled=True)
+        result = _authenticate_token(jwt_tok, cfg, jwt_secret=secret)
+        assert result is not None
+        assert result.user_id == "user1"
+        assert result.token_source == "db"
+
+    def test_api_token_with_storage(self):
+        """API tokens are looked up by hash in storage."""
+        raw = generate_token()
+
+        class MockStorage:
+            def get_api_token_by_hash(self, token_hash):
+                expected = hash_token(raw)
+                if token_hash == expected:
+                    return {
+                        "token_id": "tid",
+                        "token_prefix": "ts_abcde",
+                        "user_id": "user1",
+                        "name": "test",
+                        "scopes": "read,write",
+                        "created": "2026-01-01T00:00:00",
+                    }
+                return None
+
+        cfg = AuthConfig(enabled=True)
+        result = _authenticate_token(raw, cfg, storage=MockStorage())
+        assert result is not None
+        assert result.user_id == "user1"
+        assert result.has_scope("write")
+        assert result.token_source == "database"
+
+    def test_api_token_expired(self):
+        """Expired API tokens are rejected."""
+        raw = generate_token()
+
+        class MockStorage:
+            def get_api_token_by_hash(self, token_hash):
+                return {
+                    "token_id": "tid",
+                    "token_prefix": "ts_abcde",
+                    "user_id": "user1",
+                    "name": "test",
+                    "scopes": "read",
+                    "created": "2020-01-01T00:00:00",
+                    "expires": "2020-01-02T00:00:00",
+                }
+
+        cfg = AuthConfig(enabled=True)
+        result = _authenticate_token(raw, cfg, storage=MockStorage())
+        assert result is None
+
+    def test_unknown_token(self):
+        cfg = AuthConfig(enabled=True, tokens={"tok": "full"})
+        result = _authenticate_token("unknown", cfg)
+        assert result is None
+
+
+# ---------------------------------------------------------------------------
+# check_request with scopes
+# ---------------------------------------------------------------------------
+
+
+class TestCheckRequestScopes:
+    def test_config_read_on_write_403(self):
+        cfg = AuthConfig(enabled=True, tokens={"tok_read": "read"})
+        allowed, status, msg, _ = check_request(cfg, "POST", "/api/send", "Bearer tok_read")
+        assert not allowed
+        assert status == 403
+        assert "write" in msg
+
+    def test_config_read_on_approve_403(self):
+        cfg = AuthConfig(enabled=True, tokens={"tok_read": "read"})
+        allowed, status, msg, _ = check_request(cfg, "POST", "/api/approve", "Bearer tok_read")
+        assert not allowed
+        assert status == 403
+        assert "approve" in msg
+
+    def test_config_full_on_approve_ok(self):
+        cfg = AuthConfig(enabled=True, tokens={"tok_full": "full"})
+        allowed, status, msg, result = check_request(cfg, "POST", "/api/approve", "Bearer tok_full")
+        assert allowed
+        assert result is not None
+        assert result.has_scope("approve")
+
+    def test_jwt_with_scopes(self):
+        secret = "test"
+        jwt_tok = create_jwt("u1", frozenset({"read", "write"}), "db", secret)
+        cfg = AuthConfig(enabled=True)
+        allowed, status, msg, result = check_request(
+            cfg,
+            "POST",
+            "/api/send",
+            f"Bearer {jwt_tok}",
+            jwt_secret=secret,
+        )
+        assert allowed
+        assert result is not None
+        assert result.user_id == "u1"
+
+    def test_jwt_insufficient_scope(self):
+        secret = "test"
+        jwt_tok = create_jwt("u1", frozenset({"read"}), "db", secret)
+        cfg = AuthConfig(enabled=True)
+        allowed, status, msg, _ = check_request(
+            cfg,
+            "POST",
+            "/api/send",
+            f"Bearer {jwt_tok}",
+            jwt_secret=secret,
+        )
+        assert not allowed
+        assert status == 403
+
+    def test_admin_path_requires_approve(self):
+        cfg = AuthConfig(enabled=True, tokens={"tok_read": "read"})
+        allowed, status, msg, _ = check_request(
+            cfg,
+            "GET",
+            "/v1/api/admin/users",
+            "Bearer tok_read",
+        )
+        assert not allowed
+        assert status == 403
+
+    def test_backward_compat_role_full(self):
+        """Config tokens with role='full' get all scopes."""
+        cfg = AuthConfig(enabled=True, tokens={"tok_full": "full"})
+        allowed, _, _, result = check_request(
+            cfg,
+            "GET",
+            "/v1/api/admin/users",
+            "Bearer tok_full",
+        )
+        assert allowed
+        assert result is not None
+        assert result.has_scope("approve")
@@ -0,0 +1,328 @@
+"""Tests for the Discord channel adapter (bot, cog, views, config, CLI)."""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+discord = pytest.importorskip("discord")
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _run(coro):
+    """Run an async coroutine in a fresh event loop (no pytest-asyncio needed)."""
+    return asyncio.run(coro)
+
+
+def _make_message(*, bot=False, guild=True, content="hello", channel=None):
+    """Build a mock ``discord.Message``."""
+    msg = MagicMock(spec=discord.Message)
+    msg.author = MagicMock()
+    msg.author.bot = bot
+    msg.author.id = 12345
+    msg.content = content
+    msg.guild = MagicMock() if guild else None
+    msg.channel = channel or MagicMock()
+    msg.mentions = []
+    return msg
+
+
+def _make_interaction(*, footer_text=None, has_embeds=True):
+    """Build a mock ``discord.Interaction``."""
+    interaction = MagicMock(spec=discord.Interaction)
+    interaction.user = MagicMock()
+    interaction.user.id = 67890
+    interaction.response = MagicMock()
+    interaction.response.send_message = AsyncMock()
+
+    if has_embeds and footer_text is not None:
+        embed = MagicMock()
+        embed.footer.text = footer_text
+        interaction.message = MagicMock()
+        interaction.message.embeds = [embed]
+    elif not has_embeds:
+        interaction.message = MagicMock()
+        interaction.message.embeds = []
+    else:
+        interaction.message = None
+
+    return interaction
+
+
+# ---------------------------------------------------------------------------
+# DiscordConfig
+# ---------------------------------------------------------------------------
+
+
+class TestDiscordConfig:
+    """Tests for DiscordConfig default and custom values."""
+
+    def test_defaults(self):
+        from turnstone.channels.discord.config import DiscordConfig
+
+        cfg = DiscordConfig()
+        assert cfg.bot_token == ""
+        assert cfg.guild_id == 0
+        assert cfg.allowed_channels == []
+        assert cfg.thread_auto_archive == 1440
+        assert cfg.max_message_length == 2000
+        assert cfg.streaming_edit_interval == 1.5
+        # Inherited from ChannelConfig
+        assert cfg.redis_host == "localhost"
+        assert cfg.redis_port == 6379
+        assert cfg.model == ""
+        assert cfg.auto_approve is False
+
+    def test_custom_values(self):
+        from turnstone.channels.discord.config import DiscordConfig
+
+        cfg = DiscordConfig(
+            bot_token="tok_123",
+            guild_id=999,
+            allowed_channels=[1, 2, 3],
+            thread_auto_archive=60,
+            max_message_length=4000,
+            streaming_edit_interval=0.5,
+            model="gpt-5",
+            auto_approve=True,
+        )
+        assert cfg.bot_token == "tok_123"
+        assert cfg.guild_id == 999
+        assert cfg.allowed_channels == [1, 2, 3]
+        assert cfg.thread_auto_archive == 60
+        assert cfg.max_message_length == 4000
+        assert cfg.streaming_edit_interval == 0.5
+        assert cfg.model == "gpt-5"
+        assert cfg.auto_approve is True
+
+
+# ---------------------------------------------------------------------------
+# StreamingMessage
+# ---------------------------------------------------------------------------
+
+
+class TestStreamingMessage:
+    """Tests for the StreamingMessage helper in bot.py."""
+
+    def test_append_accumulates(self):
+        from turnstone.channels.discord.bot import StreamingMessage
+
+        channel = MagicMock()
+        channel.send = AsyncMock()
+        sm = StreamingMessage(channel=channel, edit_interval=999.0)
+
+        _run(sm.append("hello "))
+        _run(sm.append("world"))
+
+        assert "".join(sm._buffer) == "hello world"
+
+    def test_finalize_sends_when_no_prior_message(self):
+        from turnstone.channels.discord.bot import StreamingMessage
+
+        channel = MagicMock()
+        channel.send = AsyncMock()
+        sm = StreamingMessage(channel=channel, edit_interval=999.0)
+
+        _run(sm.append("hello"))
+        _run(sm.finalize())
+
+        channel.send.assert_awaited_once_with("hello")
+
+    def test_finalize_edits_existing_message(self):
+        from turnstone.channels.discord.bot import StreamingMessage
+
+        channel = MagicMock()
+        sent_msg = MagicMock()
+        sent_msg.edit = AsyncMock()
+        channel.send = AsyncMock(return_value=sent_msg)
+        sm = StreamingMessage(channel=channel, edit_interval=0.0)
+
+        # First append triggers flush (interval=0) which creates the message.
+        _run(sm.append("hi"))
+        assert sm._message is sent_msg
+
+        _run(sm.append(" there"))
+        _run(sm.finalize())
+
+        # finalize edits the existing message with full content.
+        sent_msg.edit.assert_awaited_with(content="hi there")
+
+    def test_finalize_chunks_long_content(self):
+        from turnstone.channels.discord.bot import StreamingMessage
+
+        channel = MagicMock()
+        channel.send = AsyncMock()
+        sm = StreamingMessage(channel=channel, max_length=10, edit_interval=999.0)
+
+        # Content longer than max_length should be chunked on finalize.
+        _run(sm.append("a" * 25))
+        _run(sm.finalize())
+
+        # Should have sent multiple chunks via channel.send.
+        assert channel.send.await_count >= 2
+
+    def test_finalize_empty_is_noop(self):
+        from turnstone.channels.discord.bot import StreamingMessage
+
+        channel = MagicMock()
+        channel.send = AsyncMock()
+        sm = StreamingMessage(channel=channel)
+
+        _run(sm.finalize())
+        channel.send.assert_not_awaited()
+
+
+# ---------------------------------------------------------------------------
+# MessageCog._on_message
+# ---------------------------------------------------------------------------
+
+
+class TestMessageCog:
+    """Tests for the MessageCog on_message filtering logic."""
+
+    def _make_cog(self):
+        """Build a MessageCog with a fully mocked bot and TurnstoneBot."""
+        from turnstone.channels.discord.cog import MessageCog
+
+        bot = MagicMock()
+        bot.user = MagicMock()
+        bot.user.id = 99999
+        bot.user.mentioned_in = MagicMock(return_value=False)
+
+        ts = MagicMock()
+        ts._is_allowed_channel = MagicMock(return_value=True)
+        ts.storage = MagicMock()
+        ts.router = MagicMock()
+        ts.router.resolve_user = AsyncMock(return_value="u_abc")
+        ts.router.send_message = AsyncMock()
+        ts.config = MagicMock()
+        ts._ws_tasks = {}
+        bot.turnstone = ts
+
+        cog = MessageCog(bot)
+        return cog, ts, bot
+
+    def test_ignores_bot_messages(self):
+        cog, ts, _bot = self._make_cog()
+        msg = _make_message(bot=True)
+
+        _run(cog._on_message(msg))
+
+        # No router interaction means the message was ignored.
+        ts.router.send_message.assert_not_awaited()
+
+    def test_ignores_own_messages(self):
+        cog, ts, bot = self._make_cog()
+        msg = _make_message(bot=False)
+        msg.author = bot.user  # message from ourselves
+
+        _run(cog._on_message(msg))
+
+        ts.router.send_message.assert_not_awaited()
+
+    def test_ignores_dms(self):
+        cog, ts, _bot = self._make_cog()
+        msg = _make_message(guild=False)
+
+        _run(cog._on_message(msg))
+
+        ts.router.send_message.assert_not_awaited()
+
+    def test_ignores_non_allowed_channels(self):
+        cog, ts, _bot = self._make_cog()
+        ts._is_allowed_channel = MagicMock(return_value=False)
+
+        thread = MagicMock(spec=discord.Thread)
+        thread.id = 111
+        thread.parent_id = 222
+        msg = _make_message(channel=thread)
+
+        _run(cog._on_message(msg))
+
+        ts.router.send_message.assert_not_awaited()
+
+
+# ---------------------------------------------------------------------------
+# _parse_footer (views.py)
+# ---------------------------------------------------------------------------
+
+
+class TestParseFooter:
+    """Tests for _parse_footer in views.py."""
+
+    def test_valid_footer(self):
+        from turnstone.channels.discord.views import _parse_footer
+
+        interaction = _make_interaction(footer_text="ws_abc|corr_123")
+        result = _parse_footer(interaction)
+        assert result == ("ws_abc", "corr_123")
+
+    def test_footer_with_pipe_in_correlation(self):
+        from turnstone.channels.discord.views import _parse_footer
+
+        interaction = _make_interaction(footer_text="ws_abc|corr|extra")
+        result = _parse_footer(interaction)
+        # split("|", 1) means the second part includes everything after first pipe.
+        assert result == ("ws_abc", "corr|extra")
+
+    def test_no_message_returns_none(self):
+        from turnstone.channels.discord.views import _parse_footer
+
+        interaction = MagicMock()
+        interaction.message = None
+        assert _parse_footer(interaction) is None
+
+    def test_no_embeds_returns_none(self):
+        from turnstone.channels.discord.views import _parse_footer
+
+        interaction = _make_interaction(has_embeds=False)
+        assert _parse_footer(interaction) is None
+
+    def test_empty_footer_returns_none(self):
+        from turnstone.channels.discord.views import _parse_footer
+
+        # Build an interaction whose embed has footer.text = None.
+        interaction = MagicMock(spec=discord.Interaction)
+        embed = MagicMock()
+        embed.footer.text = None
+        interaction.message = MagicMock()
+        interaction.message.embeds = [embed]
+        assert _parse_footer(interaction) is None
+
+    def test_footer_without_pipe_returns_none(self):
+        from turnstone.channels.discord.views import _parse_footer
+
+        interaction = _make_interaction(footer_text="no_pipe_here")
+        # footer text has no "|" separator
+        embed = MagicMock()
+        embed.footer.text = "no_pipe_here"
+        interaction.message.embeds = [embed]
+        assert _parse_footer(interaction) is None
+
+
+# ---------------------------------------------------------------------------
+# CLI main() — no adapter configured
+# ---------------------------------------------------------------------------
+
+
+class TestChannelCLI:
+    """Tests for the channel CLI entry point."""
+
+    def test_exits_without_adapter_token(self):
+        from turnstone.channels.cli import main
+
+        with (
+            patch.object(sys, "argv", ["turnstone-channel"]),
+            patch.dict("os.environ", {}, clear=True),
+            pytest.raises(SystemExit) as exc_info,
+        ):
+            main()
+
+        assert exc_info.value.code == 1
@@ -0,0 +1,203 @@
+"""Tests for turnstone.channels._protocol and turnstone.channels._formatter."""
+
+from __future__ import annotations
+
+from turnstone.channels._formatter import (
+    chunk_message,
+    format_approval_request,
+    format_plan_review,
+    truncate,
+)
+from turnstone.channels._protocol import ChannelEvent
+
+# ---------------------------------------------------------------------------
+# ChannelEvent
+# ---------------------------------------------------------------------------
+
+
+class TestChannelEvent:
+    def test_construction(self) -> None:
+        evt = ChannelEvent(
+            channel_type="discord",
+            channel_id="ch-1",
+            channel_user_id="u-42",
+            message="hello",
+            parent_channel_id="parent",
+            metadata={"key": "val"},
+        )
+        assert evt.channel_type == "discord"
+        assert evt.channel_id == "ch-1"
+        assert evt.channel_user_id == "u-42"
+        assert evt.message == "hello"
+        assert evt.parent_channel_id == "parent"
+        assert evt.metadata == {"key": "val"}
+
+    def test_defaults(self) -> None:
+        evt = ChannelEvent(
+            channel_type="slack",
+            channel_id="ch-2",
+            channel_user_id="u-7",
+            message="hi",
+        )
+        assert evt.parent_channel_id == ""
+        assert evt.metadata == {}
+
+    def test_metadata_independence(self) -> None:
+        """Default metadata dicts are independent across instances."""
+        a = ChannelEvent(channel_type="x", channel_id="1", channel_user_id="u", message="m")
+        b = ChannelEvent(channel_type="x", channel_id="2", channel_user_id="u", message="m")
+        a.metadata["key"] = "val"
+        assert "key" not in b.metadata
+
+
+# ---------------------------------------------------------------------------
+# chunk_message
+# ---------------------------------------------------------------------------
+
+
+class TestChunkMessage:
+    def test_empty_string(self) -> None:
+        assert chunk_message("") == [""]
+
+    def test_under_limit(self) -> None:
+        assert chunk_message("short text", max_length=100) == ["short text"]
+
+    def test_exactly_at_limit(self) -> None:
+        text = "a" * 50
+        assert chunk_message(text, max_length=50) == [text]
+
+    def test_splits_at_newline(self) -> None:
+        text = "line one\nline two\nline three"
+        chunks = chunk_message(text, max_length=18)
+        assert len(chunks) >= 2
+        # The split should happen at a newline boundary within the text.
+        # Reassembled chunks (with newline separators) should cover all content.
+        rejoined = "\n".join(chunks)
+        assert "line one" in rejoined
+        assert "line three" in rejoined
+
+    def test_splits_at_word_boundary(self) -> None:
+        text = "word1 word2 word3 word4"
+        chunks = chunk_message(text, max_length=12)
+        assert len(chunks) >= 2
+        # No chunk should start with a space (lstrip handles newlines).
+        for chunk in chunks:
+            assert not chunk.startswith("\n")
+
+    def test_hard_splits(self) -> None:
+        text = "a" * 30
+        chunks = chunk_message(text, max_length=10)
+        assert len(chunks) == 3
+        assert "".join(chunks) == text
+
+    def test_code_block_spanning_boundary(self) -> None:
+        text = "before\n```\ncode line 1\ncode line 2\ncode line 3\n```\nafter"
+        chunks = chunk_message(text, max_length=30)
+        assert len(chunks) >= 2
+        # If a chunk opens a code block without closing it, the chunker
+        # should close it and reopen in the next chunk.
+        for chunk in chunks:
+            fence_count = chunk.count("```")
+            assert fence_count % 2 == 0, f"Unmatched code fence in chunk: {chunk!r}"
+
+    def test_multiple_code_blocks(self) -> None:
+        text = "```\nblock1\n```\ntext\n```\nblock2\n```"
+        chunks = chunk_message(text, max_length=20)
+        for chunk in chunks:
+            fence_count = chunk.count("```")
+            assert fence_count % 2 == 0, f"Unmatched code fence in chunk: {chunk!r}"
+
+    def test_custom_max_length(self) -> None:
+        text = "hello world"
+        chunks = chunk_message(text, max_length=5)
+        assert len(chunks) >= 2
+        assert chunks[0] == "hello"
+
+    def test_very_long_single_line(self) -> None:
+        text = "x" * 5000
+        chunks = chunk_message(text, max_length=2000)
+        assert len(chunks) == 3
+        total = "".join(chunks)
+        assert total == text
+
+
+# ---------------------------------------------------------------------------
+# format_approval_request
+# ---------------------------------------------------------------------------
+
+
+class TestFormatApprovalRequest:
+    def test_single_tool(self) -> None:
+        items = [{"function": {"name": "read_file", "arguments": "/etc/hosts"}}]
+        result = format_approval_request(items)
+        assert "Tool approval required" in result
+        assert "`read_file`" in result
+
+    def test_multiple_tools(self) -> None:
+        items = [
+            {"function": {"name": "tool_a", "arguments": "arg1"}},
+            {"function": {"name": "tool_b", "arguments": "arg2"}},
+        ]
+        result = format_approval_request(items)
+        assert "`tool_a`" in result
+        assert "`tool_b`" in result
+
+    def test_long_arguments_truncated(self) -> None:
+        long_args = "x" * 500
+        items = [{"function": {"name": "fn", "arguments": long_args}}]
+        result = format_approval_request(items)
+        # The result should be shorter than the original args.
+        assert len(result) < 500
+
+    def test_server_sse_format(self) -> None:
+        """Items from the server SSE use func_name/preview, not function.name."""
+        items = [
+            {
+                "call_id": "c1",
+                "func_name": "bash",
+                "preview": "ls -la",
+                "header": "Execute: ls -la",
+                "needs_approval": True,
+            }
+        ]
+        result = format_approval_request(items)
+        assert "`bash`" in result
+        assert "Execute: ls -la" in result
+
+    def test_server_sse_format_no_header(self) -> None:
+        items = [{"func_name": "read_file", "preview": "/etc/hosts"}]
+        result = format_approval_request(items)
+        assert "`read_file`" in result
+        assert "/etc/hosts" in result
+
+
+# ---------------------------------------------------------------------------
+# format_plan_review
+# ---------------------------------------------------------------------------
+
+
+class TestFormatPlanReview:
+    def test_format(self) -> None:
+        result = format_plan_review("Step 1: do stuff")
+        assert result.startswith("**Plan review requested:**")
+        assert "Step 1: do stuff" in result
+
+
+# ---------------------------------------------------------------------------
+# truncate
+# ---------------------------------------------------------------------------
+
+
+class TestTruncate:
+    def test_short_text_unchanged(self) -> None:
+        assert truncate("hello", max_length=200) == "hello"
+
+    def test_long_text_truncated(self) -> None:
+        text = "a" * 300
+        result = truncate(text, max_length=200)
+        assert len(result) == 200
+        assert result.endswith("\u2026")
+
+    def test_exactly_at_limit(self) -> None:
+        text = "b" * 200
+        assert truncate(text, max_length=200) == text
@@ -0,0 +1,107 @@
+"""Tests for turnstone.channels._routing.ChannelRouter."""
+
+from __future__ import annotations
+
+import json
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from turnstone.channels._routing import ChannelRouter
+
+
+@pytest.fixture
+def mock_broker() -> AsyncMock:
+    """Return a mock AsyncRedisBroker."""
+    broker = AsyncMock()
+    broker._prefix = "test"
+    broker.push_inbound = AsyncMock()
+    broker.push_response = AsyncMock()
+    broker.subscribe = AsyncMock()
+    broker.unsubscribe = AsyncMock()
+    return broker
+
+
+@pytest.fixture
+def mock_storage() -> MagicMock:
+    """Return a mock StorageBackend."""
+    storage = MagicMock()
+    storage.get_channel_user = MagicMock(return_value=None)
+    storage.get_channel_route = MagicMock(return_value=None)
+    storage.get_channel_route_by_ws = MagicMock(return_value=None)
+    storage.create_channel_route = MagicMock()
+    storage.delete_channel_route = MagicMock(return_value=True)
+    return storage
+
+
+@pytest.fixture
+def router(mock_broker: AsyncMock, mock_storage: MagicMock) -> ChannelRouter:
+    return ChannelRouter(broker=mock_broker, storage=mock_storage)
+
+
+class TestResolveUser:
+    @pytest.mark.anyio
+    async def test_linked_user(self, router: ChannelRouter, mock_storage: MagicMock) -> None:
+        mock_storage.get_channel_user.return_value = {"user_id": "usr-1", "channel_user_id": "d-42"}
+        result = await router.resolve_user("discord", "d-42")
+        assert result == "usr-1"
+        mock_storage.get_channel_user.assert_called_once_with("discord", "d-42")
+
+    @pytest.mark.anyio
+    async def test_unlinked_user(self, router: ChannelRouter, mock_storage: MagicMock) -> None:
+        mock_storage.get_channel_user.return_value = None
+        result = await router.resolve_user("slack", "s-99")
+        assert result is None
+
+
+class TestSendMessage:
+    @pytest.mark.anyio
+    async def test_pushes_send_message(self, router: ChannelRouter, mock_broker: AsyncMock) -> None:
+        cid = await router.send_message("ws-1", "hello world")
+        assert isinstance(cid, str)
+        assert len(cid) > 0
+        mock_broker.push_inbound.assert_awaited_once()
+        raw = mock_broker.push_inbound.call_args[0][0]
+        payload = json.loads(raw)
+        assert payload["type"] == "send"
+        assert payload["ws_id"] == "ws-1"
+        assert payload["message"] == "hello world"
+        assert payload["correlation_id"] == cid
+
+
+class TestSendApproval:
+    @pytest.mark.anyio
+    async def test_pushes_to_response_queue(
+        self, router: ChannelRouter, mock_broker: AsyncMock
+    ) -> None:
+        await router.send_approval("ws-1", "corr-abc", approved=True, feedback="ok")
+        mock_broker.push_response.assert_awaited_once()
+        queue_name = mock_broker.push_response.call_args[0][0]
+        assert queue_name == "corr-abc"
+        raw = mock_broker.push_response.call_args[0][1]
+        payload = json.loads(raw)
+        assert payload["type"] == "approve"
+        assert payload["approved"] is True
+        assert payload["ws_id"] == "ws-1"
+
+
+class TestSendPlanFeedback:
+    @pytest.mark.anyio
+    async def test_pushes_to_response_queue(
+        self, router: ChannelRouter, mock_broker: AsyncMock
+    ) -> None:
+        await router.send_plan_feedback("ws-2", "corr-xyz", "looks good")
+        mock_broker.push_response.assert_awaited_once()
+        raw = mock_broker.push_response.call_args[0][1]
+        payload = json.loads(raw)
+        assert payload["type"] == "plan_feedback"
+        assert payload["feedback"] == "looks good"
+
+
+class TestDeleteRoute:
+    @pytest.mark.anyio
+    async def test_calls_storage_delete(
+        self, router: ChannelRouter, mock_storage: MagicMock
+    ) -> None:
+        await router.delete_route("discord", "ch-123")
+        mock_storage.delete_channel_route.assert_called_once_with("discord", "ch-123")
@@ -0,0 +1,136 @@
+"""Tests for channel_users and channel_routes storage CRUD."""
+
+from __future__ import annotations
+
+import pytest
+
+from turnstone.core.storage._sqlite import SQLiteBackend
+
+
+@pytest.fixture
+def db(tmp_path):
+    """Fresh SQLite backend for each test."""
+    backend = SQLiteBackend(str(tmp_path / "test.db"))
+    return backend
+
+
+class TestChannelUserCRUD:
+    """Tests for channel_users table operations."""
+
+    def test_create_and_get(self, db):
+        db.create_channel_user("discord", "12345", "u_abc")
+        result = db.get_channel_user("discord", "12345")
+        assert result is not None
+        assert result["channel_type"] == "discord"
+        assert result["channel_user_id"] == "12345"
+        assert result["user_id"] == "u_abc"
+        assert "created" in result
+
+    def test_get_nonexistent(self, db):
+        assert db.get_channel_user("discord", "99999") is None
+
+    def test_create_duplicate_noop(self, db):
+        db.create_channel_user("discord", "12345", "u_abc")
+        db.create_channel_user("discord", "12345", "u_different")
+        result = db.get_channel_user("discord", "12345")
+        assert result is not None
+        assert result["user_id"] == "u_abc"  # first write wins
+
+    def test_same_user_different_channels(self, db):
+        db.create_channel_user("discord", "d_123", "u_abc")
+        db.create_channel_user("slack", "s_456", "u_abc")
+        d = db.get_channel_user("discord", "d_123")
+        s = db.get_channel_user("slack", "s_456")
+        assert d is not None and d["user_id"] == "u_abc"
+        assert s is not None and s["user_id"] == "u_abc"
+
+    def test_list_by_user(self, db):
+        db.create_channel_user("discord", "d_123", "u_abc")
+        db.create_channel_user("slack", "s_456", "u_abc")
+        db.create_channel_user("discord", "d_999", "u_other")
+        results = db.list_channel_users_by_user("u_abc")
+        assert len(results) == 2
+        types = {r["channel_type"] for r in results}
+        assert types == {"discord", "slack"}
+
+    def test_list_by_user_empty(self, db):
+        assert db.list_channel_users_by_user("u_nobody") == []
+
+    def test_delete(self, db):
+        db.create_channel_user("discord", "12345", "u_abc")
+        assert db.delete_channel_user("discord", "12345") is True
+        assert db.get_channel_user("discord", "12345") is None
+
+    def test_delete_nonexistent(self, db):
+        assert db.delete_channel_user("discord", "99999") is False
+
+    def test_delete_user_cascades_channel_users(self, db):
+        """Deleting a turnstone user should cascade to channel_users."""
+        db.create_user("u_abc", "admin", "Admin", "hash123")
+        db.create_channel_user("discord", "12345", "u_abc")
+        db.delete_user("u_abc")
+        assert db.get_channel_user("discord", "12345") is None
+
+
+class TestChannelRouteCRUD:
+    """Tests for channel_routes table operations."""
+
+    def test_create_and_get(self, db):
+        db.create_channel_route("discord", "thread_123", "ws_abc", "node_1")
+        result = db.get_channel_route("discord", "thread_123")
+        assert result is not None
+        assert result["channel_type"] == "discord"
+        assert result["channel_id"] == "thread_123"
+        assert result["ws_id"] == "ws_abc"
+        assert result["node_id"] == "node_1"
+        assert "created" in result
+
+    def test_get_nonexistent(self, db):
+        assert db.get_channel_route("discord", "thread_999") is None
+
+    def test_create_duplicate_noop(self, db):
+        db.create_channel_route("discord", "thread_123", "ws_abc")
+        db.create_channel_route("discord", "thread_123", "ws_different")
+        result = db.get_channel_route("discord", "thread_123")
+        assert result is not None
+        assert result["ws_id"] == "ws_abc"  # first write wins
+
+    def test_default_empty_node_id(self, db):
+        db.create_channel_route("discord", "thread_123", "ws_abc")
+        result = db.get_channel_route("discord", "thread_123")
+        assert result is not None
+        assert result["node_id"] == ""
+
+    def test_get_by_ws(self, db):
+        db.create_channel_route("discord", "thread_123", "ws_abc", "node_1")
+        result = db.get_channel_route_by_ws("ws_abc")
+        assert result is not None
+        assert result["channel_id"] == "thread_123"
+        assert result["ws_id"] == "ws_abc"
+
+    def test_get_by_ws_nonexistent(self, db):
+        assert db.get_channel_route_by_ws("ws_nobody") is None
+
+    def test_delete(self, db):
+        db.create_channel_route("discord", "thread_123", "ws_abc")
+        assert db.delete_channel_route("discord", "thread_123") is True
+        assert db.get_channel_route("discord", "thread_123") is None
+
+    def test_delete_nonexistent(self, db):
+        assert db.delete_channel_route("discord", "thread_999") is False
+
+    def test_multiple_channels_same_type(self, db):
+        db.create_channel_route("discord", "thread_1", "ws_1")
+        db.create_channel_route("discord", "thread_2", "ws_2")
+        r1 = db.get_channel_route("discord", "thread_1")
+        r2 = db.get_channel_route("discord", "thread_2")
+        assert r1 is not None and r1["ws_id"] == "ws_1"
+        assert r2 is not None and r2["ws_id"] == "ws_2"
+
+    def test_different_channel_types(self, db):
+        db.create_channel_route("discord", "thread_1", "ws_1")
+        db.create_channel_route("slack", "channel_1", "ws_2")
+        d = db.get_channel_route("discord", "thread_1")
+        s = db.get_channel_route("slack", "channel_1")
+        assert d is not None and d["ws_id"] == "ws_1"
+        assert s is not None and s["ws_id"] == "ws_2"
@@ -0,0 +1,214 @@
+"""Tests for turnstone.core.log — structured logging configuration."""
+
+from __future__ import annotations
+
+import json
+import logging
+
+import structlog
+
+from turnstone.core.log import (
+    configure_logging,
+    ctx_node_id,
+    ctx_request_id,
+    ctx_user_id,
+    ctx_ws_id,
+    get_logger,
+)
+
+
+class TestConfigureLogging:
+    """Test configure_logging() sets up handlers and formatters."""
+
+    def setup_method(self):
+        # Reset structlog and stdlib between tests
+        structlog.reset_defaults()
+        root = logging.getLogger()
+        root.handlers.clear()
+        root.setLevel(logging.WARNING)
+        # Reset context vars
+        for var in (ctx_node_id, ctx_ws_id, ctx_user_id, ctx_request_id):
+            var.set("")
+
+    def test_sets_root_handler(self):
+        configure_logging(level="INFO", json_output=False, service="test")
+        root = logging.getLogger()
+        assert len(root.handlers) == 1
+        assert root.level == logging.INFO
+
+    def test_level_debug(self):
+        configure_logging(level="DEBUG", json_output=False)
+        root = logging.getLogger()
+        assert root.level == logging.DEBUG
+
+    def test_level_warning(self):
+        configure_logging(level="WARNING", json_output=False)
+        root = logging.getLogger()
+        assert root.level == logging.WARNING
+
+    def test_json_output(self, capsys):
+        configure_logging(level="INFO", json_output=True, service="test-svc")
+        log = logging.getLogger("test.json_output")
+        log.info("hello world")
+        captured = capsys.readouterr()
+        # JSON goes to stderr
+        line = captured.err.strip()
+        data = json.loads(line)
+        assert data["event"] == "hello world"
+        assert data["level"] == "info"
+        assert data["service"] == "test-svc"
+        assert "timestamp" in data
+
+    def test_console_output(self, capsys):
+        configure_logging(level="INFO", json_output=False)
+        log = logging.getLogger("test.console_output")
+        log.info("console hello")
+        captured = capsys.readouterr()
+        assert "console hello" in captured.err
+
+    def test_quiet_third_party(self):
+        configure_logging(level="DEBUG", json_output=False)
+        for name in ("httpx", "httpcore", "openai", "anthropic", "uvicorn.access"):
+            assert logging.getLogger(name).level == logging.WARNING
+
+    def test_replaces_existing_handlers(self):
+        root = logging.getLogger()
+        # Count existing handlers (pytest may add its own)
+        before = len(root.handlers)
+        root.addHandler(logging.StreamHandler())
+        root.addHandler(logging.StreamHandler())
+        assert len(root.handlers) == before + 2
+        configure_logging(level="INFO", json_output=False)
+        # configure_logging clears all and adds exactly 1
+        assert len(root.handlers) == 1
+
+    def test_env_var_level_override(self, monkeypatch):
+        monkeypatch.setenv("TURNSTONE_LOG_LEVEL", "ERROR")
+        configure_logging(level="DEBUG", json_output=False)
+        root = logging.getLogger()
+        assert root.level == logging.ERROR
+
+    def test_env_var_format_json(self, monkeypatch, capsys):
+        monkeypatch.setenv("TURNSTONE_LOG_FORMAT", "json")
+        configure_logging(level="INFO", service="test")
+        log = logging.getLogger("test.env_json")
+        log.info("env json test")
+        captured = capsys.readouterr()
+        data = json.loads(captured.err.strip())
+        assert data["event"] == "env json test"
+
+    def test_env_var_format_text(self, monkeypatch, capsys):
+        monkeypatch.setenv("TURNSTONE_LOG_FORMAT", "text")
+        configure_logging(level="INFO", json_output=True)  # json_output overridden by env
+        log = logging.getLogger("test.env_text")
+        log.info("env text test")
+        captured = capsys.readouterr()
+        # Should NOT be JSON
+        line = captured.err.strip()
+        assert "env text test" in line
+        # Verify it's not JSON
+        try:
+            json.loads(line)
+            is_json = True
+        except json.JSONDecodeError:
+            is_json = False
+        assert not is_json
+
+
+class TestContextInjection:
+    """Test that context variables appear in log output."""
+
+    def setup_method(self):
+        structlog.reset_defaults()
+        root = logging.getLogger()
+        root.handlers.clear()
+        root.setLevel(logging.WARNING)
+        for var in (ctx_node_id, ctx_ws_id, ctx_user_id, ctx_request_id):
+            var.set("")
+
+    def test_node_id_in_output(self, capsys):
+        configure_logging(level="INFO", json_output=True)
+        ctx_node_id.set("worker-01_a3f2")
+        log = logging.getLogger("test.ctx")
+        log.info("ctx test")
+        data = json.loads(capsys.readouterr().err.strip())
+        assert data["node_id"] == "worker-01_a3f2"
+
+    def test_ws_id_in_output(self, capsys):
+        configure_logging(level="INFO", json_output=True)
+        ctx_ws_id.set("abc123")
+        log = logging.getLogger("test.ctx")
+        log.info("ws test")
+        data = json.loads(capsys.readouterr().err.strip())
+        assert data["ws_id"] == "abc123"
+
+    def test_empty_context_omitted(self, capsys):
+        configure_logging(level="INFO", json_output=True)
+        # All context vars are empty string (default)
+        log = logging.getLogger("test.ctx")
+        log.info("empty ctx")
+        data = json.loads(capsys.readouterr().err.strip())
+        assert "node_id" not in data
+        assert "ws_id" not in data
+        assert "user_id" not in data
+        assert "request_id" not in data
+
+    def test_multiple_context_vars(self, capsys):
+        configure_logging(level="INFO", json_output=True)
+        ctx_node_id.set("node-1")
+        ctx_ws_id.set("ws-2")
+        ctx_request_id.set("req-3")
+        log = logging.getLogger("test.ctx")
+        log.info("multi ctx")
+        data = json.loads(capsys.readouterr().err.strip())
+        assert data["node_id"] == "node-1"
+        assert data["ws_id"] == "ws-2"
+        assert data["request_id"] == "req-3"
+        assert "user_id" not in data
+
+
+class TestGetLogger:
+    """Test get_logger() returns a usable bound logger."""
+
+    def setup_method(self):
+        structlog.reset_defaults()
+        root = logging.getLogger()
+        root.handlers.clear()
+        root.setLevel(logging.WARNING)
+
+    def test_get_logger_returns_bound_logger(self):
+        configure_logging(level="INFO", json_output=False)
+        log = get_logger("test.bound")
+        assert log is not None
+
+    def test_get_logger_outputs(self, capsys):
+        configure_logging(level="INFO", json_output=True)
+        log = get_logger("test.bound")
+        log.info("bound logger test", extra_key="extra_val")
+        data = json.loads(capsys.readouterr().err.strip())
+        assert data["event"] == "bound logger test"
+        assert data["extra_key"] == "extra_val"
+
+
+class TestServiceField:
+    """Test that service name is injected when configured."""
+
+    def setup_method(self):
+        structlog.reset_defaults()
+        root = logging.getLogger()
+        root.handlers.clear()
+        root.setLevel(logging.WARNING)
+
+    def test_service_present(self, capsys):
+        configure_logging(level="INFO", json_output=True, service="myservice")
+        log = logging.getLogger("test.svc")
+        log.info("svc test")
+        data = json.loads(capsys.readouterr().err.strip())
+        assert data["service"] == "myservice"
+
+    def test_no_service_when_empty(self, capsys):
+        configure_logging(level="INFO", json_output=True)
+        log = logging.getLogger("test.svc")
+        log.info("no svc")
+        data = json.loads(capsys.readouterr().err.strip())
+        assert "service" not in data
@@ -530,11 +530,11 @@ class TestWorkstreamModelParam:

        captured_alias = None

-        def factory(ui: Any, model_alias: str | None = None) -> Any:
+        def factory(ui: Any, model_alias: str | None = None, ws_id: str | None = None) -> Any:
            nonlocal captured_alias
            captured_alias = model_alias
            mock_session = MagicMock()
-            mock_session.session_id = "test123"
+            mock_session.ws_id = "test123"
            return mock_session

        mgr = WorkstreamManager(factory)
@@ -544,11 +544,11 @@ class TestWorkstreamModelParam:
    def test_create_without_model(self) -> None:
        captured_alias = None

-        def factory(ui: Any, model_alias: str | None = None) -> Any:
+        def factory(ui: Any, model_alias: str | None = None, ws_id: str | None = None) -> Any:
            nonlocal captured_alias
            captured_alias = model_alias
            mock_session = MagicMock()
-            mock_session.session_id = "test123"
+            mock_session.ws_id = "test123"
            return mock_session

        from turnstone.core.workstream import WorkstreamManager
@@ -0,0 +1,338 @@
+"""Tests for the channel gateway HTTP notify endpoint."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock
+
+import pytest
+from starlette.testclient import TestClient
+
+from turnstone.channels._http import create_channel_app
+from turnstone.core.storage._sqlite import SQLiteBackend
+
+
+@pytest.fixture
+def storage(tmp_path):
+    return SQLiteBackend(str(tmp_path / "test.db"))
+
+
+@pytest.fixture
+def mock_adapter():
+    adapter = AsyncMock()
+    adapter.channel_type = "discord"
+    adapter.send = AsyncMock(return_value="msg_001")
+    return adapter
+
+
+@pytest.fixture
+def no_auth_client(storage, mock_adapter):
+    """Client with no auth configured (for fail-closed tests)."""
+    app = create_channel_app({"discord": mock_adapter}, storage)
+    return TestClient(app)
+
+
+@pytest.fixture
+def client(storage, mock_adapter):
+    """Default client with static auth token configured."""
+    app = create_channel_app({"discord": mock_adapter}, storage, auth_token="test-secret-token")
+    return TestClient(app)
+
+
+@pytest.fixture
+def authed_client(storage, mock_adapter):
+    """Alias — same as client, for auth-specific test clarity."""
+    app = create_channel_app({"discord": mock_adapter}, storage, auth_token="test-secret-token")
+    return TestClient(app)
+
+
+@pytest.fixture
+def jwt_client(storage, mock_adapter):
+    """Client with JWT auth configured."""
+    app = create_channel_app({"discord": mock_adapter}, storage, jwt_secret="a" * 32)
+    return TestClient(app)
+
+
+class TestNotifyEndpoint:
+    def test_health(self, client):
+        resp = client.get("/health")
+        assert resp.status_code == 200
+        assert resp.json()["status"] == "ok"
+
+    def _headers(self) -> dict[str, str]:
+        return {"Authorization": "Bearer test-secret-token"}
+
+    def test_direct_discord_target(self, client, mock_adapter):
+        resp = client.post(
+            "/v1/api/notify",
+            json={
+                "target": {"channel_type": "discord", "channel_id": "123456"},
+                "message": "Hello!",
+            },
+            headers=self._headers(),
+        )
+        assert resp.status_code == 200
+        results = resp.json()["results"]
+        assert len(results) == 1
+        assert results[0]["status"] == "sent"
+        assert results[0]["message_id"] == "msg_001"
+        mock_adapter.send.assert_called_once_with("123456", "Hello!")
+
+    def test_with_title(self, client, mock_adapter):
+        resp = client.post(
+            "/v1/api/notify",
+            json={
+                "target": {"channel_type": "discord", "channel_id": "123456"},
+                "message": "Hello!",
+                "title": "Alert",
+            },
+            headers=self._headers(),
+        )
+        assert resp.status_code == 200
+        mock_adapter.send.assert_called_once_with("123456", "**Alert**\nHello!")
+
+    def test_username_resolution(self, client, storage, mock_adapter):
+        # Create a user and link a channel
+        storage.create_user("u1", "testuser", "Test User", "hash")
+        storage.create_channel_user("discord", "disc_123", "u1")
+
+        resp = client.post(
+            "/v1/api/notify",
+            json={
+                "target": {"username": "testuser"},
+                "message": "Hello!",
+            },
+            headers=self._headers(),
+        )
+        assert resp.status_code == 200
+        results = resp.json()["results"]
+        assert len(results) == 1
+        assert results[0]["status"] == "sent"
+        mock_adapter.send.assert_called_once_with("disc_123", "Hello!")
+
+    def test_unknown_username(self, client):
+        resp = client.post(
+            "/v1/api/notify",
+            json={
+                "target": {"username": "nobody"},
+                "message": "Hello!",
+            },
+            headers=self._headers(),
+        )
+        assert resp.status_code == 404
+        error = resp.json()["error"]
+        assert "nobody" not in error
+        assert "not found or has no linked channels" in error
+
+    def test_user_no_channels(self, authed_client, storage):
+        storage.create_user("u1", "testuser", "Test User", "hash")
+
+        resp = authed_client.post(
+            "/v1/api/notify",
+            json={
+                "target": {"username": "testuser"},
+                "message": "Hello!",
+            },
+            headers={"Authorization": "Bearer test-secret-token"},
+        )
+        assert resp.status_code == 404
+        # Generic message — must not differentiate "not found" vs "no channels"
+        error = resp.json()["error"]
+        assert "testuser" not in error
+        assert "not found or has no linked channels" in error
+
+    def test_missing_fields(self, client):
+        resp = client.post(
+            "/v1/api/notify",
+            json={"target": {"username": "x"}},
+            headers=self._headers(),
+        )
+        assert resp.status_code == 400
+
+    def test_missing_target(self, client):
+        resp = client.post(
+            "/v1/api/notify",
+            json={"message": "Hello!"},
+            headers=self._headers(),
+        )
+        assert resp.status_code == 400
+
+    def test_invalid_target(self, client):
+        resp = client.post(
+            "/v1/api/notify",
+            json={
+                "target": {"invalid": "field"},
+                "message": "Hello!",
+            },
+            headers=self._headers(),
+        )
+        assert resp.status_code == 400
+
+    def test_no_adapter(self, client, storage):
+        # App has discord adapter, try email target
+        resp = client.post(
+            "/v1/api/notify",
+            json={
+                "target": {"channel_type": "email", "channel_id": "test@example.com"},
+                "message": "Hello!",
+            },
+            headers=self._headers(),
+        )
+        assert resp.status_code == 200
+        results = resp.json()["results"]
+        assert results[0]["status"] == "no_adapter"
+
+    def test_adapter_failure(self, client, mock_adapter):
+        mock_adapter.send.side_effect = RuntimeError("Discord API error")
+        resp = client.post(
+            "/v1/api/notify",
+            json={
+                "target": {"channel_type": "discord", "channel_id": "123456"},
+                "message": "Hello!",
+            },
+            headers=self._headers(),
+        )
+        assert resp.status_code == 200
+        results = resp.json()["results"]
+        assert results[0]["status"] == "failed"
+
+    def test_invalid_json(self, client):
+        resp = client.post(
+            "/v1/api/notify",
+            content=b"not json",
+            headers={
+                "content-type": "application/json",
+                "Authorization": "Bearer test-secret-token",
+            },
+        )
+        assert resp.status_code == 400
+
+    def test_whitespace_only_message(self, client):
+        """Whitespace-only messages should be rejected."""
+        resp = client.post(
+            "/v1/api/notify",
+            json={
+                "target": {"channel_type": "discord", "channel_id": "123"},
+                "message": "   ",
+            },
+            headers=self._headers(),
+        )
+        assert resp.status_code == 400
+
+
+class TestNotifyAuth:
+    """Tests for authentication on the /v1/api/notify endpoint."""
+
+    def test_reject_when_unconfigured(self, no_auth_client):
+        """Requests are rejected (fail closed) when no auth is configured."""
+        resp = no_auth_client.post(
+            "/v1/api/notify",
+            json={
+                "target": {"channel_type": "discord", "channel_id": "123"},
+                "message": "Hello!",
+            },
+        )
+        assert resp.status_code == 401
+
+    def test_reject_without_token(self, authed_client):
+        """Requests without Authorization header are rejected when auth is configured."""
+        resp = authed_client.post(
+            "/v1/api/notify",
+            json={
+                "target": {"channel_type": "discord", "channel_id": "123"},
+                "message": "Hello!",
+            },
+        )
+        assert resp.status_code == 401
+
+    def test_reject_wrong_token(self, authed_client):
+        """Requests with wrong token are rejected."""
+        resp = authed_client.post(
+            "/v1/api/notify",
+            json={
+                "target": {"channel_type": "discord", "channel_id": "123"},
+                "message": "Hello!",
+            },
+            headers={"Authorization": "Bearer wrong-token"},
+        )
+        assert resp.status_code == 401
+
+    def test_accept_valid_static_token(self, authed_client, mock_adapter):
+        """Requests with correct static token are accepted."""
+        resp = authed_client.post(
+            "/v1/api/notify",
+            json={
+                "target": {"channel_type": "discord", "channel_id": "123"},
+                "message": "Hello!",
+            },
+            headers={"Authorization": "Bearer test-secret-token"},
+        )
+        assert resp.status_code == 200
+        assert resp.json()["results"][0]["status"] == "sent"
+
+    def test_accept_valid_jwt(self, jwt_client, mock_adapter):
+        """Requests with a valid JWT for the channel audience are accepted."""
+        from turnstone.core.auth import JWT_AUD_CHANNEL, create_jwt
+
+        token = create_jwt(
+            user_id="system",
+            scopes=frozenset({"write"}),
+            source="service",
+            secret="a" * 32,
+            audience=JWT_AUD_CHANNEL,
+        )
+        resp = jwt_client.post(
+            "/v1/api/notify",
+            json={
+                "target": {"channel_type": "discord", "channel_id": "123"},
+                "message": "Hello!",
+            },
+            headers={"Authorization": f"Bearer {token}"},
+        )
+        assert resp.status_code == 200
+
+    def test_reject_jwt_wrong_audience(self, jwt_client):
+        """JWTs with wrong audience are rejected."""
+        from turnstone.core.auth import create_jwt
+
+        token = create_jwt(
+            user_id="system",
+            scopes=frozenset({"write"}),
+            source="service",
+            secret="a" * 32,
+            audience="turnstone-server",  # wrong audience
+        )
+        resp = jwt_client.post(
+            "/v1/api/notify",
+            json={
+                "target": {"channel_type": "discord", "channel_id": "123"},
+                "message": "Hello!",
+            },
+            headers={"Authorization": f"Bearer {token}"},
+        )
+        assert resp.status_code == 401
+
+    def test_reject_jwt_wrong_secret(self, jwt_client):
+        """JWTs signed with wrong secret are rejected."""
+        from turnstone.core.auth import JWT_AUD_CHANNEL, create_jwt
+
+        token = create_jwt(
+            user_id="system",
+            scopes=frozenset({"write"}),
+            source="service",
+            secret="b" * 32,  # wrong secret
+            audience=JWT_AUD_CHANNEL,
+        )
+        resp = jwt_client.post(
+            "/v1/api/notify",
+            json={
+                "target": {"channel_type": "discord", "channel_id": "123"},
+                "message": "Hello!",
+            },
+            headers={"Authorization": f"Bearer {token}"},
+        )
+        assert resp.status_code == 401
+
+    def test_health_bypasses_auth(self, authed_client):
+        """Health endpoint is always accessible regardless of auth config."""
+        resp = authed_client.get("/health")
+        assert resp.status_code == 200
@@ -0,0 +1,618 @@
+"""Tests for the notify tool (prepare + execute) in ChatSession."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from unittest.mock import MagicMock
+
+if TYPE_CHECKING:
+    from turnstone.core.session import ChatSession
+
+
+def _make_session() -> ChatSession:
+    """Create a minimal ChatSession with mocked dependencies."""
+    from unittest.mock import patch
+
+    with (
+        patch("turnstone.core.memory.register_workstream"),
+        patch("turnstone.core.session.save_message"),
+    ):
+        from turnstone.core.session import ChatSession
+
+        ui = MagicMock()
+        session = ChatSession(
+            client=MagicMock(),
+            model="test-model",
+            ui=ui,
+            instructions=None,
+            temperature=0.7,
+            max_tokens=1000,
+            tool_timeout=30,
+        )
+    return session
+
+
+class TestPrepareNotify:
+    def test_valid_username_target(self):
+        session = _make_session()
+        result = session._prepare_notify(
+            "call_1",
+            {
+                "message": "Hello!",
+                "username": "admin",
+            },
+        )
+        assert "execute" in result
+        assert result["func_name"] == "notify"
+        assert result["needs_approval"] is False
+        assert "@admin" in result["header"]
+        assert result["username"] == "admin"
+        assert result["message"] == "Hello!"
+
+    def test_valid_direct_target(self):
+        session = _make_session()
+        result = session._prepare_notify(
+            "call_1",
+            {
+                "message": "Hello!",
+                "channel_type": "discord",
+                "channel_id": "123456",
+            },
+        )
+        assert "execute" in result
+        assert result["channel_type"] == "discord"
+        assert result["channel_id"] == "123456"
+        assert "discord:123456" in result["header"]
+
+    def test_missing_message(self):
+        session = _make_session()
+        result = session._prepare_notify("call_1", {"username": "admin"})
+        assert "error" in result
+        assert "message" in result["error"].lower()
+
+    def test_empty_message(self):
+        session = _make_session()
+        result = session._prepare_notify(
+            "call_1",
+            {
+                "message": "",
+                "username": "admin",
+            },
+        )
+        assert "error" in result
+
+    def test_message_too_long(self):
+        session = _make_session()
+        result = session._prepare_notify(
+            "call_1",
+            {
+                "message": "x" * 2001,
+                "username": "admin",
+            },
+        )
+        assert "error" in result
+        assert "2000" in result["error"]
+
+    def test_both_username_and_direct(self):
+        session = _make_session()
+        result = session._prepare_notify(
+            "call_1",
+            {
+                "message": "Hello!",
+                "username": "admin",
+                "channel_type": "discord",
+                "channel_id": "123",
+            },
+        )
+        assert "error" in result
+        assert "both" in result["error"].lower() or "ambiguous" in result["error"].lower()
+
+    def test_no_target(self):
+        session = _make_session()
+        result = session._prepare_notify("call_1", {"message": "Hello!"})
+        assert "error" in result
+
+    def test_channel_type_without_id(self):
+        session = _make_session()
+        result = session._prepare_notify(
+            "call_1",
+            {
+                "message": "Hello!",
+                "channel_type": "discord",
+            },
+        )
+        assert "error" in result
+        assert "channel_id" in result["error"]
+
+    def test_channel_id_without_type(self):
+        session = _make_session()
+        result = session._prepare_notify(
+            "call_1",
+            {
+                "message": "Hello!",
+                "channel_id": "123456",
+            },
+        )
+        assert "error" in result
+        assert "channel_type" in result["error"]
+
+    def test_preview_truncated(self):
+        session = _make_session()
+        result = session._prepare_notify(
+            "call_1",
+            {
+                "message": "a" * 200,
+                "username": "admin",
+            },
+        )
+        assert result["preview"].endswith("...")
+        assert len(result["preview"]) <= 123  # 120 chars + "..."
+
+    def test_title_passed_through(self):
+        session = _make_session()
+        result = session._prepare_notify(
+            "call_1",
+            {
+                "message": "Hello!",
+                "username": "admin",
+                "title": "Alert",
+            },
+        )
+        assert result["title"] == "Alert"
+
+
+class TestExecNotify:
+    def test_sends_http_to_channel_gateway(self, tmp_path):
+        from turnstone.core.storage._sqlite import SQLiteBackend
+
+        storage = SQLiteBackend(str(tmp_path / "test.db"))
+        storage.register_service("channel", "ch-1", "http://localhost:8091")
+
+        session = _make_session()
+        item = {
+            "call_id": "call_1",
+            "func_name": "notify",
+            "message": "Hello!",
+            "username": "admin",
+            "channel_type": "",
+            "channel_id": "",
+            "title": "Alert",
+        }
+
+        mock_resp = MagicMock()
+        mock_resp.status_code = 200
+        mock_resp.json.return_value = {
+            "results": [{"channel_type": "discord", "channel_id": "123", "status": "sent"}]
+        }
+
+        from unittest.mock import patch
+
+        with (
+            patch("turnstone.core.session.get_storage", return_value=storage),
+            patch("turnstone.core.session.httpx.post", return_value=mock_resp) as mock_post,
+            patch.dict("os.environ", {}, clear=False),
+        ):
+            call_id, msg = session._exec_notify(item)
+
+        assert call_id == "call_1"
+        assert "sent successfully" in msg.lower()
+        mock_post.assert_called_once()
+        post_kwargs = mock_post.call_args
+        assert post_kwargs.kwargs["json"]["target"] == {"username": "admin"}
+        assert post_kwargs.kwargs["json"]["message"] == "Hello!"
+
+    def test_no_services_available(self, tmp_path):
+        from turnstone.core.storage._sqlite import SQLiteBackend
+
+        storage = SQLiteBackend(str(tmp_path / "test.db"))
+        # No services registered
+
+        session = _make_session()
+        item = {
+            "call_id": "call_1",
+            "func_name": "notify",
+            "message": "Hello!",
+            "username": "admin",
+            "channel_type": "",
+            "channel_id": "",
+            "title": "",
+        }
+
+        from unittest.mock import patch
+
+        with (
+            patch("turnstone.core.session.get_storage", return_value=storage),
+            patch("turnstone.core.session.time.sleep"),
+        ):
+            call_id, msg = session._exec_notify(item)
+
+        assert "no channel gateway" in msg.lower()
+
+    def test_rate_limit(self, tmp_path):
+        from turnstone.core.storage._sqlite import SQLiteBackend
+
+        storage = SQLiteBackend(str(tmp_path / "test.db"))
+        storage.register_service("channel", "ch-1", "http://localhost:8091")
+
+        session = _make_session()
+        item = {
+            "call_id": "call_1",
+            "func_name": "notify",
+            "message": "Hello!",
+            "username": "admin",
+            "channel_type": "",
+            "channel_id": "",
+            "title": "",
+        }
+
+        mock_resp = MagicMock()
+        mock_resp.status_code = 200
+        mock_resp.json.return_value = {
+            "results": [{"channel_type": "discord", "channel_id": "123", "status": "sent"}]
+        }
+
+        from unittest.mock import patch
+
+        with (
+            patch("turnstone.core.session.get_storage", return_value=storage),
+            patch("turnstone.core.session.httpx.post", return_value=mock_resp),
+            patch.dict("os.environ", {}, clear=False),
+        ):
+            for _i in range(5):
+                call_id, msg = session._exec_notify(item)
+                assert "sent successfully" in msg.lower()
+
+            # 6th should fail
+            call_id, msg = session._exec_notify(item)
+            assert "rate limit" in msg.lower()
+
+    def test_rate_limit_not_consumed_on_failure(self, tmp_path):
+        """Failed delivery should not consume rate limit slots."""
+        from turnstone.core.storage._sqlite import SQLiteBackend
+
+        storage = SQLiteBackend(str(tmp_path / "test.db"))
+        storage.register_service("channel", "ch-1", "http://localhost:8091")
+
+        session = _make_session()
+        item = {
+            "call_id": "call_1",
+            "func_name": "notify",
+            "message": "Hello!",
+            "username": "admin",
+            "channel_type": "",
+            "channel_id": "",
+            "title": "",
+        }
+
+        from unittest.mock import patch
+
+        with (
+            patch("turnstone.core.session.get_storage", return_value=storage),
+            patch(
+                "turnstone.core.session.httpx.post",
+                side_effect=ConnectionError("refused"),
+            ),
+            patch.dict("os.environ", {}, clear=False),
+            patch("turnstone.core.session.time.sleep"),
+        ):
+            # All fail — counter should stay at 0
+            for _i in range(3):
+                session._exec_notify(item)
+            assert session._notify_count == 0
+
+    def test_counter_on_init(self):
+        session = _make_session()
+        assert session._notify_count == 0
+
+    def test_http_failure_reported(self, tmp_path):
+        from turnstone.core.storage._sqlite import SQLiteBackend
+
+        storage = SQLiteBackend(str(tmp_path / "test.db"))
+        storage.register_service("channel", "ch-1", "http://localhost:8091")
+
+        session = _make_session()
+        item = {
+            "call_id": "call_1",
+            "func_name": "notify",
+            "message": "Hello!",
+            "username": "",
+            "channel_type": "discord",
+            "channel_id": "999",
+            "title": "",
+        }
+
+        from unittest.mock import patch
+
+        with (
+            patch("turnstone.core.session.get_storage", return_value=storage),
+            patch(
+                "turnstone.core.session.httpx.post",
+                side_effect=ConnectionError("refused"),
+            ),
+            patch.dict("os.environ", {}, clear=False),
+            patch("turnstone.core.session.time.sleep"),
+        ):
+            call_id, msg = session._exec_notify(item)
+
+        # Error message should be generic (no internal details)
+        assert "delivery failed" in msg.lower()
+        assert "refused" not in msg
+        assert "ch-1" not in msg
+
+    def test_first_healthy_only(self, tmp_path):
+        """Only the first healthy gateway should receive the request."""
+        from turnstone.core.storage._sqlite import SQLiteBackend
+
+        storage = SQLiteBackend(str(tmp_path / "test.db"))
+        storage.register_service("channel", "ch-1", "http://localhost:8091")
+        storage.register_service("channel", "ch-2", "http://localhost:8092")
+
+        session = _make_session()
+        item = {
+            "call_id": "call_1",
+            "func_name": "notify",
+            "message": "Hello!",
+            "username": "admin",
+            "channel_type": "",
+            "channel_id": "",
+            "title": "",
+        }
+
+        mock_resp = MagicMock()
+        mock_resp.status_code = 200
+        mock_resp.json.return_value = {
+            "results": [{"channel_type": "discord", "channel_id": "123", "status": "sent"}]
+        }
+
+        from unittest.mock import patch
+
+        with (
+            patch("turnstone.core.session.get_storage", return_value=storage),
+            patch("turnstone.core.session.httpx.post", return_value=mock_resp) as mock_post,
+            patch.dict("os.environ", {}, clear=False),
+        ):
+            session._exec_notify(item)
+
+        # Should only have been called once (first healthy)
+        assert mock_post.call_count == 1
+
+    def test_ssrf_protection(self, tmp_path):
+        """URLs with non-http(s) schemes should be skipped."""
+        from turnstone.core.storage._sqlite import SQLiteBackend
+
+        storage = SQLiteBackend(str(tmp_path / "test.db"))
+        # Register a service with an invalid scheme
+        storage.register_service("channel", "ch-bad", "ftp://evil.example.com")
+
+        session = _make_session()
+        item = {
+            "call_id": "call_1",
+            "func_name": "notify",
+            "message": "Hello!",
+            "username": "admin",
+            "channel_type": "",
+            "channel_id": "",
+            "title": "",
+        }
+
+        from unittest.mock import patch
+
+        with (
+            patch("turnstone.core.session.get_storage", return_value=storage),
+            patch("turnstone.core.session.httpx.post") as mock_post,
+            patch.dict("os.environ", {}, clear=False),
+            patch("turnstone.core.session.time.sleep"),
+        ):
+            call_id, msg = session._exec_notify(item)
+
+        # httpx.post should never be called for ftp:// URL
+        mock_post.assert_not_called()
+        assert "delivery failed" in msg.lower()
+
+    def test_retry_on_no_services(self, tmp_path):
+        """Retries service lookup when no gateways are initially available."""
+        session = _make_session()
+        item = {
+            "call_id": "call_1",
+            "func_name": "notify",
+            "message": "Hello!",
+            "username": "admin",
+            "channel_type": "",
+            "channel_id": "",
+            "title": "",
+        }
+
+        # First two calls return empty, third returns a service
+        call_count = 0
+
+        def _list_services(stype: str, max_age_seconds: int = 120) -> list[dict[str, str]]:
+            nonlocal call_count
+            call_count += 1
+            if call_count <= 2:
+                return []
+            return [
+                {
+                    "service_type": "channel",
+                    "service_id": "ch-1",
+                    "url": "http://localhost:8091",
+                    "metadata": "{}",
+                    "last_heartbeat": "",
+                    "created": "",
+                }
+            ]
+
+        mock_resp = MagicMock()
+        mock_resp.status_code = 200
+        mock_resp.json.return_value = {
+            "results": [{"channel_type": "discord", "channel_id": "123", "status": "sent"}]
+        }
+
+        from unittest.mock import patch
+
+        mock_storage = MagicMock()
+        mock_storage.list_services = _list_services
+
+        with (
+            patch("turnstone.core.session.get_storage", return_value=mock_storage),
+            patch("turnstone.core.session.httpx.post", return_value=mock_resp),
+            patch.dict("os.environ", {}, clear=False),
+            patch("turnstone.core.session.time.sleep") as mock_sleep,
+        ):
+            call_id, msg = session._exec_notify(item)
+
+        assert "sent successfully" in msg.lower()
+        # Should have slept twice (retry delays)
+        assert mock_sleep.call_count == 2
+
+    def test_retry_on_all_gateways_failed(self, tmp_path):
+        """Retries when all gateways fail on first attempt but succeed on retry."""
+        from turnstone.core.storage._sqlite import SQLiteBackend
+
+        storage = SQLiteBackend(str(tmp_path / "test.db"))
+        storage.register_service("channel", "ch-1", "http://localhost:8091")
+
+        session = _make_session()
+        item = {
+            "call_id": "call_1",
+            "func_name": "notify",
+            "message": "Hello!",
+            "username": "admin",
+            "channel_type": "",
+            "channel_id": "",
+            "title": "",
+        }
+
+        call_count = 0
+
+        def _post(*args, **kwargs):
+            nonlocal call_count
+            call_count += 1
+            if call_count <= 1:
+                raise ConnectionError("refused")
+            resp = MagicMock()
+            resp.status_code = 200
+            resp.json.return_value = {
+                "results": [{"channel_type": "discord", "channel_id": "123", "status": "sent"}]
+            }
+            return resp
+
+        from unittest.mock import patch
+
+        with (
+            patch("turnstone.core.session.get_storage", return_value=storage),
+            patch("turnstone.core.session.httpx.post", side_effect=_post),
+            patch.dict("os.environ", {}, clear=False),
+            patch("turnstone.core.session.time.sleep") as mock_sleep,
+        ):
+            call_id, msg = session._exec_notify(item)
+
+        assert "sent successfully" in msg.lower()
+        assert mock_sleep.call_count == 1
+
+    def test_no_services_logs_warning(self, tmp_path):
+        """Server-side warning is logged when no services are available."""
+        from turnstone.core.storage._sqlite import SQLiteBackend
+
+        storage = SQLiteBackend(str(tmp_path / "test.db"))
+
+        session = _make_session()
+        item = {
+            "call_id": "call_1",
+            "func_name": "notify",
+            "message": "Hello!",
+            "username": "admin",
+            "channel_type": "",
+            "channel_id": "",
+            "title": "",
+        }
+
+        from unittest.mock import patch
+
+        with (
+            patch("turnstone.core.session.get_storage", return_value=storage),
+            patch("turnstone.core.session.time.sleep"),
+            patch("turnstone.core.session.log") as mock_log,
+        ):
+            session._exec_notify(item)
+
+        # Should have logged warnings for retries + final exhaustion
+        warning_calls = [c for c in mock_log.warning.call_args_list]
+        assert len(warning_calls) >= 3  # 2 retry warnings + 1 exhaustion
+        events = [c.args[0] for c in warning_calls]
+        assert "notify.no_services" in events
+        assert "notify.no_services_exhausted" in events
+
+    def test_all_gateways_failed_logs_warning(self, tmp_path):
+        """Server-side warning is logged when all gateways fail."""
+        from turnstone.core.storage._sqlite import SQLiteBackend
+
+        storage = SQLiteBackend(str(tmp_path / "test.db"))
+        storage.register_service("channel", "ch-1", "http://localhost:8091")
+
+        session = _make_session()
+        item = {
+            "call_id": "call_1",
+            "func_name": "notify",
+            "message": "Hello!",
+            "username": "admin",
+            "channel_type": "",
+            "channel_id": "",
+            "title": "",
+        }
+
+        from unittest.mock import patch
+
+        with (
+            patch("turnstone.core.session.get_storage", return_value=storage),
+            patch(
+                "turnstone.core.session.httpx.post",
+                side_effect=ConnectionError("refused"),
+            ),
+            patch.dict("os.environ", {}, clear=False),
+            patch("turnstone.core.session.time.sleep"),
+            patch("turnstone.core.session.log") as mock_log,
+        ):
+            session._exec_notify(item)
+
+        warning_calls = [c for c in mock_log.warning.call_args_list]
+        events = [c.args[0] for c in warning_calls]
+        # 2 retry warnings + 1 final failure
+        assert "notify.all_gateways_failed" in events
+        assert "notify.delivery_failed" in events
+
+    def test_gateway_200_but_no_delivery(self, tmp_path):
+        """HTTP 200 with all results failed should not count as success."""
+        from turnstone.core.storage._sqlite import SQLiteBackend
+
+        storage = SQLiteBackend(str(tmp_path / "test.db"))
+        storage.register_service("channel", "ch-1", "http://localhost:8091")
+
+        session = _make_session()
+        item = {
+            "call_id": "call_1",
+            "func_name": "notify",
+            "message": "Hello!",
+            "username": "admin",
+            "channel_type": "",
+            "channel_id": "",
+            "title": "",
+        }
+
+        mock_resp = MagicMock()
+        mock_resp.status_code = 200
+        mock_resp.json.return_value = {
+            "results": [{"channel_type": "discord", "channel_id": "123", "status": "no_adapter"}]
+        }
+
+        from unittest.mock import patch
+
+        with (
+            patch("turnstone.core.session.get_storage", return_value=storage),
+            patch("turnstone.core.session.httpx.post", return_value=mock_resp),
+            patch.dict("os.environ", {}, clear=False),
+            patch("turnstone.core.session.time.sleep"),
+        ):
+            call_id, msg = session._exec_notify(item)
+
+        assert "delivery failed" in msg.lower()
+        assert session._notify_count == 0
@@ -27,7 +27,7 @@ class TestServerSpec:
        expected = {
            "/v1/api/workstreams",
            "/v1/api/dashboard",
-            "/v1/api/sessions",
+            "/v1/api/workstreams/saved",
            "/v1/api/send",
            "/v1/api/approve",
            "/v1/api/plan",
@@ -1103,6 +1103,43 @@ class TestOpenAIParameterGating:
        assert "temperature" not in kwargs
        assert "reasoning_effort" not in kwargs

+    def test_gpt5_pro_unsupported_effort_falls_back(self) -> None:
+        """GPT-5 pro only supports 'high'; unsupported values fall back to default."""
+        caps = self.provider.get_capabilities("gpt-5-pro")
+        kwargs: dict[str, Any] = {}
+        self.provider._apply_model_params(kwargs, caps, temperature=0.7, reasoning_effort="medium")
+        assert "temperature" not in kwargs
+        assert kwargs["reasoning_effort"] == "high"  # fell back to default
+
+    def test_gpt5_pro_supported_effort_passes_through(self) -> None:
+        """GPT-5 pro accepts 'high' directly."""
+        caps = self.provider.get_capabilities("gpt-5-pro")
+        kwargs: dict[str, Any] = {}
+        self.provider._apply_model_params(kwargs, caps, temperature=0.7, reasoning_effort="high")
+        assert kwargs["reasoning_effort"] == "high"
+
+    def test_gpt54_1m_context_and_effort(self) -> None:
+        """GPT-5.4: 1M context, temperature when effort=none, xhigh supported."""
+        caps = self.provider.get_capabilities("gpt-5.4")
+        assert caps.context_window == 1050000
+        kwargs: dict[str, Any] = {}
+        self.provider._apply_model_params(kwargs, caps, temperature=0.7, reasoning_effort="none")
+        assert kwargs["temperature"] == 0.7
+        assert "reasoning_effort" not in kwargs
+        kwargs2: dict[str, Any] = {}
+        self.provider._apply_model_params(kwargs2, caps, temperature=0.7, reasoning_effort="xhigh")
+        assert "temperature" not in kwargs2
+        assert kwargs2["reasoning_effort"] == "xhigh"
+
+    def test_gpt54_pro_no_temperature_always_reasoning(self) -> None:
+        """GPT-5.4 pro: no temperature, medium/high/xhigh only."""
+        caps = self.provider.get_capabilities("gpt-5.4-pro")
+        assert caps.context_window == 1050000
+        kwargs: dict[str, Any] = {}
+        self.provider._apply_model_params(kwargs, caps, temperature=0.7, reasoning_effort="low")
+        assert "temperature" not in kwargs
+        assert kwargs["reasoning_effort"] == "medium"  # fell back from unsupported "low"
+

 class TestAnthropicReasoningNone:
    """Verify 'none' effort disables thinking for manual-thinking models."""
@@ -0,0 +1,97 @@
+"""Tests for the atomic workstream resumption flow.
+
+Covers CreateWorkstreamMessage resume_ws field, WorkstreamResumedEvent,
+WorkstreamCreatedEvent resumed fields, and server endpoint handling.
+"""
+
+from __future__ import annotations
+
+import json
+
+from turnstone.mq.protocol import (
+    CreateWorkstreamMessage,
+    WorkstreamCreatedEvent,
+    WorkstreamResumedEvent,
+)
+
+# ---------------------------------------------------------------------------
+# Protocol tests
+# ---------------------------------------------------------------------------
+
+
+class TestCreateWorkstreamMessageResumeField:
+    def test_resume_ws_defaults_empty(self) -> None:
+        msg = CreateWorkstreamMessage(name="test")
+        assert msg.resume_ws == ""
+
+    def test_resume_ws_set(self) -> None:
+        msg = CreateWorkstreamMessage(name="test", resume_ws="ws-abc")
+        assert msg.resume_ws == "ws-abc"
+
+    def test_resume_ws_serializes(self) -> None:
+        msg = CreateWorkstreamMessage(resume_ws="ws-xyz")
+        data = json.loads(msg.to_json())
+        assert data["resume_ws"] == "ws-xyz"
+
+    def test_resume_ws_deserializes(self) -> None:
+        msg = CreateWorkstreamMessage(resume_ws="ws-123")
+        raw = msg.to_json()
+        from turnstone.mq.protocol import InboundMessage
+
+        restored = InboundMessage.from_json(raw)
+        assert getattr(restored, "resume_ws", "") == "ws-123"
+
+
+class TestWorkstreamCreatedEventResumeFields:
+    def test_default_not_resumed(self) -> None:
+        event = WorkstreamCreatedEvent(ws_id="ws-1", name="test")
+        assert event.resumed is False
+        assert event.message_count == 0
+
+    def test_resumed_fields(self) -> None:
+        event = WorkstreamCreatedEvent(ws_id="ws-1", name="test", resumed=True, message_count=42)
+        assert event.resumed is True
+        assert event.message_count == 42
+
+    def test_serializes_resumed_fields(self) -> None:
+        event = WorkstreamCreatedEvent(ws_id="ws-1", resumed=True, message_count=10)
+        data = json.loads(event.to_json())
+        assert data["resumed"] is True
+        assert data["message_count"] == 10
+
+    def test_deserializes_resumed_fields(self) -> None:
+        event = WorkstreamCreatedEvent(ws_id="ws-1", resumed=True, message_count=5)
+        from turnstone.mq.protocol import OutboundEvent
+
+        restored = OutboundEvent.from_json(event.to_json())
+        assert isinstance(restored, WorkstreamCreatedEvent)
+        assert restored.resumed is True
+        assert restored.message_count == 5
+
+
+class TestWorkstreamResumedEvent:
+    def test_defaults(self) -> None:
+        event = WorkstreamResumedEvent(ws_id="ws-1")
+        assert event.type == "ws_resumed"
+        assert event.message_count == 0
+        assert event.name == ""
+
+    def test_with_values(self) -> None:
+        event = WorkstreamResumedEvent(ws_id="ws-1", message_count=25, name="My Chat")
+        assert event.message_count == 25
+        assert event.name == "My Chat"
+
+    def test_round_trip(self) -> None:
+        event = WorkstreamResumedEvent(ws_id="ws-1", message_count=10, name="Chat")
+        from turnstone.mq.protocol import OutboundEvent
+
+        restored = OutboundEvent.from_json(event.to_json())
+        assert isinstance(restored, WorkstreamResumedEvent)
+        assert restored.message_count == 10
+        assert restored.name == "Chat"
+
+    def test_registered_in_outbound_registry(self) -> None:
+        from turnstone.mq.protocol import _OUTBOUND_REGISTRY
+
+        assert "ws_resumed" in _OUTBOUND_REGISTRY
+        assert _OUTBOUND_REGISTRY["ws_resumed"] is WorkstreamResumedEvent
@@ -0,0 +1,264 @@
+"""Tests for scheduled task admin API endpoints."""
+
+from __future__ import annotations
+
+import pytest
+from starlette.applications import Starlette
+from starlette.routing import Mount, Route
+from starlette.testclient import TestClient
+
+from turnstone.console.server import (
+    admin_create_schedule,
+    admin_delete_schedule,
+    admin_get_schedule,
+    admin_list_schedule_runs,
+    admin_list_schedules,
+    admin_update_schedule,
+)
+from turnstone.core.storage._sqlite import SQLiteBackend
+
+
+@pytest.fixture
+def storage(tmp_path):
+    """Fresh SQLite backend for each test."""
+    return SQLiteBackend(str(tmp_path / "test.db"))
+
+
+@pytest.fixture
+def client(storage):
+    """TestClient with storage and auth bypassed."""
+    app = Starlette(
+        routes=[
+            Mount(
+                "/v1",
+                routes=[
+                    Route("/api/admin/schedules", admin_list_schedules),
+                    Route("/api/admin/schedules", admin_create_schedule, methods=["POST"]),
+                    Route("/api/admin/schedules/{task_id}", admin_get_schedule),
+                    Route(
+                        "/api/admin/schedules/{task_id}",
+                        admin_update_schedule,
+                        methods=["PUT"],
+                    ),
+                    Route(
+                        "/api/admin/schedules/{task_id}",
+                        admin_delete_schedule,
+                        methods=["DELETE"],
+                    ),
+                    Route(
+                        "/api/admin/schedules/{task_id}/runs",
+                        admin_list_schedule_runs,
+                    ),
+                ],
+            ),
+        ],
+    )
+    app.state.auth_storage = storage
+    return TestClient(app)
+
+
+def _cron_payload(**overrides):
+    """Build default cron schedule creation payload."""
+    defaults = {
+        "name": "Daily report",
+        "description": "Generate the summary",
+        "schedule_type": "cron",
+        "cron_expr": "0 9 * * *",
+        "target_mode": "auto",
+        "model": "gpt-5",
+        "initial_message": "Generate the daily report",
+    }
+    defaults.update(overrides)
+    return defaults
+
+
+def _at_payload(**overrides):
+    """Build default at-time schedule creation payload."""
+    defaults = {
+        "name": "One-shot task",
+        "description": "Run once",
+        "schedule_type": "at",
+        "at_time": "2099-01-01T00:00:00+00:00",
+        "target_mode": "auto",
+        "model": "gpt-5",
+        "initial_message": "Do the thing",
+    }
+    defaults.update(overrides)
+    return defaults
+
+
+class TestScheduleAPI:
+    """Tests for the 6 admin schedule endpoints."""
+
+    def test_list_empty(self, client):
+        resp = client.get("/v1/api/admin/schedules")
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["schedules"] == []
+
+    def test_create_cron(self, client):
+        resp = client.post("/v1/api/admin/schedules", json=_cron_payload())
+        assert resp.status_code == 200
+        task = resp.json()
+        assert task["name"] == "Daily report"
+        assert task["schedule_type"] == "cron"
+        assert task["cron_expr"] == "0 9 * * *"
+        assert task["enabled"] is True
+        assert "task_id" in task
+        assert "created" in task
+        assert "next_run" in task
+        assert task["next_run"] != ""
+
+    def test_create_at(self, client):
+        resp = client.post("/v1/api/admin/schedules", json=_at_payload())
+        assert resp.status_code == 200
+        task = resp.json()
+        assert task["schedule_type"] == "at"
+        assert task["at_time"] == "2099-01-01T00:00:00+00:00"
+        assert task["next_run"] == "2099-01-01T00:00:00+00:00"
+
+    def test_create_missing_name(self, client):
+        payload = _cron_payload()
+        del payload["name"]
+        resp = client.post("/v1/api/admin/schedules", json=payload)
+        assert resp.status_code == 400
+        assert "name" in resp.json()["error"].lower()
+
+    def test_create_invalid_cron(self, client):
+        resp = client.post(
+            "/v1/api/admin/schedules",
+            json=_cron_payload(cron_expr="not a cron"),
+        )
+        assert resp.status_code == 400
+        assert "cron" in resp.json()["error"].lower()
+
+    def test_create_naive_at_time(self, client):
+        """Naive timestamps (no timezone) should be rejected."""
+        resp = client.post(
+            "/v1/api/admin/schedules",
+            json=_at_payload(at_time="2099-01-01T00:00:00"),
+        )
+        assert resp.status_code == 400
+        assert "timezone" in resp.json()["error"].lower()
+
+    def test_create_past_at_time(self, client):
+        resp = client.post(
+            "/v1/api/admin/schedules",
+            json=_at_payload(at_time="2000-01-01T00:00:00+00:00"),
+        )
+        assert resp.status_code == 400
+        assert "future" in resp.json()["error"].lower()
+
+    def test_get_schedule(self, client):
+        create_resp = client.post("/v1/api/admin/schedules", json=_cron_payload())
+        task_id = create_resp.json()["task_id"]
+
+        resp = client.get(f"/v1/api/admin/schedules/{task_id}")
+        assert resp.status_code == 200
+        assert resp.json()["task_id"] == task_id
+        assert resp.json()["name"] == "Daily report"
+
+    def test_get_nonexistent(self, client):
+        resp = client.get("/v1/api/admin/schedules/nonexistent_id")
+        assert resp.status_code == 404
+
+    def test_update_schedule(self, client):
+        create_resp = client.post("/v1/api/admin/schedules", json=_cron_payload())
+        task_id = create_resp.json()["task_id"]
+
+        resp = client.put(
+            f"/v1/api/admin/schedules/{task_id}",
+            json={"name": "Weekly report"},
+        )
+        assert resp.status_code == 200
+        assert resp.json()["name"] == "Weekly report"
+
+        # Verify via GET
+        get_resp = client.get(f"/v1/api/admin/schedules/{task_id}")
+        assert get_resp.json()["name"] == "Weekly report"
+
+    def test_update_nonexistent(self, client):
+        resp = client.put(
+            "/v1/api/admin/schedules/nonexistent_id",
+            json={"name": "Nope"},
+        )
+        assert resp.status_code == 404
+
+    def test_delete_schedule(self, client):
+        create_resp = client.post("/v1/api/admin/schedules", json=_cron_payload())
+        task_id = create_resp.json()["task_id"]
+
+        resp = client.delete(f"/v1/api/admin/schedules/{task_id}")
+        assert resp.status_code == 200
+        assert resp.json()["status"] == "ok"
+
+        # Verify gone
+        get_resp = client.get(f"/v1/api/admin/schedules/{task_id}")
+        assert get_resp.status_code == 404
+
+    def test_delete_nonexistent(self, client):
+        resp = client.delete("/v1/api/admin/schedules/nonexistent_id")
+        assert resp.status_code == 404
+
+    def test_list_runs_empty(self, client):
+        create_resp = client.post("/v1/api/admin/schedules", json=_cron_payload())
+        task_id = create_resp.json()["task_id"]
+
+        resp = client.get(f"/v1/api/admin/schedules/{task_id}/runs")
+        assert resp.status_code == 200
+        assert resp.json()["runs"] == []
+
+    def test_list_runs_nonexistent(self, client):
+        resp = client.get("/v1/api/admin/schedules/nonexistent_id/runs")
+        assert resp.status_code == 404
+
+    def test_create_specific_node_target(self, client):
+        payload = _cron_payload(target_mode="node-custom-001")
+        resp = client.post("/v1/api/admin/schedules", json=payload)
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["target_mode"] == "node-custom-001"
+
+    def test_list_runs_with_data(self, client, storage):
+        create_resp = client.post("/v1/api/admin/schedules", json=_cron_payload())
+        task_id = create_resp.json()["task_id"]
+
+        # Record runs directly in storage
+        storage.record_task_run(
+            run_id="run_001",
+            task_id=task_id,
+            node_id="node-1",
+            ws_id="ws_abc",
+            correlation_id="corr_001",
+            started="2025-06-01T09:00:00",
+            status="dispatched",
+            error="",
+        )
+        storage.record_task_run(
+            run_id="run_002",
+            task_id=task_id,
+            node_id="node-2",
+            ws_id="",
+            correlation_id="corr_002",
+            started="2025-06-01T09:01:00",
+            status="failed",
+            error="No reachable nodes",
+        )
+
+        resp = client.get(f"/v1/api/admin/schedules/{task_id}/runs")
+        assert resp.status_code == 200
+        runs = resp.json()["runs"]
+        assert len(runs) == 2
+        # Most recent first
+        assert runs[0]["run_id"] == "run_002"
+        assert runs[0]["status"] == "failed"
+        assert runs[1]["run_id"] == "run_001"
+
+    def test_list_runs_invalid_limit(self, client):
+        create_resp = client.post("/v1/api/admin/schedules", json=_cron_payload())
+        task_id = create_resp.json()["task_id"]
+
+        # Invalid limit should not crash — falls back to 50
+        resp = client.get(f"/v1/api/admin/schedules/{task_id}/runs?limit=abc")
+        assert resp.status_code == 200
+        assert resp.json()["runs"] == []
@@ -0,0 +1,259 @@
+"""Tests for scheduled_tasks and scheduled_task_runs storage CRUD."""
+
+from __future__ import annotations
+
+import time
+
+import pytest
+
+from turnstone.core.storage._sqlite import SQLiteBackend
+
+
+@pytest.fixture
+def db(tmp_path):
+    """Fresh SQLite backend for each test."""
+    backend = SQLiteBackend(str(tmp_path / "test.db"))
+    return backend
+
+
+def _make_task_kwargs(**overrides):
+    """Build default kwargs for create_scheduled_task."""
+    defaults = {
+        "task_id": "task_001",
+        "name": "Daily report",
+        "description": "Generate the daily summary",
+        "schedule_type": "cron",
+        "cron_expr": "0 9 * * *",
+        "at_time": "",
+        "target_mode": "auto",
+        "model": "gpt-5",
+        "initial_message": "Generate the daily report",
+        "auto_approve": False,
+        "auto_approve_tools": [],
+        "created_by": "u_admin",
+        "next_run": "2099-01-01T09:00:00",
+    }
+    defaults.update(overrides)
+    return defaults
+
+
+class TestScheduledTaskCRUD:
+    """Tests for scheduled_tasks table operations."""
+
+    def test_create_and_get(self, db):
+        db.create_scheduled_task(**_make_task_kwargs())
+        result = db.get_scheduled_task("task_001")
+        assert result is not None
+        assert result["task_id"] == "task_001"
+        assert result["name"] == "Daily report"
+        assert result["description"] == "Generate the daily summary"
+        assert result["schedule_type"] == "cron"
+        assert result["cron_expr"] == "0 9 * * *"
+        assert result["at_time"] == ""
+        assert result["target_mode"] == "auto"
+        assert result["model"] == "gpt-5"
+        assert result["initial_message"] == "Generate the daily report"
+        assert result["auto_approve"] == 0
+        assert result["auto_approve_tools"] == ""
+        assert result["enabled"] == 1
+        assert result["created_by"] == "u_admin"
+        assert result["next_run"] == "2099-01-01T09:00:00"
+        assert "created" in result
+        assert "updated" in result
+
+    def test_get_nonexistent(self, db):
+        assert db.get_scheduled_task("no_such_task") is None
+
+    def test_create_duplicate_noop(self, db):
+        db.create_scheduled_task(**_make_task_kwargs(name="First"))
+        db.create_scheduled_task(**_make_task_kwargs(name="Second"))
+        result = db.get_scheduled_task("task_001")
+        assert result is not None
+        assert result["name"] == "First"  # first write wins
+
+    def test_list_tasks(self, db):
+        db.create_scheduled_task(**_make_task_kwargs(task_id="task_a", name="Alpha"))
+        # Ensure different created timestamps (resolution is 1 second)
+        time.sleep(1.1)
+        db.create_scheduled_task(**_make_task_kwargs(task_id="task_b", name="Beta"))
+        tasks = db.list_scheduled_tasks()
+        assert len(tasks) == 2
+        # Ordered by created DESC — most recent first
+        assert tasks[0]["task_id"] == "task_b"
+        assert tasks[1]["task_id"] == "task_a"
+
+    def test_update_task(self, db):
+        db.create_scheduled_task(**_make_task_kwargs())
+        original = db.get_scheduled_task("task_001")
+        assert original is not None
+        original_updated = original["updated"]
+
+        time.sleep(0.05)
+        result = db.update_scheduled_task("task_001", name="Weekly report")
+        assert result is True
+
+        updated = db.get_scheduled_task("task_001")
+        assert updated is not None
+        assert updated["name"] == "Weekly report"
+        assert updated["updated"] >= original_updated
+
+    def test_update_enable_disable(self, db):
+        db.create_scheduled_task(**_make_task_kwargs())
+        task = db.get_scheduled_task("task_001")
+        assert task is not None
+        assert task["enabled"] == 1
+
+        db.update_scheduled_task("task_001", enabled=False)
+        task = db.get_scheduled_task("task_001")
+        assert task is not None
+        assert task["enabled"] == 0
+
+        db.update_scheduled_task("task_001", enabled=True)
+        task = db.get_scheduled_task("task_001")
+        assert task is not None
+        assert task["enabled"] == 1
+
+    def test_delete_task(self, db):
+        db.create_scheduled_task(**_make_task_kwargs())
+        assert db.delete_scheduled_task("task_001") is True
+        assert db.get_scheduled_task("task_001") is None
+        # Deleting again returns False
+        assert db.delete_scheduled_task("task_001") is False
+
+    def test_delete_cascades_runs(self, db):
+        db.create_scheduled_task(**_make_task_kwargs())
+        db.record_task_run(
+            run_id="run_001",
+            task_id="task_001",
+            node_id="node_1",
+            ws_id="ws_abc",
+            correlation_id="corr_001",
+            started="2025-01-01T09:00:00",
+            status="dispatched",
+            error="",
+        )
+        assert len(db.list_task_runs("task_001")) == 1
+
+        db.delete_scheduled_task("task_001")
+        assert db.list_task_runs("task_001") == []
+
+    def test_list_due_tasks(self, db):
+        db.create_scheduled_task(
+            **_make_task_kwargs(task_id="past", next_run="2020-01-01T00:00:00")
+        )
+        db.create_scheduled_task(
+            **_make_task_kwargs(task_id="future", next_run="2099-12-31T23:59:59")
+        )
+        now = "2025-06-01T12:00:00"
+        due = db.list_due_tasks(now)
+        assert len(due) == 1
+        assert due[0]["task_id"] == "past"
+
+    def test_list_due_tasks_skips_disabled(self, db):
+        db.create_scheduled_task(
+            **_make_task_kwargs(task_id="disabled_task", next_run="2020-01-01T00:00:00")
+        )
+        db.update_scheduled_task("disabled_task", enabled=False)
+        due = db.list_due_tasks("2025-06-01T12:00:00")
+        assert len(due) == 0
+
+    def test_list_due_tasks_empty_next_run(self, db):
+        db.create_scheduled_task(**_make_task_kwargs(task_id="empty_next", next_run=""))
+        due = db.list_due_tasks("2099-12-31T23:59:59")
+        assert len(due) == 0
+
+    def test_at_task_fields(self, db):
+        db.create_scheduled_task(
+            **_make_task_kwargs(
+                task_id="at_task",
+                schedule_type="at",
+                cron_expr="",
+                at_time="2099-06-15T14:00:00",
+                next_run="2099-06-15T14:00:00",
+            )
+        )
+        result = db.get_scheduled_task("at_task")
+        assert result is not None
+        assert result["schedule_type"] == "at"
+        assert result["at_time"] == "2099-06-15T14:00:00"
+
+
+class TestScheduledTaskRuns:
+    """Tests for scheduled_task_runs table operations."""
+
+    def test_record_and_list(self, db):
+        db.create_scheduled_task(**_make_task_kwargs())
+        db.record_task_run(
+            run_id="run_a",
+            task_id="task_001",
+            node_id="node_1",
+            ws_id="ws_1",
+            correlation_id="corr_a",
+            started="2025-01-01T09:00:00",
+            status="dispatched",
+            error="",
+        )
+        db.record_task_run(
+            run_id="run_b",
+            task_id="task_001",
+            node_id="node_2",
+            ws_id="ws_2",
+            correlation_id="corr_b",
+            started="2025-01-02T09:00:00",
+            status="dispatched",
+            error="",
+        )
+        runs = db.list_task_runs("task_001")
+        assert len(runs) == 2
+        # Ordered by started DESC — most recent first
+        assert runs[0]["run_id"] == "run_b"
+        assert runs[1]["run_id"] == "run_a"
+
+    def test_list_runs_respects_limit(self, db):
+        db.create_scheduled_task(**_make_task_kwargs())
+        for i in range(3):
+            db.record_task_run(
+                run_id=f"run_{i}",
+                task_id="task_001",
+                node_id="node_1",
+                ws_id="",
+                correlation_id=f"corr_{i}",
+                started=f"2025-01-0{i + 1}T09:00:00",
+                status="dispatched",
+                error="",
+            )
+        runs = db.list_task_runs("task_001", limit=2)
+        assert len(runs) == 2
+
+    def test_list_runs_empty(self, db):
+        assert db.list_task_runs("no_such_task") == []
+
+    def test_prune_task_runs(self, db):
+        db.create_scheduled_task(**_make_task_kwargs())
+        # Old run (should be pruned)
+        db.record_task_run(
+            run_id="old_run",
+            task_id="task_001",
+            node_id="node_1",
+            ws_id="",
+            correlation_id="c_old",
+            started="2020-01-01T00:00:00",
+            status="dispatched",
+            error="",
+        )
+        # Recent run (should survive)
+        db.record_task_run(
+            run_id="new_run",
+            task_id="task_001",
+            node_id="node_1",
+            ws_id="",
+            correlation_id="c_new",
+            started="2099-01-01T00:00:00",
+            status="dispatched",
+            error="",
+        )
+        pruned = db.prune_task_runs(retention_days=90)
+        assert pruned == 1
+        runs = db.list_task_runs("task_001")
+        assert len(runs) == 1
+        assert runs[0]["run_id"] == "new_run"
@@ -0,0 +1,272 @@
+"""Tests for turnstone.console.scheduler — TaskScheduler tick and dispatch."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock
+
+import pytest
+
+from turnstone.console.scheduler import TaskScheduler
+
+
+@pytest.fixture
+def mocks():
+    """Broker, collector, and storage mocks for scheduler tests."""
+    broker = MagicMock()
+    broker._redis = MagicMock()
+    collector = MagicMock()
+    storage = MagicMock()
+    return broker, collector, storage
+
+
+def _make_task(**overrides):
+    """Build a minimal task dict matching storage row format."""
+    defaults = {
+        "task_id": "task_001",
+        "name": "Test task",
+        "description": "",
+        "schedule_type": "cron",
+        "cron_expr": "0 9 * * *",
+        "at_time": "",
+        "target_mode": "auto",
+        "model": "gpt-5",
+        "initial_message": "Run the tests",
+        "auto_approve": 0,
+        "auto_approve_tools": "",
+        "enabled": 1,
+        "created_by": "u_admin",
+        "next_run": "2020-01-01T09:00:00",
+        "last_run": "",
+        "created": "2020-01-01T00:00:00",
+        "updated": "2020-01-01T00:00:00",
+    }
+    defaults.update(overrides)
+    return defaults
+
+
+def _make_node(node_id="node-001", reachable=True, ws_total=2, max_ws=10):
+    """Build a minimal node dict matching collector output."""
+    return {
+        "node_id": node_id,
+        "reachable": reachable,
+        "ws_total": ws_total,
+        "max_ws": max_ws,
+    }
+
+
+class TestSchedulerTick:
+    """Tests for _tick() lock acquisition and dispatch logic."""
+
+    def test_tick_acquires_lock(self, mocks):
+        broker, collector, storage = mocks
+        broker._redis.set.return_value = True
+        storage.list_due_tasks.return_value = []
+
+        scheduler = TaskScheduler(broker, collector, storage)
+        scheduler._tick()
+
+        broker._redis.set.assert_called_once()
+        storage.list_due_tasks.assert_called_once()
+        # Lock released via Lua eval (conditional delete)
+        broker._redis.eval.assert_called_once()
+
+    def test_tick_skips_when_locked(self, mocks):
+        broker, collector, storage = mocks
+        broker._redis.set.return_value = None  # lock held by another console
+
+        scheduler = TaskScheduler(broker, collector, storage)
+        scheduler._tick()
+
+        storage.list_due_tasks.assert_not_called()
+
+    def test_dispatch_auto_mode(self, mocks):
+        broker, collector, storage = mocks
+        broker._redis.set.return_value = True
+
+        task = _make_task(target_mode="auto")
+        storage.list_due_tasks.return_value = [task]
+        collector.get_nodes.return_value = ([_make_node()], 1)
+
+        scheduler = TaskScheduler(broker, collector, storage)
+        scheduler._tick()
+
+        broker.push_inbound.assert_called_once()
+        _, kwargs = broker.push_inbound.call_args
+        assert (
+            kwargs.get("node_id") == "node-001"
+            or broker.push_inbound.call_args[1].get("node_id") == "node-001"
+        )
+        storage.record_task_run.assert_called_once()
+        run_kwargs = storage.record_task_run.call_args[1]
+        assert run_kwargs["node_id"] == "node-001"
+        assert run_kwargs["status"] == "dispatched"
+
+    def test_dispatch_pool_mode(self, mocks):
+        broker, collector, storage = mocks
+        broker._redis.set.return_value = True
+
+        task = _make_task(target_mode="pool")
+        storage.list_due_tasks.return_value = [task]
+
+        scheduler = TaskScheduler(broker, collector, storage)
+        scheduler._tick()
+
+        broker.push_inbound.assert_called_once()
+        # Pool dispatch calls push_inbound without node_id kwarg
+        args, kwargs = broker.push_inbound.call_args
+        assert kwargs.get("node_id") is None or "node_id" not in kwargs
+        storage.record_task_run.assert_called_once()
+        run_kwargs = storage.record_task_run.call_args[1]
+        assert run_kwargs["node_id"] == "pool"
+
+    def test_dispatch_all_mode(self, mocks):
+        broker, collector, storage = mocks
+        broker._redis.set.return_value = True
+
+        task = _make_task(target_mode="all")
+        storage.list_due_tasks.return_value = [task]
+        collector.get_nodes.return_value = (
+            [_make_node("node-001"), _make_node("node-002")],
+            2,
+        )
+
+        scheduler = TaskScheduler(broker, collector, storage)
+        scheduler._tick()
+
+        assert broker.push_inbound.call_count == 2
+        assert storage.record_task_run.call_count == 2
+
+    def test_dispatch_specific_node(self, mocks):
+        broker, collector, storage = mocks
+        broker._redis.set.return_value = True
+
+        task = _make_task(target_mode="node-001")
+        storage.list_due_tasks.return_value = [task]
+
+        scheduler = TaskScheduler(broker, collector, storage)
+        scheduler._tick()
+
+        broker.push_inbound.assert_called_once()
+        _, kwargs = broker.push_inbound.call_args
+        assert kwargs["node_id"] == "node-001"
+
+    def test_at_task_disables_after_dispatch(self, mocks):
+        broker, collector, storage = mocks
+        broker._redis.set.return_value = True
+
+        task = _make_task(schedule_type="at", cron_expr="", at_time="2099-01-01T00:00:00")
+        storage.list_due_tasks.return_value = [task]
+        collector.get_nodes.return_value = ([_make_node()], 1)
+
+        scheduler = TaskScheduler(broker, collector, storage)
+        scheduler._tick()
+
+        # At-task should be disabled after dispatch
+        update_calls = storage.update_scheduled_task.call_args_list
+        assert len(update_calls) == 1
+        args, kwargs = update_calls[0]
+        assert args[0] == "task_001"
+        assert kwargs["enabled"] is False
+        assert kwargs["next_run"] == ""
+
+    def test_cron_task_updates_next_run(self, mocks):
+        broker, collector, storage = mocks
+        broker._redis.set.return_value = True
+
+        task = _make_task(schedule_type="cron", cron_expr="0 9 * * *")
+        storage.list_due_tasks.return_value = [task]
+        collector.get_nodes.return_value = ([_make_node()], 1)
+
+        scheduler = TaskScheduler(broker, collector, storage)
+        scheduler._tick()
+
+        update_calls = storage.update_scheduled_task.call_args_list
+        assert len(update_calls) == 1
+        _, kwargs = update_calls[0]
+        assert kwargs["next_run"] != ""
+        assert "enabled" not in kwargs  # cron tasks stay enabled
+
+    def test_no_reachable_nodes_records_failure(self, mocks):
+        broker, collector, storage = mocks
+        broker._redis.set.return_value = True
+
+        task = _make_task(target_mode="auto")
+        storage.list_due_tasks.return_value = [task]
+        # No reachable nodes
+        collector.get_nodes.return_value = (
+            [_make_node("node-001", reachable=False)],
+            1,
+        )
+
+        scheduler = TaskScheduler(broker, collector, storage)
+        scheduler._tick()
+
+        broker.push_inbound.assert_not_called()
+        storage.record_task_run.assert_called_once()
+        run_kwargs = storage.record_task_run.call_args[1]
+        assert run_kwargs["status"] == "failed"
+        assert run_kwargs["error"] != ""
+
+    def test_failure_does_not_advance_schedule(self, mocks):
+        """When dispatch fails, last_run/next_run should not be updated."""
+        broker, collector, storage = mocks
+        broker._redis.set.return_value = True
+
+        task = _make_task(target_mode="auto")
+        storage.list_due_tasks.return_value = [task]
+        collector.get_nodes.return_value = ([], 0)  # no nodes at all
+
+        scheduler = TaskScheduler(broker, collector, storage)
+        scheduler._tick()
+
+        # update_scheduled_task should NOT be called (no last_run/next_run advance)
+        storage.update_scheduled_task.assert_not_called()
+
+    def test_fan_out_capped(self, mocks):
+        """Fan-out 'all' mode should respect max_fan_out limit."""
+        broker, collector, storage = mocks
+        broker._redis.set.return_value = True
+
+        task = _make_task(target_mode="all")
+        storage.list_due_tasks.return_value = [task]
+        # 10 reachable nodes but max_fan_out=3
+        nodes = [_make_node(f"node-{i:03d}") for i in range(10)]
+        collector.get_nodes.return_value = (nodes, 10)
+
+        scheduler = TaskScheduler(broker, collector, storage, max_fan_out=3)
+        scheduler._tick()
+
+        assert broker.push_inbound.call_count == 3
+        assert storage.record_task_run.call_count == 3
+
+    def test_specific_node_target(self, mocks):
+        """Non-enum target_mode is treated as a specific node_id."""
+        broker, collector, storage = mocks
+        broker._redis.set.return_value = True
+
+        task = _make_task(target_mode="node-custom-123")
+        storage.list_due_tasks.return_value = [task]
+
+        scheduler = TaskScheduler(broker, collector, storage)
+        scheduler._tick()
+
+        broker.push_inbound.assert_called_once()
+        call_kwargs = broker.push_inbound.call_args
+        assert call_kwargs[1]["node_id"] == "node-custom-123"
+
+    def test_user_id_in_dispatched_message(self, mocks):
+        """Dispatched message should include created_by as user_id."""
+        import json
+
+        broker, collector, storage = mocks
+        broker._redis.set.return_value = True
+
+        task = _make_task(target_mode="pool", created_by="u_scheduler_admin")
+        storage.list_due_tasks.return_value = [task]
+
+        scheduler = TaskScheduler(broker, collector, storage)
+        scheduler._tick()
+
+        msg_json = broker.push_inbound.call_args[0][0]
+        msg_data = json.loads(msg_json)
+        assert msg_data["user_id"] == "u_scheduler_admin"
@@ -2,6 +2,8 @@

 from __future__ import annotations

+import json
+
 import httpx
 import pytest

@@ -240,3 +242,140 @@ async def test_query_params_passed():
        assert "state=running" in captured_url[0]
        assert "page=2" in captured_url[0]
        assert "per_page=25" in captured_url[0]
+
+
+# ---------------------------------------------------------------------------
+# Schedules
+# ---------------------------------------------------------------------------
+
+_SCHEDULE_FIXTURE = {
+    "task_id": "t1",
+    "name": "nightly",
+    "description": "",
+    "schedule_type": "cron",
+    "cron_expr": "0 2 * * *",
+    "at_time": "",
+    "target_mode": "auto",
+    "model": "",
+    "initial_message": "Run nightly checks",
+    "auto_approve": False,
+    "auto_approve_tools": [],
+    "enabled": True,
+    "created_by": "u1",
+    "last_run": None,
+    "next_run": "2026-03-06T02:00:00Z",
+    "created": "2026-03-05T12:00:00Z",
+    "updated": "2026-03-05T12:00:00Z",
+}
+
+
+@pytest.mark.anyio
+async def test_list_schedules():
+    transport = _mock_transport(
+        {"GET /v1/api/admin/schedules": _json_response({"schedules": [_SCHEDULE_FIXTURE]})}
+    )
+    async with httpx.AsyncClient(transport=transport, base_url="http://test") as hc:
+        client = AsyncTurnstoneConsole(httpx_client=hc)
+        resp = await client.list_schedules()
+        assert len(resp.schedules) == 1
+        assert resp.schedules[0].task_id == "t1"
+        assert resp.schedules[0].name == "nightly"
+
+
+@pytest.mark.anyio
+async def test_create_schedule():
+    captured_body: list[dict] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured_body.append(json.loads(request.content))
+        return _json_response(_SCHEDULE_FIXTURE)
+
+    transport = httpx.MockTransport(handler)
+    async with httpx.AsyncClient(transport=transport, base_url="http://test") as hc:
+        client = AsyncTurnstoneConsole(httpx_client=hc)
+        resp = await client.create_schedule(
+            name="nightly",
+            schedule_type="cron",
+            initial_message="Run nightly checks",
+            cron_expr="0 2 * * *",
+        )
+        assert resp.task_id == "t1"
+        body = captured_body[0]
+        assert body["name"] == "nightly"
+        assert body["schedule_type"] == "cron"
+        assert body["cron_expr"] == "0 2 * * *"
+        assert body["initial_message"] == "Run nightly checks"
+        # Optional fields with defaults should not appear when not set
+        assert "description" not in body
+        assert "model" not in body
+
+
+@pytest.mark.anyio
+async def test_get_schedule():
+    transport = _mock_transport(
+        {"GET /v1/api/admin/schedules/t1": _json_response(_SCHEDULE_FIXTURE)}
+    )
+    async with httpx.AsyncClient(transport=transport, base_url="http://test") as hc:
+        client = AsyncTurnstoneConsole(httpx_client=hc)
+        resp = await client.get_schedule("t1")
+        assert resp.task_id == "t1"
+        assert resp.schedule_type == "cron"
+
+
+@pytest.mark.anyio
+async def test_update_schedule_partial():
+    """Only explicitly-passed fields should appear in the request body."""
+    captured_body: list[dict] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured_body.append(json.loads(request.content))
+        return _json_response({**_SCHEDULE_FIXTURE, "enabled": False})
+
+    transport = httpx.MockTransport(handler)
+    async with httpx.AsyncClient(transport=transport, base_url="http://test") as hc:
+        client = AsyncTurnstoneConsole(httpx_client=hc)
+        resp = await client.update_schedule("t1", enabled=False)
+        assert resp.enabled is False
+        body = captured_body[0]
+        assert body == {"enabled": False}
+
+
+@pytest.mark.anyio
+async def test_delete_schedule():
+    transport = _mock_transport(
+        {"DELETE /v1/api/admin/schedules/t1": _json_response({"status": "ok"})}
+    )
+    async with httpx.AsyncClient(transport=transport, base_url="http://test") as hc:
+        client = AsyncTurnstoneConsole(httpx_client=hc)
+        resp = await client.delete_schedule("t1")
+        assert resp.status == "ok"
+
+
+@pytest.mark.anyio
+async def test_list_schedule_runs():
+    transport = _mock_transport(
+        {
+            "GET /v1/api/admin/schedules/t1/runs": _json_response(
+                {
+                    "runs": [
+                        {
+                            "run_id": "r1",
+                            "task_id": "t1",
+                            "node_id": "n1",
+                            "ws_id": "ws1",
+                            "correlation_id": "c1",
+                            "started": "2026-03-05T02:00:00Z",
+                            "status": "dispatched",
+                            "error": "",
+                        }
+                    ]
+                }
+            )
+        }
+    )
+    async with httpx.AsyncClient(transport=transport, base_url="http://test") as hc:
+        client = AsyncTurnstoneConsole(httpx_client=hc)
+        resp = await client.list_schedule_runs("t1", limit=10)
+        assert len(resp.runs) == 1
+        assert resp.runs[0].run_id == "r1"
+        assert resp.runs[0].status == "dispatched"
@@ -148,19 +148,19 @@ async def test_command():


 # ---------------------------------------------------------------------------
-# Sessions
+# History
 # ---------------------------------------------------------------------------


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


 # ---------------------------------------------------------------------------
@@ -49,6 +49,21 @@ def test_sync_runner_iter():
        runner.close()


+def test_sync_runner_iter_empty():
+    """_SyncRunner.run_iter handles empty async generator via sentinel."""
+    runner = _SyncRunner()
+    try:
+
+        async def _empty():
+            return
+            yield  # pragma: no cover  # makes this an async generator
+
+        items = list(runner.run_iter(_empty()))
+        assert items == []
+    finally:
+        runner.close()
+
+
 # ---------------------------------------------------------------------------
 # TurnstoneServer (sync)
 # ---------------------------------------------------------------------------
@@ -609,7 +609,7 @@ class TestServerHealthMetrics:
        mock_ui._ws_context_ratio = 0.0

        mock_session = MagicMock()
-        mock_session.session_id = "test-session-id"
+        mock_session.ws_id = "test-session-id"

        mock_ws = MagicMock()
        mock_ws.id = "test-ws"
@@ -785,7 +785,7 @@ class TestServerRateLimiting:
        mock_ui._ws_context_ratio = 0.0

        mock_session = MagicMock()
-        mock_session.session_id = "test-session-id"
+        mock_session.ws_id = "test-session-id"

        mock_ws = MagicMock()
        mock_ws.id = "test-ws"
@@ -0,0 +1,86 @@
+"""Tests for the services registry storage methods."""
+
+from __future__ import annotations
+
+import pytest
+
+from turnstone.core.storage._sqlite import SQLiteBackend
+
+
+@pytest.fixture
+def storage(tmp_path):
+    return SQLiteBackend(str(tmp_path / "test.db"))
+
+
+class TestServiceRegistry:
+    def test_register_and_list(self, storage):
+        storage.register_service("channel", "ch-1", "http://localhost:8091")
+        services = storage.list_services("channel", max_age_seconds=120)
+        assert len(services) == 1
+        assert services[0]["service_type"] == "channel"
+        assert services[0]["service_id"] == "ch-1"
+        assert services[0]["url"] == "http://localhost:8091"
+
+    def test_register_upsert(self, storage):
+        storage.register_service("channel", "ch-1", "http://old:8091")
+        storage.register_service("channel", "ch-1", "http://new:8091")
+        services = storage.list_services("channel", max_age_seconds=120)
+        assert len(services) == 1
+        assert services[0]["url"] == "http://new:8091"
+
+    def test_heartbeat(self, storage):
+        storage.register_service("channel", "ch-1", "http://localhost:8091")
+        result = storage.heartbeat_service("channel", "ch-1")
+        assert result is True
+
+    def test_heartbeat_nonexistent(self, storage):
+        result = storage.heartbeat_service("channel", "nonexistent")
+        assert result is False
+
+    def test_list_filters_stale(self, storage):
+        storage.register_service("channel", "ch-1", "http://localhost:8091")
+        # Manually set heartbeat to the past so it's stale
+        from datetime import UTC, datetime, timedelta
+
+        import sqlalchemy as sa
+
+        from turnstone.core.storage._schema import services
+
+        old_time = (datetime.now(UTC) - timedelta(seconds=300)).strftime("%Y-%m-%dT%H:%M:%S")
+        with storage._engine.connect() as conn:
+            conn.execute(sa.update(services).values(last_heartbeat=old_time))
+            conn.commit()
+
+        # Should be excluded with 120s max age
+        result = storage.list_services("channel", max_age_seconds=120)
+        assert len(result) == 0
+
+    def test_list_empty(self, storage):
+        services = storage.list_services("channel", max_age_seconds=120)
+        assert services == []
+
+    def test_list_filters_by_type(self, storage):
+        storage.register_service("channel", "ch-1", "http://localhost:8091")
+        storage.register_service("bridge", "br-1", "http://localhost:8080")
+        channels = storage.list_services("channel", max_age_seconds=120)
+        bridges = storage.list_services("bridge", max_age_seconds=120)
+        assert len(channels) == 1
+        assert len(bridges) == 1
+
+    def test_deregister(self, storage):
+        storage.register_service("channel", "ch-1", "http://localhost:8091")
+        result = storage.deregister_service("channel", "ch-1")
+        assert result is True
+        services = storage.list_services("channel", max_age_seconds=120)
+        assert services == []
+
+    def test_deregister_nonexistent(self, storage):
+        result = storage.deregister_service("channel", "nonexistent")
+        assert result is False
+
+    def test_metadata(self, storage):
+        storage.register_service(
+            "channel", "ch-1", "http://localhost:8091", metadata='{"adapter": "discord"}'
+        )
+        services = storage.list_services("channel", max_age_seconds=120)
+        assert services[0]["metadata"] == '{"adapter": "discord"}'
@@ -161,12 +161,12 @@ class TestPlanExec:

        return call_id, content, captured.get("messages", [])

-    def test_plan_file_uses_session_id(self, tmp_db, tmp_path, monkeypatch):
-        """Plan file is named .plan-<session_id>.md, not .plan.md."""
+    def test_plan_file_uses_ws_id(self, tmp_db, tmp_path, monkeypatch):
+        """Plan file is named .plan-<ws_id>.md, not .plan.md."""
        monkeypatch.chdir(tmp_path)
        session = _make_session()
        self._run_plan(session, "add feature")
-        expected = tmp_path / f".plan-{session._session_id}.md"
+        expected = tmp_path / f".plan-{session._ws_id}.md"
        assert expected.exists(), f"Expected {expected} to be created"
        assert not (tmp_path / ".plan.md").exists()

@@ -176,7 +176,7 @@ class TestPlanExec:
        session = _make_session()
        plan_content = "## Goal\n\nAdd a new endpoint."
        self._run_plan(session, "add endpoint", agent_return=plan_content)
-        plan_file = tmp_path / f".plan-{session._session_id}.md"
+        plan_file = tmp_path / f".plan-{session._ws_id}.md"
        assert plan_file.read_text() == plan_content

    def test_two_sessions_produce_different_files(self, tmp_db, tmp_path, monkeypatch):
@@ -184,7 +184,7 @@ class TestPlanExec:
        monkeypatch.chdir(tmp_path)
        s1 = _make_session()
        s2 = _make_session()
-        assert s1._session_id != s2._session_id
+        assert s1._ws_id != s2._ws_id
        self._run_plan(s1, "feature A")
        self._run_plan(s2, "feature B")
        files = list(tmp_path.glob(".plan-*.md"))
@@ -1,155 +1,155 @@
-"""Tests for session persistence and resume functionality."""
+"""Tests for workstream persistence and resume functionality."""

 from unittest.mock import MagicMock

 import sqlalchemy as sa

 from turnstone.core.memory import (
-    delete_session,
-    list_sessions,
-    load_session_config,
-    load_session_messages,
-    prune_sessions,
-    register_session,
-    resolve_session,
+    delete_workstream,
+    list_workstreams_with_history,
+    load_messages,
+    load_workstream_config,
+    prune_workstreams,
+    register_workstream,
+    resolve_workstream,
    save_message,
-    save_session_config,
-    set_session_alias,
-    update_session_title,
+    save_workstream_config,
+    set_workstream_alias,
+    update_workstream_title,
 )
 from turnstone.core.session import ChatSession
 from turnstone.core.storage import get_storage

-# ── Session registration ──────────────────────────────────────────────
+# ── Workstream registration ───────────────────────────────────────────


-class TestRegisterSession:
+class TestRegisterWorkstream:
    def test_register_creates_row(self, tmp_db):
-        register_session("abc123")
-        # Session exists in DB (resolve works) even without messages
-        assert resolve_session("abc123") == "abc123"
+        register_workstream("abc123")
+        # Workstream exists in DB (resolve works) even without messages
+        assert resolve_workstream("abc123") == "abc123"

    def test_register_with_title(self, tmp_db):
-        register_session("abc123", title="My Session")
+        register_workstream("abc123", name="My Workstream")
        save_message("abc123", "user", "hello")
-        rows = list_sessions()
-        assert rows[0][2] == "My Session"  # title
+        rows = list_workstreams_with_history()
+        assert rows[0][2] is None  # title column (name is separate)

    def test_register_idempotent(self, tmp_db):
-        register_session("abc123", title="First")
-        register_session("abc123", title="Second")  # should be ignored
+        register_workstream("abc123")
+        update_workstream_title("abc123", "First")
+        register_workstream("abc123")  # should be ignored
+        update_workstream_title("abc123", "First")  # title is set via update
        save_message("abc123", "user", "hello")
-        rows = list_sessions()
+        rows = list_workstreams_with_history()
        assert len(rows) == 1
-        assert rows[0][2] == "First"  # original title preserved
+        assert rows[0][2] == "First"  # title preserved

    def test_update_title(self, tmp_db):
-        register_session("abc123")
-        update_session_title("abc123", "New Title")
+        register_workstream("abc123")
+        update_workstream_title("abc123", "New Title")
        save_message("abc123", "user", "hello")
-        rows = list_sessions()
+        rows = list_workstreams_with_history()
        assert rows[0][2] == "New Title"


-# ── Session alias ─────────────────────────────────────────────────────
+# ── Workstream alias ──────────────────────────────────────────────────


-class TestSessionAlias:
+class TestWorkstreamAlias:
    def test_set_alias(self, tmp_db):
-        register_session("abc123")
-        assert set_session_alias("abc123", "my-session") is True
+        register_workstream("abc123")
+        assert set_workstream_alias("abc123", "my-session") is True
        save_message("abc123", "user", "hello")
-        rows = list_sessions()
+        rows = list_workstreams_with_history()
        assert rows[0][1] == "my-session"  # alias

    def test_alias_conflict(self, tmp_db):
-        register_session("abc123")
-        register_session("def456")
-        set_session_alias("abc123", "taken")
-        assert set_session_alias("def456", "taken") is False
+        register_workstream("abc123")
+        register_workstream("def456")
+        set_workstream_alias("abc123", "taken")
+        assert set_workstream_alias("def456", "taken") is False

-    def test_alias_same_session_ok(self, tmp_db):
-        register_session("abc123")
-        set_session_alias("abc123", "mine")
-        assert set_session_alias("abc123", "mine") is True  # no-op, same session
+    def test_alias_same_workstream_ok(self, tmp_db):
+        register_workstream("abc123")
+        set_workstream_alias("abc123", "mine")
+        assert set_workstream_alias("abc123", "mine") is True  # no-op, same workstream


-# ── Session resolution ────────────────────────────────────────────────
+# ── Workstream resolution ─────────────────────────────────────────────


-class TestResolveSession:
+class TestResolveWorkstream:
    def test_resolve_by_alias(self, tmp_db):
-        register_session("abc123")
-        set_session_alias("abc123", "my-alias")
-        assert resolve_session("my-alias") == "abc123"
+        register_workstream("abc123")
+        set_workstream_alias("abc123", "my-alias")
+        assert resolve_workstream("my-alias") == "abc123"

    def test_resolve_by_exact_id(self, tmp_db):
-        register_session("abc123def456")
-        assert resolve_session("abc123def456") == "abc123def456"
+        register_workstream("abc123def456")
+        assert resolve_workstream("abc123def456") == "abc123def456"

    def test_resolve_by_prefix(self, tmp_db):
-        register_session("abc123def456")
-        assert resolve_session("abc123") == "abc123def456"
+        register_workstream("abc123def456")
+        assert resolve_workstream("abc123") == "abc123def456"

    def test_resolve_prefix_ambiguous(self, tmp_db):
-        register_session("abc123aaaaaa")
-        register_session("abc123bbbbbb")
+        register_workstream("abc123aaaaaa")
+        register_workstream("abc123bbbbbb")
        # Ambiguous prefix should return None
-        assert resolve_session("abc123") is None
+        assert resolve_workstream("abc123") is None

    def test_resolve_not_found(self, tmp_db):
-        assert resolve_session("nonexistent") is None
-
-    def test_resolve_legacy_session(self, tmp_db):
-        """Sessions that exist only in conversations (pre-migration) should auto-register."""
-        save_message("legacy123456", "user", "old message")
-        result = resolve_session("legacy123456")
-        assert result == "legacy123456"
-        # Should now appear in sessions list
-        rows = list_sessions()
-        assert any(r[0] == "legacy123456" for r in rows)
+        assert resolve_workstream("nonexistent") is None


-# ── List sessions ─────────────────────────────────────────────────────
+# ── List workstreams with history ──────────────────────────────────────


-class TestListSessions:
+class TestListWorkstreamsWithHistory:
    def test_empty(self, tmp_db):
-        assert list_sessions() == []
+        assert list_workstreams_with_history() == []

    def test_ordered_by_updated(self, tmp_db):
-        register_session("first")
+        register_workstream("first")
        save_message("first", "user", "hello")
-        register_session("second")
+        # Force an older timestamp so ordering is deterministic
+        engine = get_storage()._engine  # noqa: SLF001
+        with engine.connect() as conn:
+            conn.execute(
+                sa.text("UPDATE workstreams SET updated = '2020-01-01' WHERE ws_id = 'first'")
+            )
+            conn.commit()
+        register_workstream("second")
        save_message("second", "user", "hello")
        # second is more recent
-        rows = list_sessions()
+        rows = list_workstreams_with_history()
        assert rows[0][0] == "second"
        assert rows[1][0] == "first"

    def test_includes_message_count(self, tmp_db):
-        register_session("sess1")
+        register_workstream("sess1")
        save_message("sess1", "user", "hello")
        save_message("sess1", "assistant", "hi")
-        rows = list_sessions()
+        rows = list_workstreams_with_history()
        assert rows[0][5] == 2  # msg_count

    def test_respects_limit(self, tmp_db):
        for i in range(5):
-            register_session(f"sess{i}")
+            register_workstream(f"sess{i}")
            save_message(f"sess{i}", "user", "hello")
-        rows = list_sessions(limit=3)
+        rows = list_workstreams_with_history(limit=3)
        assert len(rows) == 3


-# ── Load session messages ─────────────────────────────────────────────
+# ── Load messages ─────────────────────────────────────────────────────


-class TestLoadSessionMessages:
+class TestLoadMessages:
    def test_simple_user_assistant(self, tmp_db):
        save_message("s1", "user", "hello")
        save_message("s1", "assistant", "hi there")
-        msgs = load_session_messages("s1")
+        msgs = load_messages("s1")
        assert len(msgs) == 2
        assert msgs[0] == {"role": "user", "content": "hello"}
        assert msgs[1] == {"role": "assistant", "content": "hi there"}
@@ -159,7 +159,7 @@ class TestLoadSessionMessages:
        save_message("s1", "assistant", "Let me check.")
        save_message("s1", "tool_call", None, "bash", '{"command":"ls"}', tool_call_id="call_abc")
        save_message("s1", "tool_result", "file1.txt\nfile2.txt", "bash", tool_call_id="call_abc")
-        msgs = load_session_messages("s1")
+        msgs = load_messages("s1")
        assert len(msgs) == 3  # user, assistant+tool_calls, tool
        # Assistant should have content merged with tool_calls
        assert msgs[1]["role"] == "assistant"
@@ -177,7 +177,7 @@ class TestLoadSessionMessages:
        save_message("s1", "user", "do stuff")
        save_message("s1", "tool_call", None, "bash", '{"command":"ls"}')
        save_message("s1", "tool_result", "output", "bash")
-        msgs = load_session_messages("s1")
+        msgs = load_messages("s1")
        assert len(msgs) == 3
        # Synthetic IDs should match
        tc_id = msgs[1]["tool_calls"][0]["id"]
@@ -189,36 +189,36 @@ class TestLoadSessionMessages:
        save_message("s1", "tool_call", None, "search", '{"query":"b"}', tool_call_id="call_2")
        save_message("s1", "tool_result", "result a", "search", tool_call_id="call_1")
        save_message("s1", "tool_result", "result b", "search", tool_call_id="call_2")
-        msgs = load_session_messages("s1")
+        msgs = load_messages("s1")
        assert len(msgs) == 4  # user, assistant+2 tool_calls, 2 tool results
        assert len(msgs[1]["tool_calls"]) == 2
        assert msgs[2]["tool_call_id"] == "call_1"
        assert msgs[3]["tool_call_id"] == "call_2"

-    def test_empty_session(self, tmp_db):
-        assert load_session_messages("nonexistent") == []
+    def test_empty_workstream(self, tmp_db):
+        assert load_messages("nonexistent") == []

    def test_orphaned_tool_result_skipped(self, tmp_db):
        save_message("s1", "user", "hello")
        save_message("s1", "tool_result", "orphan", "bash")
-        msgs = load_session_messages("s1")
+        msgs = load_messages("s1")
        assert len(msgs) == 1  # only the user message


-# ── Delete session ────────────────────────────────────────────────────
+# ── Delete workstream ─────────────────────────────────────────────────


-class TestDeleteSession:
-    def test_delete_removes_session_and_messages(self, tmp_db):
-        register_session("abc123")
+class TestDeleteWorkstream:
+    def test_delete_removes_workstream_and_messages(self, tmp_db):
+        register_workstream("abc123")
        save_message("abc123", "user", "hello")
        save_message("abc123", "assistant", "hi")
-        assert delete_session("abc123") is True
-        assert list_sessions() == []
-        assert load_session_messages("abc123") == []
+        assert delete_workstream("abc123") is True
+        assert list_workstreams_with_history() == []
+        assert load_messages("abc123") == []

    def test_delete_nonexistent(self, tmp_db):
-        assert delete_session("nonexistent") is True  # no-op, still returns True
+        assert delete_workstream("nonexistent") is False


 # ── save_message with tool_call_id ────────────────────────────────────
@@ -230,7 +230,7 @@ class TestSaveMessageToolCallId:
        engine = get_storage()._engine  # noqa: SLF001
        with engine.connect() as conn:
            row = conn.execute(
-                sa.text("SELECT tool_call_id FROM conversations WHERE session_id = 's1'")
+                sa.text("SELECT tool_call_id FROM conversations WHERE ws_id = 's1'")
            ).fetchone()
            assert row[0] == "call_xyz"

@@ -239,20 +239,20 @@ class TestSaveMessageToolCallId:
        engine = get_storage()._engine  # noqa: SLF001
        with engine.connect() as conn:
            row = conn.execute(
-                sa.text("SELECT tool_call_id FROM conversations WHERE session_id = 's1'")
+                sa.text("SELECT tool_call_id FROM conversations WHERE ws_id = 's1'")
            ).fetchone()
            assert row[0] is None


-# ── Sessions table creation ───────────────────────────────────────────
+# ── Workstreams table creation ────────────────────────────────────────


-class TestSessionsTable:
-    def test_sessions_table_exists(self, tmp_db):
+class TestWorkstreamsTable:
+    def test_workstreams_table_exists(self, tmp_db):
        engine = get_storage()._engine  # noqa: SLF001
        with engine.connect() as conn:
            rows = conn.execute(
-                sa.text("SELECT name FROM sqlite_master WHERE type='table' AND name='sessions'")
+                sa.text("SELECT name FROM sqlite_master WHERE type='table' AND name='workstreams'")
            ).fetchall()
            assert len(rows) == 1

@@ -263,15 +263,15 @@ class TestSessionsTable:
            conn.execute(sa.text("SELECT tool_call_id FROM conversations LIMIT 0"))


-# ── ChatSession.resume_session ────────────────────────────────────────
+# ── ChatSession.resume ────────────────────────────────────────────────


-class TestResumeSession:
+class TestResumeWorkstream:
    def test_resume_loads_messages(self, tmp_db, mock_openai_client):
-        # Set up a session with messages in DB
-        register_session("old_sess_123")
-        save_message("old_sess_123", "user", "hello world")
-        save_message("old_sess_123", "assistant", "hi there")
+        # Set up a workstream with messages in DB
+        register_workstream("old_ws_123")
+        save_message("old_ws_123", "user", "hello world")
+        save_message("old_ws_123", "assistant", "hi there")

        # Create a new session and resume
        session = ChatSession(
@@ -283,12 +283,12 @@ class TestResumeSession:
            max_tokens=1000,
            tool_timeout=10,
        )
-        original_id = session._session_id
-        assert original_id != "old_sess_123"
+        original_id = session._ws_id
+        assert original_id != "old_ws_123"

-        result = session.resume_session("old_sess_123")
+        result = session.resume("old_ws_123")
        assert result is True
-        assert session._session_id == "old_sess_123"
+        assert session._ws_id == "old_ws_123"
        assert len(session.messages) == 2
        assert session.messages[0]["content"] == "hello world"
        assert session._title_generated is True
@@ -303,9 +303,9 @@ class TestResumeSession:
            max_tokens=1000,
            tool_timeout=10,
        )
-        assert session.resume_session("nonexistent") is False
+        assert session.resume("nonexistent") is False

-    def test_session_registered_on_init(self, tmp_db, mock_openai_client):
+    def test_workstream_not_registered_until_message(self, tmp_db, mock_openai_client):
        session = ChatSession(
            client=mock_openai_client,
            model="test-model",
@@ -315,20 +315,19 @@ class TestResumeSession:
            max_tokens=1000,
            tool_timeout=10,
        )
-        # Session is registered in DB (resolvable) even before any messages
-        assert resolve_session(session._session_id) == session._session_id
-        # But does not appear in list_sessions until a message is saved
-        assert not any(r[0] == session._session_id for r in list_sessions())
+        # Workstream is not auto-registered on init — only on /new or server creation
+        assert resolve_workstream(session._ws_id) is None
+        assert not any(r[0] == session._ws_id for r in list_workstreams_with_history())


-# ── save_message updates sessions.updated ─────────────────────────────
+# ── save_message updates workstreams.updated ──────────────────────────


-class TestSaveMessageUpdatesSession:
+class TestSaveMessageUpdatesWorkstream:
    def test_updated_timestamp_bumped(self, tmp_db):
-        register_session("s1")
+        register_workstream("s1")
        save_message("s1", "user", "first")
-        rows = list_sessions()
+        rows = list_workstreams_with_history()
        _original_updated = rows[0][4]

        import time
@@ -336,18 +335,18 @@ class TestSaveMessageUpdatesSession:
        time.sleep(0.01)  # ensure different timestamp
        save_message("s1", "user", "hello")

-        rows = list_sessions()
+        rows = list_workstreams_with_history()
        new_updated = rows[0][4]
        # updated should be same or later (sqlite datetime resolution is seconds,
        # so they may be equal in fast tests — just verify no error)
        assert new_updated is not None


-# ── Interrupted session repair ───────────────────────────────────────
+# ── Interrupted workstream repair ─────────────────────────────────────


-class TestInterruptedSessionRepair:
-    """load_session_messages() should strip trailing incomplete tool call turns."""
+class TestInterruptedWorkstreamRepair:
+    """load_messages() should strip trailing incomplete tool call turns."""

    def test_complete_tool_turn_preserved(self, tmp_db):
        """2 tool_calls + 2 tool_results = complete, no stripping."""
@@ -356,7 +355,7 @@ class TestInterruptedSessionRepair:
        save_message("s1", "tool_call", None, "bash", '{"command":"pwd"}', "call_2")
        save_message("s1", "tool_result", "file.txt", tool_call_id="call_1")
        save_message("s1", "tool_result", "/home", tool_call_id="call_2")
-        msgs = load_session_messages("s1")
+        msgs = load_messages("s1")
        assert len(msgs) == 4  # user + assistant(2 calls) + 2 tool results

    def test_partial_tool_results_stripped(self, tmp_db):
@@ -365,7 +364,7 @@ class TestInterruptedSessionRepair:
        save_message("s1", "tool_call", None, "bash", '{"command":"ls"}', "call_1")
        save_message("s1", "tool_call", None, "bash", '{"command":"pwd"}', "call_2")
        save_message("s1", "tool_result", "file.txt", tool_call_id="call_1")
-        msgs = load_session_messages("s1")
+        msgs = load_messages("s1")
        assert len(msgs) == 1  # only user message remains
        assert msgs[0]["role"] == "user"

@@ -375,7 +374,7 @@ class TestInterruptedSessionRepair:
        save_message("s1", "assistant", "Let me check")
        save_message("s1", "tool_call", None, "bash", '{"command":"ls"}', "call_1")
        save_message("s1", "tool_call", None, "bash", '{"command":"pwd"}', "call_2")
-        msgs = load_session_messages("s1")
+        msgs = load_messages("s1")
        # assistant with content was merged into tool_call assistant, so stripped
        assert len(msgs) == 1
        assert msgs[0]["role"] == "user"
@@ -386,42 +385,42 @@ class TestInterruptedSessionRepair:
        save_message("s1", "assistant", "response")
        save_message("s1", "user", "second")
        save_message("s1", "tool_call", None, "bash", '{"command":"ls"}', "call_1")
-        msgs = load_session_messages("s1")
+        msgs = load_messages("s1")
        assert len(msgs) == 3  # user + assistant + user (incomplete turn stripped)
        assert msgs[0]["role"] == "user"
        assert msgs[1]["role"] == "assistant"
        assert msgs[2]["role"] == "user"


-# ── Session config persistence ───────────────────────────────────────
+# ── Workstream config persistence ─────────────────────────────────────


-class TestSessionConfig:
+class TestWorkstreamConfig:
    def test_save_load_roundtrip(self, tmp_db):
        config = {"temperature": "0.3", "reasoning_effort": "high", "creative_mode": "False"}
-        save_session_config("s1", config)
-        loaded = load_session_config("s1")
+        save_workstream_config("s1", config)
+        loaded = load_workstream_config("s1")
        assert loaded == config

    def test_update_existing_key(self, tmp_db):
-        save_session_config("s1", {"temperature": "0.3"})
-        save_session_config("s1", {"temperature": "0.7"})
-        loaded = load_session_config("s1")
+        save_workstream_config("s1", {"temperature": "0.3"})
+        save_workstream_config("s1", {"temperature": "0.7"})
+        loaded = load_workstream_config("s1")
        assert loaded["temperature"] == "0.7"

-    def test_missing_session_returns_empty(self, tmp_db):
-        loaded = load_session_config("nonexistent")
+    def test_missing_workstream_returns_empty(self, tmp_db):
+        loaded = load_workstream_config("nonexistent")
        assert loaded == {}

-    def test_delete_session_removes_config(self, tmp_db):
-        register_session("s1")
+    def test_delete_workstream_removes_config(self, tmp_db):
+        register_workstream("s1")
        save_message("s1", "user", "hi")
-        save_session_config("s1", {"temperature": "0.5"})
-        delete_session("s1")
-        assert load_session_config("s1") == {}
+        save_workstream_config("s1", {"temperature": "0.5"})
+        delete_workstream("s1")
+        assert load_workstream_config("s1") == {}

    def test_resume_restores_config(self, tmp_db):
-        """ChatSession.resume_session() should restore persisted config."""
+        """ChatSession.resume() should restore persisted config."""
        client = MagicMock()
        client.models.list.return_value.data = [MagicMock(id="test-model")]
        ui = MagicMock()
@@ -430,11 +429,11 @@ class TestSessionConfig:
        ui.on_state_change = MagicMock()
        ui.on_rename = MagicMock()

-        # Create a session with specific config
-        register_session("orig")
+        # Create a workstream with specific config
+        register_workstream("orig")
        save_message("orig", "user", "hello")
        save_message("orig", "assistant", "hi there")
-        save_session_config(
+        save_workstream_config(
            "orig",
            {
                "temperature": "0.3",
@@ -456,7 +455,7 @@ class TestSessionConfig:
            tool_timeout=30,
        )
        assert session.temperature == 0.7  # default
-        result = session.resume_session("orig")
+        result = session.resume("orig")
        assert result is True
        assert session.temperature == 0.3
        assert session.reasoning_effort == "high"
@@ -465,84 +464,84 @@ class TestSessionConfig:
        assert session.creative_mode is True


-# ── Prune sessions ───────────────────────────────────────────────────
+# ── Prune workstreams ─────────────────────────────────────────────────


-class TestPruneSessions:
+class TestPruneWorkstreams:
    def test_orphan_removed(self, tmp_db):
-        """Session registered with no messages should be pruned."""
-        register_session("orphan")
-        orphans, stale = prune_sessions()
+        """Workstream registered with no messages should be pruned."""
+        register_workstream("orphan")
+        orphans, stale = prune_workstreams()
        assert orphans == 1
-        assert list_sessions() == []
+        assert list_workstreams_with_history() == []

-    def test_session_with_messages_kept(self, tmp_db):
-        """Session with messages should not be pruned."""
-        register_session("active")
+    def test_workstream_with_messages_kept(self, tmp_db):
+        """Workstream with messages should not be pruned."""
+        register_workstream("active")
        save_message("active", "user", "hello")
-        orphans, _stale = prune_sessions()
+        orphans, _stale = prune_workstreams()
        assert orphans == 0
-        assert len(list_sessions()) == 1
+        assert len(list_workstreams_with_history()) == 1

    def test_stale_unnamed_removed(self, tmp_db):
-        """Old unnamed session should be pruned by retention policy."""
-        register_session("old1")
+        """Old unnamed workstream should be pruned by retention policy."""
+        register_workstream("old1")
        save_message("old1", "user", "ancient message")
        # Force the updated timestamp to the past so it looks stale
        engine = get_storage()._engine  # noqa: SLF001
        with engine.connect() as conn:
            conn.execute(
-                sa.text("UPDATE sessions SET updated = '2020-01-01' WHERE session_id = 'old1'")
+                sa.text("UPDATE workstreams SET updated = '2020-01-01' WHERE ws_id = 'old1'")
            )
            conn.commit()
-        _orphans, stale = prune_sessions(retention_days=30)
+        _orphans, stale = prune_workstreams(retention_days=30)
        assert stale == 1

-    def test_named_session_preserved(self, tmp_db):
-        """Session with alias should be kept regardless of age."""
-        register_session("old2")
-        set_session_alias("old2", "important")
+    def test_named_workstream_preserved(self, tmp_db):
+        """Workstream with alias should be kept regardless of age."""
+        register_workstream("old2")
+        set_workstream_alias("old2", "important")
        save_message("old2", "user", "old but named")
        # Force old timestamp
        engine = get_storage()._engine  # noqa: SLF001
        with engine.connect() as conn:
            conn.execute(
-                sa.text("UPDATE sessions SET updated = '2020-01-01' WHERE session_id = 'old2'")
+                sa.text("UPDATE workstreams SET updated = '2020-01-01' WHERE ws_id = 'old2'")
            )
            conn.commit()
-        _orphans, stale = prune_sessions(retention_days=30)
+        _orphans, stale = prune_workstreams(retention_days=30)
        assert stale == 0
-        assert len(list_sessions()) == 1
+        assert len(list_workstreams_with_history()) == 1

    def test_fresh_unnamed_preserved(self, tmp_db):
-        """Recent unnamed session should not be pruned."""
-        register_session("fresh")
+        """Recent unnamed workstream should not be pruned."""
+        register_workstream("fresh")
        save_message("fresh", "user", "just now")
-        _orphans, stale = prune_sessions(retention_days=30)
+        _orphans, stale = prune_workstreams(retention_days=30)
        assert stale == 0
-        assert len(list_sessions()) == 1
+        assert len(list_workstreams_with_history()) == 1

-    def test_prune_removes_session_config(self, tmp_db):
-        """Pruning orphan/stale sessions should also remove their config rows."""
-        register_session("orphan_cfg")
-        save_session_config("orphan_cfg", {"temperature": "0.5"})
+    def test_prune_removes_workstream_config(self, tmp_db):
+        """Pruning orphan/stale workstreams should also remove their config rows."""
+        register_workstream("orphan_cfg")
+        save_workstream_config("orphan_cfg", {"temperature": "0.5"})

-        register_session("stale_cfg")
+        register_workstream("stale_cfg")
        save_message("stale_cfg", "user", "old")
-        save_session_config("stale_cfg", {"temperature": "0.9"})
+        save_workstream_config("stale_cfg", {"temperature": "0.9"})
        engine = get_storage()._engine  # noqa: SLF001
        with engine.connect() as conn:
            conn.execute(
-                sa.text("UPDATE sessions SET updated = '2020-01-01' WHERE session_id = 'stale_cfg'")
+                sa.text("UPDATE workstreams SET updated = '2020-01-01' WHERE ws_id = 'stale_cfg'")
            )
            conn.commit()

        # Both should have config before prune
-        assert load_session_config("orphan_cfg") == {"temperature": "0.5"}
-        assert load_session_config("stale_cfg") == {"temperature": "0.9"}
+        assert load_workstream_config("orphan_cfg") == {"temperature": "0.5"}
+        assert load_workstream_config("stale_cfg") == {"temperature": "0.9"}

-        prune_sessions(retention_days=30)
+        prune_workstreams(retention_days=30)

        # Config rows should be cleaned up
-        assert load_session_config("orphan_cfg") == {}
-        assert load_session_config("stale_cfg") == {}
+        assert load_workstream_config("orphan_cfg") == {}
+        assert load_workstream_config("stale_cfg") == {}
@@ -14,28 +14,28 @@ def backend(tmp_path):
    reset_storage()


-# -- Session operations --------------------------------------------------------
+# -- Workstream registration ---------------------------------------------------


-class TestRegisterSession:
-    def test_register_creates_session(self, backend):
-        backend.register_session("s1", title="Test")
-        name = backend.get_session_name("s1")
+class TestRegisterWorkstream:
+    def test_register_creates_workstream(self, backend):
+        backend.register_workstream("s1", title="Test")
+        name = backend.get_workstream_display_name("s1")
        assert name == "Test"

    def test_register_idempotent(self, backend):
-        backend.register_session("s1", title="First")
-        backend.register_session("s1", title="Second")
-        name = backend.get_session_name("s1")
+        backend.register_workstream("s1", title="First")
+        backend.register_workstream("s1", title="Second")
+        name = backend.get_workstream_display_name("s1")
        assert name == "First"  # INSERT OR IGNORE preserves first


 class TestSaveAndLoadMessages:
    def test_roundtrip(self, backend):
-        backend.register_session("s1")
+        backend.register_workstream("s1")
        backend.save_message("s1", "user", "hello")
        backend.save_message("s1", "assistant", "world")
-        msgs = backend.load_session_messages("s1")
+        msgs = backend.load_messages("s1")
        assert len(msgs) == 2
        assert msgs[0]["role"] == "user"
        assert msgs[0]["content"] == "hello"
@@ -43,12 +43,12 @@ class TestSaveAndLoadMessages:
        assert msgs[1]["content"] == "world"

    def test_tool_call_grouping(self, backend):
-        backend.register_session("s1")
+        backend.register_workstream("s1")
        backend.save_message("s1", "user", "do something")
        backend.save_message("s1", "tool_call", None, "bash", '{"cmd":"ls"}', tool_call_id="c1")
        backend.save_message("s1", "tool_result", "file.txt", tool_call_id="c1")
        backend.save_message("s1", "assistant", "done")
-        msgs = backend.load_session_messages("s1")
+        msgs = backend.load_messages("s1")
        assert len(msgs) == 4
        assert msgs[1]["role"] == "assistant"
        assert len(msgs[1]["tool_calls"]) == 1
@@ -57,136 +57,136 @@ class TestSaveAndLoadMessages:
        assert msgs[2]["content"] == "file.txt"

    def test_incomplete_turn_repair(self, backend):
-        backend.register_session("s1")
+        backend.register_workstream("s1")
        backend.save_message("s1", "user", "do something")
        backend.save_message("s1", "tool_call", None, "bash", '{"cmd":"ls"}', tool_call_id="c1")
        backend.save_message("s1", "tool_call", None, "read", '{"path":"a"}', tool_call_id="c2")
        # Only 1 result for 2 calls — incomplete turn
        backend.save_message("s1", "tool_result", "ok", tool_call_id="c1")
-        msgs = backend.load_session_messages("s1")
+        msgs = backend.load_messages("s1")
        # Incomplete turn should be stripped
        assert len(msgs) == 1  # only the user message remains

    def test_provider_data_preserved(self, backend):
        import json

-        backend.register_session("s1")
+        backend.register_workstream("s1")
        pd = json.dumps({"encrypted": True})
        backend.save_message("s1", "assistant", "hi", provider_data=pd)
-        msgs = backend.load_session_messages("s1")
+        msgs = backend.load_messages("s1")
        assert msgs[0].get("_provider_content") == {"encrypted": True}

-    def test_empty_session_returns_empty(self, backend):
-        assert backend.load_session_messages("nonexistent") == []
+    def test_empty_workstream_returns_empty(self, backend):
+        assert backend.load_messages("nonexistent") == []


-class TestListSessions:
-    def test_lists_sessions_with_messages(self, backend):
-        backend.register_session("s1")
+class TestListWorkstreamsWithHistory:
+    def test_lists_workstreams_with_messages(self, backend):
+        backend.register_workstream("s1")
        backend.save_message("s1", "user", "hi")
-        backend.register_session("s2")  # no messages
-        rows = backend.list_sessions()
+        backend.register_workstream("s2")  # no messages
+        rows = backend.list_workstreams_with_history()
        assert len(rows) == 1
        assert rows[0][0] == "s1"

    def test_respects_limit(self, backend):
        for i in range(5):
            sid = f"s{i}"
-            backend.register_session(sid)
+            backend.register_workstream(sid)
            backend.save_message(sid, "user", f"msg {i}")
-        rows = backend.list_sessions(limit=3)
+        rows = backend.list_workstreams_with_history(limit=3)
        assert len(rows) == 3


-class TestDeleteSession:
+class TestDeleteWorkstream:
    def test_deletes_all_data(self, backend):
-        backend.register_session("s1")
+        backend.register_workstream("s1")
        backend.save_message("s1", "user", "hi")
-        backend.save_session_config("s1", {"temp": "0.5"})
-        assert backend.delete_session("s1")
-        assert backend.load_session_messages("s1") == []
-        assert backend.load_session_config("s1") == {}
-        assert backend.get_session_name("s1") is None
+        backend.save_workstream_config("s1", {"temp": "0.5"})
+        assert backend.delete_workstream("s1")
+        assert backend.load_messages("s1") == []
+        assert backend.load_workstream_config("s1") == {}
+        assert backend.get_workstream_display_name("s1") is None


-class TestPruneSessions:
+class TestPruneWorkstreams:
    def test_orphan_removed(self, backend):
-        backend.register_session("orphan")
-        orphans, stale = backend.prune_sessions()
+        backend.register_workstream("orphan")
+        orphans, stale = backend.prune_workstreams()
        assert orphans == 1

    def test_stale_removed(self, backend):
        import sqlalchemy as sa

-        backend.register_session("old")
+        backend.register_workstream("old")
        backend.save_message("old", "user", "hi")
        # Force old timestamp
        with backend._engine.connect() as conn:
            conn.execute(
-                sa.text("UPDATE sessions SET updated = '2020-01-01' WHERE session_id = 'old'")
+                sa.text("UPDATE workstreams SET updated = '2020-01-01' WHERE ws_id = 'old'")
            )
            conn.commit()
-        _, stale = backend.prune_sessions(retention_days=30)
+        _, stale = backend.prune_workstreams(retention_days=30)
        assert stale == 1


-class TestResolveSession:
+class TestResolveWorkstream:
    def test_exact_alias(self, backend):
-        backend.register_session("s1")
-        backend.set_session_alias("s1", "myalias")
-        assert backend.resolve_session("myalias") == "s1"
+        backend.register_workstream("s1")
+        backend.set_workstream_alias("s1", "myalias")
+        assert backend.resolve_workstream("myalias") == "s1"

    def test_exact_id(self, backend):
-        backend.register_session("abc-123-def")
-        assert backend.resolve_session("abc-123-def") == "abc-123-def"
+        backend.register_workstream("abc-123-def")
+        assert backend.resolve_workstream("abc-123-def") == "abc-123-def"

    def test_prefix_match(self, backend):
-        backend.register_session("abc-123-def")
-        assert backend.resolve_session("abc") == "abc-123-def"
+        backend.register_workstream("abc-123-def")
+        assert backend.resolve_workstream("abc") == "abc-123-def"

    def test_not_found(self, backend):
-        assert backend.resolve_session("nonexistent") is None
+        assert backend.resolve_workstream("nonexistent") is None


-# -- Session config ------------------------------------------------------------
+# -- Workstream config ---------------------------------------------------------


-class TestSessionConfig:
+class TestWorkstreamConfig:
    def test_roundtrip(self, backend):
-        backend.register_session("s1")
-        backend.save_session_config("s1", {"temperature": "0.7", "effort": "high"})
-        cfg = backend.load_session_config("s1")
+        backend.register_workstream("s1")
+        backend.save_workstream_config("s1", {"temperature": "0.7", "effort": "high"})
+        cfg = backend.load_workstream_config("s1")
        assert cfg == {"temperature": "0.7", "effort": "high"}

    def test_empty_config(self, backend):
-        assert backend.load_session_config("nonexistent") == {}
+        assert backend.load_workstream_config("nonexistent") == {}


-# -- Session metadata ----------------------------------------------------------
+# -- Workstream metadata ------------------------------------------------------


-class TestSessionMetadata:
+class TestWorkstreamMetadata:
    def test_alias(self, backend):
-        backend.register_session("s1")
-        assert backend.set_session_alias("s1", "my-session")
-        assert backend.get_session_name("s1") == "my-session"
+        backend.register_workstream("s1")
+        assert backend.set_workstream_alias("s1", "my-session")
+        assert backend.get_workstream_display_name("s1") == "my-session"

    def test_alias_conflict(self, backend):
-        backend.register_session("s1")
-        backend.register_session("s2")
-        backend.set_session_alias("s1", "taken")
-        assert not backend.set_session_alias("s2", "taken")
+        backend.register_workstream("s1")
+        backend.register_workstream("s2")
+        backend.set_workstream_alias("s1", "taken")
+        assert not backend.set_workstream_alias("s2", "taken")

    def test_title(self, backend):
-        backend.register_session("s1")
-        backend.update_session_title("s1", "My Title")
-        assert backend.get_session_name("s1") == "My Title"
+        backend.register_workstream("s1")
+        backend.update_workstream_title("s1", "My Title")
+        assert backend.get_workstream_display_name("s1") == "My Title"

    def test_alias_preferred_over_title(self, backend):
-        backend.register_session("s1")
-        backend.update_session_title("s1", "Title")
-        backend.set_session_alias("s1", "Alias")
-        assert backend.get_session_name("s1") == "Alias"
+        backend.register_workstream("s1")
+        backend.update_workstream_title("s1", "Title")
+        backend.set_workstream_alias("s1", "Alias")
+        assert backend.get_workstream_display_name("s1") == "Alias"


 # -- Key-value store -----------------------------------------------------------
@@ -234,7 +234,7 @@ class TestKVStore:

 class TestSearch:
    def test_search_history(self, backend):
-        backend.register_session("s1")
+        backend.register_workstream("s1")
        backend.save_message("s1", "user", "hello world")
        backend.save_message("s1", "user", "goodbye world")
        results = backend.search_history("hello")
@@ -242,13 +242,67 @@ class TestSearch:
        assert any("hello" in str(r[3]) for r in results)

    def test_search_recent(self, backend):
-        backend.register_session("s1")
+        backend.register_workstream("s1")
        backend.save_message("s1", "user", "msg1")
        backend.save_message("s1", "user", "msg2")
        results = backend.search_history_recent(limit=1)
        assert len(results) == 1


+# -- Workstream operations -----------------------------------------------------
+
+
+class TestWorkstreams:
+    def test_register_and_list(self, backend):
+        backend.register_workstream("ws1", node_id="node-a", name="first")
+        backend.register_workstream("ws2", node_id="node-a", name="second")
+        rows = backend.list_workstreams()
+        assert len(rows) == 2
+        ws_ids = {r[0] for r in rows}
+        assert ws_ids == {"ws1", "ws2"}
+
+    def test_register_idempotent(self, backend):
+        backend.register_workstream("ws1", name="first")
+        backend.register_workstream("ws1", name="overwrite")
+        rows = backend.list_workstreams()
+        assert len(rows) == 1
+        assert rows[0][2] == "first"  # name preserved from first insert
+
+    def test_update_state(self, backend):
+        backend.register_workstream("ws1")
+        backend.update_workstream_state("ws1", "running")
+        rows = backend.list_workstreams()
+        assert rows[0][3] == "running"
+
+    def test_update_name(self, backend):
+        backend.register_workstream("ws1", name="old")
+        backend.update_workstream_name("ws1", "new")
+        rows = backend.list_workstreams()
+        assert rows[0][2] == "new"
+
+    def test_delete(self, backend):
+        backend.register_workstream("ws1")
+        assert backend.delete_workstream("ws1") is True
+        assert backend.list_workstreams() == []
+        assert backend.delete_workstream("ws1") is False
+
+    def test_list_by_node(self, backend):
+        backend.register_workstream("ws1", node_id="node-a")
+        backend.register_workstream("ws2", node_id="node-b")
+        rows = backend.list_workstreams(node_id="node-a")
+        assert len(rows) == 1
+        assert rows[0][0] == "ws1"
+
+    def test_workstream_with_messages_in_history(self, backend):
+        backend.register_workstream("ws1", node_id="node-a")
+        backend.save_message("ws1", "user", "hello")
+        rows = backend.list_workstreams_with_history()
+        assert len(rows) == 1
+        # Columns: ws_id, alias, title, created, updated, count, node_id
+        assert rows[0][0] == "ws1"
+        assert rows[0][6] == "node-a"
+
+
 # -- Lifecycle -----------------------------------------------------------------


@@ -72,16 +72,16 @@ class TestToolsMetadata:
    """Validate the metadata extracted from JSON files."""

    def test_tool_count(self):
-        assert len(TOOLS) == 14
+        assert len(TOOLS) == 15

    def test_agent_tools_count(self):
-        assert len(AGENT_TOOLS) == 6
+        assert len(AGENT_TOOLS) == 7

    def test_task_agent_tools_count(self):
-        assert len(TASK_AGENT_TOOLS) == 9
+        assert len(TASK_AGENT_TOOLS) == 10

    def test_auto_approve_sets_match(self):
-        expected = {"read_file", "search", "math", "man", "web_fetch", "web_search"}
+        expected = {"read_file", "search", "math", "man", "web_fetch", "web_search", "notify"}
        assert expected == AGENT_AUTO_TOOLS
        assert expected == TASK_AUTO_TOOLS

@@ -101,6 +101,7 @@ class TestToolsMetadata:
            "remember": "key",
            "recall": "query",
            "forget": "key",
+            "notify": "message",
        }
        assert expected == PRIMARY_KEY_MAP

@@ -0,0 +1,155 @@
+"""Tests for user identity storage operations (SQLite backend)."""
+
+from __future__ import annotations
+
+import pytest
+
+from turnstone.core.storage._sqlite import SQLiteBackend
+
+
+@pytest.fixture()
+def db(tmp_path):
+    """Create a fresh SQLite backend for each test."""
+    return SQLiteBackend(str(tmp_path / "test.db"))
+
+
+class TestUserCRUD:
+    def test_create_and_get(self, db):
+        db.create_user("u1", "admin", "Admin User", "$2b$hash")
+        user = db.get_user("u1")
+        assert user is not None
+        assert user["user_id"] == "u1"
+        assert user["username"] == "admin"
+        assert user["display_name"] == "Admin User"
+        assert user["password_hash"] == "$2b$hash"
+
+    def test_get_nonexistent(self, db):
+        assert db.get_user("missing") is None
+
+    def test_get_by_username(self, db):
+        db.create_user("u1", "admin", "Admin", "$2b$hash")
+        user = db.get_user_by_username("admin")
+        assert user is not None
+        assert user["user_id"] == "u1"
+
+    def test_get_by_username_nonexistent(self, db):
+        assert db.get_user_by_username("nope") is None
+
+    def test_create_duplicate_noop(self, db):
+        db.create_user("u1", "admin", "First", "$2b$hash1")
+        db.create_user("u1", "admin2", "Second", "$2b$hash2")
+        user = db.get_user("u1")
+        assert user is not None
+        assert user["display_name"] == "First"
+
+    def test_list_users(self, db):
+        db.create_user("u1", "admin", "Admin", "$2b$h1")
+        db.create_user("u2", "reader", "Reader", "$2b$h2")
+        users = db.list_users()
+        assert len(users) == 2
+        assert "password_hash" not in users[0]
+
+    def test_delete_user(self, db):
+        db.create_user("u1", "admin", "Admin", "$2b$hash")
+        assert db.delete_user("u1")
+        assert db.get_user("u1") is None
+
+    def test_delete_nonexistent(self, db):
+        assert not db.delete_user("missing")
+
+    def test_delete_cascades_tokens(self, db):
+        db.create_user("u1", "admin", "Admin", "$2b$hash")
+        db.create_api_token("t1", "hash1", "ts_abcde", "u1", "tok1", "read,write")
+        db.create_api_token("t2", "hash2", "ts_fghij", "u1", "tok2", "read")
+        assert len(db.list_api_tokens("u1")) == 2
+        db.delete_user("u1")
+        assert len(db.list_api_tokens("u1")) == 0
+
+
+class TestApiTokenCRUD:
+    def test_create_and_lookup_by_hash(self, db):
+        db.create_user("u1", "admin", "Admin", "$2b$hash")
+        db.create_api_token("t1", "tokenhash123", "ts_abcde", "u1", "My Token", "read,write")
+        tok = db.get_api_token_by_hash("tokenhash123")
+        assert tok is not None
+        assert tok["token_id"] == "t1"
+        assert tok["user_id"] == "u1"
+        assert tok["scopes"] == "read,write"
+
+    def test_lookup_missing_hash(self, db):
+        assert db.get_api_token_by_hash("nonexistent") is None
+
+    def test_list_tokens_excludes_hash(self, db):
+        db.create_user("u1", "admin", "Admin", "$2b$hash")
+        db.create_api_token("t1", "secret_hash", "ts_abcde", "u1", "tok1", "read")
+        tokens = db.list_api_tokens("u1")
+        assert len(tokens) == 1
+        assert "token_hash" not in tokens[0]
+        assert tokens[0]["token_prefix"] == "ts_abcde"
+
+    def test_list_tokens_by_user(self, db):
+        db.create_user("u1", "admin", "Admin", "$2b$hash")
+        db.create_user("u2", "reader", "Reader", "$2b$hash")
+        db.create_api_token("t1", "h1", "ts_a", "u1", "tok1", "read")
+        db.create_api_token("t2", "h2", "ts_b", "u2", "tok2", "read")
+        assert len(db.list_api_tokens("u1")) == 1
+        assert len(db.list_api_tokens("u2")) == 1
+
+    def test_delete_token(self, db):
+        db.create_user("u1", "admin", "Admin", "$2b$hash")
+        db.create_api_token("t1", "h1", "ts_a", "u1", "tok1", "read")
+        assert db.delete_api_token("t1")
+        assert db.get_api_token_by_hash("h1") is None
+
+    def test_delete_nonexistent_token(self, db):
+        assert not db.delete_api_token("missing")
+
+    def test_token_with_expiry(self, db):
+        db.create_user("u1", "admin", "Admin", "$2b$hash")
+        db.create_api_token(
+            "t1",
+            "h1",
+            "ts_a",
+            "u1",
+            "tok1",
+            "read",
+            expires="2030-01-01T00:00:00",
+        )
+        tok = db.get_api_token_by_hash("h1")
+        assert tok is not None
+        assert tok["expires"] == "2030-01-01T00:00:00"
+
+    def test_token_without_expiry(self, db):
+        db.create_user("u1", "admin", "Admin", "$2b$hash")
+        db.create_api_token("t1", "h1", "ts_a", "u1", "tok1", "read")
+        tok = db.get_api_token_by_hash("h1")
+        assert tok is not None
+        assert "expires" not in tok
+
+
+class TestWorkstreamUserId:
+    def test_register_workstream_with_user_id(self, db):
+        db.register_workstream("ws1", user_id="u1")
+        import sqlalchemy as sa
+
+        from turnstone.core.storage._schema import workstreams
+
+        with db._engine.connect() as conn:
+            row = conn.execute(
+                sa.select(workstreams.c.user_id).where(workstreams.c.ws_id == "ws1")
+            ).fetchone()
+            assert row is not None
+            assert row[0] == "u1"
+
+    def test_register_workstream_without_user_id(self, db):
+        db.register_workstream("ws1")
+        import sqlalchemy as sa
+
+        from turnstone.core.storage._schema import workstreams
+
+        with db._engine.connect() as conn:
+            row = conn.execute(
+                sa.select(workstreams.c.user_id).where(workstreams.c.ws_id == "ws1")
+            ).fetchone()
+            assert row is not None
+            assert row[0] is None
@@ -20,7 +20,7 @@ class FakeSession:
        self.messages = []


-def _fake_factory(ui, model_alias=None):
+def _fake_factory(ui, model_alias=None, ws_id=None):
    return FakeSession()


@@ -440,8 +440,10 @@ class TestManagerThreadSafety:
        for t in threads:
            t.join()

-        assert mgr.count == 5
-        assert len(errors) == 5
+        # All threads resolved (created or rejected)
+        assert len(created) + len(errors) == 10
+        # Never exceeded capacity
+        assert mgr.count <= 5

    def test_concurrent_switch(self):
        """Concurrent switches should not corrupt state."""
@@ -1,3 +1,3 @@
 """turnstone - Multi-node AI orchestration platform with tool use, agent routing, and cluster simulation."""

-__version__ = "0.3.5"
+__version__ = "0.4.3"
@@ -0,0 +1,186 @@
+"""CLI admin commands for user and token management.
+
+Entry point: turnstone-admin
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+import uuid
+from typing import Any
+
+
+def _get_storage() -> Any:
+    """Initialize and return the storage backend."""
+    from turnstone.core.storage import init_storage
+
+    db_backend = os.environ.get("TURNSTONE_DB_BACKEND", "sqlite")
+    db_url = os.environ.get("TURNSTONE_DB_URL", "")
+    db_path = os.environ.get("TURNSTONE_DB_PATH", "")
+    return init_storage(db_backend, path=db_path, url=db_url)
+
+
+def _cmd_create_user(args: argparse.Namespace) -> None:
+    import getpass
+
+    from turnstone.core.auth import (
+        generate_token,
+        hash_password,
+        hash_token,
+        is_valid_username,
+        token_prefix,
+    )
+
+    if not is_valid_username(args.username):
+        print("Error: invalid username (1-64 chars: letters, digits, . _ -)", file=sys.stderr)
+        sys.exit(1)
+
+    storage = _get_storage()
+    user_id = uuid.uuid4().hex
+
+    # Prompt for password
+    password = args.password
+    if not password:
+        password = getpass.getpass("Password: ")
+        confirm = getpass.getpass("Confirm password: ")
+        if password != confirm:
+            print("Error: passwords do not match", file=sys.stderr)
+            sys.exit(1)
+
+    pw_hash = hash_password(password)
+    storage.create_user(user_id, args.username, args.name, pw_hash)
+    print(f"Created user: {user_id}")
+    print(f"  Username: {args.username}")
+    print(f"  Name: {args.name}")
+
+    if args.token:
+        scopes = args.scopes or "read,write,approve"
+        raw = generate_token()
+        tid = uuid.uuid4().hex
+        storage.create_api_token(
+            token_id=tid,
+            token_hash=hash_token(raw),
+            token_prefix=token_prefix(raw),
+            user_id=user_id,
+            name="initial",
+            scopes=scopes,
+        )
+        print(f"\n  Token: {raw}")
+        print(f"  Token ID: {tid}")
+        print(f"  Scopes: {scopes}")
+        print("  (Save this token now — it cannot be retrieved again)")
+
+
+def _cmd_create_token(args: argparse.Namespace) -> None:
+    from turnstone.core.auth import generate_token, hash_token, token_prefix
+
+    storage = _get_storage()
+
+    if storage.get_user(args.user) is None:
+        print(f"Error: user {args.user} not found", file=sys.stderr)
+        sys.exit(1)
+
+    expires = None
+    if args.expires_days:
+        from datetime import UTC, datetime, timedelta
+
+        expires = (datetime.now(UTC) + timedelta(days=args.expires_days)).strftime(
+            "%Y-%m-%dT%H:%M:%S"
+        )
+
+    raw = generate_token()
+    tid = uuid.uuid4().hex
+    storage.create_api_token(
+        token_id=tid,
+        token_hash=hash_token(raw),
+        token_prefix=token_prefix(raw),
+        user_id=args.user,
+        name=args.name or "",
+        scopes=args.scopes,
+        expires=expires,
+    )
+    print(f"Token: {raw}")
+    print(f"  ID: {tid}")
+    print(f"  Scopes: {args.scopes}")
+    if expires:
+        print(f"  Expires: {expires}")
+    print("  (Save this token now — it cannot be retrieved again)")
+
+
+def _cmd_list_users(args: argparse.Namespace) -> None:
+    storage = _get_storage()
+    users = storage.list_users()
+    if not users:
+        print("No users found.")
+        return
+    for u in users:
+        print(f"  {u['user_id'][:12]}..  {u['display_name']}  ({u['created']})")
+
+
+def _cmd_list_tokens(args: argparse.Namespace) -> None:
+    storage = _get_storage()
+    tokens = storage.list_api_tokens(args.user)
+    if not tokens:
+        print(f"No tokens found for user {args.user}.")
+        return
+    for t in tokens:
+        exp = f"  expires={t['expires']}" if t.get("expires") else ""
+        print(
+            f"  {t['token_id'][:12]}..  {t['token_prefix']}..  scopes={t['scopes']}"
+            f"  name={t['name']}{exp}"
+        )
+
+
+def _cmd_revoke_token(args: argparse.Namespace) -> None:
+    storage = _get_storage()
+    if storage.delete_api_token(args.token_id):
+        print(f"Revoked token {args.token_id}")
+    else:
+        print("Token not found", file=sys.stderr)
+        sys.exit(1)
+
+
+def main() -> None:
+    """Entry point for turnstone-admin CLI."""
+    parser = argparse.ArgumentParser(
+        prog="turnstone-admin",
+        description="Turnstone user and token administration",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    p_cu = sub.add_parser("create-user", help="Create a new user")
+    p_cu.add_argument("--username", required=True, help="Login username")
+    p_cu.add_argument("--name", required=True, help="Display name")
+    p_cu.add_argument("--password", default="", help="Password (prompted if not provided)")
+    p_cu.add_argument("--token", action="store_true", help="Also create an initial API token")
+    p_cu.add_argument("--scopes", default="read,write,approve", help="Scopes for initial token")
+
+    p_ct = sub.add_parser("create-token", help="Create an API token for a user")
+    p_ct.add_argument("--user", required=True, help="User ID")
+    p_ct.add_argument("--name", default="", help="Human label for the token")
+    p_ct.add_argument("--scopes", default="read,write", help="Comma-separated scopes")
+    p_ct.add_argument("--expires-days", type=int, default=None, help="Days until expiry")
+
+    sub.add_parser("list-users", help="List all users")
+
+    p_lt = sub.add_parser("list-tokens", help="List tokens for a user")
+    p_lt.add_argument("--user", required=True, help="User ID")
+
+    p_rt = sub.add_parser("revoke-token", help="Revoke an API token")
+    p_rt.add_argument("--token-id", required=True, help="Token ID to revoke")
+
+    args = parser.parse_args()
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+
+    dispatch = {
+        "create-user": _cmd_create_user,
+        "create-token": _cmd_create_token,
+        "list-users": _cmd_list_users,
+        "list-tokens": _cmd_list_tokens,
+        "revoke-token": _cmd_revoke_token,
+    }
+    dispatch[args.command](args)
@@ -20,8 +20,22 @@ from turnstone.api.openapi import EndpointSpec, QueryParam, build_openapi
 from turnstone.api.schemas import (
    AuthLoginRequest,
    AuthLoginResponse,
+    AuthSetupRequest,
+    AuthSetupResponse,
+    AuthStatusResponse,
+    CreateScheduleRequest,
+    CreateTokenRequest,
+    CreateTokenResponse,
+    CreateUserRequest,
    ErrorResponse,
+    ListScheduleRunsResponse,
+    ListSchedulesResponse,
+    ListTokensResponse,
+    ListUsersResponse,
+    ScheduleInfo,
    StatusResponse,
+    UpdateScheduleRequest,
+    UserInfo,
 )

 CONSOLE_ENDPOINTS: list[EndpointSpec] = [
@@ -103,6 +117,22 @@ CONSOLE_ENDPOINTS: list[EndpointSpec] = [
        error_codes=[401],
        tags=["Auth"],
    ),
+    EndpointSpec(
+        "/v1/api/auth/setup",
+        "POST",
+        "Create first admin user",
+        request_model=AuthSetupRequest,
+        response_model=AuthSetupResponse,
+        error_codes=[400, 409, 503],
+        tags=["Auth"],
+    ),
+    EndpointSpec(
+        "/v1/api/auth/status",
+        "GET",
+        "Return auth state",
+        response_model=AuthStatusResponse,
+        tags=["Auth"],
+    ),
    EndpointSpec(
        "/v1/api/auth/logout",
        "POST",
@@ -110,6 +140,108 @@ CONSOLE_ENDPOINTS: list[EndpointSpec] = [
        response_model=StatusResponse,
        tags=["Auth"],
    ),
+    # --- Admin ---
+    EndpointSpec(
+        "/v1/api/admin/users",
+        "GET",
+        "List all users",
+        response_model=ListUsersResponse,
+        tags=["Admin"],
+    ),
+    EndpointSpec(
+        "/v1/api/admin/users",
+        "POST",
+        "Create a user",
+        request_model=CreateUserRequest,
+        response_model=UserInfo,
+        tags=["Admin"],
+    ),
+    EndpointSpec(
+        "/v1/api/admin/users/{user_id}",
+        "DELETE",
+        "Delete a user and their tokens",
+        response_model=StatusResponse,
+        error_codes=[404],
+        tags=["Admin"],
+    ),
+    EndpointSpec(
+        "/v1/api/admin/users/{user_id}/tokens",
+        "GET",
+        "List tokens for a user",
+        response_model=ListTokensResponse,
+        tags=["Admin"],
+    ),
+    EndpointSpec(
+        "/v1/api/admin/users/{user_id}/tokens",
+        "POST",
+        "Create an API token (raw token shown once)",
+        request_model=CreateTokenRequest,
+        response_model=CreateTokenResponse,
+        tags=["Admin"],
+    ),
+    EndpointSpec(
+        "/v1/api/admin/tokens/{token_id}",
+        "DELETE",
+        "Revoke an API token",
+        response_model=StatusResponse,
+        error_codes=[404],
+        tags=["Admin"],
+    ),
+    # --- Schedules ---
+    EndpointSpec(
+        "/v1/api/admin/schedules",
+        "GET",
+        "List all scheduled tasks",
+        response_model=ListSchedulesResponse,
+        tags=["Schedules"],
+    ),
+    EndpointSpec(
+        "/v1/api/admin/schedules",
+        "POST",
+        "Create a scheduled task",
+        request_model=CreateScheduleRequest,
+        response_model=ScheduleInfo,
+        error_codes=[400],
+        tags=["Schedules"],
+    ),
+    EndpointSpec(
+        "/v1/api/admin/schedules/{task_id}",
+        "GET",
+        "Get a scheduled task",
+        response_model=ScheduleInfo,
+        error_codes=[404],
+        tags=["Schedules"],
+    ),
+    EndpointSpec(
+        "/v1/api/admin/schedules/{task_id}",
+        "PUT",
+        "Update a scheduled task",
+        request_model=UpdateScheduleRequest,
+        response_model=ScheduleInfo,
+        error_codes=[400, 404],
+        tags=["Schedules"],
+    ),
+    EndpointSpec(
+        "/v1/api/admin/schedules/{task_id}",
+        "DELETE",
+        "Delete a scheduled task",
+        response_model=StatusResponse,
+        error_codes=[404],
+        tags=["Schedules"],
+    ),
+    EndpointSpec(
+        "/v1/api/admin/schedules/{task_id}/runs",
+        "GET",
+        "List run history for a scheduled task",
+        response_model=ListScheduleRunsResponse,
+        query_params=[
+            QueryParam(
+                "limit", "Max results (default 50, max 200)", schema_type="integer", default=50
+            ),
+        ],
+        error_codes=[404],
+        tags=["Schedules"],
+    ),
    # --- Observability ---
    EndpointSpec(
        "/health",
@@ -125,6 +257,15 @@ _ALL_MODELS: list[type[BaseModel]] = [
    StatusResponse,
    AuthLoginRequest,
    AuthLoginResponse,
+    AuthSetupRequest,
+    AuthSetupResponse,
+    AuthStatusResponse,
+    CreateUserRequest,
+    UserInfo,
+    ListUsersResponse,
+    CreateTokenRequest,
+    CreateTokenResponse,
+    ListTokensResponse,
    ClusterOverviewResponse,
    ClusterNodesResponse,
    ClusterWorkstreamsResponse,
@@ -132,6 +273,11 @@ _ALL_MODELS: list[type[BaseModel]] = [
    ConsoleCreateWsRequest,
    ConsoleCreateWsResponse,
    ConsoleHealthResponse,
+    CreateScheduleRequest,
+    UpdateScheduleRequest,
+    ScheduleInfo,
+    ListSchedulesResponse,
+    ListScheduleRunsResponse,
 ]


@@ -35,13 +35,207 @@ class StatusResponse(BaseModel):


 class AuthLoginRequest(BaseModel):
-    """POST /v1/api/auth/login request body."""
+    """POST /v1/api/auth/login request body.

-    token: str = Field(description="Bearer token to authenticate")
+    Either username+password or token must be provided.
+    """
+
+    username: str = Field(default="", description="Login username")
+    password: str = Field(default="", description="Login password")
+    token: str = Field(default="", description="Legacy: bearer token to authenticate")


 class AuthLoginResponse(BaseModel):
    """POST /v1/api/auth/login success response."""

    status: str = Field(default="ok")
-    role: str = Field(description="Assigned role", examples=["full", "read"])
+    user_id: str = Field(default="", description="Authenticated user ID")
+    role: str = Field(description="Legacy role", examples=["full", "read"])
+    scopes: str = Field(
+        default="", description="Comma-separated scopes", examples=["read,write,approve"]
+    )
+    jwt: str = Field(default="", description="JWT session token (if JWT auth is configured)")
+
+
+# ---------------------------------------------------------------------------
+# Admin — User identity + API tokens
+# ---------------------------------------------------------------------------
+
+
+class CreateUserRequest(BaseModel):
+    """POST /v1/api/admin/users request body."""
+
+    username: str = Field(description="Login username (unique)")
+    display_name: str = Field(description="Human-readable display name")
+    password: str = Field(description="Initial password")
+
+
+class UserInfo(BaseModel):
+    """User record (no password_hash)."""
+
+    user_id: str
+    username: str
+    display_name: str
+    created: str
+
+
+class ListUsersResponse(BaseModel):
+    """GET /v1/api/admin/users response."""
+
+    users: list[UserInfo]
+
+
+class CreateTokenRequest(BaseModel):
+    """POST /v1/api/admin/users/{user_id}/tokens request body."""
+
+    name: str = Field(default="", description="Human label for the token")
+    scopes: str = Field(
+        default="read,write,approve",
+        description="Comma-separated scopes: read, write, approve",
+    )
+    expires_days: int | None = Field(
+        default=None,
+        description="Days until expiry (null = no expiry)",
+    )
+
+
+class TokenInfo(BaseModel):
+    """Token metadata (never includes the hash or raw token)."""
+
+    token_id: str
+    token_prefix: str
+    name: str
+    scopes: str
+    created: str
+    expires: str | None = None
+
+
+class CreateTokenResponse(BaseModel):
+    """POST /v1/api/admin/users/{user_id}/tokens response (raw token shown once)."""
+
+    token: str = Field(description="Raw API token — save this, it cannot be retrieved again")
+    token_id: str
+    token_prefix: str
+    scopes: str
+
+
+class ListTokensResponse(BaseModel):
+    """GET /v1/api/admin/users/{user_id}/tokens response."""
+
+    tokens: list[TokenInfo]
+
+
+# ---------------------------------------------------------------------------
+# Auth — Setup + status
+# ---------------------------------------------------------------------------
+
+
+class AuthSetupRequest(BaseModel):
+    """POST /v1/api/auth/setup request body."""
+
+    username: str = Field(description="Login username (1-64 ASCII characters)")
+    display_name: str = Field(description="Display name")
+    password: str = Field(description="Password (minimum 8 characters)")
+
+
+class AuthSetupResponse(BaseModel):
+    """POST /v1/api/auth/setup success response."""
+
+    status: str = Field(default="ok")
+    user_id: str
+    username: str
+    role: str = Field(default="full")
+    scopes: str = Field(default="approve,read,write")
+    jwt: str = Field(default="", description="JWT session token")
+
+
+class AuthStatusResponse(BaseModel):
+    """GET /v1/api/auth/status response."""
+
+    auth_enabled: bool
+    has_users: bool
+    setup_required: bool
+
+
+# ---------------------------------------------------------------------------
+# Schedules
+# ---------------------------------------------------------------------------
+
+
+class CreateScheduleRequest(BaseModel):
+    """POST /v1/api/admin/schedules request body."""
+
+    name: str = Field(description="Human-readable schedule name")
+    description: str = Field(default="", description="Optional description")
+    schedule_type: str = Field(description="'cron' or 'at'")
+    cron_expr: str = Field(default="", description="Cron expression (when schedule_type='cron')")
+    at_time: str = Field(default="", description="ISO8601 timestamp (when schedule_type='at')")
+    target_mode: str = Field(default="auto", description="auto, pool, all, or specific node_id")
+    model: str = Field(default="", description="Model alias for the workstream")
+    initial_message: str = Field(description="Message sent to the new workstream")
+    auto_approve: bool = Field(default=False)
+    auto_approve_tools: list[str] = Field(default_factory=list)
+    enabled: bool = Field(default=True)
+
+
+class UpdateScheduleRequest(BaseModel):
+    """PUT /v1/api/admin/schedules/{task_id} request body (partial update)."""
+
+    name: str | None = None
+    description: str | None = None
+    schedule_type: str | None = None
+    cron_expr: str | None = None
+    at_time: str | None = None
+    target_mode: str | None = None
+    model: str | None = None
+    initial_message: str | None = None
+    auto_approve: bool | None = None
+    auto_approve_tools: list[str] | None = None
+    enabled: bool | None = None
+
+
+class ScheduleInfo(BaseModel):
+    """Scheduled task details."""
+
+    task_id: str
+    name: str
+    description: str = ""
+    schedule_type: str
+    cron_expr: str = ""
+    at_time: str = ""
+    target_mode: str = "auto"
+    model: str = ""
+    initial_message: str
+    auto_approve: bool = False
+    auto_approve_tools: list[str] = Field(default_factory=list)
+    enabled: bool = True
+    created_by: str = ""
+    last_run: str | None = None
+    next_run: str | None = None
+    created: str = ""
+    updated: str = ""
+
+
+class ListSchedulesResponse(BaseModel):
+    """GET /v1/api/admin/schedules response."""
+
+    schedules: list[ScheduleInfo]
+
+
+class ScheduleRunInfo(BaseModel):
+    """Single execution record for a scheduled task."""
+
+    run_id: str
+    task_id: str
+    node_id: str = ""
+    ws_id: str = ""
+    correlation_id: str = ""
+    started: str
+    status: str = "dispatched"
+    error: str = ""
+
+
+class ListScheduleRunsResponse(BaseModel):
+    """GET /v1/api/admin/schedules/{task_id}/runs response."""
+
+    runs: list[ScheduleRunInfo]
@@ -39,11 +39,19 @@ class CreateWorkstreamRequest(BaseModel):
    name: str = Field(default="", description="Workstream display name (auto-generated if empty)")
    model: str = Field(default="", description="Model alias from registry")
    auto_approve: bool = Field(default=False, description="Auto-approve all tool calls")
+    resume_ws: str = Field(
+        default="",
+        description="Workstream ID to resume atomically during creation (empty = fresh start)",
+    )


 class CreateWorkstreamResponse(BaseModel):
    ws_id: str = Field(description="Unique ID of the new workstream")
    name: str = Field(description="Assigned workstream name")
+    resumed: bool = Field(default=False, description="Whether a previous workstream was resumed")
+    message_count: int = Field(
+        default=0, description="Number of messages in the resumed workstream"
+    )


 class CloseWorkstreamRequest(BaseModel):
@@ -59,7 +67,6 @@ class WorkstreamInfo(BaseModel):
    id: str
    name: str
    state: str
-    session_id: str | None = None


 class ListWorkstreamsResponse(BaseModel):
@@ -70,7 +77,6 @@ class DashboardWorkstream(BaseModel):
    id: str
    name: str
    state: str
-    session_id: str | None = None
    title: str = ""
    tokens: int = 0
    context_ratio: float = 0.0
@@ -97,12 +103,12 @@ class DashboardResponse(BaseModel):


 # ---------------------------------------------------------------------------
-# Sessions
+# Saved workstreams
 # ---------------------------------------------------------------------------


-class SessionInfo(BaseModel):
-    session_id: str
+class SavedWorkstreamInfo(BaseModel):
+    ws_id: str
    alias: str | None = None
    title: str | None = None
    created: str
@@ -110,8 +116,8 @@ class SessionInfo(BaseModel):
    message_count: int


-class ListSessionsResponse(BaseModel):
-    sessions: list[SessionInfo]
+class ListSavedWorkstreamsResponse(BaseModel):
+    workstreams: list[SavedWorkstreamInfo]


 # ---------------------------------------------------------------------------
@@ -11,6 +11,9 @@ if TYPE_CHECKING:
 from turnstone.api.schemas import (
    AuthLoginRequest,
    AuthLoginResponse,
+    AuthSetupRequest,
+    AuthSetupResponse,
+    AuthStatusResponse,
    ErrorResponse,
    StatusResponse,
 )
@@ -22,7 +25,7 @@ from turnstone.api.server_schemas import (
    CreateWorkstreamResponse,
    DashboardResponse,
    HealthResponse,
-    ListSessionsResponse,
+    ListSavedWorkstreamsResponse,
    ListWorkstreamsResponse,
    PlanFeedbackRequest,
    SendRequest,
@@ -119,13 +122,13 @@ SERVER_ENDPOINTS: list[EndpointSpec] = [
        "across all workstreams. Returns text/event-stream.",
        tags=["Streaming"],
    ),
-    # --- Sessions ---
+    # --- Saved workstreams ---
    EndpointSpec(
-        "/v1/api/sessions",
+        "/v1/api/workstreams/saved",
        "GET",
-        "List saved sessions",
-        response_model=ListSessionsResponse,
-        tags=["Sessions"],
+        "List saved workstreams",
+        response_model=ListSavedWorkstreamsResponse,
+        tags=["Workstreams"],
    ),
    # --- Auth ---
    EndpointSpec(
@@ -137,6 +140,22 @@ SERVER_ENDPOINTS: list[EndpointSpec] = [
        error_codes=[401],
        tags=["Auth"],
    ),
+    EndpointSpec(
+        "/v1/api/auth/setup",
+        "POST",
+        "Create first admin user",
+        request_model=AuthSetupRequest,
+        response_model=AuthSetupResponse,
+        error_codes=[400, 409, 503],
+        tags=["Auth"],
+    ),
+    EndpointSpec(
+        "/v1/api/auth/status",
+        "GET",
+        "Return auth state",
+        response_model=AuthStatusResponse,
+        tags=["Auth"],
+    ),
    EndpointSpec(
        "/v1/api/auth/logout",
        "POST",
@@ -159,6 +178,9 @@ _ALL_MODELS: list[type[BaseModel]] = [
    StatusResponse,
    AuthLoginRequest,
    AuthLoginResponse,
+    AuthSetupRequest,
+    AuthSetupResponse,
+    AuthStatusResponse,
    SendRequest,
    SendResponse,
    ApproveRequest,
@@ -169,7 +191,7 @@ _ALL_MODELS: list[type[BaseModel]] = [
    CloseWorkstreamRequest,
    ListWorkstreamsResponse,
    DashboardResponse,
-    ListSessionsResponse,
+    ListSavedWorkstreamsResponse,
    HealthResponse,
 ]

@@ -0,0 +1,15 @@
+"""Shared channel infrastructure for turnstone communication integrations.
+
+Provides the :class:`ChannelAdapter` protocol, the :class:`ChannelEvent`
+normalized event type, the :class:`ChannelRouter` for workstream mapping,
+and shared formatting / configuration utilities.
+"""
+
+from turnstone.channels._protocol import ChannelAdapter, ChannelEvent
+from turnstone.channels._routing import ChannelRouter
+
+__all__ = [
+    "ChannelAdapter",
+    "ChannelEvent",
+    "ChannelRouter",
+]
@@ -0,0 +1,23 @@
+"""Base configuration shared by all channel adapters."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ChannelConfig:
+    """Base configuration shared by all channel adapters.
+
+    Individual adapters extend this with platform-specific fields (tokens,
+    guild IDs, etc.).
+    """
+
+    redis_host: str = "localhost"
+    redis_port: int = 6379
+    redis_db: int = 0
+    redis_password: str | None = None
+    prefix: str = "turnstone"
+    model: str = ""
+    auto_approve: bool = False
+    auto_approve_tools: list[str] = field(default_factory=list)
@@ -0,0 +1,116 @@
+"""Message formatting utilities for channel adapters.
+
+Handles chunking long messages for platforms with character limits, formatting
+tool-approval requests, and plan-review prompts.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def chunk_message(text: str, max_length: int = 2000) -> list[str]:
+    """Split *text* into chunks that fit within *max_length*.
+
+    Respects code-block boundaries: if a fenced code block (````` ```)
+    spans a chunk boundary the current chunk is closed with ````` ``` ``
+    and the next chunk reopens it.  Prefers splitting at newline
+    boundaries, then word boundaries, then hard-splits.
+    """
+    if len(text) <= max_length:
+        return [text]
+
+    chunks: list[str] = []
+    remaining = text
+    in_code_block = False
+
+    while remaining:
+        if len(remaining) <= max_length:
+            chunks.append(remaining)
+            break
+
+        # Reserve space for a closing ``` if we're inside a code block.
+        limit = max_length - 4 if in_code_block else max_length
+        limit = max(limit, 1)
+
+        candidate = remaining[:limit]
+
+        # Prefer a newline boundary.
+        split_idx = candidate.rfind("\n")
+        if split_idx <= 0:
+            # Fall back to a word boundary.
+            split_idx = candidate.rfind(" ")
+        if split_idx <= 0:
+            # Hard split.
+            split_idx = limit
+
+        chunk = remaining[:split_idx]
+        remaining = remaining[split_idx:].lstrip("\n")
+
+        # Track code-block fences in this chunk.
+        fence_count = chunk.count("```")
+        block_open = in_code_block
+
+        if fence_count % 2 != 0:
+            in_code_block = not in_code_block
+
+        # If we end inside a code block, close it in this chunk and
+        # reopen in the next.
+        if in_code_block:
+            chunk += "\n```"
+            remaining = "```\n" + remaining
+            in_code_block = False
+        elif block_open and fence_count % 2 != 0:
+            # We were inside a code block and the chunk closed it
+            # properly -- nothing extra needed.
+            pass
+
+        chunks.append(chunk)
+
+    return chunks
+
+
+def format_approval_request(items: list[dict[str, Any]]) -> str:
+    """Format tool-approval *items* into a human-readable message.
+
+    Items use the server's SSE format: ``func_name``, ``preview``,
+    ``approval_label``, ``header``.  Falls back to the nested
+    ``function.name`` format for compatibility.
+    """
+    lines: list[str] = ["**Tool approval required:**"]
+    for item in items:
+        # Server SSE format: top-level func_name / preview
+        name = item.get("func_name") or item.get("approval_label", "")
+        if not name:
+            # Fallback: nested function.name (SDK / older format)
+            func = item.get("function", {})
+            name = func.get("name", "unknown")
+        preview = item.get("preview", "")
+        if not preview:
+            args = item.get("function", {}).get("arguments", "")
+            if isinstance(args, dict):
+                import json
+
+                args = json.dumps(args, ensure_ascii=False)
+            preview = str(args)
+        preview = truncate(preview)
+        header = item.get("header", "")
+        if header:
+            lines.append(f"\u2022 `{name}`: {header}")
+        elif preview:
+            lines.append(f"\u2022 `{name}`: {preview}")
+        else:
+            lines.append(f"\u2022 `{name}`")
+    return "\n".join(lines)
+
+
+def format_plan_review(content: str) -> str:
+    """Format a plan-review prompt with a header."""
+    return f"**Plan review requested:**\n\n{content}"
+
+
+def truncate(text: str, max_length: int = 200) -> str:
+    """Truncate *text* to *max_length*, appending an ellipsis if trimmed."""
+    if len(text) <= max_length:
+        return text
+    return text[: max_length - 1] + "\u2026"
@@ -0,0 +1,195 @@
+"""Lightweight HTTP server for the channel gateway.
+
+Runs alongside the channel adapters (Discord, etc.) to receive notification
+requests from the bridge.  Exposes ``POST /v1/api/notify`` and ``GET /health``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import socket
+import uuid
+from typing import TYPE_CHECKING, Any
+
+from starlette.applications import Starlette
+from starlette.responses import JSONResponse
+from starlette.routing import Mount, Route
+
+from turnstone.core.log import get_logger
+
+if TYPE_CHECKING:
+    from starlette.requests import Request
+
+    from turnstone.channels._protocol import ChannelAdapter
+    from turnstone.core.storage._protocol import StorageBackend
+
+log = get_logger(__name__)
+
+
+async def _handle_health(request: Request) -> JSONResponse:
+    return JSONResponse({"status": "ok", "service": "channel"})
+
+
+def _check_auth(request: Request) -> JSONResponse | None:
+    """Validate the request's Authorization header.  Returns an error response or None."""
+    auth_token: str = getattr(request.app.state, "auth_token", "")
+    jwt_secret: str = getattr(request.app.state, "jwt_secret", "")
+
+    if not auth_token and not jwt_secret:
+        log.warning("notify.auth_not_configured")
+        return JSONResponse({"error": "authentication not configured"}, status_code=401)
+
+    header = request.headers.get("Authorization", "")
+    if not header.startswith("Bearer "):
+        return JSONResponse({"error": "Unauthorized"}, status_code=401)
+
+    token = header[7:]
+
+    # Static token check
+    if auth_token:
+        import hmac
+
+        if hmac.compare_digest(token, auth_token):
+            return None
+
+    # JWT check
+    if jwt_secret and "." in token:
+        from turnstone.core.auth import JWT_AUD_CHANNEL, validate_jwt
+
+        result = validate_jwt(token, jwt_secret, audience=JWT_AUD_CHANNEL)
+        if result is not None:
+            return None
+
+    return JSONResponse({"error": "Unauthorized"}, status_code=401)
+
+
+async def _handle_notify(request: Request) -> JSONResponse:
+    """Deliver a notification to one or more channel adapters."""
+    auth_err = _check_auth(request)
+    if auth_err is not None:
+        return auth_err
+
+    adapters: dict[str, ChannelAdapter] = request.app.state.adapters
+    storage: StorageBackend = request.app.state.storage
+
+    try:
+        body: dict[str, Any] = await request.json()
+    except (json.JSONDecodeError, ValueError):
+        return JSONResponse({"error": "invalid JSON"}, status_code=400)
+
+    target = body.get("target")
+    message = body.get("message", "").strip() if isinstance(body.get("message"), str) else ""
+    title = body.get("title", "").strip() if isinstance(body.get("title"), str) else ""
+
+    if not target or not message:
+        return JSONResponse({"error": "target and message are required"}, status_code=400)
+
+    content = f"**{title}**\n{message}" if title else message
+
+    # Resolve targets
+    targets: list[tuple[str, str]] = []
+    if "username" in target:
+        user = await asyncio.to_thread(storage.get_user_by_username, target["username"])
+        if user is None:
+            log.warning("notify.user_not_found", username=target["username"])
+            return JSONResponse(
+                {"error": "target not found or has no linked channels"},
+                status_code=404,
+            )
+        links = await asyncio.to_thread(storage.list_channel_users_by_user, user["user_id"])
+        for link in links:
+            targets.append((link["channel_type"], link["channel_user_id"]))
+        if not targets:
+            log.warning("notify.user_no_linked_channels", username=target["username"])
+            return JSONResponse(
+                {"error": "target not found or has no linked channels"},
+                status_code=404,
+            )
+    elif "channel_type" in target and "channel_id" in target:
+        targets.append((target["channel_type"], target["channel_id"]))
+    else:
+        return JSONResponse(
+            {"error": "target must have username or channel_type+channel_id"},
+            status_code=400,
+        )
+
+    results: list[dict[str, str]] = []
+    for channel_type, channel_id in targets:
+        adapter = adapters.get(channel_type)
+        if adapter is None:
+            results.append(
+                {
+                    "channel_type": channel_type,
+                    "channel_id": channel_id,
+                    "status": "no_adapter",
+                }
+            )
+            log.warning(
+                "notify.no_adapter",
+                channel_type=channel_type,
+                channel_id=channel_id,
+            )
+            continue
+        try:
+            msg_id = await adapter.send(channel_id, content)
+            results.append(
+                {
+                    "channel_type": channel_type,
+                    "channel_id": channel_id,
+                    "status": "sent",
+                    "message_id": msg_id,
+                }
+            )
+            log.info(
+                "notify.delivered",
+                channel_type=channel_type,
+                channel_id=channel_id,
+                message_id=msg_id,
+            )
+        except Exception:
+            log.exception(
+                "notify.delivery_failed",
+                channel_type=channel_type,
+                channel_id=channel_id,
+            )
+            results.append(
+                {
+                    "channel_type": channel_type,
+                    "channel_id": channel_id,
+                    "status": "failed",
+                }
+            )
+
+    return JSONResponse({"results": results})
+
+
+def create_channel_app(
+    adapters: dict[str, ChannelAdapter],
+    storage: StorageBackend,
+    *,
+    auth_token: str = "",
+    jwt_secret: str = "",
+) -> Starlette:
+    """Create the channel gateway HTTP application."""
+    app = Starlette(
+        routes=[
+            Route("/health", _handle_health),
+            Mount(
+                "/v1",
+                routes=[
+                    Route("/api/notify", _handle_notify, methods=["POST"]),
+                ],
+            ),
+        ],
+    )
+    app.state.adapters = adapters
+    app.state.storage = storage
+    app.state.auth_token = auth_token
+    app.state.jwt_secret = jwt_secret
+    return app
+
+
+def _get_service_id() -> str:
+    """Generate a unique service ID from hostname + random suffix."""
+    return f"channel-{socket.gethostname()}-{uuid.uuid4().hex[:8]}"
@@ -0,0 +1,70 @@
+"""Channel adapter protocol and normalized event type.
+
+Defines the :class:`ChannelEvent` data class for inbound events and the
+:class:`ChannelAdapter` structural protocol that all bidirectional channel
+adapters (Discord, Slack, etc.) must satisfy.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+
+@dataclass
+class ChannelEvent:
+    """Normalized inbound event from any channel."""
+
+    channel_type: str  # "discord", "slack"
+    channel_id: str  # thread/channel ID
+    channel_user_id: str  # platform user ID
+    message: str
+    parent_channel_id: str = ""  # main channel (for thread creation)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@runtime_checkable
+class ChannelAdapter(Protocol):
+    """Protocol for bidirectional channel adapters."""
+
+    channel_type: str
+
+    async def start(self) -> None:
+        """Connect to the platform and begin listening for events."""
+        ...
+
+    async def stop(self) -> None:
+        """Disconnect and release resources."""
+        ...
+
+    async def send(self, channel_id: str, content: str) -> str:
+        """Send a message to a channel. Returns the platform message ID."""
+        ...
+
+    async def edit_message(self, channel_id: str, message_id: str, content: str) -> None:
+        """Edit an existing message in a channel."""
+        ...
+
+    async def send_approval_request(
+        self,
+        channel_id: str,
+        ws_id: str,
+        correlation_id: str,
+        items: list[dict[str, Any]],
+    ) -> None:
+        """Send an interactive tool-approval prompt to a channel."""
+        ...
+
+    async def send_plan_review(
+        self,
+        channel_id: str,
+        ws_id: str,
+        correlation_id: str,
+        content: str,
+    ) -> None:
+        """Send a plan-review prompt to a channel."""
+        ...
+
+    async def create_thread(self, parent_channel_id: str, name: str, message_id: str = "") -> str:
+        """Create a thread under a parent channel. Returns the new thread ID."""
+        ...
@@ -0,0 +1,297 @@
+"""Channel router -- maps external channels/threads to turnstone workstreams.
+
+:class:`ChannelRouter` uses the async Redis broker for MQ communication and
+the storage backend for persistent channel-to-workstream mappings.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING
+
+from turnstone.core.log import get_logger
+from turnstone.mq.protocol import (
+    ApproveMessage,
+    CreateWorkstreamMessage,
+    OutboundEvent,
+    PlanFeedbackMessage,
+    SendMessage,
+    WorkstreamClosedEvent,
+    WorkstreamCreatedEvent,
+)
+
+if TYPE_CHECKING:
+    from turnstone.core.storage import StorageBackend
+    from turnstone.mq.async_broker import AsyncRedisBroker
+
+log = get_logger(__name__)
+
+_WS_CREATE_TIMEOUT = 30.0  # seconds
+
+
+class ChannelRouter:
+    """Manage channel-to-workstream routing and MQ message dispatch.
+
+    Parameters
+    ----------
+    broker:
+        An :class:`AsyncRedisBroker` used for pub/sub and queue operations.
+    storage:
+        A :class:`StorageBackend` instance for persistent route lookups.
+        All storage calls are synchronous and will be wrapped in
+        :func:`asyncio.to_thread`.
+    """
+
+    def __init__(
+        self,
+        broker: AsyncRedisBroker,
+        storage: StorageBackend,
+        *,
+        auto_approve: bool = False,
+        auto_approve_tools: list[str] | None = None,
+    ) -> None:
+        self._broker = broker
+        self._storage = storage
+        self._auto_approve = auto_approve
+        self._auto_approve_tools: list[str] = auto_approve_tools or []
+        self._pending: dict[str, asyncio.Event] = {}
+        self._pending_results: dict[str, str] = {}
+        self._global_task: asyncio.Task[None] | None = None
+        self._create_locks: dict[str, asyncio.Lock] = {}
+
+    # -- lifecycle -----------------------------------------------------------
+
+    async def start(self) -> None:
+        """Subscribe to global events for workstream lifecycle."""
+        channel = f"{self._broker._prefix}:events:global"
+        await self._broker.subscribe(channel, self._on_global_event)
+        log.info("channel_router.started", channel=channel)
+
+    async def stop(self) -> None:
+        """Unsubscribe and clean up pending state."""
+        channel = f"{self._broker._prefix}:events:global"
+        await self._broker.unsubscribe(channel)
+        # Wake any waiters so they don't hang forever.
+        for evt in self._pending.values():
+            evt.set()
+        self._pending.clear()
+        self._pending_results.clear()
+        log.info("channel_router.stopped")
+
+    # -- event handler -------------------------------------------------------
+
+    async def _on_global_event(self, raw: str) -> None:
+        """Handle events on the global pub/sub channel.
+
+        Exceptions are caught so the broker listener task stays alive.
+        """
+        try:
+            event = OutboundEvent.from_json(raw)
+
+            if isinstance(event, WorkstreamCreatedEvent):
+                cid = event.correlation_id
+                if cid in self._pending:
+                    self._pending_results[cid] = event.ws_id
+                    self._pending[cid].set()
+                    log.debug(
+                        "channel_router.ws_created",
+                        ws_id=event.ws_id,
+                        correlation_id=cid,
+                    )
+
+            elif isinstance(event, WorkstreamClosedEvent):
+                ws_id = event.ws_id
+                route = await asyncio.to_thread(self._storage.get_channel_route_by_ws, ws_id)
+                if route:
+                    # Don't delete the route — the workstream may have been evicted
+                    # and the thread can reactivate it.  Route cleanup only happens
+                    # via explicit /close or delete_route().
+                    log.info(
+                        "channel_router.ws_closed_route_kept",
+                        ws_id=ws_id,
+                        channel_type=route["channel_type"],
+                        channel_id=route["channel_id"],
+                    )
+        except Exception:
+            log.exception("channel_router.global_event_error")
+
+    # -- workstream management -----------------------------------------------
+
+    async def get_or_create_workstream(
+        self,
+        channel_type: str,
+        channel_id: str,
+        name: str = "",
+        model: str = "",
+        initial_message: str = "",
+    ) -> tuple[str, bool]:
+        """Look up or create a workstream for a channel.
+
+        Returns ``(ws_id, is_new)`` where *is_new* is ``True`` when a new
+        workstream was created.
+
+        A per-channel lock prevents duplicate workstreams when concurrent
+        messages arrive for the same channel before the first creation
+        completes.
+        """
+        key = f"{channel_type}:{channel_id}"
+        lock = self._create_locks.setdefault(key, asyncio.Lock())
+
+        old_ws_id: str | None = None
+
+        async with lock:
+            # 1. Check for existing route.
+            old_ws_id = ""
+            route = await asyncio.to_thread(
+                self._storage.get_channel_route, channel_type, channel_id
+            )
+            if route:
+                # Verify the workstream is still alive (owned by a bridge node).
+                owner = await self._broker.get_ws_owner(route["ws_id"])
+                if owner:
+                    return route["ws_id"], False
+                # Workstream was evicted/closed — capture old ws_id for
+                # resume, then remove the stale route.
+                old_ws_id = route["ws_id"]
+                await asyncio.to_thread(
+                    self._storage.delete_channel_route, channel_type, channel_id
+                )
+                log.info(
+                    "channel_router.stale_route_cleared",
+                    ws_id=old_ws_id,
+                    channel_type=channel_type,
+                    channel_id=channel_id,
+                )
+
+            # 2. Create via MQ with atomic resume (reuse old ws_id directly).
+            resume_ws = old_ws_id or ""
+            msg = CreateWorkstreamMessage(
+                name=name,
+                model=model,
+                initial_message="" if resume_ws else initial_message,
+                resume_ws=resume_ws,
+                auto_approve=self._auto_approve,
+                auto_approve_tools=list(self._auto_approve_tools),
+            )
+            cid = msg.correlation_id
+            waiter = asyncio.Event()
+            self._pending[cid] = waiter
+
+            await self._broker.push_inbound(msg.to_json())
+            log.info(
+                "channel_router.creating_workstream",
+                correlation_id=cid,
+                channel_type=channel_type,
+                channel_id=channel_id,
+                resume_ws=resume_ws or None,
+            )
+
+            try:
+                await asyncio.wait_for(waiter.wait(), timeout=_WS_CREATE_TIMEOUT)
+            except TimeoutError:
+                self._pending.pop(cid, None)
+                self._pending_results.pop(cid, None)
+                raise
+
+            ws_id = self._pending_results.pop(cid, "")
+            self._pending.pop(cid, None)
+
+            if not ws_id:
+                msg_err = "workstream creation returned empty ws_id"
+                raise RuntimeError(msg_err)
+
+            # 4. Persist the route.
+            await asyncio.to_thread(
+                self._storage.create_channel_route, channel_type, channel_id, ws_id
+            )
+            log.info(
+                "channel_router.route_created",
+                ws_id=ws_id,
+                channel_type=channel_type,
+                channel_id=channel_id,
+            )
+
+            return ws_id, True
+
+    # -- user resolution -----------------------------------------------------
+
+    async def resolve_user(self, channel_type: str, channel_user_id: str) -> str | None:
+        """Resolve an external platform user to a turnstone ``user_id``.
+
+        Returns ``None`` if no mapping exists.
+        """
+        result = await asyncio.to_thread(
+            self._storage.get_channel_user, channel_type, channel_user_id
+        )
+        if result is None:
+            return None
+        return result.get("user_id")
+
+    # -- message dispatch ----------------------------------------------------
+
+    async def send_message(self, ws_id: str, message: str) -> str:
+        """Push a :class:`SendMessage` to the broker.
+
+        Returns the ``correlation_id`` of the submitted message.
+        """
+        msg = SendMessage(
+            ws_id=ws_id,
+            message=message,
+            auto_approve=self._auto_approve,
+            auto_approve_tools=list(self._auto_approve_tools),
+        )
+        await self._broker.push_inbound(msg.to_json())
+        log.debug("channel_router.send_message", ws_id=ws_id, correlation_id=msg.correlation_id)
+        return msg.correlation_id
+
+    async def send_approval(
+        self,
+        ws_id: str,
+        correlation_id: str,
+        approved: bool,
+        feedback: str = "",
+        always: bool = False,
+    ) -> None:
+        """Push an :class:`ApproveMessage` to the broker response queue."""
+        msg = ApproveMessage(
+            ws_id=ws_id,
+            request_id=correlation_id,
+            approved=approved,
+            feedback=feedback or None,
+            always=always,
+        )
+        await self._broker.push_response(correlation_id, msg.to_json())
+        log.debug(
+            "channel_router.send_approval",
+            ws_id=ws_id,
+            correlation_id=correlation_id,
+            approved=approved,
+        )
+
+    async def send_plan_feedback(self, ws_id: str, correlation_id: str, feedback: str) -> None:
+        """Push a :class:`PlanFeedbackMessage` to the broker response queue."""
+        msg = PlanFeedbackMessage(
+            ws_id=ws_id,
+            request_id=correlation_id,
+            feedback=feedback,
+        )
+        await self._broker.push_response(correlation_id, msg.to_json())
+        log.debug(
+            "channel_router.send_plan_feedback",
+            ws_id=ws_id,
+            correlation_id=correlation_id,
+        )
+
+    # -- route management ----------------------------------------------------
+
+    async def delete_route(self, channel_type: str, channel_id: str) -> None:
+        """Remove a channel-to-workstream mapping."""
+        deleted = await asyncio.to_thread(
+            self._storage.delete_channel_route, channel_type, channel_id
+        )
+        log.info(
+            "channel_router.delete_route",
+            channel_type=channel_type,
+            channel_id=channel_id,
+            deleted=deleted,
+        )
@@ -0,0 +1,238 @@
+"""Unified channel gateway entry point.
+
+Launches one or more channel adapters (Discord, Slack, etc.) connected to
+the turnstone cluster via Redis MQ.  An HTTP server runs alongside for
+inbound notification delivery from the server.
+
+Run as: ``turnstone-channel --discord-token $TURNSTONE_DISCORD_TOKEN``
+"""
+
+from __future__ import annotations
+
+import os
+import socket
+import sys
+
+
+def main() -> None:
+    """Parse arguments, initialize storage and broker, and run adapters."""
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="turnstone channel gateway — bridges messaging platforms to the turnstone cluster"
+    )
+
+    # -- Redis ---------------------------------------------------------------
+    from turnstone.mq.broker import add_redis_args
+
+    add_redis_args(parser)
+
+    # -- Discord -------------------------------------------------------------
+    parser.add_argument(
+        "--discord-token",
+        default=os.environ.get("TURNSTONE_DISCORD_TOKEN", ""),
+        help="Discord bot token (default: $TURNSTONE_DISCORD_TOKEN)",
+    )
+    parser.add_argument(
+        "--discord-guild",
+        type=int,
+        default=0,
+        help="Restrict to a single Discord guild (0 = all, default: %(default)s)",
+    )
+    parser.add_argument(
+        "--discord-channels",
+        default="",
+        help="Comma-separated list of allowed Discord channel IDs (default: all)",
+    )
+
+    # -- HTTP server ---------------------------------------------------------
+    parser.add_argument(
+        "--http-host",
+        default="127.0.0.1",
+        help="HTTP server bind address (default: %(default)s)",
+    )
+    parser.add_argument(
+        "--http-port",
+        type=int,
+        default=int(os.environ.get("TURNSTONE_CHANNEL_PORT", "8091")),
+        help="HTTP server port (default: $TURNSTONE_CHANNEL_PORT or 8091)",
+    )
+
+    # -- Auth ----------------------------------------------------------------
+    parser.add_argument(
+        "--auth-token",
+        default=os.environ.get("TURNSTONE_CHANNEL_AUTH_TOKEN", ""),
+        help="Static auth token for /v1/api/notify (default: $TURNSTONE_CHANNEL_AUTH_TOKEN)",
+    )
+
+    # -- Workstream defaults -------------------------------------------------
+    parser.add_argument(
+        "--model",
+        default="",
+        help="Default model for new workstreams (default: server default)",
+    )
+    parser.add_argument(
+        "--auto-approve",
+        action="store_true",
+        help="Auto-approve all tool calls",
+    )
+
+    # -- Logging -------------------------------------------------------------
+    from turnstone.core.log import add_log_args
+
+    add_log_args(parser)
+
+    args = parser.parse_args()
+
+    # -- Logging setup -------------------------------------------------------
+    from turnstone.core.log import configure_logging_from_args
+
+    configure_logging_from_args(args, "channel")
+
+    from turnstone.core.log import get_logger
+
+    log = get_logger(__name__)
+
+    # -- Storage -------------------------------------------------------------
+    from turnstone.core.storage._registry import init_storage
+
+    db_backend = os.environ.get("TURNSTONE_DB_BACKEND", "sqlite")
+    db_url = os.environ.get("TURNSTONE_DB_URL", "")
+    db_path = os.environ.get("TURNSTONE_DB_PATH", "")
+
+    init_storage(
+        backend=db_backend,
+        url=db_url,
+        path=db_path,
+    )
+
+    # -- Auth config ---------------------------------------------------------
+    auth_token = args.auth_token
+    jwt_secret = os.environ.get("TURNSTONE_JWT_SECRET", "").strip()
+
+    # -- Broker --------------------------------------------------------------
+    from turnstone.mq.broker import async_broker_from_args
+
+    broker = async_broker_from_args(args)
+
+    # -- Adapter selection ---------------------------------------------------
+    adapters_configured = False
+
+    if args.discord_token:
+        adapters_configured = True
+
+    if not adapters_configured:
+        print(
+            "Error: no channel adapters configured. "
+            "Set --discord-token or $TURNSTONE_DISCORD_TOKEN.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    # -- Run -----------------------------------------------------------------
+    if args.discord_token:
+        import asyncio
+
+        from turnstone.channels._http import _get_service_id, create_channel_app
+        from turnstone.channels.discord.bot import TurnstoneBot
+        from turnstone.channels.discord.config import DiscordConfig
+        from turnstone.core.storage._registry import get_storage
+
+        allowed_channels: list[int] = []
+        if args.discord_channels:
+            allowed_channels = [
+                int(c.strip()) for c in args.discord_channels.split(",") if c.strip()
+            ]
+
+        config = DiscordConfig(
+            redis_host=args.redis_host,
+            redis_port=args.redis_port,
+            redis_db=args.redis_db,
+            redis_password=args.redis_password,
+            model=args.model,
+            auto_approve=args.auto_approve,
+            bot_token=args.discord_token,
+            guild_id=args.discord_guild,
+            allowed_channels=allowed_channels,
+        )
+
+        storage = get_storage()
+        bot = TurnstoneBot(config, broker, storage)
+        adapters = {"discord": bot}
+
+        # Create HTTP app for notification delivery
+        channel_app = create_channel_app(
+            adapters,  # type: ignore[arg-type]
+            storage,
+            auth_token=auth_token,
+            jwt_secret=jwt_secret,
+        )
+
+        log.info(
+            "channel.starting",
+            adapter="discord",
+            guild_id=config.guild_id,
+            http_port=args.http_port,
+        )
+
+        async def _run_all() -> None:
+            """Run Discord bot + HTTP server + service heartbeat concurrently."""
+            import uvicorn
+
+            service_id = _get_service_id()
+
+            # Resolve advertise URL — env override for Docker/K8s,
+            # otherwise derive from bind address.
+            advertise_url = os.environ.get("TURNSTONE_CHANNEL_ADVERTISE_URL", "").strip()
+            if not advertise_url:
+                if args.http_host in ("0.0.0.0", "::"):
+                    advertise_host = socket.gethostname()
+                else:
+                    advertise_host = args.http_host
+                advertise_url = f"http://{advertise_host}:{args.http_port}"
+            service_url = advertise_url
+
+            # Register in service registry
+            storage.register_service("channel", service_id, service_url)
+            log.info(
+                "channel.service_registered",
+                service_id=service_id,
+                url=service_url,
+            )
+
+            async def _heartbeat_loop() -> None:
+                """Periodically update service heartbeat."""
+                while True:
+                    await asyncio.sleep(30)
+                    try:
+                        await asyncio.to_thread(storage.heartbeat_service, "channel", service_id)
+                    except Exception:
+                        log.exception("channel.heartbeat_failed")
+
+            uv_config = uvicorn.Config(
+                channel_app,
+                host=args.http_host,
+                port=args.http_port,
+                log_level="warning",
+            )
+            server = uvicorn.Server(uv_config)
+
+            heartbeat_task = asyncio.create_task(_heartbeat_loop())
+            try:
+                await asyncio.gather(
+                    bot.start(),
+                    server.serve(),
+                )
+            finally:
+                heartbeat_task.cancel()
+                await asyncio.to_thread(storage.deregister_service, "channel", service_id)
+                log.info("channel.service_deregistered", service_id=service_id)
+
+        import contextlib
+
+        with contextlib.suppress(KeyboardInterrupt):
+            asyncio.run(_run_all())
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,9 @@
+"""Discord channel adapter for turnstone."""
+
+from turnstone.channels.discord.bot import TurnstoneBot
+from turnstone.channels.discord.config import DiscordConfig
+
+__all__ = [
+    "DiscordConfig",
+    "TurnstoneBot",
+]
@@ -0,0 +1,383 @@
+"""Discord bot adapter — connects Discord threads to turnstone workstreams.
+
+:class:`TurnstoneBot` extends ``discord.ext.commands.Bot`` and manages the
+lifecycle of event subscriptions, streaming message edits, and interactive
+approval / plan-review views.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from turnstone.channels._formatter import chunk_message
+from turnstone.channels._routing import ChannelRouter
+from turnstone.core.log import get_logger
+from turnstone.mq.protocol import (
+    ApprovalRequestEvent,
+    ContentEvent,
+    ErrorEvent,
+    OutboundEvent,
+    PlanReviewEvent,
+    TurnCompleteEvent,
+    WorkstreamResumedEvent,
+)
+
+if TYPE_CHECKING:
+    import discord
+    from discord.ext import commands
+
+    from turnstone.channels.discord.config import DiscordConfig
+    from turnstone.core.storage._protocol import StorageBackend
+    from turnstone.mq.async_broker import AsyncRedisBroker
+
+log = get_logger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# StreamingMessage helper
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class StreamingMessage:
+    """Accumulates streamed content and periodically edits a Discord message.
+
+    Discord rate-limits message edits, so we batch content updates and flush
+    at a configurable interval.  On finalize we send any remaining content
+    and chunk if the total exceeds the platform limit.
+    """
+
+    channel: discord.abc.Messageable
+    max_length: int = 2000
+    edit_interval: float = 1.5
+    _message: discord.Message | None = field(default=None, init=False, repr=False)
+    _buffer: list[str] = field(default_factory=list, init=False, repr=False)
+    _last_edit: float = field(default=0.0, init=False, repr=False)
+
+    async def append(self, text: str) -> None:
+        """Add *text* to the buffer and edit the message if the interval has elapsed."""
+        self._buffer.append(text)
+        now = time.monotonic()
+        if now - self._last_edit >= self.edit_interval:
+            await self._flush()
+
+    async def finalize(self) -> None:
+        """Flush any remaining buffered content, chunking if necessary."""
+        content = "".join(self._buffer)
+        if not content:
+            return
+
+        if self._message is not None:
+            # Final edit — may need chunking if content grew beyond the limit.
+            chunks = chunk_message(content, self.max_length)
+            try:
+                await self._message.edit(content=chunks[0])
+            except Exception:
+                log.debug("streaming_message.edit_failed_on_finalize")
+            # Any overflow chunks are sent as new messages.
+            for chunk in chunks[1:]:
+                await self.channel.send(chunk)
+        else:
+            # Never sent an initial message — send all chunks now.
+            for chunk in chunk_message(content, self.max_length):
+                await self.channel.send(chunk)
+
+    async def _flush(self) -> None:
+        """Edit or create the message with the current buffer contents."""
+        content = "".join(self._buffer)
+        if not content:
+            return
+
+        # Truncate to max_length for the in-progress edit (finalize handles overflow).
+        display = content[: self.max_length]
+
+        try:
+            if self._message is None:
+                self._message = await self.channel.send(display)
+            else:
+                await self._message.edit(content=display)
+        except Exception:
+            log.debug("streaming_message.flush_failed")
+        self._last_edit = time.monotonic()
+
+
+# ---------------------------------------------------------------------------
+# TurnstoneBot
+# ---------------------------------------------------------------------------
+
+
+class TurnstoneBot:
+    """Discord bot that bridges Discord threads to turnstone workstreams.
+
+    Parameters
+    ----------
+    config:
+        Discord-specific configuration.
+    broker:
+        Async Redis broker for MQ communication.
+    storage:
+        Storage backend for persistent route / user lookups.
+    """
+
+    channel_type: str = "discord"
+
+    def __init__(
+        self,
+        config: DiscordConfig,
+        broker: AsyncRedisBroker,
+        storage: StorageBackend,
+    ) -> None:
+        import discord
+        from discord.ext import commands
+
+        self.config = config
+        self.broker = broker
+        self.storage = storage
+        self.router = ChannelRouter(
+            broker,
+            storage,
+            auto_approve=config.auto_approve,
+            auto_approve_tools=list(config.auto_approve_tools),
+        )
+
+        self._subscribed_ws: set[str] = set()
+        self._streaming: dict[str, StreamingMessage] = {}
+
+        intents = discord.Intents.default()
+        intents.message_content = True
+
+        self._bot: commands.Bot = commands.Bot(
+            command_prefix="!ts ",
+            intents=intents,
+            help_command=None,
+        )
+
+        # Attach ourselves so cogs can access the TurnstoneBot instance.
+        self._bot.turnstone = self  # type: ignore[attr-defined]
+
+        # Register lifecycle hooks.
+        self._bot.setup_hook = self._setup_hook  # type: ignore[method-assign]
+
+        @self._bot.event
+        async def on_ready() -> None:
+            await self._on_ready()
+
+    # -- lifecycle -----------------------------------------------------------
+
+    async def _setup_hook(self) -> None:
+        """Called by discord.py after login but before connecting to the gateway."""
+        from turnstone.channels.discord.cog import MessageCog
+        from turnstone.channels.discord.views import ApprovalView, PlanReviewView
+
+        await self.broker.connect()
+        await self.router.start()
+
+        msg_cog = MessageCog(self._bot)
+        await self._bot.add_cog(msg_cog._cog)
+
+        # Register persistent views so button callbacks survive restarts.
+        self._bot.add_view(ApprovalView(self)._view)
+        self._bot.add_view(PlanReviewView(self)._view)
+
+        log.info("discord.setup_hook_complete")
+
+    async def _on_ready(self) -> None:
+        """Sync slash commands and recover existing routes."""
+        import discord
+
+        bot = self._bot
+        log.info("discord.ready", user=str(bot.user), guild_count=len(bot.guilds))
+
+        if self.config.guild_id:
+            guild = discord.Object(id=self.config.guild_id)
+            bot.tree.copy_global_to(guild=guild)
+            await bot.tree.sync(guild=guild)
+            log.info("discord.commands_synced", guild_id=self.config.guild_id)
+        else:
+            await bot.tree.sync()
+            log.info("discord.commands_synced_global")
+
+        await self._recover_routes()
+
+    async def _recover_routes(self) -> None:
+        """Re-subscribe to event channels for existing discord routes.
+
+        Queries the storage backend for all channel routes of type ``discord``
+        and subscribes to each workstream's event channel.
+        """
+        routes = await asyncio.to_thread(self.storage.list_channel_routes_by_type, "discord")
+        for route in routes:
+            ws_id = route["ws_id"]
+            channel_id = int(route["channel_id"])
+            channel = self._bot.get_channel(channel_id)
+            if channel is not None:
+                await self.subscribe_ws(ws_id, channel)  # type: ignore[arg-type]
+                log.info("discord.route_recovered", ws_id=ws_id, channel_id=channel_id)
+            else:
+                log.warning(
+                    "discord.route_recovery_channel_missing",
+                    ws_id=ws_id,
+                    channel_id=channel_id,
+                )
+
+    # -- subscription management ---------------------------------------------
+
+    async def subscribe_ws(
+        self,
+        ws_id: str,
+        thread: discord.abc.Messageable,
+    ) -> None:
+        """Subscribe to workstream events and dispatch them to *thread*."""
+        if ws_id in self._subscribed_ws:
+            return
+
+        channel = f"{self.broker._prefix}:events:{ws_id}"
+
+        async def _callback(raw: str) -> None:
+            await self._on_ws_event(ws_id, thread, raw)
+
+        await self.broker.subscribe(channel, _callback)
+        self._subscribed_ws.add(ws_id)
+        log.info("discord.subscribed", ws_id=ws_id)
+
+    async def unsubscribe_ws(self, ws_id: str) -> None:
+        """Cancel the subscription for *ws_id* and clean up streaming state."""
+        channel = f"{self.broker._prefix}:events:{ws_id}"
+        await self.broker.unsubscribe(channel)
+        self._subscribed_ws.discard(ws_id)
+        self._streaming.pop(ws_id, None)
+        log.info("discord.unsubscribed", ws_id=ws_id)
+
+    # -- event dispatch ------------------------------------------------------
+
+    async def _on_ws_event(
+        self,
+        ws_id: str,
+        thread: discord.abc.Messageable,
+        raw: str,
+    ) -> None:
+        """Handle an outbound event for a subscribed workstream."""
+        import discord
+
+        from turnstone.channels._formatter import format_approval_request, format_plan_review
+        from turnstone.channels.discord.views import ApprovalView, PlanReviewView
+
+        event = OutboundEvent.from_json(raw)
+
+        if isinstance(event, ContentEvent):
+            sm = self._streaming.get(ws_id)
+            if sm is None:
+                sm = StreamingMessage(
+                    channel=thread,
+                    max_length=self.config.max_message_length,
+                    edit_interval=self.config.streaming_edit_interval,
+                )
+                self._streaming[ws_id] = sm
+            await sm.append(event.text)
+
+        elif isinstance(event, ApprovalRequestEvent):
+            if self.config.auto_approve or self._should_auto_approve(event):
+                await self.router.send_approval(ws_id, event.correlation_id, approved=True)
+                await thread.send("*Tool auto-approved.*")
+            else:
+                text = format_approval_request(event.items)
+                embed = discord.Embed(
+                    title="Tool Approval Required",
+                    description=text,
+                    color=discord.Color.orange(),
+                )
+                embed.set_footer(text=f"{ws_id}|{event.correlation_id}")
+                await thread.send(embed=embed, view=ApprovalView(self)._view)
+
+        elif isinstance(event, PlanReviewEvent):
+            text = format_plan_review(event.content)
+            embed = discord.Embed(
+                title="Plan Review",
+                description=text,
+                color=discord.Color.blue(),
+            )
+            embed.set_footer(text=f"{ws_id}|{event.correlation_id}")
+            await thread.send(embed=embed, view=PlanReviewView(self)._view)
+
+        elif isinstance(event, TurnCompleteEvent):
+            sm = self._streaming.pop(ws_id, None)
+            if sm is not None:
+                await sm.finalize()
+
+        elif isinstance(event, WorkstreamResumedEvent):
+            name = event.name or "previous workstream"
+            count = event.message_count
+            await thread.send(f"*Resumed: {name} ({count} messages restored)*")
+
+        elif isinstance(event, ErrorEvent):
+            safe_msg = event.message[:500] if event.message else "An error occurred"
+            await thread.send(f"**Error:** {safe_msg}")
+
+    # -- helpers -------------------------------------------------------------
+
+    def _should_auto_approve(self, event: ApprovalRequestEvent) -> bool:
+        """Return True if all tools in *event.items* are in the auto-approve list."""
+        allowed = self.config.auto_approve_tools
+        if not allowed or not event.items:
+            return False
+        for item in event.items:
+            # Support both server SSE format (func_name) and OpenAI format (function.name).
+            name = (
+                item.get("func_name")
+                or item.get("approval_label")
+                or item.get("function", {}).get("name", "")
+            )
+            if name not in allowed:
+                return False
+        return True
+
+    def _is_allowed_channel(self, channel_id: int) -> bool:
+        """Return True if *channel_id* is in the allowed list (or list is empty)."""
+        if not self.config.allowed_channels:
+            return True
+        return channel_id in self.config.allowed_channels
+
+    def run(self, **kwargs: object) -> None:
+        """Start the bot (blocking). Pass-through to ``commands.Bot.run``."""
+        self._bot.run(self.config.bot_token, log_handler=None, **kwargs)  # type: ignore[arg-type]
+
+    async def start(self) -> None:
+        """Start the bot (async). Use this for multi-adapter ``asyncio.gather``."""
+        await self._bot.start(self.config.bot_token, reconnect=True)
+
+    async def send(self, channel_id: str, content: str) -> str:
+        """Send a message to a Discord channel or user DM.
+
+        Implements the :class:`ChannelAdapter` protocol.  Tries the ID as a
+        channel first; if not found, attempts a user DM.  Long messages are
+        chunked via :func:`chunk_message`.
+        """
+        import discord
+
+        int_id = int(channel_id)
+        target: discord.abc.Messageable | None = self._bot.get_channel(int_id)  # type: ignore[assignment]
+        if target is None:
+            try:
+                user = await self._bot.fetch_user(int_id)
+                target = await user.create_dm()
+            except discord.NotFound as exc:
+                raise ValueError(f"Discord channel/user {channel_id} not found") from exc
+
+        content = discord.utils.escape_mentions(content)
+        chunks = chunk_message(content, self.config.max_message_length)
+        msg: discord.Message | None = None
+        for chunk in chunks:
+            msg = await target.send(chunk)  # type: ignore[union-attr]
+
+        return str(msg.id) if msg else ""
+
+    async def stop(self) -> None:
+        """Disconnect the bot and clean up subscriptions."""
+        for ws_id in list(self._subscribed_ws):
+            await self.unsubscribe_ws(ws_id)
+        await self.router.stop()
+        await self.broker.close()
+        await self._bot.close()
@@ -0,0 +1,399 @@
+"""Message handling cog for the Discord channel adapter.
+
+Handles ``on_message`` events and slash commands (``/link``, ``/unlink``,
+``/ask``, ``/status``, ``/close``).
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING
+
+from turnstone.core.log import get_logger
+from turnstone.mq.protocol import CloseWorkstreamMessage
+
+if TYPE_CHECKING:
+    import discord
+    from discord.ext import commands
+
+    from turnstone.channels.discord.bot import TurnstoneBot
+
+log = get_logger(__name__)
+
+_THREAD_NAME_MAX = 100
+
+
+class MessageCog:
+    """Cog that processes messages and registers slash commands.
+
+    Accessed via ``bot.turnstone`` to reach the :class:`TurnstoneBot` wrapper.
+    """
+
+    def __init__(self, bot: commands.Bot) -> None:
+        import discord
+        from discord import app_commands
+        from discord.ext import commands as _commands
+
+        self.bot = bot
+        self.ts: TurnstoneBot = bot.turnstone  # type: ignore[attr-defined]
+
+        # -- Cog wiring (manual since we can't use decorators with guarded imports) --
+
+        # We build the cog dynamically so discord.py's import is fully deferred.
+        cog_self = self
+
+        class _Cog(_commands.Cog, name="Turnstone"):  # type: ignore[call-arg]
+            """Turnstone Discord integration."""
+
+            @_commands.Cog.listener()
+            async def on_message(self_cog: _Cog, message: discord.Message) -> None:  # noqa: N805
+                await cog_self._on_message(message)
+
+            @app_commands.command(name="link", description="Link your Discord account to Turnstone")
+            async def link(self_cog: _Cog, interaction: discord.Interaction) -> None:  # noqa: N805
+                await interaction.response.send_modal(cog_self._link_modal_cls(cog_self))
+
+            @app_commands.command(
+                name="unlink", description="Unlink your Discord account from Turnstone"
+            )
+            async def unlink(self_cog: _Cog, interaction: discord.Interaction) -> None:  # noqa: N805
+                await cog_self._cmd_unlink(interaction)
+
+            @app_commands.command(name="ask", description="Start a new Turnstone workstream")
+            @app_commands.describe(message="Your message to the assistant")
+            async def ask(self_cog: _Cog, interaction: discord.Interaction, message: str) -> None:  # noqa: N805
+                await cog_self._cmd_ask(interaction, message)
+
+            @app_commands.command(name="status", description="Show workstream status")
+            async def status(self_cog: _Cog, interaction: discord.Interaction) -> None:  # noqa: N805
+                await cog_self._cmd_status(interaction)
+
+            @app_commands.command(name="close", description="Close the current workstream")
+            async def close(self_cog: _Cog, interaction: discord.Interaction) -> None:  # noqa: N805
+                await cog_self._cmd_close(interaction)
+
+        self._cog = _Cog()
+
+        # -- Modal for /link (avoids token appearing in slash command audit logs) --
+        class _LinkTokenModal(discord.ui.Modal, title="Link Account"):  # type: ignore[call-arg]
+            token: discord.ui.TextInput[_LinkTokenModal] = discord.ui.TextInput(
+                label="API Token",
+                style=discord.TextStyle.short,
+                placeholder="Paste your ts_... API token",
+                required=True,
+            )
+
+            def __init__(modal_self, cog: MessageCog) -> None:  # noqa: N805
+                super().__init__()
+                modal_self._cog = cog
+
+            async def on_submit(modal_self, interaction: discord.Interaction) -> None:  # noqa: N805
+                await modal_self._cog._cmd_link(interaction, str(modal_self.token))
+
+        self._link_modal_cls = _LinkTokenModal
+
+    # -- on_message ----------------------------------------------------------
+
+    async def _on_message(self, message: discord.Message) -> None:
+        """Route incoming messages to existing workstream threads."""
+        import discord
+
+        # Ignore self and other bots.
+        if message.author == self.bot.user or message.author.bot:
+            return
+
+        # Ignore DMs.
+        if message.guild is None:
+            return
+
+        channel = message.channel
+
+        # --- Message in a Discord Thread ---
+        if isinstance(channel, discord.Thread):
+            parent_id = channel.parent_id or 0
+            if not self.ts._is_allowed_channel(parent_id):
+                return
+
+            # Check if this thread has an existing route.
+            route = await asyncio.to_thread(
+                self.ts.storage.get_channel_route, "discord", str(channel.id)
+            )
+            if route is None:
+                # Not our thread — ignore.
+                return
+
+            # Resolve user.
+            user_id = await self.ts.router.resolve_user("discord", str(message.author.id))
+            if user_id is None:
+                return
+
+            # Use get_or_create_workstream so stale routes (evicted ws) are
+            # auto-refreshed with a new workstream.
+            try:
+                ws_id, is_new = await self.ts.router.get_or_create_workstream(
+                    "discord",
+                    str(channel.id),
+                    name=channel.name or "",
+                    initial_message="",
+                )
+            except (TimeoutError, RuntimeError):
+                log.warning("discord.ws_reactivation_failed", thread_id=channel.id)
+                return
+
+            if is_new:
+                await channel.send("*Workstream reactivated.*")
+
+            # Ensure subscription is active (handles bot restart recovery).
+            if ws_id not in self.ts._subscribed_ws:
+                await self.ts.subscribe_ws(ws_id, channel)
+
+            await self.ts.router.send_message(ws_id, message.content)
+            log.debug(
+                "discord.message_routed",
+                ws_id=ws_id,
+                thread_id=channel.id,
+                author=str(message.author),
+            )
+            return
+
+        # --- @mention in a non-thread channel ---
+        if self.bot.user is not None and self.bot.user.mentioned_in(message):
+            if not self.ts._is_allowed_channel(channel.id):
+                return
+
+            user_id = await self.ts.router.resolve_user("discord", str(message.author.id))
+            if user_id is None:
+                return
+
+            # Strip the mention from the message text.
+            content = message.content
+            if self.bot.user is not None:
+                content = content.replace(f"<@{self.bot.user.id}>", "").strip()
+                content = content.replace(f"<@!{self.bot.user.id}>", "").strip()
+
+            if not content:
+                content = "Hello"
+
+            # Create a thread from the message.
+            thread_name = content[:_THREAD_NAME_MAX] if len(content) > _THREAD_NAME_MAX else content
+            thread = await message.create_thread(
+                name=thread_name,
+                auto_archive_duration=self.ts.config.thread_auto_archive,  # type: ignore[arg-type]
+            )
+
+            # Create workstream with the initial message.
+            ws_id, _is_new = await self.ts.router.get_or_create_workstream(
+                channel_type="discord",
+                channel_id=str(thread.id),
+                name=thread_name,
+                model=self.ts.config.model,
+                initial_message=content,
+            )
+
+            await self.ts.subscribe_ws(ws_id, thread)
+            log.info(
+                "discord.workstream_created",
+                ws_id=ws_id,
+                thread_id=thread.id,
+                author=str(message.author),
+            )
+
+    # -- slash commands ------------------------------------------------------
+
+    async def _cmd_link(self, interaction: discord.Interaction, token: str) -> None:
+        """Link a Discord user to a turnstone account via API token."""
+        from turnstone.core.auth import hash_token
+
+        # Check if already linked.
+        existing = await asyncio.to_thread(
+            self.ts.storage.get_channel_user, "discord", str(interaction.user.id)
+        )
+        if existing:
+            await interaction.response.send_message(
+                "Your Discord account is already linked. Use `/unlink` first.",
+                ephemeral=True,
+            )
+            return
+
+        token_hash = hash_token(token)
+        token_record = await asyncio.to_thread(self.ts.storage.get_api_token_by_hash, token_hash)
+
+        if token_record is None:
+            await interaction.response.send_message(
+                "Invalid token. Please provide a valid Turnstone API token.",
+                ephemeral=True,
+            )
+            return
+
+        user_id = token_record.get("user_id", "")
+        if not user_id:
+            await interaction.response.send_message(
+                "Token has no associated user.",
+                ephemeral=True,
+            )
+            return
+
+        await asyncio.to_thread(
+            self.ts.storage.create_channel_user,
+            "discord",
+            str(interaction.user.id),
+            user_id,
+        )
+
+        await interaction.response.send_message("Account linked!", ephemeral=True)
+        log.info(
+            "discord.user_linked",
+            discord_user=str(interaction.user),
+            user_id=user_id,
+        )
+
+    async def _cmd_unlink(self, interaction: discord.Interaction) -> None:
+        """Remove the channel user mapping for the calling Discord user."""
+        deleted = await asyncio.to_thread(
+            self.ts.storage.delete_channel_user,
+            "discord",
+            str(interaction.user.id),
+        )
+        if deleted:
+            await interaction.response.send_message("Account unlinked.", ephemeral=True)
+            log.info("discord.user_unlinked", discord_user=str(interaction.user))
+        else:
+            await interaction.response.send_message(
+                "No linked account found.",
+                ephemeral=True,
+            )
+
+    async def _cmd_ask(self, interaction: discord.Interaction, message: str) -> None:
+        """Create a new thread and workstream with an initial message."""
+        import discord
+
+        user_id = await self.ts.router.resolve_user("discord", str(interaction.user.id))
+        if user_id is None:
+            await interaction.response.send_message(
+                "Your Discord account is not linked. Use `/link` first.",
+                ephemeral=True,
+            )
+            return
+
+        await interaction.response.defer()
+
+        channel = interaction.channel
+        if channel is None:
+            await interaction.followup.send("Cannot determine channel.", ephemeral=True)
+            return
+
+        thread_name = message[:_THREAD_NAME_MAX] if len(message) > _THREAD_NAME_MAX else message
+
+        # Create a standalone thread in the current channel.
+        if isinstance(channel, discord.TextChannel):
+            thread = await channel.create_thread(
+                name=thread_name,
+                auto_archive_duration=self.ts.config.thread_auto_archive,  # type: ignore[arg-type]
+                type=discord.ChannelType.public_thread,
+            )
+        else:
+            await interaction.followup.send(
+                "Cannot create a thread in this channel type.",
+                ephemeral=True,
+            )
+            return
+
+        ws_id, _is_new = await self.ts.router.get_or_create_workstream(
+            channel_type="discord",
+            channel_id=str(thread.id),
+            name=thread_name,
+            model=self.ts.config.model,
+            initial_message=message,
+        )
+
+        await self.ts.subscribe_ws(ws_id, thread)
+
+        await interaction.followup.send(
+            f"Workstream started in {thread.mention}",
+            ephemeral=True,
+        )
+        log.info(
+            "discord.ask_workstream_created",
+            ws_id=ws_id,
+            thread_id=thread.id,
+            author=str(interaction.user),
+        )
+
+    async def _cmd_status(self, interaction: discord.Interaction) -> None:
+        """Show workstream status for the current thread."""
+        import discord
+
+        channel = interaction.channel
+        if not isinstance(channel, discord.Thread):
+            await interaction.response.send_message(
+                "This command can only be used inside a thread.",
+                ephemeral=True,
+            )
+            return
+
+        route = await asyncio.to_thread(
+            self.ts.storage.get_channel_route, "discord", str(channel.id)
+        )
+        if route is None:
+            await interaction.response.send_message(
+                "No workstream is associated with this thread.",
+                ephemeral=True,
+            )
+            return
+
+        ws_id = route["ws_id"]
+        node_id = route.get("node_id", "")
+        created = route.get("created", "")
+
+        embed = discord.Embed(
+            title="Workstream Status",
+            color=discord.Color.green(),
+        )
+        embed.add_field(name="Workstream ID", value=ws_id, inline=False)
+        if node_id:
+            embed.add_field(name="Node", value=node_id, inline=True)
+        if created:
+            embed.add_field(name="Created", value=created, inline=True)
+
+        await interaction.response.send_message(embed=embed, ephemeral=True)
+
+    async def _cmd_close(self, interaction: discord.Interaction) -> None:
+        """Close the workstream and archive the thread."""
+        import discord
+
+        channel = interaction.channel
+        if not isinstance(channel, discord.Thread):
+            await interaction.response.send_message(
+                "This command can only be used inside a thread.",
+                ephemeral=True,
+            )
+            return
+
+        route = await asyncio.to_thread(
+            self.ts.storage.get_channel_route, "discord", str(channel.id)
+        )
+        if route is None:
+            await interaction.response.send_message(
+                "No workstream is associated with this thread.",
+                ephemeral=True,
+            )
+            return
+
+        ws_id = route["ws_id"]
+
+        # Close via MQ.
+        msg = CloseWorkstreamMessage(ws_id=ws_id)
+        await self.ts.broker.push_inbound(msg.to_json())
+
+        # Delete route and unsubscribe.
+        await self.ts.router.delete_route("discord", str(channel.id))
+        await self.ts.unsubscribe_ws(ws_id)
+
+        await interaction.response.send_message("Workstream closed.")
+        log.info("discord.workstream_closed", ws_id=ws_id, thread_id=channel.id)
+
+        # Archive the thread.
+        try:
+            await channel.edit(archived=True)
+        except discord.Forbidden:
+            log.warning("discord.archive_forbidden", thread_id=channel.id)
@@ -0,0 +1,23 @@
+"""Discord-specific configuration."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from turnstone.channels._config import ChannelConfig
+
+
+@dataclass
+class DiscordConfig(ChannelConfig):
+    """Configuration for the Discord channel adapter.
+
+    Extends :class:`ChannelConfig` with Discord-specific settings such as
+    the bot token, guild restriction, and streaming parameters.
+    """
+
+    bot_token: str = ""
+    guild_id: int = 0  # 0 = all guilds
+    allowed_channels: list[int] = field(default_factory=list)  # empty = all
+    thread_auto_archive: int = 1440  # minutes (24h)
+    max_message_length: int = 2000
+    streaming_edit_interval: float = 1.5  # seconds between message edits
@@ -0,0 +1,320 @@
+"""Persistent interactive views for Discord approval and plan review.
+
+These views use static ``custom_id`` values so they survive bot restarts.
+Correlation information (``ws_id`` and ``correlation_id``) is stored in the
+embed footer of the message the view is attached to.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from turnstone.core.log import get_logger
+
+if TYPE_CHECKING:
+    import discord
+
+    from turnstone.channels.discord.bot import TurnstoneBot
+
+log = get_logger(__name__)
+
+
+def _parse_footer(interaction: discord.Interaction) -> tuple[str, str] | None:
+    """Extract ``(ws_id, correlation_id)`` from the first embed's footer."""
+    if not interaction.message or not interaction.message.embeds:
+        return None
+    footer = interaction.message.embeds[0].footer.text
+    if not footer or "|" not in footer:
+        return None
+    parts = footer.split("|", 1)
+    return parts[0], parts[1]
+
+
+async def _disable_buttons(interaction: discord.Interaction, label: str) -> None:
+    """Edit the message to disable all buttons and append a result label."""
+    import discord
+
+    if interaction.message is None:
+        return
+
+    view = discord.ui.View()
+    for item in interaction.message.components or []:
+        for child in item.children:  # type: ignore[union-attr]
+            button: discord.ui.Button[discord.ui.View] = discord.ui.Button(
+                label=getattr(child, "label", ""),
+                style=discord.ButtonStyle.secondary,
+                disabled=True,
+                custom_id=getattr(child, "custom_id", None),
+            )
+            view.add_item(button)
+
+    embed = interaction.message.embeds[0] if interaction.message.embeds else None
+    if embed is not None:
+        embed.color = discord.Color.greyple()
+        embed.title = f"{embed.title} - {label}"
+
+    await interaction.message.edit(embed=embed, view=view)
+
+
+# ---------------------------------------------------------------------------
+# ApprovalView
+# ---------------------------------------------------------------------------
+
+
+class ApprovalView:
+    """Persistent view with Approve / Reject / Always Approve buttons."""
+
+    def __init__(self, bot: TurnstoneBot) -> None:
+        import discord
+
+        self.bot = bot
+        view_self = self
+
+        class _View(discord.ui.View):
+            def __init__(inner_self) -> None:  # noqa: N805
+                super().__init__(timeout=None)
+
+            @discord.ui.button(
+                label="Approve",
+                style=discord.ButtonStyle.green,
+                custom_id="ts:approve",
+            )
+            async def approve(
+                inner_self,  # noqa: N805
+                interaction: discord.Interaction,
+                button: discord.ui.Button[_View],
+            ) -> None:
+                await view_self._handle(interaction, approved=True, always=False)
+
+            @discord.ui.button(
+                label="Reject",
+                style=discord.ButtonStyle.red,
+                custom_id="ts:reject",
+            )
+            async def reject(
+                inner_self,  # noqa: N805
+                interaction: discord.Interaction,
+                button: discord.ui.Button[_View],
+            ) -> None:
+                await view_self._handle(interaction, approved=False, always=False)
+
+            @discord.ui.button(
+                label="Always Approve",
+                style=discord.ButtonStyle.secondary,
+                custom_id="ts:always",
+            )
+            async def always_approve(
+                inner_self,  # noqa: N805
+                interaction: discord.Interaction,
+                button: discord.ui.Button[_View],
+            ) -> None:
+                await view_self._handle(interaction, approved=True, always=True)
+
+        self._view = _View()
+
+    async def _handle(
+        self,
+        interaction: discord.Interaction,
+        *,
+        approved: bool,
+        always: bool,
+    ) -> None:
+        """Process an approval button click."""
+        parsed = _parse_footer(interaction)
+        if parsed is None:
+            await interaction.response.send_message(
+                "Could not determine workstream context.",
+                ephemeral=True,
+            )
+            return
+
+        ws_id, correlation_id = parsed
+
+        # Verify user is linked.  Scope enforcement (approve) happens
+        # server-side when the bridge executes the tool approval.
+        user_id = await self.bot.router.resolve_user("discord", str(interaction.user.id))
+        if user_id is None:
+            await interaction.response.send_message(
+                "Your Discord account is not linked. Use `/link` first.",
+                ephemeral=True,
+            )
+            return
+
+        # Defer before doing async work so Discord doesn't time out.
+        await interaction.response.defer(ephemeral=True)
+
+        await self.bot.router.send_approval(
+            ws_id=ws_id,
+            correlation_id=correlation_id,
+            approved=approved,
+            always=always,
+        )
+
+        label = "Always Approved" if always else ("Approved" if approved else "Rejected")
+        await _disable_buttons(interaction, label)
+        await interaction.followup.send(
+            f"Tool execution **{label.lower()}**.",
+            ephemeral=True,
+        )
+        log.info(
+            "discord.approval_response",
+            ws_id=ws_id,
+            correlation_id=correlation_id,
+            approved=approved,
+            always=always,
+        )
+
+
+# ---------------------------------------------------------------------------
+# PlanReviewView
+# ---------------------------------------------------------------------------
+
+
+class PlanReviewView:
+    """Persistent view with Approve Plan / Request Changes buttons."""
+
+    def __init__(self, bot: TurnstoneBot) -> None:
+        import discord
+
+        self.bot = bot
+        view_self = self
+
+        class _FeedbackModal(discord.ui.Modal, title="Request Changes"):  # type: ignore[call-arg]
+            feedback: discord.ui.TextInput[_FeedbackModal] = discord.ui.TextInput(
+                label="Feedback",
+                style=discord.TextStyle.paragraph,
+                placeholder="Describe the changes you'd like...",
+                required=True,
+                max_length=2000,
+            )
+
+            def __init__(modal_self, ws_id: str, correlation_id: str) -> None:  # noqa: N805
+                super().__init__()
+                modal_self.ws_id = ws_id
+                modal_self.correlation_id = correlation_id
+
+            async def on_submit(modal_self, interaction: discord.Interaction) -> None:  # noqa: N805
+                await view_self._send_feedback(
+                    interaction,
+                    modal_self.ws_id,
+                    modal_self.correlation_id,
+                    str(modal_self.feedback),
+                )
+
+        self._modal_cls = _FeedbackModal
+
+        class _View(discord.ui.View):
+            def __init__(inner_self) -> None:  # noqa: N805
+                super().__init__(timeout=None)
+
+            @discord.ui.button(
+                label="Approve Plan",
+                style=discord.ButtonStyle.green,
+                custom_id="ts:plan_approve",
+            )
+            async def approve_plan(
+                inner_self,  # noqa: N805
+                interaction: discord.Interaction,
+                button: discord.ui.Button[_View],
+            ) -> None:
+                await view_self._handle_approve(interaction)
+
+            @discord.ui.button(
+                label="Request Changes",
+                style=discord.ButtonStyle.secondary,
+                custom_id="ts:plan_changes",
+            )
+            async def request_changes(
+                inner_self,  # noqa: N805
+                interaction: discord.Interaction,
+                button: discord.ui.Button[_View],
+            ) -> None:
+                await view_self._handle_changes(interaction)
+
+        self._view = _View()
+
+    async def _handle_approve(self, interaction: discord.Interaction) -> None:
+        """Approve the plan (empty feedback = approved)."""
+        parsed = _parse_footer(interaction)
+        if parsed is None:
+            await interaction.response.send_message(
+                "Could not determine workstream context.",
+                ephemeral=True,
+            )
+            return
+
+        ws_id, correlation_id = parsed
+
+        user_id = await self.bot.router.resolve_user("discord", str(interaction.user.id))
+        if user_id is None:
+            await interaction.response.send_message(
+                "Your Discord account is not linked. Use `/link` first.",
+                ephemeral=True,
+            )
+            return
+
+        # Defer before doing async work so Discord doesn't time out.
+        await interaction.response.defer(ephemeral=True)
+
+        await self.bot.router.send_plan_feedback(
+            ws_id=ws_id,
+            correlation_id=correlation_id,
+            feedback="",
+        )
+
+        await _disable_buttons(interaction, "Approved")
+        await interaction.followup.send("Plan **approved**.", ephemeral=True)
+        log.info(
+            "discord.plan_approved",
+            ws_id=ws_id,
+            correlation_id=correlation_id,
+        )
+
+    async def _handle_changes(self, interaction: discord.Interaction) -> None:
+        """Open a modal for feedback text."""
+        parsed = _parse_footer(interaction)
+        if parsed is None:
+            await interaction.response.send_message(
+                "Could not determine workstream context.",
+                ephemeral=True,
+            )
+            return
+
+        ws_id, correlation_id = parsed
+        modal = self._modal_cls(ws_id, correlation_id)
+        await interaction.response.send_modal(modal)
+
+    async def _send_feedback(
+        self,
+        interaction: discord.Interaction,
+        ws_id: str,
+        correlation_id: str,
+        feedback: str,
+    ) -> None:
+        """Send plan feedback after the modal is submitted."""
+        user_id = await self.bot.router.resolve_user("discord", str(interaction.user.id))
+        if user_id is None:
+            await interaction.response.send_message(
+                "Your Discord account is not linked. Use `/link` first.",
+                ephemeral=True,
+            )
+            return
+
+        # Defer before doing async work so Discord doesn't time out.
+        await interaction.response.defer(ephemeral=True)
+
+        await self.bot.router.send_plan_feedback(
+            ws_id=ws_id,
+            correlation_id=correlation_id,
+            feedback=feedback,
+        )
+
+        await interaction.followup.send(
+            "Feedback submitted. The plan will be revised.",
+            ephemeral=True,
+        )
+        log.info(
+            "discord.plan_changes_requested",
+            ws_id=ws_id,
+            correlation_id=correlation_id,
+        )
@@ -41,7 +41,7 @@ SLASH_COMMANDS = [
    "/instructions",
    "/clear",
    "/new",
-    "/sessions",
+    "/workstreams",
    "/resume",
    "/name",
    "/delete",
@@ -787,8 +787,8 @@ def main() -> None:
    parser.add_argument(
        "--resume",
        default=None,
-        metavar="SESSION",
-        help="Resume a previous session by alias or session_id",
+        metavar="WS",
+        help="Resume a previous workstream by alias or ws_id",
    )
    parser.add_argument(
        "--skip-permissions",
@@ -801,11 +801,11 @@ def main() -> None:
        help="API key (default: $OPENAI_API_KEY, or 'dummy' for local servers)",
    )
    parser.add_argument(
-        "--session-retention-days",
+        "--retention-days",
        type=int,
        default=90,
        metavar="DAYS",
-        help="Delete unnamed sessions older than DAYS days on startup, 0 to disable (default: 90)",
+        help="Delete unnamed workstreams older than DAYS days on startup, 0 to disable (default: 90)",
    )
    parser.add_argument(
        "--console-url",
@@ -828,6 +828,10 @@ def main() -> None:
    apply_config(parser, ["api", "model", "session", "tools", "console", "auth", "mcp", "database"])
    args = parser.parse_args()

+    from turnstone.core.log import configure_logging
+
+    configure_logging(level="WARNING", service="cli")
+
    # Initialize storage backend
    from turnstone.core.storage import init_storage

@@ -841,10 +845,10 @@ def main() -> None:
    )
    init_storage(db_backend, path=db_path, url=db_url, pool_size=db_pool_size)

-    # Prune stale / empty sessions on startup
-    from turnstone.core.memory import prune_sessions
+    # Prune stale / empty workstreams on startup
+    from turnstone.core.memory import prune_workstreams

-    prune_sessions(retention_days=args.session_retention_days, log_fn=print)
+    prune_workstreams(retention_days=args.retention_days, log_fn=print)

    # Set up readline
    setup_readline()
@@ -890,8 +894,10 @@ def main() -> None:

    mcp_client = create_mcp_client(getattr(args, "mcp_config", None))

-    # Session factory — captures shared config for creating workstream sessions
-    def session_factory(ui: SessionUI | None, model_alias: str | None = None) -> ChatSession:
+    # ChatSession factory — captures shared config for creating workstreams
+    def session_factory(
+        ui: SessionUI | None, model_alias: str | None = None, ws_id: str | None = None
+    ) -> ChatSession:
        assert ui is not None, "session_factory requires a non-None UI"
        r_client, r_model, r_cfg = registry.resolve(model_alias)
        return ChatSession(
@@ -923,19 +929,19 @@ def main() -> None:

    # Handle --resume
    if args.resume:
-        from turnstone.core.memory import resolve_session
+        from turnstone.core.memory import resolve_workstream

-        target_id = resolve_session(args.resume)
+        target_id = resolve_workstream(args.resume)
        if not target_id:
-            print(red(f"Session not found: {args.resume}"))
+            print(red(f"Workstream not found: {args.resume}"))
            sys.exit(1)
        if ws.session is None:
            print(red("No session available."))
            sys.exit(1)
-        if not ws.session.resume_session(target_id):
-            print(red(f"Session '{args.resume}' has no messages."))
+        if not ws.session.resume(target_id):
+            print(red(f"Workstream '{args.resume}' has no messages."))
            sys.exit(1)
-        print(f"Resumed session {bold(target_id)} ({len(ws.session.messages)} messages)")
+        print(f"Resumed workstream {bold(target_id)} ({len(ws.session.messages)} messages)")

    # Background attention notification — write to stderr while user types
    def _bg_attention_notify(ws_id: str, state: WorkstreamState) -> None:
@@ -0,0 +1,259 @@
+"""Background task scheduler for timed workstream dispatch.
+
+Runs as a daemon thread inside the console process. Checks for due tasks
+every ``check_interval`` seconds and dispatches them as
+``CreateWorkstreamMessage`` via the MQ broker.
+
+Uses Redis ``SET NX EX`` for distributed locking in multi-console deployments.
+"""
+
+from __future__ import annotations
+
+import threading
+import uuid
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+
+import structlog
+
+if TYPE_CHECKING:
+    from turnstone.console.collector import ClusterCollector
+    from turnstone.core.storage._protocol import StorageBackend
+    from turnstone.mq.broker import RedisBroker
+
+log = structlog.get_logger(__name__)
+
+
+def _pick_best_node(collector: ClusterCollector) -> str:
+    """Select the reachable node with the most available capacity."""
+    nodes, _ = collector.get_nodes(sort_by="activity", limit=1000, offset=0)
+    best_id = ""
+    best_headroom = -1
+    for n in nodes:
+        if not n.get("reachable", False):
+            continue
+        headroom = n.get("max_ws", 10) - n.get("ws_total", 0)
+        if headroom > best_headroom:
+            best_headroom = headroom
+            best_id = n["node_id"]
+    return best_id
+
+
+class TaskScheduler:
+    """Background scheduler for dispatching timed workstreams."""
+
+    def __init__(
+        self,
+        broker: RedisBroker,
+        collector: ClusterCollector,
+        storage: StorageBackend,
+        prefix: str = "turnstone",
+        check_interval: float = 15.0,
+        lock_ttl: int = 60,
+        max_fan_out: int = 20,
+    ) -> None:
+        self._broker = broker
+        self._collector = collector
+        self._storage = storage
+        self._prefix = prefix
+        self._check_interval = check_interval
+        self._lock_ttl = lock_ttl
+        self._max_fan_out = max_fan_out
+        self._stop_event = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._tick_count = 0
+        self._prune_every = 240  # ~1 hour at 15s intervals
+
+    def start(self) -> None:
+        """Start the scheduler daemon thread."""
+        self._stop_event.clear()
+        self._thread = threading.Thread(target=self._loop, daemon=True, name="scheduler")
+        self._thread.start()
+        log.info("scheduler.started", check_interval=self._check_interval)
+
+    def stop(self) -> None:
+        """Stop the scheduler and wait for the thread to finish."""
+        self._stop_event.set()
+        if self._thread is not None:
+            self._thread.join(timeout=5)
+        log.info("scheduler.stopped")
+
+    def _loop(self) -> None:
+        """Main scheduler loop — tick then sleep."""
+        while not self._stop_event.is_set():
+            try:
+                self._tick()
+            except Exception:
+                log.exception("scheduler.tick_error")
+            self._stop_event.wait(self._check_interval)
+
+    # Lua script for safe lock release — only delete if we still own the lock
+    _UNLOCK_SCRIPT = "if redis.call('get',KEYS[1])==ARGV[1] then return redis.call('del',KEYS[1]) else return 0 end"
+
+    def _tick(self) -> None:
+        """Single scheduler iteration: acquire lock, query due tasks, dispatch."""
+        now = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%S")
+
+        # Distributed lock with unique owner — prevents releasing another instance's lock
+        lock_key = f"{self._prefix}:scheduler:lock"
+        lock_value = uuid.uuid4().hex
+        acquired = self._broker._redis.set(lock_key, lock_value, nx=True, ex=self._lock_ttl)
+        if not acquired:
+            return
+
+        try:
+            due_tasks = self._storage.list_due_tasks(now)
+            for task in due_tasks:
+                self._dispatch_task(task, now)
+
+            # Periodic run history pruning (~once per hour)
+            self._tick_count += 1
+            if self._tick_count % self._prune_every == 0:
+                pruned = self._storage.prune_task_runs(retention_days=90)
+                if pruned:
+                    log.info("scheduler.pruned_runs", count=pruned)
+        finally:
+            # Only release our own lock (safe even if TTL expired and another took it)
+            self._broker._redis.eval(  # type: ignore[no-untyped-call]
+                self._UNLOCK_SCRIPT, 1, lock_key, lock_value
+            )
+
+    def _dispatch_task(self, task: dict[str, Any], now: str) -> None:
+        """Dispatch a single task as one or more CreateWorkstreamMessages."""
+        target_mode = task["target_mode"]
+        task_id = task["task_id"]
+        dispatched = False
+
+        if target_mode == "all":
+            nodes, _ = self._collector.get_nodes(sort_by="activity", limit=1000, offset=0)
+            fan_count = 0
+            for n in nodes:
+                if n.get("reachable", False):
+                    if fan_count >= self._max_fan_out:
+                        log.warning(
+                            "scheduler.fan_out_capped",
+                            task_id=task_id,
+                            max_fan_out=self._max_fan_out,
+                        )
+                        break
+                    self._dispatch_to_node(task, n["node_id"], now)
+                    fan_count += 1
+                    dispatched = True
+            if not dispatched:
+                self._record_failure(task, now, "No reachable nodes for fan-out")
+        elif target_mode == "pool":
+            self._dispatch_to_pool(task, now)
+            dispatched = True
+        elif target_mode == "auto":
+            node_id = _pick_best_node(self._collector)
+            if node_id:
+                self._dispatch_to_node(task, node_id, now)
+                dispatched = True
+            else:
+                self._record_failure(task, now, "No reachable nodes")
+        else:
+            # Specific node_id
+            self._dispatch_to_node(task, target_mode, now)
+            dispatched = True
+
+        if not dispatched:
+            return  # Don't advance schedule on failure
+
+        # Update last_run and compute next_run
+        next_run = self._compute_next_run(task)
+        if task["schedule_type"] == "at":
+            self._storage.update_scheduled_task(task_id, last_run=now, next_run="", enabled=False)
+        else:
+            self._storage.update_scheduled_task(task_id, last_run=now, next_run=next_run)
+
+        log_kw: dict[str, Any] = {
+            "task_id": task_id,
+            "target_mode": target_mode,
+            "schedule_type": task["schedule_type"],
+            "created_by": task.get("created_by", ""),
+        }
+        if task.get("auto_approve", 0):
+            log_kw["auto_approve"] = True
+            log_kw["auto_approve_tools"] = task.get("auto_approve_tools", "")
+            log.warning("scheduler.task_dispatched_auto_approve", **log_kw)
+        else:
+            log.info("scheduler.task_dispatched", **log_kw)
+
+    @staticmethod
+    def _parse_tools(task: dict[str, Any]) -> list[str]:
+        raw = task.get("auto_approve_tools", "")
+        return [t.strip() for t in raw.split(",") if t.strip()]
+
+    def _dispatch_to_node(self, task: dict[str, Any], node_id: str, now: str) -> None:
+        """Send a CreateWorkstreamMessage to a specific node."""
+        from turnstone.mq.protocol import CreateWorkstreamMessage
+
+        msg = CreateWorkstreamMessage(
+            name=task["name"],
+            model=task.get("model", ""),
+            target_node=node_id,
+            initial_message=task["initial_message"],
+            auto_approve=bool(task.get("auto_approve", 0)),
+            auto_approve_tools=self._parse_tools(task),
+            user_id=task.get("created_by", ""),
+        )
+        self._broker.push_inbound(msg.to_json(), node_id=node_id)
+
+        self._storage.record_task_run(
+            run_id=uuid.uuid4().hex,
+            task_id=task["task_id"],
+            node_id=node_id,
+            ws_id="",
+            correlation_id=msg.correlation_id,
+            started=now,
+            status="dispatched",
+            error="",
+        )
+
+    def _dispatch_to_pool(self, task: dict[str, Any], now: str) -> None:
+        """Send a CreateWorkstreamMessage to the shared pool queue."""
+        from turnstone.mq.protocol import CreateWorkstreamMessage
+
+        msg = CreateWorkstreamMessage(
+            name=task["name"],
+            model=task.get("model", ""),
+            initial_message=task["initial_message"],
+            auto_approve=bool(task.get("auto_approve", 0)),
+            auto_approve_tools=self._parse_tools(task),
+            user_id=task.get("created_by", ""),
+        )
+        self._broker.push_inbound(msg.to_json())
+
+        self._storage.record_task_run(
+            run_id=uuid.uuid4().hex,
+            task_id=task["task_id"],
+            node_id="pool",
+            ws_id="",
+            correlation_id=msg.correlation_id,
+            started=now,
+            status="dispatched",
+            error="",
+        )
+
+    def _record_failure(self, task: dict[str, Any], now: str, error: str) -> None:
+        """Record a failed dispatch attempt."""
+        self._storage.record_task_run(
+            run_id=uuid.uuid4().hex,
+            task_id=task["task_id"],
+            node_id="",
+            ws_id="",
+            correlation_id="",
+            started=now,
+            status="failed",
+            error=error,
+        )
+        log.warning("scheduler.dispatch_failed", task_id=task["task_id"], error=error)
+
+    @staticmethod
+    def _compute_next_run(task: dict[str, Any]) -> str:
+        """Compute the next run time. Returns empty string for one-shot tasks."""
+        from turnstone.console.server import _compute_next_run
+
+        return _compute_next_run(
+            task["schedule_type"], task.get("cron_expr", ""), task.get("at_time", "")
+        )
@@ -52,12 +52,14 @@ function connectSSE() {
  }
  evtSource = new EventSource("/v1/api/cluster/events");
  var statusBar = document.getElementById("status-bar");
-  evtSource.onmessage = function (e) {
+  evtSource.onopen = function () {
    retryDelay = 1000;
    statusBar.classList.remove("disconnected");
    statusBar.textContent = "";
    var csb = document.getElementById("cluster-status-bar");
    if (csb) csb.classList.remove("stale");
+  };
+  evtSource.onmessage = function (e) {
    try {
      var data = JSON.parse(e.data);
      handleClusterEvent(data);
@@ -68,6 +70,9 @@ function connectSSE() {
  evtSource.onerror = function () {
    evtSource.close();
    evtSource = null;
+    // Don't show reconnecting state if login overlay is visible
+    var loginOverlay = document.getElementById("login-overlay");
+    if (loginOverlay && loginOverlay.style.display !== "none") return;
    statusBar.textContent = "Reconnecting\u2026";
    statusBar.classList.add("disconnected");
    var csb = document.getElementById("cluster-status-bar");
@@ -126,6 +131,8 @@ function showOverview() {
  document.getElementById("view-overview").style.display = "";
  document.getElementById("view-node").style.display = "none";
  document.getElementById("view-filtered").style.display = "none";
+  var adminView = document.getElementById("view-admin");
+  if (adminView) adminView.style.display = "none";
  document.getElementById("breadcrumb").style.display = "none";
  document.getElementById("main").scrollTop = 0;
  loadOverview();
@@ -637,6 +644,8 @@ function drillDownToNode(nodeId, serverUrl) {
  document.getElementById("view-overview").style.display = "none";
  document.getElementById("view-node").style.display = "";
  document.getElementById("view-filtered").style.display = "none";
+  var adminView = document.getElementById("view-admin");
+  if (adminView) adminView.style.display = "none";
  document.getElementById("breadcrumb").style.display = "";
  document.getElementById("breadcrumb-label").textContent = nodeId;
  var link = document.getElementById("node-link");
@@ -685,6 +694,8 @@ function drillDownByState(state) {
  document.getElementById("view-overview").style.display = "none";
  document.getElementById("view-node").style.display = "none";
  document.getElementById("view-filtered").style.display = "";
+  var adminView = document.getElementById("view-admin");
+  if (adminView) adminView.style.display = "none";
  document.getElementById("breadcrumb").style.display = "";
  var sd = STATE_DISPLAY[state] || STATE_DISPLAY.idle;
  document.getElementById("breadcrumb-label").textContent =
@@ -703,6 +714,8 @@ function drillDownByNode(nodeId) {
  document.getElementById("view-overview").style.display = "none";
  document.getElementById("view-node").style.display = "none";
  document.getElementById("view-filtered").style.display = "";
+  var adminView = document.getElementById("view-admin");
+  if (adminView) adminView.style.display = "none";
  document.getElementById("breadcrumb").style.display = "";
  document.getElementById("breadcrumb-label").textContent = nodeId;
  document.getElementById("filtered-title").textContent =
@@ -884,14 +897,11 @@ function renderWsTable(container, wsList) {
      row.classList.add("has-link");
      (function (nodeId, wsId) {
        row.onclick = function () {
-          window.open(
+          window.location.href =
            "/node/" +
-              encodeURIComponent(nodeId) +
-              "/?ws_id=" +
-              encodeURIComponent(wsId),
-            "_blank",
-            "noopener",
-          );
+            encodeURIComponent(nodeId) +
+            "/?ws_id=" +
+            encodeURIComponent(wsId);
        };
        row.onkeydown = function (e) {
          if (e.key === "Enter" || e.key === " ") {
@@ -918,6 +928,8 @@ window.addEventListener("popstate", function (e) {
    return;
  }
  if (e.state.view === "overview") showOverview();
+  else if (e.state.view === "admin" && typeof showAdmin === "function")
+    showAdmin();
  else if (e.state.view === "node" && e.state.nodeId)
    drillDownToNode(e.state.nodeId, e.state.serverUrl);
  else if (e.state.view === "filtered" && e.state.filter) {
@@ -1085,8 +1097,15 @@ document.addEventListener("keydown", function (e) {
 });

 // --- Init ---
+// SSE connects after auth is confirmed — either via onLoginSuccess after
+// login, or after the first successful data load (page refresh with valid cookie).
+var _sseStarted = false;
+function _ensureSSE() {
+  if (!_sseStarted) {
+    _sseStarted = true;
+    connectSSE();
+  }
+}
 history.replaceState({ view: "overview" }, "");
 initLogin();
-connectSSE();
 loadOverview();
-// Try loading — if auth required, login overlay will show
@@ -16,6 +16,7 @@
  <span id="cluster-summary" aria-live="polite"></span>
  <span id="status-bar" role="status" aria-live="polite"></span>
  <button id="new-ws-btn" class="header-btn header-btn-accent" onclick="showNewWsModal()" title="Create workstream">+ new</button>
+  <button id="admin-btn" class="header-btn" onclick="showAdmin()" title="User &amp; token administration">admin</button>
  <button id="logout-btn" class="header-btn" onclick="logout()" style="display:none">logout</button>
  <button id="theme-toggle" class="header-btn" onclick="toggleTheme()" aria-label="Toggle light/dark theme">&#9790;</button>
 </div>
@@ -51,7 +52,7 @@
      <span class="dash-col dash-col-ctx">CTX</span>
    </div>
    <div id="node-ws-table" class="dash-table" role="group" aria-label="Workstreams" aria-live="polite"></div>
-    <a id="node-link" class="node-link" target="_blank" rel="noopener">Open node UI</a>
+    <a id="node-link" class="node-link">Open node UI</a>
  </div>

  <!-- FILTERED WORKSTREAMS -->
@@ -72,6 +73,97 @@
    <div id="filtered-ws-table" class="dash-table" role="group" aria-label="Workstreams" aria-live="polite"></div>
    <div id="filtered-pagination" class="pagination"></div>
  </div>
+
+  <!-- ADMIN PANEL -->
+  <div id="view-admin" style="display:none">
+    <div class="admin-tabs" role="tablist">
+      <button id="tab-users" class="admin-tab active" data-tab="users" role="tab" aria-selected="true" aria-controls="admin-users" tabindex="0" onclick="switchAdminTab('users')">Users</button>
+      <button id="tab-tokens" class="admin-tab" data-tab="tokens" role="tab" aria-selected="false" aria-controls="admin-tokens" tabindex="-1" onclick="switchAdminTab('tokens')">Tokens</button>
+      <button id="tab-channels" class="admin-tab" data-tab="channels" role="tab" aria-selected="false" aria-controls="admin-channels" tabindex="-1" onclick="switchAdminTab('channels')">Channels</button>
+      <button id="tab-schedules" class="admin-tab" data-tab="schedules" role="tab" aria-selected="false" aria-controls="admin-schedules" tabindex="-1" onclick="switchAdminTab('schedules')">Schedules</button>
+    </div>
+
+    <!-- Users Tab -->
+    <div id="admin-users" class="admin-panel" role="tabpanel" aria-labelledby="tab-users">
+      <div class="admin-toolbar">
+        <span class="section-header" style="margin:0">USERS</span>
+        <button class="admin-action-btn" onclick="showCreateUserModal()">+ Create user</button>
+      </div>
+      <div class="admin-colheaders" aria-hidden="true">
+        <span class="admin-col admin-col-username">USERNAME</span>
+        <span class="admin-col admin-col-name">DISPLAY NAME</span>
+        <span class="admin-col admin-col-created">CREATED</span>
+        <span class="admin-col admin-col-actions">ACTIONS</span>
+      </div>
+      <div id="admin-users-table" role="list" aria-label="Users" aria-live="polite">
+        <div class="dashboard-empty">Loading users...</div>
+      </div>
+    </div>
+
+    <!-- Tokens Tab -->
+    <div id="admin-tokens" class="admin-panel" role="tabpanel" aria-labelledby="tab-tokens" style="display:none">
+      <div class="admin-toolbar">
+        <span class="section-header" style="margin:0">TOKENS</span>
+        <label for="admin-token-user" class="sr-only">Filter tokens by user</label>
+        <select id="admin-token-user" onchange="loadAdminTokens()">
+          <option value="">Select user...</option>
+        </select>
+        <button class="admin-action-btn" onclick="showCreateTokenModal()">+ Create token</button>
+      </div>
+      <div class="admin-colheaders" aria-hidden="true">
+        <span class="admin-col admin-col-prefix">PREFIX</span>
+        <span class="admin-col admin-col-tname">NAME</span>
+        <span class="admin-col admin-col-scopes">SCOPES</span>
+        <span class="admin-col admin-col-created">CREATED</span>
+        <span class="admin-col admin-col-expires">EXPIRES</span>
+        <span class="admin-col admin-col-actions">ACTIONS</span>
+      </div>
+      <div id="admin-tokens-table" role="list" aria-label="Tokens" aria-live="polite">
+        <div class="dashboard-empty">Select a user to view tokens</div>
+      </div>
+    </div>
+
+    <!-- Channels Tab -->
+    <div id="admin-channels" class="admin-panel" role="tabpanel" aria-labelledby="tab-channels" style="display:none">
+      <div class="admin-toolbar">
+        <span class="section-header" style="margin:0">CHANNEL LINKS</span>
+        <label for="admin-channel-user" class="sr-only">Filter channels by user</label>
+        <select id="admin-channel-user" onchange="loadAdminChannels()">
+          <option value="">Select user...</option>
+        </select>
+        <button class="admin-action-btn" onclick="showCreateChannelModal()">+ Link channel</button>
+      </div>
+      <div class="admin-colheaders" aria-hidden="true">
+        <span class="admin-col admin-col-chtype">CHANNEL</span>
+        <span class="admin-col admin-col-chuid">EXTERNAL ID</span>
+        <span class="admin-col admin-col-created">LINKED</span>
+        <span class="admin-col admin-col-actions">ACTIONS</span>
+      </div>
+      <div id="admin-channels-table" role="list" aria-label="Channel links" aria-live="polite">
+        <div class="dashboard-empty">Select a user to view channel links</div>
+      </div>
+    </div>
+
+    <!-- Schedules Tab -->
+    <div id="admin-schedules" class="admin-panel" role="tabpanel" aria-labelledby="tab-schedules" style="display:none">
+      <div class="admin-toolbar">
+        <span class="section-header" style="margin:0">SCHEDULED TASKS</span>
+        <button class="admin-action-btn" onclick="showCreateScheduleModal()">+ New schedule</button>
+      </div>
+      <div class="admin-colheaders" aria-hidden="true">
+        <span class="admin-col admin-col-sname">NAME</span>
+        <span class="admin-col admin-col-stype">TYPE</span>
+        <span class="admin-col admin-col-sschedule">SCHEDULE</span>
+        <span class="admin-col admin-col-starget">TARGET</span>
+        <span class="admin-col admin-col-snext">NEXT RUN</span>
+        <span class="admin-col admin-col-sstatus">STATUS</span>
+        <span class="admin-col admin-col-actions">ACTIONS</span>
+      </div>
+      <div id="admin-schedules-table" role="list" aria-label="Scheduled tasks" aria-live="polite">
+        <div class="dashboard-empty">Loading schedules...</div>
+      </div>
+    </div>
+  </div>
 </div>

 <div id="cluster-status-bar" role="region" aria-label="Cluster status">
@@ -123,6 +215,201 @@ window.TURNSTONE_KB_SHORTCUTS = [
  </div>
 </div>

+<!-- Create User Modal -->
+<div id="create-user-overlay" style="display:none" role="dialog" aria-modal="true" aria-labelledby="create-user-title">
+  <div id="create-user-box" class="admin-modal">
+    <h2 id="create-user-title">Create User</h2>
+    <div id="create-user-error" role="alert" aria-live="assertive"></div>
+    <label for="cu-username">Username</label>
+    <input id="cu-username" type="text" placeholder="login username" autocomplete="off" spellcheck="false">
+    <label for="cu-displayname">Display name</label>
+    <input id="cu-displayname" type="text" placeholder="Full name" autocomplete="off">
+    <label for="cu-password">Password</label>
+    <input id="cu-password" type="password" placeholder="Minimum 8 characters" autocomplete="new-password">
+    <label for="cu-confirm">Confirm password</label>
+    <input id="cu-confirm" type="password" placeholder="Confirm password" autocomplete="new-password">
+    <div class="modal-buttons">
+      <button class="modal-cancel" onclick="hideCreateUserModal()">Cancel</button>
+      <button id="cu-submit" class="modal-submit" onclick="submitCreateUser()">Create</button>
+    </div>
+  </div>
+</div>
+
+<!-- Create Token Modal -->
+<div id="create-token-overlay" style="display:none" role="dialog" aria-modal="true" aria-labelledby="create-token-title">
+  <div id="create-token-box" class="admin-modal">
+    <h2 id="create-token-title">Create API Token</h2>
+    <div id="create-token-error" role="alert" aria-live="assertive"></div>
+    <label for="ct-name">Token name <span class="label-hint">optional</span></label>
+    <input id="ct-name" type="text" placeholder="e.g. CI pipeline, bridge-prod" autocomplete="off">
+    <label for="ct-scopes">Scopes</label>
+    <select id="ct-scopes">
+      <option value="read,write,approve">Full access (read, write, approve)</option>
+      <option value="read,write">Read + write</option>
+      <option value="read">Read only</option>
+    </select>
+    <label for="ct-expires">Expiry <span class="label-hint">optional</span></label>
+    <select id="ct-expires">
+      <option value="">Never</option>
+      <option value="30">30 days</option>
+      <option value="90">90 days</option>
+      <option value="365">1 year</option>
+    </select>
+    <div class="modal-buttons">
+      <button class="modal-cancel" onclick="hideCreateTokenModal()">Cancel</button>
+      <button id="ct-submit" class="modal-submit" onclick="submitCreateToken()">Create</button>
+    </div>
+  </div>
+</div>
+
+<!-- Token Created (show-once) Modal -->
+<div id="token-created-overlay" style="display:none" role="dialog" aria-modal="true" aria-labelledby="token-created-title">
+  <div id="token-created-box" class="admin-modal">
+    <h2 id="token-created-title">Token Created</h2>
+    <p class="token-created-warning">Copy this token now. It will not be shown again.</p>
+    <div id="token-created-value" class="token-display"></div>
+    <div class="modal-buttons">
+      <button class="modal-submit" onclick="copyCreatedToken()">Copy to clipboard</button>
+      <button class="modal-cancel" onclick="hideTokenCreatedModal()">Done</button>
+    </div>
+  </div>
+</div>
+
+<!-- Confirm Action Modal (reusable) -->
+<div id="confirm-overlay" style="display:none" role="alertdialog" aria-modal="true" aria-labelledby="confirm-title" aria-describedby="confirm-message">
+  <div id="confirm-box" class="admin-modal">
+    <h2 id="confirm-title">Confirm</h2>
+    <p id="confirm-message" style="color:var(--fg-dim);margin:12px 0 20px;line-height:1.5"></p>
+    <div class="modal-buttons">
+      <button class="modal-cancel" onclick="hideConfirmModal()">Cancel</button>
+      <button id="confirm-submit" class="modal-submit" style="background:var(--red);border-color:var(--red)" onclick="_confirmCallback()">Confirm</button>
+    </div>
+  </div>
+</div>
+
+<!-- Create Channel Link Modal -->
+<div id="create-channel-overlay" style="display:none" role="dialog" aria-modal="true" aria-labelledby="create-channel-title">
+  <div id="create-channel-box" class="admin-modal">
+    <h2 id="create-channel-title">Link Channel Account</h2>
+    <div id="create-channel-error" role="alert" aria-live="assertive"></div>
+    <label for="cc-type">Channel type</label>
+    <select id="cc-type">
+      <option value="discord">Discord</option>
+    </select>
+    <label for="cc-uid">External user ID <span class="label-hint">the user's ID on the platform</span></label>
+    <input id="cc-uid" type="text" placeholder="e.g. 123456789012345678" autocomplete="off" spellcheck="false">
+    <div class="modal-buttons">
+      <button class="modal-cancel" onclick="hideCreateChannelModal()">Cancel</button>
+      <button id="cc-submit" class="modal-submit" onclick="submitCreateChannel()">Link</button>
+    </div>
+  </div>
+</div>
+
+<!-- Create Schedule Modal -->
+<div id="create-schedule-overlay" style="display:none" role="dialog" aria-modal="true" aria-labelledby="create-schedule-title">
+  <div id="create-schedule-box" class="admin-modal admin-modal-wide">
+    <h2 id="create-schedule-title">New Schedule</h2>
+    <div id="create-schedule-error" role="alert" aria-live="assertive"></div>
+    <label for="cs-name">Name</label>
+    <input id="cs-name" type="text" placeholder="Daily health check" autocomplete="off">
+    <label for="cs-desc">Description <span class="label-hint">optional</span></label>
+    <input id="cs-desc" type="text" placeholder="" autocomplete="off">
+    <label for="cs-type">Schedule type</label>
+    <select id="cs-type" onchange="toggleScheduleTypeFields()">
+      <option value="cron">Cron (recurring)</option>
+      <option value="at">At (one-shot)</option>
+    </select>
+    <div id="cs-cron-group">
+      <label for="cs-cron">Cron expression</label>
+      <input id="cs-cron" type="text" placeholder="0 9 * * MON-FRI" autocomplete="off" spellcheck="false" aria-describedby="cs-cron-hint">
+      <span id="cs-cron-hint" class="label-hint" style="display:block;margin-top:3px">min hour day month weekday</span>
+    </div>
+    <div id="cs-at-group" style="display:none">
+      <label for="cs-at">Run at</label>
+      <input id="cs-at" type="datetime-local">
+    </div>
+    <label for="cs-target">Target</label>
+    <select id="cs-target" onchange="toggleScheduleNodeField()">
+      <option value="auto">Auto (best available)</option>
+      <option value="pool">Pool (any bridge)</option>
+      <option value="all">All nodes</option>
+      <option value="node">Specific node...</option>
+    </select>
+    <div id="cs-node-group" style="display:none">
+      <label for="cs-node">Node ID</label>
+      <input id="cs-node" type="text" placeholder="node-001" autocomplete="off" spellcheck="false">
+    </div>
+    <label for="cs-model">Model <span class="label-hint">optional</span></label>
+    <input id="cs-model" type="text" placeholder="Default model" autocomplete="off">
+    <label for="cs-message">Initial message</label>
+    <textarea id="cs-message" rows="3" placeholder="What should the workstream do?"></textarea>
+    <label class="admin-checkbox"><input id="cs-autoapprove" type="checkbox"> Auto-approve tool calls</label>
+    <div class="modal-buttons">
+      <button class="modal-cancel" onclick="hideCreateScheduleModal()">Cancel</button>
+      <button id="cs-submit" class="modal-submit" onclick="submitCreateSchedule()">Create</button>
+    </div>
+  </div>
+</div>
+
+<!-- Edit Schedule Modal -->
+<div id="edit-schedule-overlay" style="display:none" role="dialog" aria-modal="true" aria-labelledby="edit-schedule-title">
+  <div id="edit-schedule-box" class="admin-modal admin-modal-wide">
+    <h2 id="edit-schedule-title">Edit Schedule</h2>
+    <div id="edit-schedule-error" role="alert" aria-live="assertive"></div>
+    <input id="es-id" type="hidden">
+    <label for="es-name">Name</label>
+    <input id="es-name" type="text" autocomplete="off">
+    <label for="es-desc">Description</label>
+    <input id="es-desc" type="text" autocomplete="off">
+    <label for="es-type">Schedule type</label>
+    <select id="es-type" onchange="toggleEditScheduleTypeFields()">
+      <option value="cron">Cron (recurring)</option>
+      <option value="at">At (one-shot)</option>
+    </select>
+    <div id="es-cron-group">
+      <label for="es-cron">Cron expression</label>
+      <input id="es-cron" type="text" autocomplete="off" spellcheck="false">
+    </div>
+    <div id="es-at-group" style="display:none">
+      <label for="es-at">Run at</label>
+      <input id="es-at" type="datetime-local">
+    </div>
+    <label for="es-target">Target</label>
+    <select id="es-target" onchange="toggleEditScheduleNodeField()">
+      <option value="auto">Auto (best available)</option>
+      <option value="pool">Pool (any bridge)</option>
+      <option value="all">All nodes</option>
+      <option value="node">Specific node...</option>
+    </select>
+    <div id="es-node-group" style="display:none">
+      <label for="es-node">Node ID</label>
+      <input id="es-node" type="text" autocomplete="off" spellcheck="false">
+    </div>
+    <label for="es-model">Model</label>
+    <input id="es-model" type="text" autocomplete="off">
+    <label for="es-message">Initial message</label>
+    <textarea id="es-message" rows="3"></textarea>
+    <label class="admin-checkbox"><input id="es-autoapprove" type="checkbox"> Auto-approve tool calls</label>
+    <label class="admin-checkbox"><input id="es-enabled" type="checkbox"> Enabled</label>
+    <div class="modal-buttons">
+      <button class="modal-cancel" onclick="hideEditScheduleModal()">Cancel</button>
+      <button id="es-submit" class="modal-submit" onclick="submitEditSchedule()">Save</button>
+    </div>
+  </div>
+</div>
+
+<!-- Schedule Runs Modal -->
+<div id="schedule-runs-overlay" style="display:none" role="dialog" aria-modal="true" aria-labelledby="schedule-runs-title">
+  <div id="schedule-runs-box" class="admin-modal admin-modal-wide">
+    <h2 id="schedule-runs-title">Run History</h2>
+    <div id="schedule-runs-table"></div>
+    <div class="modal-buttons">
+      <button class="modal-cancel" onclick="hideScheduleRunsModal()">Close</button>
+    </div>
+  </div>
+</div>
+
+<script src="/static/admin.js"></script>
 <script src="/static/app.js"></script>
 </body>
 </html>
@@ -23,6 +23,7 @@
   ========================================================================== */
 #main {
  flex: 1;
+  min-height: 0;
  overflow-y: auto;
  padding: 20px 24px;
  padding-bottom: 60px;
@@ -678,6 +679,356 @@
  #header h1 { font-size: 13px; }
 }

+/* ==========================================================================
+   Admin panel
+   ========================================================================== */
+
+.admin-tabs {
+  display: flex;
+  gap: 2px;
+  margin-bottom: 16px;
+  border-bottom: 1px solid var(--border);
+  padding-bottom: 0;
+}
+.admin-tab {
+  background: none;
+  border: none;
+  border-bottom: 2px solid transparent;
+  color: var(--fg-dim);
+  font-family: var(--font-display);
+  font-size: 11px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  padding: 8px 16px 10px;
+  cursor: pointer;
+  transition: color 0.15s, border-color 0.15s;
+}
+.admin-tab:hover { color: var(--fg); }
+.admin-tab.active {
+  color: var(--accent);
+  border-bottom-color: var(--accent);
+}
+
+.admin-toolbar {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  margin-bottom: 12px;
+}
+.admin-action-btn {
+  margin-left: auto;
+  background: var(--accent);
+  color: var(--bg);
+  border: none;
+  border-radius: var(--radius-sm);
+  font-family: var(--font-display);
+  font-size: 11px;
+  font-weight: 600;
+  padding: 6px 14px;
+  cursor: pointer;
+  letter-spacing: 0.02em;
+  transition: filter 0.15s;
+}
+.admin-action-btn:hover { filter: brightness(1.1); }
+.admin-action-btn:focus-visible { outline: 2px solid var(--fg-bright); outline-offset: 2px; }
+.admin-action-btn:disabled { opacity: 0.4; cursor: not-allowed; }
+
+.admin-toolbar select {
+  background: var(--bg);
+  color: var(--fg);
+  border: 1px solid var(--border-strong);
+  border-radius: var(--radius-sm);
+  font: inherit;
+  font-size: 12px;
+  padding: 5px 30px 5px 10px;
+  min-width: 180px;
+  appearance: none;
+  -webkit-appearance: none;
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='8' viewBox='0 0 12 8'%3E%3Cpath d='M1 1l5 5 5-5' stroke='%238a93ad' stroke-width='1.5' fill='none' stroke-linecap='round'/%3E%3C/svg%3E");
+  background-repeat: no-repeat;
+  background-position: right 10px center;
+}
+.admin-toolbar select:focus { border-color: var(--accent); outline: none; box-shadow: 0 0 0 3px var(--accent-dim); }
+
+/* Admin table grid */
+.admin-colheaders {
+  display: grid;
+  padding: 0 12px;
+  margin-bottom: 4px;
+}
+.admin-colheaders .admin-col {
+  font-family: var(--font-display);
+  font-size: 10px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--fg-dim);
+}
+.admin-row {
+  display: grid;
+  padding: 8px 12px;
+  align-items: center;
+  border-radius: var(--radius-sm);
+  transition: background 0.1s;
+}
+.admin-row:nth-child(even) { background: var(--row-alt, rgba(255,255,255,0.015)); }
+.admin-row:hover { background: var(--bg-highlight); }
+
+.admin-col { font-size: 12px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.admin-col code { font-family: var(--font-mono); font-size: 11px; color: var(--fg-dim); }
+
+/* Users grid: USERNAME | NAME | CREATED | ACTIONS */
+#admin-users .admin-colheaders,
+#admin-users .admin-row {
+  grid-template-columns: 140px 1fr 100px 80px;
+}
+
+/* Tokens grid: PREFIX | NAME | SCOPES | CREATED | EXPIRES | ACTIONS */
+#admin-tokens .admin-colheaders,
+#admin-tokens .admin-row {
+  grid-template-columns: 100px 1fr 160px 100px 100px 80px;
+}
+
+/* Channels grid: CHANNEL | EXTERNAL ID | LINKED | ACTIONS */
+#admin-channels .admin-colheaders,
+#admin-channels .admin-row {
+  grid-template-columns: 100px 1fr 100px 80px;
+}
+
+/* Scope badges */
+.scope-badge {
+  display: inline-block;
+  font-family: var(--font-display);
+  font-size: 9px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  padding: 1px 6px;
+  border-radius: 2px;
+  margin-right: 3px;
+  background: var(--bg-highlight);
+  color: var(--fg-dim);
+  border: 1px solid var(--border);
+}
+.scope-write { color: var(--cyan); border-color: rgba(103, 232, 249, 0.2); }
+.scope-approve { color: var(--accent); border-color: var(--accent-dim); }
+.scope-channel { color: var(--magenta); border-color: rgba(192, 132, 252, 0.25); }
+
+/* Action buttons */
+.admin-btn-danger {
+  background: none;
+  border: 1px solid var(--red);
+  color: var(--red);
+  font-family: var(--font-display);
+  font-size: 10px;
+  font-weight: 500;
+  padding: 2px 8px;
+  border-radius: var(--radius-sm);
+  cursor: pointer;
+  opacity: 0.8;
+  transition: opacity 0.15s, background 0.15s;
+}
+.admin-btn-danger:hover { opacity: 1; background: rgba(248, 113, 113, 0.1); }
+.admin-btn-danger:focus-visible { outline: 2px solid var(--red); outline-offset: 2px; }
+
+.admin-btn-action {
+  background: none;
+  border: 1px solid var(--border-strong);
+  color: var(--fg-dim);
+  font-family: var(--font-display);
+  font-size: 10px;
+  font-weight: 500;
+  padding: 2px 8px;
+  border-radius: var(--radius-sm);
+  cursor: pointer;
+  opacity: 0.8;
+  transition: opacity 0.15s, background 0.15s;
+  margin-right: 4px;
+}
+.admin-btn-action:hover { opacity: 1; background: rgba(255, 255, 255, 0.05); color: var(--fg); }
+.admin-btn-action:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+
+/* Schedules grid: NAME | TYPE | SCHEDULE | TARGET | NEXT RUN | STATUS | ACTIONS */
+#admin-schedules .admin-colheaders,
+#admin-schedules .admin-row {
+  grid-template-columns: 1.5fr 60px 1.2fr 80px 130px 70px 170px;
+}
+
+/* Schedule runs grid: STARTED | NODE | STATUS | ERROR */
+.sched-runs-grid { grid-template-columns: 2fr 1fr 1fr 2fr; }
+
+/* Schedule status indicators */
+.sched-active { color: var(--green); font-weight: 500; }
+.sched-disabled { color: var(--fg-dim); }
+.sched-expired { color: var(--accent); }
+
+/* Wide modal variant for schedule forms */
+.admin-modal-wide { width: 480px; }
+
+/* Checkbox labels inside admin modals */
+.admin-modal label.admin-checkbox {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-size: 12px;
+  font-weight: 500;
+  text-transform: none;
+  letter-spacing: 0;
+  color: var(--fg);
+  cursor: pointer;
+  margin-top: 14px;
+}
+.admin-modal label.admin-checkbox input[type="checkbox"] {
+  width: auto;
+  margin: 0;
+}
+
+/* Admin modals (reuse new-ws-overlay pattern) */
+.admin-modal {
+  background: var(--bg-surface);
+  border: 1px solid var(--border-strong);
+  border-radius: var(--radius);
+  padding: 32px;
+  width: 380px;
+  max-width: 90vw;
+  box-shadow: 0 24px 48px -12px rgba(0, 0, 0, 0.5), 0 0 80px -20px var(--accent-dim);
+  position: relative;
+}
+.admin-modal::before {
+  content: '';
+  position: absolute;
+  top: -1px; left: 20%; right: 20%;
+  height: 2px;
+  background: linear-gradient(90deg, transparent, var(--accent), transparent);
+  border-radius: 1px;
+}
+.admin-modal h2 {
+  font-family: var(--font-display);
+  font-size: 15px;
+  font-weight: 700;
+  color: var(--accent);
+  margin-bottom: 16px;
+  letter-spacing: 0.02em;
+}
+.admin-modal label {
+  display: block;
+  font-family: var(--font-display);
+  font-size: 10px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--fg-dim);
+  margin-bottom: 5px;
+  margin-top: 12px;
+}
+.admin-modal label:first-of-type { margin-top: 0; }
+.admin-modal input:not([type="hidden"]), .admin-modal select, .admin-modal textarea {
+  width: 100%;
+  padding: 9px 12px;
+  background: var(--bg);
+  border: 1px solid var(--border-strong);
+  border-radius: var(--radius-sm);
+  color: var(--fg);
+  font: inherit;
+  font-size: 13px;
+  transition: border-color 0.15s, box-shadow 0.15s;
+}
+.admin-modal input:focus, .admin-modal select:focus, .admin-modal textarea:focus {
+  border-color: var(--accent);
+  outline: none;
+  box-shadow: 0 0 0 3px var(--accent-dim);
+}
+.admin-modal input::placeholder, .admin-modal textarea::placeholder { color: var(--fg-dim); opacity: 0.6; }
+.admin-modal textarea { resize: vertical; min-height: 40px; }
+.admin-modal [role="alert"] { color: var(--red); font-size: 12px; margin-bottom: 8px; display: none; }
+
+.modal-buttons { display: flex; gap: 10px; margin-top: 20px; }
+.modal-cancel {
+  flex: 1;
+  padding: 9px;
+  background: var(--bg-highlight);
+  color: var(--fg);
+  border: 1px solid var(--border-strong);
+  border-radius: var(--radius-sm);
+  font: inherit;
+  font-family: var(--font-display);
+  font-size: 12px;
+  font-weight: 500;
+  cursor: pointer;
+  transition: background 0.15s;
+}
+.modal-cancel:hover { background: var(--bg-elevated); }
+.modal-cancel:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+.modal-submit {
+  flex: 1;
+  padding: 9px;
+  background: var(--accent);
+  color: var(--bg);
+  border: none;
+  border-radius: var(--radius-sm);
+  font: inherit;
+  font-family: var(--font-display);
+  font-size: 12px;
+  font-weight: 600;
+  cursor: pointer;
+  transition: filter 0.15s;
+}
+.modal-submit:hover { filter: brightness(1.1); }
+.modal-submit:focus-visible { outline: 2px solid var(--fg-bright); outline-offset: 2px; }
+.modal-submit:disabled { opacity: 0.4; cursor: not-allowed; filter: none; }
+
+#create-user-overlay, #create-token-overlay, #token-created-overlay, #create-channel-overlay, #confirm-overlay,
+#create-schedule-overlay, #edit-schedule-overlay, #schedule-runs-overlay {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.7);
+  backdrop-filter: blur(6px);
+  -webkit-backdrop-filter: blur(6px);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 500;
+}
+
+/* Token display (show-once) */
+.token-created-warning {
+  font-family: var(--font-display);
+  font-size: 11px;
+  color: var(--yellow);
+  margin-bottom: 12px;
+}
+.token-display {
+  font-family: var(--font-mono);
+  font-size: 11px;
+  color: var(--fg-bright);
+  background: var(--bg);
+  padding: 12px;
+  border-radius: var(--radius-sm);
+  border: 1px solid var(--border-strong);
+  word-break: break-all;
+  user-select: all;
+}
+
+@media (max-width: 700px) {
+  #admin-users .admin-colheaders, #admin-users .admin-row {
+    grid-template-columns: 100px 1fr 80px;
+  }
+  .admin-col-created { display: none; }
+  #admin-tokens .admin-colheaders, #admin-tokens .admin-row {
+    grid-template-columns: 80px 1fr 100px 80px;
+  }
+  .admin-col-created, .admin-col-expires { display: none; }
+  #admin-channels .admin-colheaders, #admin-channels .admin-row {
+    grid-template-columns: 80px 1fr 80px;
+  }
+  #admin-channels .admin-col-created { display: none; }
+  #admin-schedules .admin-colheaders, #admin-schedules .admin-row {
+    grid-template-columns: 1fr 60px 80px 130px;
+  }
+  .admin-col-sschedule, .admin-col-starget, .admin-col-snext { display: none; }
+}
+
 /* ==========================================================================
   Reduced motion — console-specific
   ========================================================================== */
@@ -688,4 +1039,7 @@
  .node-link, .dash-cell-node, .pagination button { transition: none; }
  .dash-row.has-link::after, .node-group-header::before { transition: none; }
  #new-ws-box select, #new-ws-box input, #new-ws-buttons button { transition: none; }
+  .admin-tab, .admin-row, .admin-btn-danger, .admin-btn-action { transition: none; }
+  .admin-action-btn, .modal-cancel, .modal-submit { transition: none; }
+  .admin-modal input, .admin-modal select { transition: none; }
 }
@@ -61,7 +61,7 @@ _CONFIG_MAP: dict[str, dict[str, str]] = {
    },
    "session": {
        "instructions": "instructions",
-        "retention_days": "session_retention_days",
+        "retention_days": "retention_days",
        "compact_max_tokens": "compact_max_tokens",
        "auto_compact_pct": "auto_compact_pct",
    },
@@ -0,0 +1,185 @@
+"""Structured logging configuration for all Turnstone services."""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from contextvars import ContextVar
+from typing import Any
+
+import structlog
+
+# ---------------------------------------------------------------------------
+# Context variables — set in request handlers, workstream managers, etc.
+# Any non-empty value is automatically injected into every log event.
+# ---------------------------------------------------------------------------
+
+ctx_node_id: ContextVar[str] = ContextVar("node_id", default="")
+ctx_ws_id: ContextVar[str] = ContextVar("ws_id", default="")
+ctx_user_id: ContextVar[str] = ContextVar("user_id", default="")
+ctx_request_id: ContextVar[str] = ContextVar("request_id", default="")
+
+_CONTEXT_VARS: list[tuple[ContextVar[str], str]] = [
+    (ctx_node_id, "node_id"),
+    (ctx_ws_id, "ws_id"),
+    (ctx_user_id, "user_id"),
+    (ctx_request_id, "request_id"),
+]
+
+# Third-party loggers that are noisy at INFO level.
+_QUIET_LOGGERS = ("httpx", "httpcore", "openai", "anthropic", "uvicorn.access")
+
+
+# ---------------------------------------------------------------------------
+# Processors
+# ---------------------------------------------------------------------------
+
+
+def _inject_context(_logger: Any, _method: str, event_dict: dict[str, Any]) -> dict[str, Any]:
+    """Add non-empty context variables to every log event."""
+    for var, key in _CONTEXT_VARS:
+        val = var.get("")
+        if val:
+            event_dict[key] = val
+    return event_dict
+
+
+def _add_service(service: str) -> structlog.types.Processor:
+    """Return a processor that stamps *service* onto every event."""
+
+    def _processor(_logger: Any, _method: str, event_dict: dict[str, Any]) -> dict[str, Any]:
+        event_dict["service"] = service
+        return event_dict
+
+    return _processor  # type: ignore[return-value]
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def configure_logging(
+    level: str = "INFO",
+    *,
+    json_output: bool | None = None,
+    service: str = "",
+) -> None:
+    """Configure structured logging for a Turnstone service.
+
+    Call this once, early in each entry-point's ``main()``.
+
+    Parameters
+    ----------
+    level:
+        Log level name (``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``,
+        ``CRITICAL``).  The ``TURNSTONE_LOG_LEVEL`` env var, if set,
+        overrides this.
+    json_output:
+        Force JSON (``True``) or console (``False``) output.  ``None``
+        auto-detects: JSON when stderr is not a TTY.  The
+        ``TURNSTONE_LOG_FORMAT`` env var (``json`` / ``text``) overrides.
+    service:
+        Service name added to every log line (e.g. ``"server"``).
+    """
+    # Env-var overrides -------------------------------------------------------
+    env_level = os.environ.get("TURNSTONE_LOG_LEVEL", "").upper()
+    if env_level:
+        level = env_level
+
+    env_fmt = os.environ.get("TURNSTONE_LOG_FORMAT", "").lower()
+    if env_fmt in ("json", "text"):
+        json_output = env_fmt == "json"
+    elif json_output is None:
+        json_output = not sys.stderr.isatty()
+
+    # Shared processor chain --------------------------------------------------
+    processors: list[structlog.types.Processor] = [
+        structlog.contextvars.merge_contextvars,
+        _inject_context,  # type: ignore[list-item]
+        structlog.stdlib.add_log_level,
+        structlog.stdlib.add_logger_name,
+        structlog.processors.TimeStamper(fmt="iso"),
+        structlog.processors.StackInfoRenderer(),
+        structlog.processors.format_exc_info,
+        structlog.processors.UnicodeDecoder(),
+    ]
+
+    if service:
+        processors.append(_add_service(service))
+
+    # Renderer ----------------------------------------------------------------
+    if json_output:
+        renderer: structlog.types.Processor = structlog.processors.JSONRenderer()
+    else:
+        renderer = structlog.dev.ConsoleRenderer(colors=sys.stderr.isatty())
+
+    # structlog config (for structlog.get_logger()) ---------------------------
+    structlog.configure(
+        processors=[
+            *processors,
+            structlog.stdlib.ProcessorFormatter.wrap_for_formatter,
+        ],
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        wrapper_class=structlog.stdlib.BoundLogger,
+        cache_logger_on_first_use=True,
+    )
+
+    # stdlib handler (for logging.getLogger()) --------------------------------
+    # foreign_pre_chain runs on events from stdlib loggers (not structlog).
+    formatter = structlog.stdlib.ProcessorFormatter(
+        foreign_pre_chain=processors,
+        processors=[
+            structlog.stdlib.ProcessorFormatter.remove_processors_meta,
+            renderer,
+        ],
+    )
+
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(formatter)
+
+    root = logging.getLogger()
+    root.handlers.clear()
+    root.addHandler(handler)
+    root.setLevel(getattr(logging, level.upper(), logging.INFO))
+
+    # Quiet noisy third-party loggers -----------------------------------------
+    for name in _QUIET_LOGGERS:
+        logging.getLogger(name).setLevel(logging.WARNING)
+
+
+def get_logger(name: str) -> structlog.stdlib.BoundLogger:
+    """Return a structlog bound logger backed by the stdlib."""
+    result: structlog.stdlib.BoundLogger = structlog.get_logger(name)
+    return result
+
+
+# ---------------------------------------------------------------------------
+# CLI helpers
+# ---------------------------------------------------------------------------
+
+
+def add_log_args(parser: Any) -> None:
+    """Add ``--log-level`` and ``--log-format`` arguments to *parser*."""
+    parser.add_argument(
+        "--log-level",
+        default="INFO",
+        choices=["DEBUG", "INFO", "WARNING", "ERROR"],
+        help="Log level (default: %(default)s)",
+    )
+    parser.add_argument(
+        "--log-format",
+        default="auto",
+        choices=["auto", "json", "text"],
+        help="Log output format (default: auto — JSON when stderr is not a TTY)",
+    )
+
+
+def configure_logging_from_args(args: Any, service: str) -> None:
+    """Call :func:`configure_logging` using parsed CLI arguments."""
+    configure_logging(
+        level=args.log_level,
+        json_output={"json": True, "text": False}.get(args.log_format),
+        service=service,
+    )
@@ -21,17 +21,11 @@ def normalize_key(key: str) -> str:
    return key.lower().replace("-", "_").replace(" ", "_")


-# -- Core session operations ---------------------------------------------------
-
-
-def register_session(session_id: str, title: str | None = None) -> None:
-    """Create a sessions row for a new session (no-op if already exists)."""
-    with contextlib.suppress(Exception):
-        get_storage().register_session(session_id, title)
+# -- Core conversation operations ---------------------------------------------


 def save_message(
-    session_id: str,
+    ws_id: str,
    role: str,
    content: str | None,
    tool_name: str | None = None,
@@ -42,108 +36,136 @@ def save_message(
    """Log a message to the conversations table."""
    with contextlib.suppress(Exception):
        get_storage().save_message(
-            session_id, role, content, tool_name, tool_args, tool_call_id, provider_data
+            ws_id, role, content, tool_name, tool_args, tool_call_id, provider_data
        )


-def load_session_messages(session_id: str) -> list[dict[str, Any]]:
-    """Load messages for a session and reconstruct OpenAI message format."""
+def load_messages(ws_id: str) -> list[dict[str, Any]]:
+    """Load messages for a workstream and reconstruct OpenAI message format."""
    try:
-        return get_storage().load_session_messages(session_id)
+        return get_storage().load_messages(ws_id)
    except Exception:
        return []


-# -- Session management --------------------------------------------------------
+# -- Workstream management ----------------------------------------------------


-def list_sessions(limit: int = 20) -> list[Any]:
-    """List recent sessions with message counts."""
+def register_workstream(
+    ws_id: str, node_id: str | None = None, name: str = "", state: str = "idle"
+) -> None:
+    """Persist a new workstream (no-op if already exists)."""
+    with contextlib.suppress(Exception):
+        get_storage().register_workstream(ws_id, node_id, name, state)
+
+
+def update_workstream_state(ws_id: str, state: str) -> None:
+    """Update a workstream's state."""
+    with contextlib.suppress(Exception):
+        get_storage().update_workstream_state(ws_id, state)
+
+
+def update_workstream_name(ws_id: str, name: str) -> None:
+    """Update a workstream's display name."""
+    with contextlib.suppress(Exception):
+        get_storage().update_workstream_name(ws_id, name)
+
+
+def list_workstreams(node_id: str | None = None, limit: int = 100) -> list[Any]:
+    """List workstreams, optionally filtered by node_id."""
    try:
-        return get_storage().list_sessions(limit)
+        return get_storage().list_workstreams(node_id, limit)
    except Exception:
        return []


-def delete_session(session_id: str) -> bool:
-    """Delete a session and all its messages."""
+def list_workstreams_with_history(limit: int = 20) -> list[Any]:
+    """List workstreams that have conversation messages."""
    try:
-        return get_storage().delete_session(session_id)
+        return get_storage().list_workstreams_with_history(limit)
+    except Exception:
+        return []
+
+
+def delete_workstream(ws_id: str) -> bool:
+    """Delete a workstream and all its conversations + config."""
+    try:
+        return get_storage().delete_workstream(ws_id)
    except Exception:
        return False


-def prune_sessions(
+def prune_workstreams(
    retention_days: int = 90,
    log_fn: Callable[[str], None] | None = None,
 ) -> tuple[int, int]:
-    """Prune orphaned and stale sessions."""
+    """Prune orphaned and stale workstreams."""
    try:
-        orphans, stale = get_storage().prune_sessions(retention_days)
+        orphans, stale = get_storage().prune_workstreams(retention_days)
    except Exception:
        return (0, 0)

    if log_fn and (orphans or stale):
        parts = []
        if orphans:
-            parts.append(f"{orphans} empty session{'s' if orphans != 1 else ''}")
+            parts.append(f"{orphans} empty workstream{'s' if orphans != 1 else ''}")
        if stale:
            parts.append(
-                f"{stale} session{'s' if stale != 1 else ''} older than {retention_days} days"
+                f"{stale} workstream{'s' if stale != 1 else ''} older than {retention_days} days"
            )
-        log_fn(f"[turnstone] Session cleanup: removed {', '.join(parts)}.")
+        log_fn(f"[turnstone] Cleanup: removed {', '.join(parts)}.")

    return (orphans, stale)


-def resolve_session(alias_or_id: str) -> str | None:
-    """Resolve an alias or session_id (or prefix) to a full session_id."""
+def resolve_workstream(alias_or_id: str) -> str | None:
+    """Resolve an alias or ws_id (or prefix) to a full ws_id."""
    try:
-        return get_storage().resolve_session(alias_or_id)
+        return get_storage().resolve_workstream(alias_or_id)
    except Exception:
        return None


-# -- Session config ------------------------------------------------------------
+# -- Workstream config --------------------------------------------------------


-def save_session_config(session_id: str, config: dict[str, str]) -> None:
-    """Persist session configuration key/value pairs."""
+def save_workstream_config(ws_id: str, config: dict[str, str]) -> None:
+    """Persist workstream configuration key/value pairs."""
    with contextlib.suppress(Exception):
-        get_storage().save_session_config(session_id, config)
+        get_storage().save_workstream_config(ws_id, config)


-def load_session_config(session_id: str) -> dict[str, str]:
-    """Load session configuration."""
+def load_workstream_config(ws_id: str) -> dict[str, str]:
+    """Load workstream configuration."""
    try:
-        return get_storage().load_session_config(session_id)
+        return get_storage().load_workstream_config(ws_id)
    except Exception:
        return {}


-# -- Session metadata ----------------------------------------------------------
+# -- Workstream metadata ------------------------------------------------------


-def set_session_alias(session_id: str, alias: str) -> bool:
+def set_workstream_alias(ws_id: str, alias: str) -> bool:
    """Set a human-friendly alias. Returns False if alias is taken."""
    try:
-        return get_storage().set_session_alias(session_id, alias)
+        return get_storage().set_workstream_alias(ws_id, alias)
    except Exception:
        return False


-def get_session_name(session_id: str) -> str | None:
-    """Return the alias (or title) for a session, or None if unset."""
+def get_workstream_display_name(ws_id: str) -> str | None:
+    """Return the alias (or title) for a workstream, or None if unset."""
    try:
-        return get_storage().get_session_name(session_id)
+        return get_storage().get_workstream_display_name(ws_id)
    except Exception:
        return None


-def update_session_title(session_id: str, title: str) -> None:
-    """Set or update the auto-generated title for a session."""
+def update_workstream_title(ws_id: str, title: str) -> None:
+    """Set or update the auto-generated title for a workstream."""
    with contextlib.suppress(Exception):
-        get_storage().update_session_title(session_id, title)
+        get_storage().update_workstream_title(ws_id, title)


 # -- Key-value store (memories) ------------------------------------------------
@@ -259,19 +259,13 @@ class MetricsCollector:

        # Per-workstream metrics (only when data is provided)
        if workstream_metrics:
-            # turnstone_workstream_info — exposes session_id as a label for joining,
-            # without propagating that high-cardinality label to counters.
-            lines.append(
-                "# HELP turnstone_workstream_info Workstream metadata"
-                " (join on session_id for per-session queries)"
-            )
+            lines.append("# HELP turnstone_workstream_info Workstream metadata")
            lines.append("# TYPE turnstone_workstream_info gauge")
            for wm in workstream_metrics:
                lstr = _fmt_labels(
                    {
                        "ws_id": wm["ws_id"],
                        "name": wm["name"],
-                        "session_id": wm["session_id"],
                    }
                )
                lines.append(f"turnstone_workstream_info{lstr} 1")
@@ -45,6 +45,14 @@ _OPENAI_CAPABILITIES: dict[str, ModelCapabilities] = {
        reasoning_effort_values=("minimal", "low", "medium", "high"),
        default_reasoning_effort="medium",
    ),
+    # GPT-5 pro — high reasoning only, extended output
+    "gpt-5-pro": ModelCapabilities(
+        context_window=400000,
+        max_output_tokens=272000,
+        supports_temperature=False,
+        reasoning_effort_values=("high",),
+        default_reasoning_effort="high",
+    ),
    # GPT-5.1 — temperature OK when reasoning_effort=none (default)
    "gpt-5.1": ModelCapabilities(
        context_window=400000,
@@ -59,6 +67,36 @@ _OPENAI_CAPABILITIES: dict[str, ModelCapabilities] = {
        reasoning_effort_values=("none", "low", "medium", "high", "xhigh"),
        default_reasoning_effort="none",
    ),
+    # GPT-5.2 pro — always-reasoning variant
+    "gpt-5.2-pro": ModelCapabilities(
+        context_window=400000,
+        max_output_tokens=128000,
+        supports_temperature=False,
+        reasoning_effort_values=("medium", "high", "xhigh"),
+        default_reasoning_effort="medium",
+    ),
+    # GPT-5.3 — same capabilities as 5.2 (matches gpt-5.3-chat-latest, codex)
+    "gpt-5.3": ModelCapabilities(
+        context_window=400000,
+        max_output_tokens=128000,
+        reasoning_effort_values=("none", "low", "medium", "high", "xhigh"),
+        default_reasoning_effort="none",
+    ),
+    # GPT-5.4 — 1M context window
+    "gpt-5.4": ModelCapabilities(
+        context_window=1050000,
+        max_output_tokens=128000,
+        reasoning_effort_values=("none", "low", "medium", "high", "xhigh"),
+        default_reasoning_effort="none",
+    ),
+    # GPT-5.4 pro — always-reasoning, 1M context
+    "gpt-5.4-pro": ModelCapabilities(
+        context_window=1050000,
+        max_output_tokens=128000,
+        supports_temperature=False,
+        reasoning_effort_values=("medium", "high", "xhigh"),
+        default_reasoning_effort="medium",
+    ),
    # O-series reasoning models
    "o1": ModelCapabilities(
        context_window=200000,
@@ -145,7 +183,11 @@ class OpenAIProvider:
            else:
                kwargs["temperature"] = temperature
        if caps.reasoning_effort_values and reasoning_effort and reasoning_effort != "none":
-            kwargs["reasoning_effort"] = reasoning_effort
+            # Validate against supported values; fall back to model default
+            if reasoning_effort in caps.reasoning_effort_values:
+                kwargs["reasoning_effort"] = reasoning_effort
+            elif caps.default_reasoning_effort and caps.default_reasoning_effort != "none":
+                kwargs["reasoning_effort"] = caps.default_reasoning_effort

    # -- web search ----------------------------------------------------------

@@ -26,29 +26,30 @@ import httpx

 from turnstone.core.config import get_tavily_key
 from turnstone.core.edit import find_occurrences, pick_nearest
+from turnstone.core.log import get_logger
 from turnstone.core.memory import (
    delete_memory,
-    delete_session,
-    get_session_name,
-    list_sessions,
+    delete_workstream,
+    get_workstream_display_name,
+    list_workstreams_with_history,
    load_memories,
-    load_session_config,
-    load_session_messages,
+    load_messages,
+    load_workstream_config,
    normalize_key,
-    register_session,
-    resolve_session,
+    resolve_workstream,
    save_memory,
    save_message,
-    save_session_config,
+    save_workstream_config,
    search_history,
    search_history_recent,
    search_memories,
-    set_session_alias,
-    update_session_title,
+    set_workstream_alias,
+    update_workstream_title,
 )
 from turnstone.core.providers import create_provider
 from turnstone.core.safety import is_command_blocked, sanitize_command
 from turnstone.core.sandbox import execute_math_sandboxed
+from turnstone.core.storage._registry import get_storage
 from turnstone.core.tools import (
    AGENT_AUTO_TOOLS,
    AGENT_TOOLS,
@@ -61,6 +62,8 @@ from turnstone.core.tools import (
 from turnstone.core.web import check_ssrf, strip_html
 from turnstone.ui.colors import DIM, GRAY, GREEN, RED, RESET, YELLOW, bold, cyan, dim

+log = get_logger(__name__)
+
 if TYPE_CHECKING:
    from collections.abc import Iterator

@@ -91,6 +94,43 @@ class SessionUI(Protocol):
    def on_rename(self, name: str) -> None: ...


+# ---------------------------------------------------------------------------
+# Notify auth helper (module-level, lazy-init)
+# ---------------------------------------------------------------------------
+
+_notify_token_manager: Any = None
+_notify_token_lock = threading.Lock()
+
+
+def _notify_auth_headers() -> dict[str, str]:
+    """Return Authorization headers for outbound notify requests."""
+    global _notify_token_manager
+
+    # Static token from env takes precedence
+    static_token = os.environ.get("TURNSTONE_CHANNEL_AUTH_TOKEN", "").strip()
+    if static_token:
+        return {"Authorization": f"Bearer {static_token}"}
+
+    # JWT via ServiceTokenManager
+    jwt_secret = os.environ.get("TURNSTONE_JWT_SECRET", "").strip()
+    if not jwt_secret:
+        return {}
+
+    with _notify_token_lock:
+        if _notify_token_manager is None:
+            from turnstone.core.auth import JWT_AUD_CHANNEL, ServiceTokenManager
+
+            _notify_token_manager = ServiceTokenManager(
+                user_id="system",
+                scopes=frozenset({"write"}),
+                source="service",
+                secret=jwt_secret,
+                audience=JWT_AUD_CHANNEL,
+            )
+    header: dict[str, str] = _notify_token_manager.bearer_header
+    return header
+
+
 # ---------------------------------------------------------------------------
 # ChatSession — the core engine
 # ---------------------------------------------------------------------------
@@ -116,6 +156,8 @@ class ChatSession:
        registry: ModelRegistry | None = None,
        model_alias: str | None = None,
        health_monitor: BackendHealthMonitor | None = None,
+        node_id: str | None = None,
+        ws_id: str | None = None,
    ):
        self.client = client
        self.model = model
@@ -148,9 +190,9 @@ class ChatSession:
        self.show_reasoning = True
        self.debug = False
        self.auto_approve = False
-        self._session_id = uuid.uuid4().hex[:12]
+        self._node_id = node_id
+        self._ws_id = ws_id or uuid.uuid4().hex
        self._title_generated = False
-        register_session(self._session_id)
        self._read_files: set[str] = set()
        self.messages: list[dict[str, Any]] = []
        self._last_usage: dict[str, int] | None = None
@@ -158,6 +200,7 @@ class ChatSession:
        self._system_tokens = 0  # tokens for system_messages
        self._assistant_pending_tokens = 0
        self.creative_mode = False
+        self._notify_count = 0
        # MCP tool integration: merge external tools with built-in
        self._mcp_client = mcp_client
        if mcp_client:
@@ -173,17 +216,17 @@ class ChatSession:
        self._save_config()

    @property
-    def session_id(self) -> str:
-        return self._session_id
+    def ws_id(self) -> str:
+        return self._ws_id

    @property
    def model_alias(self) -> str | None:
        return self._model_alias

    def _save_config(self) -> None:
-        """Persist LLM-affecting config so resumed sessions behave identically."""
-        save_session_config(
-            self._session_id,
+        """Persist LLM-affecting config so resumed workstreams behave identically."""
+        save_workstream_config(
+            self._ws_id,
            {
                "temperature": str(self.temperature),
                "reasoning_effort": self.reasoning_effort,
@@ -252,32 +295,32 @@ class ChatSession:
            # Take first line, strip quotes
            title = raw.split("\n")[0].strip().strip('"').strip("'")
            if title:
-                update_session_title(self._session_id, title[:80])
+                update_workstream_title(self._ws_id, title[:80])
        except Exception:
            pass  # Title generation is non-critical

-    def resume_session(self, session_id: str) -> bool:
-        """Load messages from a previous session and resume it.
+    def resume(self, ws_id: str) -> bool:
+        """Load messages from a previous workstream and resume it.

        Replaces the current conversation with the loaded messages,
-        adopting the old session_id so new messages continue in the same
-        session.  Restores persisted config (temperature, reasoning_effort,
-        etc.) so the resumed session behaves identically to the original.
+        adopting the old ws_id so new messages continue in the same
+        workstream.  Restores persisted config (temperature, reasoning_effort,
+        etc.) so the resumed workstream behaves identically to the original.
        Returns True on success.
        """
-        messages = load_session_messages(session_id)
+        messages = load_messages(ws_id)
        if not messages:
            return False
-        self._session_id = session_id
+        self._ws_id = ws_id
        self.messages = messages
        self._read_files.clear()
        self._last_usage = None
-        self._title_generated = True  # don't re-title resumed sessions
+        self._title_generated = True  # don't re-title resumed workstreams
        self._msg_tokens = [
            max(1, int(self._msg_char_count(m) / self._chars_per_token)) for m in self.messages
        ]
        # Restore persisted config
-        config = load_session_config(session_id)
+        config = load_workstream_config(ws_id)
        if config:
            if "temperature" in config:
                self.temperature = float(config["temperature"])
@@ -464,9 +507,10 @@ class ChatSession:

    def send(self, user_input: str) -> None:
        """Send user input and handle the response loop (including tool calls)."""
+        self._notify_count = 0
        self.messages.append({"role": "user", "content": user_input})
        self._msg_tokens.append(max(1, int(len(user_input) / self._chars_per_token)))
-        save_message(self._session_id, "user", user_input)
+        save_message(self._ws_id, "user", user_input)

        try:
            while True:
@@ -502,9 +546,7 @@ class ChatSession:

                    provider_data = _json.dumps(assistant_msg["_provider_content"])
                if content or provider_data is not None:
-                    save_message(
-                        self._session_id, "assistant", content, provider_data=provider_data
-                    )
+                    save_message(self._ws_id, "assistant", content, provider_data=provider_data)
                if tc:
                    for call in tc:
                        fn = call.get("function", {})
@@ -515,7 +557,7 @@ class ChatSession:
                            "recall",
                        ):
                            save_message(
-                                self._session_id,
+                                self._ws_id,
                                "tool_call",
                                None,
                                name,
@@ -565,7 +607,7 @@ class ChatSession:
                        "recall",
                    ):
                        save_message(
-                            self._session_id,
+                            self._ws_id,
                            "tool_result",
                            output[:2000],
                            _tname,
@@ -1244,6 +1286,7 @@ class ChatSession:
            "remember": self._prepare_remember,
            "recall": self._prepare_recall,
            "forget": self._prepare_forget,
+            "notify": self._prepare_notify,
        }
        preparer = preparers.get(func_name)
        if not preparer:
@@ -2279,9 +2322,9 @@ class ChatSession:
    )

    def _exec_plan(self, item: dict[str, Any]) -> tuple[str, str]:
-        """Run a planning agent and write the result to .plan-<session_id>.md."""
+        """Run a planning agent and write the result to .plan-<ws_id>.md."""
        call_id, prompt = item["call_id"], item["prompt"]
-        plan_path = f".plan-{self._session_id}.md"
+        plan_path = f".plan-{self._ws_id}.md"

        # If plan was called before in this session, the previous assistant
        # tool_call + tool result are already in self.messages — pass them
@@ -2390,6 +2433,195 @@ class ChatSession:
        self.ui.on_tool_result(call_id, "recall", output)
        return call_id, output

+    # -- Notify tool -----------------------------------------------------------
+
+    def _prepare_notify(self, call_id: str, args: dict[str, Any]) -> dict[str, Any]:
+        """Prepare a channel notification."""
+        message = (args.get("message") or "").strip()
+        if not message:
+            return {
+                "call_id": call_id,
+                "func_name": "notify",
+                "header": "\u2717 notify: empty message",
+                "preview": "",
+                "needs_approval": False,
+                "error": "Error: message is required",
+            }
+        if len(message) > 2000:
+            return {
+                "call_id": call_id,
+                "func_name": "notify",
+                "header": "\u2717 notify: message too long",
+                "preview": "",
+                "needs_approval": False,
+                "error": "Error: message exceeds 2000 character limit",
+            }
+
+        username = (args.get("username") or "").strip()
+        channel_type = (args.get("channel_type") or "").strip()
+        channel_id = (args.get("channel_id") or "").strip()
+        title = (args.get("title") or "").strip()
+
+        has_username = bool(username)
+        has_direct = bool(channel_type and channel_id)
+
+        if has_username and has_direct:
+            return {
+                "call_id": call_id,
+                "func_name": "notify",
+                "header": "\u2717 notify: ambiguous target",
+                "preview": "",
+                "needs_approval": False,
+                "error": "Error: provide either username or channel_type+channel_id, not both",
+            }
+        if channel_type and not channel_id:
+            return {
+                "call_id": call_id,
+                "func_name": "notify",
+                "header": "\u2717 notify: incomplete target",
+                "preview": "",
+                "needs_approval": False,
+                "error": "Error: channel_id is required when channel_type is provided",
+            }
+        if channel_id and not channel_type:
+            return {
+                "call_id": call_id,
+                "func_name": "notify",
+                "header": "\u2717 notify: incomplete target",
+                "preview": "",
+                "needs_approval": False,
+                "error": "Error: channel_type is required when channel_id is provided",
+            }
+        if not has_username and not has_direct:
+            return {
+                "call_id": call_id,
+                "func_name": "notify",
+                "header": "\u2717 notify: no target",
+                "preview": "",
+                "needs_approval": False,
+                "error": "Error: provide username or channel_type+channel_id",
+            }
+
+        target_desc = f"@{username}" if has_username else f"{channel_type}:{channel_id}"
+
+        preview = message[:120] + ("..." if len(message) > 120 else "")
+        return {
+            "call_id": call_id,
+            "func_name": "notify",
+            "header": f"\u2709 notify \u2192 {target_desc}",
+            "preview": preview,
+            "needs_approval": False,
+            "execute": self._exec_notify,
+            "message": message,
+            "username": username,
+            "channel_type": channel_type,
+            "channel_id": channel_id,
+            "title": title,
+        }
+
+    _NOTIFY_MAX_RETRIES = 2
+    _NOTIFY_RETRY_DELAYS = (1.0, 3.0)
+
+    def _exec_notify(self, item: dict[str, Any]) -> tuple[str, str]:
+        """Send a notification directly to the channel gateway via HTTP."""
+        call_id = item["call_id"]
+
+        if self._notify_count >= 5:
+            msg = "Error: notification rate limit exceeded (max 5 per turn)"
+            self.ui.on_tool_result(call_id, "notify", msg)
+            return call_id, msg
+
+        target: dict[str, str] = {}
+        if item.get("username"):
+            target["username"] = item["username"]
+        else:
+            target["channel_type"] = item["channel_type"]
+            target["channel_id"] = item["channel_id"]
+
+        payload = {
+            "target": target,
+            "message": item["message"],
+            "title": item.get("title", ""),
+        }
+
+        # Build auth headers for service-to-service call
+        auth_headers = _notify_auth_headers()
+
+        # Retry loop: attempt delivery, re-query services on each retry
+        # in case a gateway comes back online between attempts.
+        for attempt in range(1 + self._NOTIFY_MAX_RETRIES):
+            storage = get_storage()
+            services = storage.list_services("channel", max_age_seconds=120)
+            if not services:
+                if attempt < self._NOTIFY_MAX_RETRIES:
+                    delay = self._NOTIFY_RETRY_DELAYS[attempt]
+                    log.warning(
+                        "notify.no_services",
+                        attempt=attempt + 1,
+                        max_retries=self._NOTIFY_MAX_RETRIES,
+                        retry_delay=delay,
+                    )
+                    time.sleep(delay)
+                    continue
+                log.warning("notify.no_services_exhausted")
+                msg = "Error: no channel gateway services available"
+                self.ui.on_tool_result(call_id, "notify", msg)
+                return call_id, msg
+
+            # Try first healthy gateway, fall back to next
+            last_error: str = ""
+            for svc in services:
+                url = svc["url"].rstrip("/") + "/v1/api/notify"
+                # SSRF guard: only allow http(s) URLs
+                if not url.startswith(("http://", "https://")):
+                    continue
+                try:
+                    resp = httpx.post(url, json=payload, timeout=10, headers=auth_headers)
+                    if resp.status_code < 300:
+                        # Check that at least one target was actually delivered
+                        try:
+                            data = resp.json()
+                        except Exception:
+                            last_error = "invalid gateway response"
+                            continue
+                        results = data.get("results") if isinstance(data, dict) else None
+                        if isinstance(results, list) and any(
+                            isinstance(r, dict) and r.get("status") == "sent" for r in results
+                        ):
+                            self._notify_count += 1
+                            msg = "Notification sent successfully"
+                            self.ui.on_tool_result(call_id, "notify", msg)
+                            return call_id, msg
+                        last_error = "no successful deliveries"
+                        continue
+                    last_error = f"HTTP {resp.status_code}"
+                except Exception as exc:
+                    last_error = type(exc).__name__
+                    continue  # try next gateway
+
+            # All gateways failed this attempt — retry if we have attempts left
+            if attempt < self._NOTIFY_MAX_RETRIES:
+                delay = self._NOTIFY_RETRY_DELAYS[attempt]
+                log.warning(
+                    "notify.all_gateways_failed",
+                    attempt=attempt + 1,
+                    max_retries=self._NOTIFY_MAX_RETRIES,
+                    last_error=last_error,
+                    gateway_count=len(services),
+                    retry_delay=delay,
+                )
+                time.sleep(delay)
+            else:
+                log.warning(
+                    "notify.delivery_failed",
+                    last_error=last_error,
+                    gateway_count=len(services),
+                )
+
+        msg = "Error: notification delivery failed"
+        self.ui.on_tool_result(call_id, "notify", msg)
+        return call_id, msg
+
    def _exec_write_file(self, item: dict[str, Any]) -> tuple[str, str]:
        """Write content to a file, creating parent directories as needed."""
        call_id = item["call_id"]
@@ -2671,29 +2903,31 @@ class ChatSession:
            self._read_files.clear()
            self._last_usage = None
            self._msg_tokens = []
-            self.ui.on_info("Context cleared (session preserved in database).")
+            self.ui.on_info("Context cleared (messages preserved in database).")

        elif cmd == "/new":
+            from turnstone.core.memory import register_workstream
+
            self.messages.clear()
            self._read_files.clear()
            self._last_usage = None
            self._msg_tokens = []
-            self._session_id = uuid.uuid4().hex[:12]
+            self._ws_id = uuid.uuid4().hex
            self._title_generated = False
-            register_session(self._session_id)
+            register_workstream(self._ws_id, node_id=self._node_id)
            self._save_config()
-            self.ui.on_info("New session started.")
+            self.ui.on_info("New workstream started.")

-        elif cmd == "/sessions":
-            rows = list_sessions(limit=20)
+        elif cmd == "/workstreams":
+            rows = list_workstreams_with_history(limit=20)
            if not rows:
-                self.ui.on_info("No saved sessions.")
+                self.ui.on_info("No saved workstreams.")
            else:
-                lines = ["Sessions:\n"]
-                for sid, alias, title, _created, updated, count in rows:
-                    display_name = alias or sid
+                lines = ["Workstreams:\n"]
+                for wid, alias, title, _created, updated, count, *_extra in rows:
+                    display_name = alias or wid
                    display_title = f"  {title}" if title else ""
-                    marker = " *" if sid == self._session_id else "  "
+                    marker = " *" if wid == self._ws_id else "  "
                    lines.append(
                        f" {marker} {bold(display_name)}{display_title}  "
                        f"{dim(f'{count} msgs, {updated}')}"
@@ -2703,30 +2937,29 @@ class ChatSession:
        elif cmd == "/resume":
            if not arg:
                self.ui.on_info(
-                    "Usage: /resume <alias_or_session_id>\n"
-                    "Use /sessions to list available sessions."
+                    "Usage: /resume <alias_or_ws_id>\nUse /workstreams to list available workstreams."
                )
            else:
-                target_id = resolve_session(arg.strip())
+                target_id = resolve_workstream(arg.strip())
                if not target_id:
-                    self.ui.on_info(f"Session not found: {arg.strip()}")
-                elif target_id == self._session_id:
-                    self.ui.on_info("Already in that session.")
-                elif self.resume_session(target_id):
+                    self.ui.on_info(f"Workstream not found: {arg.strip()}")
+                elif target_id == self._ws_id:
+                    self.ui.on_info("Already in that workstream.")
+                elif self.resume(target_id):
                    self.ui.on_info(
-                        f"Resumed session {bold(target_id)} ({len(self.messages)} messages loaded)"
+                        f"Resumed {bold(target_id)} ({len(self.messages)} messages loaded)"
                    )
-                    name = get_session_name(target_id)
+                    name = get_workstream_display_name(target_id)
                    if name:
                        self.ui.on_rename(name)
                else:
-                    self.ui.on_info(f"Session {arg.strip()} has no messages.")
+                    self.ui.on_info(f"Workstream {arg.strip()} has no messages.")

        elif cmd == "/name":
            if not arg:
-                self.ui.on_info(f"Current session: {self._session_id}")
-            elif set_session_alias(self._session_id, arg.strip()):
-                self.ui.on_info(f"Session named: {bold(arg.strip())}")
+                self.ui.on_info(f"Current workstream: {self._ws_id}")
+            elif set_workstream_alias(self._ws_id, arg.strip()):
+                self.ui.on_info(f"Workstream named: {bold(arg.strip())}")
                self.ui.on_rename(arg.strip())
            else:
                self.ui.on_info(f"Alias '{arg.strip()}' is already in use.")
@@ -2734,18 +2967,18 @@ class ChatSession:
        elif cmd == "/delete":
            if not arg:
                self.ui.on_info(
-                    "Usage: /delete <alias_or_session_id>\nUse /sessions to list sessions."
+                    "Usage: /delete <alias_or_ws_id>\nUse /workstreams to list workstreams."
                )
            else:
-                target_id = resolve_session(arg.strip())
+                target_id = resolve_workstream(arg.strip())
                if not target_id:
-                    self.ui.on_info(f"Session not found: {arg.strip()}")
-                elif target_id == self._session_id:
-                    self.ui.on_info("Cannot delete the active session.")
-                elif delete_session(target_id):
-                    self.ui.on_info(f"Deleted session {arg.strip()}")
+                    self.ui.on_info(f"Workstream not found: {arg.strip()}")
+                elif target_id == self._ws_id:
+                    self.ui.on_info("Cannot delete the active workstream.")
+                elif delete_workstream(target_id):
+                    self.ui.on_info(f"Deleted workstream {arg.strip()}")
                else:
-                    self.ui.on_info(f"Failed to delete session {arg.strip()}")
+                    self.ui.on_info(f"Failed to delete workstream {arg.strip()}")

        elif cmd == "/history":
            query = arg.strip() if arg else None
@@ -2873,13 +3106,13 @@ class ChatSession:
                    [
                        "── Slash Commands ─────────────────────────────────────",
                        "  /instructions <text>   Set developer instructions",
-                        "  /clear                 Clear context (session preserved in database)",
-                        "  /new                   Start a new session (old session stays resumable)",
+                        "  /clear                 Clear context (workstream preserved in database)",
+                        "  /new                   Start a new workstream (old one stays resumable)",
                        "",
-                        "  /sessions              List saved sessions",
-                        "  /resume <id|alias>     Resume a previous session",
-                        "  /name <alias>          Name the current session",
-                        "  /delete <id|alias>     Delete a saved session",
+                        "  /workstreams           List saved workstreams",
+                        "  /resume <id|alias>     Resume a previous workstream",
+                        "  /name <alias>          Name the current workstream",
+                        "  /delete <id|alias>     Delete a saved workstream",
                        "",
                        "  /history [query]       Search conversation history (or show recent)",
                        "  /compact               Compact conversation (summarize old messages)",
@@ -78,7 +78,9 @@ if __name__ == "__main__":
    url = os.environ.get("TURNSTONE_DB_URL", "")
    path = os.environ.get("TURNSTONE_DB_PATH", "")

-    logging.basicConfig(level=logging.INFO)
+    from turnstone.core.log import configure_logging
+
+    configure_logging(level="INFO", service="migrate")
    init_storage(backend, path=path, url=url, run_migrations=True)
    log.info("Migrations complete")
    get_storage().close()
@@ -9,19 +9,15 @@ from typing import Any, Protocol, runtime_checkable
 class StorageBackend(Protocol):
    """Protocol that every storage backend adapter must implement.

-    Provides session management, conversation persistence, key-value storage
+    Provides workstream management, conversation persistence, key-value storage
    (for memories), and full-text search.
    """

-    # -- Core session operations -----------------------------------------------
-
-    def register_session(self, session_id: str, title: str | None = None) -> None:
-        """Create a sessions row for a new session (no-op if already exists)."""
-        ...
+    # -- Core conversation operations ------------------------------------------

    def save_message(
        self,
-        session_id: str,
+        ws_id: str,
        role: str,
        content: str | None,
        tool_name: str | None = None,
@@ -32,50 +28,46 @@ class StorageBackend(Protocol):
        """Log a message to the conversations table."""
        ...

-    def load_session_messages(self, session_id: str) -> list[dict[str, Any]]:
-        """Load messages for a session and reconstruct OpenAI message format."""
+    def load_messages(self, ws_id: str) -> list[dict[str, Any]]:
+        """Load messages for a workstream and reconstruct OpenAI message format."""
        ...

-    # -- Session management ----------------------------------------------------
+    # -- Workstream management -------------------------------------------------

-    def list_sessions(self, limit: int = 20) -> list[Any]:
-        """List recent sessions with message counts, ordered by updated DESC."""
+    def list_workstreams_with_history(self, limit: int = 20) -> list[Any]:
+        """List workstreams that have messages, ordered by updated DESC."""
        ...

-    def delete_session(self, session_id: str) -> bool:
-        """Delete a session and all its messages. Returns True on success."""
+    def prune_workstreams(self, retention_days: int = 90) -> tuple[int, int]:
+        """Remove orphaned + stale unnamed workstreams. Returns (orphans, stale)."""
        ...

-    def prune_sessions(self, retention_days: int = 90) -> tuple[int, int]:
-        """Remove orphaned + stale unnamed sessions. Returns (orphans, stale)."""
+    def resolve_workstream(self, alias_or_id: str) -> str | None:
+        """Resolve an alias or ws_id (or prefix) to a full ws_id."""
        ...

-    def resolve_session(self, alias_or_id: str) -> str | None:
-        """Resolve an alias or session_id (or prefix) to a full session_id."""
+    # -- Workstream config -----------------------------------------------------
+
+    def save_workstream_config(self, ws_id: str, config: dict[str, str]) -> None:
+        """Persist workstream configuration key/value pairs."""
        ...

-    # -- Session config --------------------------------------------------------
-
-    def save_session_config(self, session_id: str, config: dict[str, str]) -> None:
-        """Persist session configuration key/value pairs."""
+    def load_workstream_config(self, ws_id: str) -> dict[str, str]:
+        """Load workstream configuration. Returns empty dict if none stored."""
        ...

-    def load_session_config(self, session_id: str) -> dict[str, str]:
-        """Load session configuration. Returns empty dict if none stored."""
-        ...
+    # -- Workstream metadata ---------------------------------------------------

-    # -- Session metadata ------------------------------------------------------
-
-    def set_session_alias(self, session_id: str, alias: str) -> bool:
+    def set_workstream_alias(self, ws_id: str, alias: str) -> bool:
        """Set a human-friendly alias. Returns False if alias is taken."""
        ...

-    def get_session_name(self, session_id: str) -> str | None:
-        """Return the alias (or title) for a session, or None if unset."""
+    def get_workstream_display_name(self, ws_id: str) -> str | None:
+        """Return the alias (or title) for a workstream, or None if unset."""
        ...

-    def update_session_title(self, session_id: str, title: str) -> None:
-        """Set or update the auto-generated title for a session."""
+    def update_workstream_title(self, ws_id: str, title: str) -> None:
+        """Set or update the auto-generated title for a workstream."""
        ...

    # -- Generic key-value store (backs memories table) ------------------------
@@ -100,16 +92,227 @@ class StorageBackend(Protocol):
        """Search key-value pairs by query. Returns matching (key, value) pairs."""
        ...

+    # -- Workstream operations -------------------------------------------------
+
+    def register_workstream(
+        self,
+        ws_id: str,
+        node_id: str | None = None,
+        name: str = "",
+        state: str = "idle",
+        user_id: str | None = None,
+        alias: str | None = None,
+        title: str | None = None,
+    ) -> None:
+        """Create a workstreams row (no-op if already exists)."""
+        ...
+
+    def update_workstream_state(self, ws_id: str, state: str) -> None:
+        """Update a workstream's state and bump updated timestamp."""
+        ...
+
+    def update_workstream_name(self, ws_id: str, name: str) -> None:
+        """Update a workstream's display name."""
+        ...
+
+    def delete_workstream(self, ws_id: str) -> bool:
+        """Delete a workstream and all its conversations + config."""
+        ...
+
+    def list_workstreams(self, node_id: str | None = None, limit: int = 100) -> list[Any]:
+        """List workstreams, optionally filtered by node_id."""
+        ...
+
    # -- Conversation search ---------------------------------------------------

    def search_history(self, query: str, limit: int = 20) -> list[Any]:
-        """Search conversation history. Returns (timestamp, session_id, role, content, tool_name)."""
+        """Search conversation history. Returns (timestamp, ws_id, role, content, tool_name)."""
        ...

    def search_history_recent(self, limit: int = 20) -> list[Any]:
        """Return most recent conversation messages."""
        ...

+    # -- User identity operations -----------------------------------------------
+
+    def create_user(
+        self, user_id: str, username: str, display_name: str, password_hash: str
+    ) -> None:
+        """Create a user row. No-op if user_id already exists."""
+        ...
+
+    def create_first_user(
+        self, user_id: str, username: str, display_name: str, password_hash: str
+    ) -> bool:
+        """Atomically create a user only if no users exist. Returns True if created."""
+        ...
+
+    def get_user(self, user_id: str) -> dict[str, str] | None:
+        """Return user dict {user_id, username, display_name, password_hash, created} or None."""
+        ...
+
+    def get_user_by_username(self, username: str) -> dict[str, str] | None:
+        """Lookup user by username. Returns same dict as get_user or None."""
+        ...
+
+    def list_users(self) -> list[dict[str, str]]:
+        """Return all users ordered by created DESC."""
+        ...
+
+    def delete_user(self, user_id: str) -> bool:
+        """Delete user and cascade-delete all their tokens. Returns True if existed."""
+        ...
+
+    def create_api_token(
+        self,
+        token_id: str,
+        token_hash: str,
+        token_prefix: str,
+        user_id: str,
+        name: str,
+        scopes: str,
+        expires: str | None = None,
+    ) -> None:
+        """Store a hashed API token."""
+        ...
+
+    def get_api_token_by_hash(self, token_hash: str) -> dict[str, str] | None:
+        """Lookup token by SHA-256 hash. Returns dict with all columns or None."""
+        ...
+
+    def list_api_tokens(self, user_id: str) -> list[dict[str, str]]:
+        """List tokens for a user (no hash in results, prefix only)."""
+        ...
+
+    def delete_api_token(self, token_id: str) -> bool:
+        """Revoke/delete a token by ID. Returns True if existed."""
+        ...
+
+    # -- Channel user mapping ---------------------------------------------------
+
+    def create_channel_user(self, channel_type: str, channel_user_id: str, user_id: str) -> None:
+        """Map an external channel user to a turnstone user_id. No-op if exists."""
+        ...
+
+    def get_channel_user(self, channel_type: str, channel_user_id: str) -> dict[str, str] | None:
+        """Lookup turnstone user for a channel user. Returns dict or None."""
+        ...
+
+    def list_channel_users_by_user(self, user_id: str) -> list[dict[str, str]]:
+        """List all channel mappings for a turnstone user."""
+        ...
+
+    def delete_channel_user(self, channel_type: str, channel_user_id: str) -> bool:
+        """Remove a channel user mapping. Returns True if existed."""
+        ...
+
+    # -- Channel routing -------------------------------------------------------
+
+    def create_channel_route(
+        self, channel_type: str, channel_id: str, ws_id: str, node_id: str = ""
+    ) -> None:
+        """Map a channel/thread to a workstream. No-op if exists."""
+        ...
+
+    def get_channel_route(self, channel_type: str, channel_id: str) -> dict[str, str] | None:
+        """Lookup workstream for a channel/thread."""
+        ...
+
+    def get_channel_route_by_ws(self, ws_id: str) -> dict[str, str] | None:
+        """Reverse lookup: find channel/thread for a workstream."""
+        ...
+
+    def list_channel_routes_by_type(self, channel_type: str) -> list[dict[str, str]]:
+        """List all routes for a channel type, ordered by created DESC."""
+        ...
+
+    def delete_channel_route(self, channel_type: str, channel_id: str) -> bool:
+        """Remove a channel route. Returns True if existed."""
+        ...
+
+    # -- Scheduled tasks -------------------------------------------------------
+
+    def create_scheduled_task(
+        self,
+        task_id: str,
+        name: str,
+        description: str,
+        schedule_type: str,
+        cron_expr: str,
+        at_time: str,
+        target_mode: str,
+        model: str,
+        initial_message: str,
+        auto_approve: bool,
+        auto_approve_tools: list[str],
+        created_by: str,
+        next_run: str,
+    ) -> None:
+        """Create a scheduled task. No-op if task_id already exists."""
+        ...
+
+    def get_scheduled_task(self, task_id: str) -> dict[str, Any] | None:
+        """Return scheduled task dict or None."""
+        ...
+
+    def list_scheduled_tasks(self) -> list[dict[str, Any]]:
+        """Return all scheduled tasks ordered by created DESC."""
+        ...
+
+    def update_scheduled_task(self, task_id: str, **fields: Any) -> bool:
+        """Update specified fields on a scheduled task. Returns True if found."""
+        ...
+
+    def delete_scheduled_task(self, task_id: str) -> bool:
+        """Delete a scheduled task and its run history. Returns True if found."""
+        ...
+
+    def list_due_tasks(self, now: str) -> list[dict[str, Any]]:
+        """Return enabled tasks whose next_run <= now, ordered by next_run."""
+        ...
+
+    def record_task_run(
+        self,
+        run_id: str,
+        task_id: str,
+        node_id: str,
+        ws_id: str,
+        correlation_id: str,
+        started: str,
+        status: str,
+        error: str,
+    ) -> None:
+        """Record a scheduled task execution."""
+        ...
+
+    def list_task_runs(self, task_id: str, limit: int = 50) -> list[dict[str, Any]]:
+        """List run history for a task, ordered by started DESC."""
+        ...
+
+    def prune_task_runs(self, retention_days: int = 90) -> int:
+        """Delete task runs older than retention_days. Returns count deleted."""
+        ...
+
+    # -- Service registry ------------------------------------------------------
+
+    def register_service(
+        self, service_type: str, service_id: str, url: str, metadata: str = "{}"
+    ) -> None:
+        """Register or update a service instance. Upserts by (service_type, service_id)."""
+        ...
+
+    def heartbeat_service(self, service_type: str, service_id: str) -> bool:
+        """Update last_heartbeat for a registered service. Returns False if not found."""
+        ...
+
+    def list_services(self, service_type: str, max_age_seconds: int = 120) -> list[dict[str, str]]:
+        """Return healthy services of a given type (heartbeat within max_age_seconds)."""
+        ...
+
+    def deregister_service(self, service_type: str, service_id: str) -> bool:
+        """Remove a service registration. Returns True if existed."""
+        ...
+
    # -- Lifecycle -------------------------------------------------------------

    def close(self) -> None:
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Patrick Buckley	8b92302247	Bump version to 0.4.3	2026-03-07 13:11:42 -08:00
Patrick Buckley	e195ca54a6	new high level arch abstract	2026-03-07 13:01:19 -08:00
Patrick Buckley	50277cd4de	Add 10-node cluster profile to Docker Compose	2026-03-07 12:54:41 -08:00
Patrick Buckley	fb190f8977	Normalize session_id into ws_id as sole persistent identity (#29 ) * Normalize session_id into ws_id as sole persistent identity Eliminate the separate session_id concept. The workstream ID (ws_id) is now the single identity used for both real-time routing and conversation persistence, removing a layer of indirection that was 1:1 in practice and buggy on resume (stale pointers, orphaned rows). Schema changes (migration 006): - Drop sessions table; add alias/title columns to workstreams - Rename conversations.session_id → ws_id - Rename session_config table → workstream_config (ws_id column) - Data migration remaps existing conversations to ws_id Storage/API renames: - register_session → register_workstream (already existed, merged) - save_message/load_messages now keyed by ws_id - resolve_session → resolve_workstream - ChatSession.session_id property → ws_id - ChatSession.resume_session() → resume() - resume_session field → resume_ws - SessionResumedEvent → WorkstreamResumedEvent - /api/sessions → /api/workstreams/saved - /sessions slash command → /workstreams - --session-retention-days → --retention-days Channel eviction recovery simplified: reuses old ws_id directly instead of get_session_id_by_ws() reverse lookup. * Fix Copilot review feedback: stale session wording in docs, regenerate OpenAPI spec - docs/channels.md: "resumes the session" → "resumes the workstream", "Session resumed:" → "Resumed:", "old session was pruned" → "old workstream was pruned" - docs/api-reference.md: "Each session object" → "Each saved workstream object", field descriptions updated, removed stale node_id field - sdk/typescript/openapi-server.json: fully regenerated from Python models — removes all stale session_id properties from WorkstreamInfo, DashboardWorkstream, CreateWorkstreamResponse schemas	2026-03-07 12:49:07 -08:00
Patrick Buckley	25b5e32089	Bump version to 0.4.2	2026-03-05 20:18:46 -08:00
Patrick Buckley	339981a258	Add GPT-5.3, GPT-5.4, and pro model capabilities (#28 ) * Add GPT-5.3, GPT-5.4, and pro model capabilities Add capability entries for gpt-5-pro (272k output, high-only reasoning), gpt-5.2-pro, gpt-5.3, gpt-5.4 (1.05M context), and gpt-5.4-pro. * Validate reasoning_effort against model capabilities _apply_model_params now falls back to caps.default_reasoning_effort when the requested value is not in caps.reasoning_effort_values. Prevents sending unsupported effort levels to models like gpt-5-pro (high only).	2026-03-05 20:17:03 -08:00
Patrick Buckley	06de9ff83b	Bump version to 0.4.1	2026-03-05 18:13:42 -08:00
Patrick Buckley	924b976f1f	Add scheduled task docs and SDK client methods Add documentation and SDK support for the scheduled task system (cron/at scheduling via console API). Includes Python SDK methods (async + sync), TypeScript SDK methods, console.md API reference, sdk.md table update, and architecture.md module map entry.	2026-03-05 18:11:36 -08:00
Patrick Buckley	d5db817391	Fix channel gateway Docker networking and console proxy approval scope Two runtime bugs: 1. Channel gateway advertised http://127.0.0.1:8091 which is unreachable from other Docker containers. Add TURNSTONE_CHANNEL_ADVERTISE_URL env var override for Docker/K8s environments, set to http://channel:8091 in compose.yaml, and pass --http-host=0.0.0.0 so the gateway listens on all interfaces. 2. Console proxy service JWT had only "write" scope but the approval endpoint requires "approve". Tool approval buttons in the server web UI silently failed when accessed through the console proxy. Changed proxy token scopes to read+write+approve.	2026-03-05 18:01:52 -08:00
Patrick Buckley	fc8ceb4c72	Update README: 3-node cluster diagram, remove directory tree Replace single-node Mermaid diagram with a 3-node cluster layout showing bridge+server pairs per node, shared Redis MQ, console, and channel gateway. Remove the verbose directory tree listing.	2026-03-05 17:44:33 -08:00
Patrick Buckley	07234dec4d	Replace ASCII architecture diagram with Mermaid in README GitHub renders Mermaid natively as an interactive SVG. The new diagram shows all client entry points (CLI, browser, SDK, Discord), the full cluster topology including the channel gateway and notify path, and the LLM provider layer.	2026-03-05 17:34:42 -08:00
Patrick Buckley	dd4cc0b30d	Add PROGRESS.md and .coverage to .gitignore	2026-03-05 17:31:55 -08:00
Patrick Buckley	e7fe8fca9d	Add channel notification tool with security hardening (#27 ) * Add channel notification tool with security hardening Implements the `notify` tool allowing the LLM to send notifications to Discord channels/users via the channel gateway. Includes fixes for 11 review findings: JWT auth on the gateway endpoint, first-healthy gateway delivery with retry+backoff, rate limiting only on success, SSRF URL scheme validation, Discord mention sanitization, SQLite ON CONFLICT upsert preserving created timestamps, advertise URL resolution for 0.0.0.0 bind, randomized service IDs, generic error messages to prevent internal state leakage, and partial direct-target validation. Service registry with heartbeat-based health filtering (migration 005). Channel gateway registers on startup, heartbeats every 30s, deregisters on shutdown. 70 new tests covering tool prepare/execute, HTTP endpoint auth (static + JWT), storage CRUD, and retry behavior. * Add notify documentation, diagrams, and review fixes Documentation: - New sequence diagram 17-notify-flow.puml showing end-to-end delivery - Updated 16-channel-architecture.puml with services table, notify HTTP path, and Notification Flow note - channels.md: Notifications section (targeting, delivery flow, service registry, security) and new config table entries - tools.md: notify tool reference, updated counts/tables (14→15 tools) - security.md: channel gateway row in service-to-service auth table - architecture.md: notification subsystem paragraph Review fixes (copilot): - _http.py: fail closed when auth unconfigured (401 instead of pass- through), strip whitespace on message/title, generic error messages for user-not-found vs no-linked-channels - session.py: parse gateway response JSON and require at least one result with status=="sent" before counting as success - _postgresql.py: use index_elements instead of constraint for upsert	2026-03-05 17:24:00 -08:00
Patrick Buckley	42b9f89988	Add scheduled task system with cron/at scheduling (#26 ) * Add scheduled task system with cron/at scheduling, admin API, and console UI Console-integrated background scheduler dispatches workstreams on recurring cron expressions or one-shot ISO8601 timestamps. Four target modes: auto (best node by headroom), pool (shared queue), all (fan-out), or specific node. Redis distributed lock with unique owner + Lua conditional release prevents duplicate dispatch in multi-console deployments. Storage: scheduled_tasks + scheduled_task_runs tables (migration 004), 9 protocol methods on both SQLite and PostgreSQL backends, field allowlist on updates, run history auto-pruned at 90 days. API: 6 CRUD endpoints under /v1/api/admin/schedules with croniter validation, ISO8601 future-time checks, field length bounds, schedule count cap (200), and OpenAPI spec entries with Pydantic models. UI: Schedules tab in admin panel with create/edit/delete modals, run history modal, cron/at type toggle, target mode select, status dots for accessibility, responsive grid, keyboard navigation, and focus management. Security: fan-out capped at 20 nodes/task/tick, auto-approve dispatches logged at WARNING with created_by attribution, user_id propagated in CreateWorkstreamMessage for audit trail. 46 tests across storage, scheduler engine, and API endpoints. * Add croniter to test extras for CI compatibility CI installs [test] extras but not [console], so croniter was missing when schedule API tests import console/server.py validation functions. * Address Copilot review: timezone validation, focus trap, enabled flag - Reject naive at_time timestamps — require timezone offset (e.g. +00:00 or Z) - UI appends +00:00 to datetime-local values for explicit UTC - Fix datetime-local normalization: check length before appending seconds - Add textarea to modal focus trap selector (prevents focus escape) - Fix _normalize_task_dict not called in update response - Persist enabled=false on create (storage defaults to enabled=1) - Validate at_time is still in future when re-enabling a one-shot task - broker._redis coupling acknowledged as tracked tech debt	2026-03-05 16:05:00 -08:00
Patrick Buckley	77c0a7736b	Bump version to 0.4.0 and update security docs - Version bump in __init__.py, pyproject.toml, api-reference.md - security.md: document JWT aud/iss claims, login rate limiting, secure cookie defaults (24h, Secure flag), CORS restriction, service JWT auto-rotation, secret strength validation, and proxy auth forwarding via service tokens (not user JWT forwarding)	2026-03-04 20:45:00 -08:00
Patrick Buckley	872e1770e6	Feature/code dedup (#25 ) * Add JWT auth security hardening (6 fixes) - Secure cookie flag: make_set_cookie defaults Secure=True, max_age=24h - Login brute-force protection: LoginRateLimiter (5 attempts/5min per key) - JWT aud/iss claims: create_jwt/validate_jwt support audience validation - Service JWT auto-rotation: ServiceTokenManager with 1h expiry, 80% refresh - CORS restriction: configurable via TURNSTONE_CORS_ORIGINS env var - JWT secret strength: warning on secrets shorter than 32 chars - Hard fail for bridge/console when TURNSTONE_JWT_SECRET is missing * Refactor duplicated code into shared utilities and fix 3 UI bugs Code deduplication (~235 net lines removed): - Extract AuthMiddleware + 4 auth endpoint handlers to core/auth.py - Create core/web_helpers.py (require_storage_or_503, read_json_or_400, parse_cors_origins, cors_middleware) - Extract add_redis_args/broker_from_args to mq/broker.py - Extract add_log_args/configure_logging_from_args to core/log.py - Remove dead _CSS/_JS loads, duplicate states dict, _read_json helper, unused required_role(), duplicate detect_model() wrapper Bug fixes: - Fix console proxy forwarding user's JWT_AUD_CONSOLE token to server nodes (use ServiceTokenManager with JWT_AUD_SERVER instead) - Fix login form autofill: wrap inputs in <form>, add name attributes, set type=submit on button - Fix SSE reconnecting flash: add onopen handler to clear status immediately on connection (not waiting for first message) - Fix chat scroll: add min-height:0 to flex containers, overflow:hidden on body to constrain viewport height * Address CI typecheck failure and Copilot review feedback - Fix mypy arg-type: use Any for jwt.decode options (PyJWT stubs vary) - Bridge SSE loops: use event_hooks for auth header refresh on reconnect instead of static headers that go stale after token rotation - Login form: remove javascript:void(0) action (CSP anti-pattern) - Use JWT_AUD_SERVER/JWT_AUD_CONSOLE constants instead of string literals in middleware builder calls to prevent drift	2026-03-04 20:35:21 -08:00
Patrick Buckley	a6e929b0a0	Add channel integrations with Discord adapter and atomic session resu… (#24 ) * Add channel integrations with Discord adapter and atomic session resume (#24) Bidirectional channel adapter framework connecting external messaging platforms to turnstone workstreams via Redis MQ. Discord ships as the first adapter; the protocol supports future Slack/Teams integrations. Channel framework: - ChannelAdapter protocol and ChannelRouter for channel↔workstream mapping - AsyncRedisBroker with single dispatch loop and per-channel ordered workers - channel_routes table (migration 003) for persistent route storage - 9 new StorageBackend methods (4 channel_user + 5 channel_route CRUD) - Unified turnstone-channel gateway entry point, loads adapters by config - Message chunking, approval formatting, plan review formatting Discord adapter: - discord.py v2.4+ bot with thread-per-@mention model - Slash commands: /link (modal), /unlink, /ask, /status, /close - Persistent button views for tool approval and plan review - Streaming responses via edit-in-place (1.5s interval) - Stale route detection and atomic session resume via resume_session field - SessionResumedEvent confirmation back to channel - Auto-approve support (blanket + per-tool list) Atomic session resume: - resume_session field on CreateWorkstreamMessage for single-request resume - Server resumes session during POST /v1/api/workstreams/new atomically - Bridge emits SessionResumedEvent to per-workstream channel - WorkstreamCreatedEvent extended with resumed/session_id/message_count - Server UI dashboardResumeSession simplified to single request - Pruned sessions fall back gracefully to fresh start Service auth: - Bridge and console auto-mint service JWTs from TURNSTONE_JWT_SECRET - Bridge: approve scope (1 week). Console collector: read. Proxy: write. Console admin: - Channels tab with per-user view, force-link modal, unlink - 3 admin API endpoints for channel user management - Styled confirm modals replacing browser confirm() dialogs Bug fixes: - AsyncRedisBroker: replaced per-channel listener tasks with single dispatch loop + per-channel queue workers (fixes message stealing race) - Bridge: approval/plan review dedup guard prevents SSE reconnect duplicates - Bridge: _active_sends tracked for initial messages (fixes missing TurnCompleteEvent and unfinalized streaming messages) - Bridge: HTTP calls moved outside lock scope in approval handlers - Bridge: _handle_send cleans up _active_sends on HTTP/server errors - Formatter: reads server SSE format (func_name/preview) with fallback Docs, SDK, tests: - docs/channels.md setup guide, architecture diagram 16 - Updated api-reference.md, architecture.md, console.md, docker.md - Python SDK: resume_session param on create_workstream (async + sync) - TypeScript SDK: updated CreateWorkstreamRequest/Response interfaces - OpenAPI schema: resume_session request, resumed/message_count response - 91 new tests (19 storage, 15 broker, 22 protocol, 6 routing, 18 discord, 12 resume flow) — 1120 total passing * Fix CI lint/typecheck failures and address Copilot review feedback (#24) Lint: fix import ordering, remove unused imports, use contextlib.suppress. Mypy: explicit postgresql dialect import, add discord module overrides for optional-dependency CI environments. Copilot: fix double-escaping in admin confirm modals, return resolved session_id from server resume response, fix channel_routes diagram schema, use atomic setdefault for routing locks, add post-insert race guard in admin channel create, support SSE format in auto-approve check, update identity linking note in architecture diagram. * Fix remaining mypy call-arg errors for discord.py optional dependency Add type: ignore[call-arg] on Modal(title=) and Cog(name=) class definitions that fail when discord.py is not installed in CI.	2026-03-04 13:02:58 -08:00
Patrick Buckley	047680d669	Add user identity, JWT auth, and admin console UI (#23 ) * Add user identity, JWT auth, and admin console UI (#23) JWT-based authentication with three token types: config-file (hmac, backward-compat), API tokens (ts_ prefix, SHA-256 hashed), and JWTs (HS256, 24h expiry). Username:password login via bcrypt. Hierarchical scopes: read < write < approve. New tables: users (username, password_hash), api_tokens (token_hash, scopes, expires), channel_users (future channel integrations). user_id column added to sessions and workstreams for attribution. Console owns admin CRUD (6 endpoints under /api/admin/). Server validates JWTs locally with shared signing secret. Public /api/auth/setup endpoint for first-time admin creation (atomic, only works with zero users). turnstone-admin CLI for user/token management. Admin console UI: Users and Tokens tabs with full CRUD modals, scope badges, token show-once with clipboard copy, keyboard accessibility (focus traps, Escape, arrow key tabs, ARIA roles). Login UI redesigned: username:password primary, token toggle for legacy, setup wizard auto-detected via /api/auth/status. Python + TypeScript SDKs updated with login(username, password), authStatus(), setup(). New docs/security.md + diagram 15-auth-architecture.puml. All existing docs updated. OpenAPI specs include all new endpoints. 64 new tests (1023 total). Dependencies: PyJWT, bcrypt. * Fix auth bugs, XSS vector, and doc inaccuracies from PR #23 review Address Copilot review feedback: escape double quotes in escapeHtml() to prevent XSS in HTML attributes, add JWT validation fallback so config tokens containing dots still work, add user_id to AuthLoginResponse schema, return created field from admin_create_user, and correct five documentation files to match actual API behavior.	2026-03-04 09:12:18 -08:00
Patrick Buckley	0fd0ad3b2d	Add structured logging with structlog and context propagation Replace ad-hoc logging.basicConfig() calls across all 6 entry points with a centralized configure_logging() function backed by structlog. JSON output when stderr is not a TTY (production/Docker), colored console output otherwise. - New turnstone/core/log.py: configure_logging(), get_logger(), contextvars for node_id/ws_id/user_id/request_id auto-injected into every log event - All entry points (server, bridge, console, sim, cli, migrate) call configure_logging() with --log-level and --log-format CLI flags - Server operational print() calls replaced with structured log.info() - LogContextMiddleware sets request_id + ws_id per HTTP request with token-based reset to prevent context leaking across requests - Bridge _run_in_context() helper propagates ctx_node_id to child threads - Env var overrides: TURNSTONE_LOG_LEVEL, TURNSTONE_LOG_FORMAT - 18 new tests (959 total passing)	2026-03-04 06:47:30 -08:00
Patrick Buckley	f3dba836dd	Add Git LFS requirement note to README, Diagram PNGs are stored in LFS; git-lfs must be installed for cloning them.	2026-03-04 06:14:27 -08:00
Patrick Buckley	7adda343fc	Update docs and diagrams for cluster-scale schema changes - StorageBackend protocol: document 5 new workstream methods (26 total) - Session ID: 12-char hex → 32-char full UUID in API reference - /health endpoint: add node_id field to response docs - sessions table: document node_id and ws_id columns - Bridge node_id: document server-owned identity with /health retrieval - Regenerate storage architecture PNG from updated PlantUML	2026-03-04 06:12:33 -08:00
Patrick Buckley	a20a058c59	Add cluster-scale schema, fix console proxy UX, harden SDK sync runner (#22 ) * Add cluster-scale schema, fix console proxy UX, harden SDK sync runner Schema redesign for multi-node deployments: - New `workstreams` table with node_id, state, lifecycle tracking - Add node_id + ws_id columns to sessions table with indexes - Full UUID (32 hex) for session_id and ws_id (was truncated 12/8) - Server generates and owns node_id, bridge retrieves via /health - Bridge retries with exponential backoff, fatal on auth errors - WorkstreamManager persists workstreams and state changes to storage - /health endpoint exposes node_id for bridge discovery Console proxy UX fixes: - Remove duplicate turnstone branding from proxy banner - Same-tab navigation for Open Node UI and workstream deep links SDK _SyncRunner fix: - Sentinel pattern for StopAsyncIteration across thread boundary Remove misplaced PNGs from docs/diagrams/ (correct copies in png/ subdir). * Address PR #22 review feedback - Fix CLI session_factory signature (ws_id param) — CI typecheck failure - First-phase eviction in create() now calls _cleanup_ui + record_eviction - close() persists "closed" state to storage via update_workstream_state - Fix noqa comment in test to pragma: no cover	2026-03-04 06:04:59 -08:00