chore: bump version to 1.5.4

chore(deps): update ghcr.io/astral-sh/uv docker tag to v0.11.8
refactor(coord): remove priority queue + queue depth indicator + broken CSS
2026-08-13 15:32:24 -06:00 · 2026-04-30 23:51:06 -07:00 · 2026-04-30 23:48:53 -07:00 · 2026-04-30 23:48:53 -07:00 · 2026-04-30 23:48:53 -07:00 · 2026-04-30 23:48:53 -07:00
555 changed files with 37550 additions and 137367 deletions
@@ -1,61 +1,49 @@
 # =============================================================================
-# Turnstone environment overrides — ALL OPTIONAL for the dev stack.
+# Turnstone Environment Variables
+# Copy to .env and adjust values for your deployment.
 #
-# `docker compose up` from a clone works with zero config: every value below
-# has a built-in (insecure) default. Copy this file to `.env` only to override.
-#
-# The PRODUCTION stack (turnstone/deploy/compose.yaml) has no baked-in secrets
-# and DOES require TURNSTONE_JWT_SECRET and POSTGRES_PASSWORD.
-#
-# Note: for a turnstone process running on bare metal (not in a container),
-# put secrets in ~/.config/turnstone/config.toml (chmod 0600), not the
-# environment. See docs/docker.md "Join a bare-metal host".
+# Usage:
+# Single node: docker compose --profile production up
+# 10-node cluster: docker compose --profile cluster up
 # =============================================================================

-# -- LLM backend --------------------------------------------------------------
-# Optional: nodes boot without an LLM. Add real model backends from the console
-# UI (Models tab). These only set the bootstrap default a node starts with.
-# LLM_BASE_URL=http://host.docker.internal:8000/v1
-# OPENAI_API_KEY=dummy
-# ANTHROPIC_API_KEY=sk-ant-...     # set instead of OPENAI_API_KEY for Anthropic
-# TURNSTONE_SEARXNG_URL=http://searxng:8080  # web_search backend (default: bundled service; set to an external SearxNG)
-# MODEL=                           # default model alias
+# -- LLM Backend --------------------------------------------------------------
+LLM_BASE_URL=http://host.docker.internal:8000/v1
+OPENAI_API_KEY=dummy
+# ANTHROPIC_API_KEY=sk-ant-...# Set instead of OPENAI_API_KEY for Anthropic
+# TAVILY_API_KEY=tvly-... # Web search fallback (local models only)
+# MODEL=# Override default model alias

-# -- Secrets ------------------------------------------------------------------
-# The dev stack defaults these to INSECURE values. Always set real ones for
-# anything reachable beyond localhost. Generate the JWT secret with:
-#   python -c "import secrets; print(secrets.token_hex(32))"
-# TURNSTONE_JWT_SECRET=
-# POSTGRES_PASSWORD=
+# -- Authentication (required) ------------------------------------------------
+# Generate with: python -c "import secrets; print(secrets.token_hex(32))"
+TURNSTONE_JWT_SECRET=changeme-to-32-bytes-of-hex

-# -- Database -----------------------------------------------------------------
-# Defaults to the bundled PostgreSQL (shared by every service — required for
-# the console to discover nodes). Override to point at an external database:
+# -- Database ------------------------------------------------------------------
+# Single-node default is SQLite (zero config). Set these for PostgreSQL:
 # TURNSTONE_DB_BACKEND=postgresql
 # POSTGRES_USER=turnstone
-# TURNSTONE_DB_URL=postgresql+psycopg://turnstone:<pw>@postgres:5432/turnstone
+# POSTGRES_PASSWORD=changeme
+# TURNSTONE_DB_URL=postgresql+psycopg://turnstone:changeme@postgres:5432/turnstone

-# -- Ports / networking -------------------------------------------------------
-# The dashboard is reached via Caddy only (HTTP/2 avoids the browser's
-# 6-connection cap on the console's SSE streams). Both stacks expose the same
-# two host ports; everything else is proxied through the console.
-# CONSOLE_HTTPS_PORT=8443          # Caddy (dashboard HTTPS)
-# POSTGRES_PORT=5432               # exposed for bare-metal host joins
-# POSTGRES_BIND=127.0.0.1          # set 0.0.0.0 to let another machine join
+# -- Ports ---------------------------------------------------------------------
+# SERVER_PORT=8080
+# CONSOLE_PORT=8090

-# -- Workspace ----------------------------------------------------------------
-# Bind-mount a host directory the model can read/write at /workspace:
+# -- Workspace -----------------------------------------------------------------
+# Bind-mount a host directory into the container at /workspace.
+# The model can read/write files here. Default: empty Docker volume.
 # WORKSPACE_MOUNT=/path/to/your/project

-# -- Agent behavior -----------------------------------------------------------
-# SKIP_PERMISSIONS=true            # auto-approve all tool calls (dev only)
-# MCP_CONFIG=/workspace/mcp.json   # MCP server config file
+# -- Agent behavior ------------------------------------------------------------
+# SKIP_PERMISSIONS=true # Auto-approve all tool calls (dev only)
+# MCP_CONFIG=/workspace/mcp.json# MCP server configuration file

-# -- Channel gateway (Discord / Slack) ----------------------------------------
+# -- Discord channel gateway ---------------------------------------------------
 # TURNSTONE_DISCORD_TOKEN=
 # TURNSTONE_DISCORD_GUILD=0
-# TURNSTONE_SLACK_TOKEN=xoxb-...
-# TURNSTONE_SLACK_APP_TOKEN=xapp-...

-# -- Production image tag ------------------------------------------------------
-# TURNSTONE_IMAGE_TAG=latest       # pin the ghcr.io image (production stack)
+# -- Cluster (profile: cluster) -----------------------------------------------
+# These are set per-node in compose.yaml; only override for custom topologies.
+# TURNSTONE_NODE_ID=node-1
+# TURNSTONE_ADVERTISE_URL=http://server-1:8080
+
@@ -14,7 +14,7 @@ jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
        with:
          python-version: "3.14"
@@ -25,7 +25,7 @@ jobs:
  typecheck:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
        with:
          python-version: "3.14"
@@ -39,7 +39,7 @@ jobs:
      matrix:
        python-version: ["3.11", "3.12", "3.13"]
    steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
        with:
          python-version: ${{ matrix.python-version }}
@@ -47,9 +47,9 @@ jobs:
      # explicit setup, that suite silently skips if the runner
      # image happens not to ship Node, masking regressions in
      # the browser-side renderer.
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
+      - uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5
        with:
-          node-version: "24"
+          node-version: "20"
      - run: pip install -e ".[test]"
      - run: pytest tests/ -m "not live" --cov=turnstone --cov-report=term-missing --cov-report=xml -q
      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
@@ -75,14 +75,14 @@ jobs:
          --health-timeout=5s
          --health-retries=5
    steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
        with:
          python-version: "3.14"
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
+      - uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5
        with:
-          node-version: "24"
-      - run: pip install -e ".[test]"
+          node-version: "20"
+      - run: pip install -e ".[test,postgres]"
      - run: pytest tests/ -m "not live" --storage-backend=postgresql -q
        env:
          TURNSTONE_TEST_PG_URL: postgresql+psycopg://postgres:postgres@localhost:5432/turnstone_test
@@ -90,7 +90,7 @@ jobs:
  wheel-completeness:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
        with:
          python-version: "3.14"
@@ -137,8 +137,8 @@ jobs:
  lock-check:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
-      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
        with:
          uv-version: "0.9.18"
      - run: uv lock --check
@@ -146,8 +146,8 @@ jobs:
  security:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
-      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
        with:
          uv-version: "0.9.18"
      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
@@ -156,17 +156,7 @@ jobs:
      - run: uv sync --frozen --all-extras
      - run: uv pip install pip-audit
      - name: Security audit (dependencies)
-        # PYSEC-2025-183 (pyjwt): "weak encryption" — disputed by the
-        # supplier because the key length is chosen by the calling
-        # application, not the library.  Turnstone generates its JWT
-        # signing keys via the standard ``secrets`` module at
-        # operator-controlled strength (see ``turnstone/core/auth.py``),
-        # so the advisory does not apply.  pyjwt 2.12.1 is the current
-        # latest release; no fix version exists.
-        run: >-
-          uv export --no-emit-project --frozen
-          | uv run pip-audit --strict --desc -r /dev/stdin
-          --ignore-vuln PYSEC-2025-183
+        run: uv export --no-emit-project --frozen | uv run pip-audit --strict --desc -r /dev/stdin

  security-ts:
    runs-on: ubuntu-latest
@@ -174,7 +164,7 @@ jobs:
      run:
        working-directory: sdk/typescript
    steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
        with:
          node-version: "24"
@@ -24,7 +24,7 @@ jobs:
      github.event.workflow_run.head_repository.full_name == github.repository
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          ref: ${{ github.event.workflow_run.head_sha }}
          fetch-depth: 0
@@ -43,7 +43,7 @@ jobs:

      - name: Log in to GHCR
        if: steps.tag.outputs.skip == 'false'
-        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
@@ -67,12 +67,12 @@ jobs:
          fi
          echo "tags=${TAGS}" >> "$GITHUB_OUTPUT"

-      - uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4
+      - uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4
        if: steps.tag.outputs.skip == 'false'

      - name: Build and push
        if: steps.tag.outputs.skip == 'false'
-        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7
        with:
          context: .
          push: true
@@ -19,7 +19,7 @@ jobs:
    runs-on: ubuntu-latest
    environment: pypi
    steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          ref: ${{ github.event.workflow_run.head_sha }}
          fetch-depth: 0
@@ -40,7 +40,7 @@ jobs:
          fi
          echo "head_ref=${ref}" >> "$GITHUB_OUTPUT"

-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          ref: ${{ steps.ref.outputs.head_ref }}

@@ -9,11 +9,6 @@ build/
 .venv/
 venv/
 .env
-# Local compose overrides (e.g. run.sh's node-count limiter, bootstrap output)
-compose.override.yaml
-compose.override.yml
-docker-compose.override.yaml
-docker-compose.override.yml
 *.so
 .mypy_cache/
 .ruff_cache/
@@ -6,845 +6,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [PEP 440](https://peps.python.org/pep-0440/) for
 version numbers (`X.Y.Z`, with `X.Y.ZaN` / `bN` / `rcN` for pre-releases).

-Three release tracks are maintained — the current stable, one prior
-stable, and the experimental line:
+Three release tracks are maintained:

- **`stable/1.5`** — patch-only (`v1.5.x`)
- **`stable/1.6`** — patch-only (`v1.6.x`)
- **`main`** — experimental (next major)
+- **`stable/1.0`** — patch-only (`v1.0.x`)
+- **`stable/1.3`** — patch-only (`v1.3.x`)
+- **`stable/1.4`** — patch-only (`v1.4.x`)
+- **`main`** — experimental (`v1.5.0aN`)

-## [1.6.0]
-
-The first stable release of the 1.6 line — and the first under Apache 2.0.
-
-> **⚠️ Before upgrading from 1.5.x:** 1.6.0 changes the internal
-> conversation storage schema (Alembic migration `060`, applied
-> automatically on first start). The migration converts existing
-> workstreams and attachments in place — **back up your storage before
-> upgrading** (`pg_dump` for PostgreSQL; copy the database file for
-> SQLite). Background: discussion
-> [#631](https://github.com/turnstonelabs/turnstone/discussions/631).
-
-**Breaking changes at a glance** (details in the sections below):
-`web_search` backend overhaul (Tavily/DuckDuckGo removed, `topic` →
-`category`), the `man` / `math` / `plan_agent` built-in tools and the
-plan-review protocol removed, and the body-keyed `/v1/api/command`
-endpoint replaced by path-keyed workstream verbs.
-
-### License
-
- **Relicensed to Apache 2.0** — from BUSL-1.1, effective with this
-  release (#546, contributor assent record in #548). Versions 1.5.x and
-  earlier remain under BUSL-1.1 as shipped, and the `stable/1.5` branch
-  keeps its original LICENSE. New `NOTICE` and
-  `CONTRIBUTORS.md` files; `THIRD-PARTY-NOTICES` refreshed to match the
-  bundled library versions.
-
-### Added
-
- **Mid-conversation system messages** — advisories, watch results,
-  skill hints, and operator interjections are now first-class
-  `role=system` turns in the trajectory instead of ad-hoc reminder
-  envelopes. Models with native mid-conversation system support receive
-  them verbatim; for everything else they fold into a nonce-fenced
-  wrapper. The one-shot `_reminders` side-channel is gone.
- **Self-hosted SearxNG web search** — the `web_search` backend for
-  local/vLLM models is now a bundled [SearxNG](https://searxng.org)
-  service (in both compose stacks; internal network only). Configure via
-  `tools.searxng_url` / `tools.searxng_engines`. Commercial providers
-  keep their native server-side search; the model can target a corpus by
-  passing `category` (`general`, `news`, `it`, `science`). Operators
-  exposing the bundled SearxNG publicly: see the AGPL-3.0 §13 note in
-  [docs/docker.md](docs/docker.md).
- **Endpoint-backed reranking** — a reranker is now a per-model
-  definition (Cohere/Jina-compatible wire: vLLM, TEI, llama.cpp, or a
-  commercial endpoint), disabled by default. When configured it scores
-  `web_search` results and the BM25 retrieval surfaces (deferred tools,
-  skills, memory) behind a `tools.rerank_bm25` toggle with a relevance
-  floor; a calibration CLI (and calibrate-on-detect) tunes the floor
-  per model.
- **Proactive memory relevance** — injected memories are selected by
-  BM25 + reranker against the recent user messages instead of recency
-  alone, and first composition defers to the first user turn so fresh
-  sessions select against a real query.
- **Smart Approvals** — opt-in (default off): high-confidence `approve`
-  verdicts from the intent judge auto-approve the tool call instead of
-  waiting for a human, with a confidence threshold and verdict
-  bookkeeping designed so a denied or reset judge never auto-fires.
- **Early-painted tool calls** — committed tool calls render immediately
-  as pending cards (both UIs upgrade the card in place by `call_id`)
-  instead of waiting for the judge verdict, so big parallel batches no
-  longer sit invisible during judging.
- **Voice I/O v1** — speech-to-text and text-to-speech as model roles
-  speaking the OpenAI audio wire protocol (#618); the interactive
-  composer grows a mic button.
- **Rewind / retry / edit-first-message** — full UX in both the
-  interactive UI and the coordinator pane, backed by shared path-keyed
-  verb handlers (#549).
- **Workstream export** — download a conversation as OpenAI-format
-  messages JSON.
- **Skills platform round** — `SKILL.md` ingestion learns
-  `when_to_use` / `model` / `effort` / `paths`; prompt substitution
-  supports `$ARGUMENTS`, `$N`, `$<name>`, and `${CLAUDE_*}` (#572);
-  per-skill `disable-model-invocation` and `user-invocable` flags
-  (#571); `skill` + `list_skills` unify into one dual-kind tool; new
-  `model.skills.write` permission.
- **Coordinator hardening for small models** — workstream references in
-  coordinator tool calls are validated with did-you-mean recovery, and
-  `wait_for_workstream` fails fast with uniform `not_found` entries
-  instead of hanging on a hallucinated `ws_id`.
- **Provider support** — Claude Fable 5 and Claude Opus 4.8; xAI/Grok
-  via the OpenAI Responses lane; vLLM reasoning-field replay completes
-  the reasoning-persistence work (#537).
- **Cluster-by-default deployment** — the compose stack fronts
-  everything with Caddy and supports bare-metal node join; a one-line
-  `curl | bash` installer bootstraps a node; nodes with no configured
-  models boot into a degraded state instead of crash-looping; channel
-  gateways stand by when no adapter token is set.
- **MCP OAuth tokens encrypted at rest**.
- **`turnstone-admin` reads `config.toml`** — same `[database]` section
-  and precedence as the server (`CLI / config.toml > TURNSTONE_DB_* env
-  > defaults`), including `pool_size` and the `ssl*` knobs it previously
-  dropped; new `--config PATH` flag.
-
-### Changed
-
- **Conversation storage and the provider wire are rebuilt around a
-  canonical trajectory** (migration `060` — see the upgrade note).
-  Internally a conversation is now a provider-neutral `Turn` sequence
-  lowered to each provider's wire format at send time; provider-specific
-  tool-call metadata rides an opaque producer-tagged lane (replayed
-  verbatim to the producing provider, rebuilt for others); attachments
-  become content-addressed, reference-counted rows resolved at the
-  provider boundary; orphan tool-call repair happens once, at send time.
-  Wire-visible behavior is unchanged for OpenAI-compatible providers;
-  histories are preserved across the migration.
- **The console and web UI share one L-shell** — a left glyph rail, a
-  tab bar, and a pane host now frame interactive chats, coordinator
-  sessions, dashboards, and the admin panel as tabs in a single window;
-  the standalone web UI adopts the same shell and the old split-pane
-  layout is retired. Coordinator and interactive conversations render
-  through shared `.conv-*` card builders, the rail collapses to a glyph
-  strip (remembered per browser), mobile gets an off-canvas drawer, and
-  the frontend is now ES modules end to end.
- **Admin panel modals → the Service Hatch shelf** — all ~35 admin
-  modals are replaced by pane-scoped shelves plus a small dialog tier
-  for confirmations. Schedules gain a cron builder with a next-3-runs
-  preview endpoint, model capabilities render as an LED tile matrix, and
-  the legacy modal machinery is deleted.
- **SSE delivery is resumable end to end** — per-workstream ring buffer
-  with `Last-Event-ID` replay (cap raised 2,000 → 50,000), fresh-connect
-  and reconnect unified on one event-id cursor (in-flight tool batches
-  included), persisted `last_error` replays on connect, the console
-  proxy forwards `Last-Event-ID`, and panes close their connections on
-  `beforeunload` to stop multi-pane refresh from exhausting the
-  browser's per-host connection cap (#539).
- **Workstream verbs are path-keyed** *(BREAKING)* — `rewind` / `retry`
-  / `edit-first-message` live at
-  `/v1/api/workstreams/{ws_id}/<verb>` alongside the other session
-  verbs; the body-keyed `/v1/api/command` endpoint is removed (#549).
- **`/history` is projected server-side** — both UIs consume the same
-  REST-first wire shape instead of re-deriving it client-side.
- **Saved workstreams & coordinators: card grid → sortable table** with
-  model/skill/context columns, pagination, and a unified selector across
-  both dashboards.
- **`tools.web_search_backend` accepted values** *(BREAKING)* — now `""`
-  (auto), `"searxng"`, or `"mcp:server:tool"`. The old `"tavily"` and
-  `"ddg"` values are gone; a config still set to either disables web
-  search and logs a warning. Auto-detect resolves to SearxNG when
-  `searxng_url` is set.
- **`web_search` tool: `topic` → `category`** *(BREAKING)* — renamed
-  LLM-facing parameter; values map to SearxNG categories. The Tavily-era
-  `finance` topic is gone.
- **Core install includes what most deployments use** — `anthropic`,
-  `postgres`, `console`, and `tls` are core dependencies rather than
-  extras.
- **NODES table → bottom-bar node picker** in the console.
-
-### Fixed
-
- **Cluster mTLS actually survives operations** — certificate identity
-  keys on the advertised host rather than the container ID, renewals are
-  scoped per node, reloaded certs hot-swap into the live SSL context,
-  and healthchecks/boot retries are mTLS-aware.
- **Intent-verdict lifecycle** — history replay ships risk-none verdict
-  rows (live/replay parity), late verdicts persist as `superseded` for
-  the audit trail instead of vanishing, bulk verdict insert tolerates
-  per-row conflicts, and cancel-on-approval honors its run-to-completion
-  contract.
- **Usage accounting** — dashboard totals were under-counting; auxiliary
-  LLM spend (judge, rerank, memory) is now recorded.
- **Concurrent first-boot migrations** no longer deadlock on the
-  advisory lock.
- **Output renderer** — single-`$` inline math no longer false-positives
-  in prose; `strip_html` preserves block structure and drops a ReDoS
-  risk.
- **Model registry** orders versions numerically (no more `1.10 < 1.9`
-  selection).
-
-### Removed
-
- **Tavily and DuckDuckGo `web_search` backends** *(BREAKING)* —
-  replaced by the bundled SearxNG service. Removed:
-  `tools.tavily_api_key`, `$TAVILY_API_KEY`, `[api].tavily_key`, and the
-  `ddg` install extra. Point `TURNSTONE_SEARXNG_URL` at an existing
-  instance or use the bundled one; no database migration required.
- **`man`, `math`, and `plan_agent` built-in tools** *(BREAKING)* —
-  `man`/`math` duplicated `bash`; planning is better expressed as a
-  `task_agent` running a planning skill. Also removed: the `math`
-  sandbox executor, the read-only `AGENT_TOOLS` sub-agent set, the
-  plan-review protocol (`/v1/api/plan`, `plan_review`/`plan_resolved`
-  SSE events, `on_plan_review` hooks), and the `model.plan_*` settings.
-  Interactive built-in tool count: 19 → 16.
- **`stable/1.4` track retired** — the maintenance policy is now the
-  current stable plus one prior (`stable/1.6` + `stable/1.5` as of this
-  release). 1.4's final release was `v1.4.0`; its tags and released
-  artifacts remain available, under BUSL-1.1 as shipped.
-
-### Security
-
- **Zero direct-HTML frontend** — every `innerHTML` sink across the
-  console and web UI is replaced with DOM construction or `setSafeHtml`,
-  inline handlers became delegated bindings, and CI lints pin the
-  invariant (plus `var`-free and const-reassign checks) across all
-  swept bundles.
- **Output guard grows an LLM stage** — merged with the heuristics as
-  escalate-only (an LLM verdict can raise but never lower a heuristic
-  positive), with annotated findings, a capability gate, and hardening
-  against domain-camouflaged injection (#560, #573).
- **One trust-fence primitive** — operator and judge envelopes share a
-  nonce-fenced wrapper (64-bit nonces, host-escaping); the output guard
-  flags nonce forgery, and skill hints no longer echo model-controlled
-  filter values into trusted text.
- **RBAC** — built-in role overrides get an editor, and several
-  under-enforced permission gates are tightened (#585).
- **Permissive `config.toml` warns** — a single startup warning when the
-  resolved config file is group- or world-readable; operators usually
-  want `0600`.
- **Dependency floors** — `starlette>=1.0.1` (PYSEC-2026-161 host-header
-  path injection) and `aiohttp>=3.14.0` (security release).
-
-## [1.5.17]
-
-Backports a clutch of coordinator-tool clarity fixes plus a watch-delivery
-correctness fix from `main` to the `stable/1.5` track, plus a previously-
-latent intent-verdicts persistence bug exposed by the new heuristic-verdict
-INSERT paths.  No schema changes.
-
-### Fixed
-
- **`intent_verdicts` PK collisions on every llm_fallback delivery** —
-  async LLM-tier "llm_fallback" verdicts (`turnstone/core/judge.py` —
-  `_deliver_fallbacks` and the in-loop fallback path) deliberately
-  reuse the heuristic verdict's `verdict_id` so the row gets
-  "upgraded in place" from `tier="heuristic"` → `tier="llm_fallback"`
-  when the LLM judge times out, is cancelled, or returns no content.
-  The consumer `_persist_intent_verdict` was doing a plain INSERT,
-  hitting the `intent_verdicts_pkey` constraint on every fallback
-  delivery; Postgres logged the duplicate-key error, the application
-  try/except swallowed it at `log.debug`, and the row never actually
-  got upgraded — the LLM judge's annotation
-  (`"(LLM judge did not return a verdict)"`) was lost.  The collision
-  rate exploded on this release because the new heuristic-INSERT
-  paths in the auto-approve early-return branches of `approve_tools`
-  (introduced below) leave no gap for the fallback to land cleanly
-  into.  Fix: new `upsert_intent_verdict` storage method using
-  `ON CONFLICT (verdict_id) DO UPDATE` that updates only `tier`,
-  `reasoning`, `judge_model` — the three fields that genuinely
-  change between heuristic and llm_fallback.  Every other column
-  (identity, carried-verbatim, and `user_decision`) is excluded;
-  `user_decision` in particular would otherwise be clobbered back
-  to `"pending"` when a fallback arrives after the operator has
-  already resolved the approval.  The bulk-INSERT path stays as
-  plain INSERT — fresh UUIDs in `judge.evaluate` make in-turn dups
-  impossible; the inverse race (fallback wins before bulk lands) is
-  reachable but unchanged in observable behavior by this fix,
-  documented at the bulk site for a future hardening pass.
- **Coordinator LLM re-spawn loops on large fan-outs** — the spawn-tool
-  return JSON used `ws_id` as its key, which primed the model's recency
-  bias to feed the spawn result straight back into another
-  `spawn_workstream(ws_id=...)` call instead of progressing to
-  `wait_for_workstream(ws_ids=[...])`.  On 10+ child fan-outs this cascaded
-  into self-inflicted re-spawn loops.  The LLM-facing tool result now emits
-  `child_ws_id` (the storage column / HTTP API contract is unchanged); the
-  field name is already an existing project term so the rename aligns
-  rather than introduces new vocabulary.  Also handles the silent
-  upstream-omits-ws_id success-shape edge that previously emitted
-  `{"child_ws_id": null}` to the LLM — now surfaces a tool error so the
-  model retries rather than chasing a null id.
- **`inspect_workstream` blowing the coordinator context budget** — a
-  coord doing a fan-out wave against tool-heavy children could land
-  >100 KB of raw output per inspect call, and the previous safety net
-  (`_truncate_output`'s head+tail strategy) silently dropped *middle*
-  messages — exactly the wrong shape for understanding a child's
-  trajectory (the FIRST sets the brief, the LAST shows the conclusion,
-  the middle is the connective tissue).  Output now goes through a
-  three-tier degradation ladder mirroring the search tool's
-  `_format_search_results`: `_tier="full"` (every message verbatim) →
-  `_tier="compact"` (per-message head/tail-snipped content + snipped
-  `tool_calls.arguments`, falling through a `(20,30)` / `(10,20)` /
-  `(5,10)` message-list trim ladder) → `_tier="skeleton"` (counts, role
-  distribution, last-assistant preview).  Budget 32 KiB matches the
-  search tool's; the chosen tier is annotated on the response so the
-  model can recall with a tighter `message_limit` if signal was lost.
- **Auto-approved verdicts indistinguishable from pending review** —
-  `intent_verdict` rows for auto-approved tool calls landed with
-  `user_decision=""`, which read identically to "still waiting for the
-  operator" in the audit trail and led to a real misdiagnosis incident.
-  The column now carries an explicit vocabulary at insert: `pending` /
-  `approved` / `denied` / `timeout` / `policy` / `blanket` / `skill` /
-  `always` / `auto_approve_tools`.  The auto-approve early-return
-  branches in `approve_tools` now persist heuristic verdicts stamped
-  with their reason (previously dropped on the floor), and late LLM-tier
-  verdicts that arrive for an already-auto-approved call_id are stamped
-  via a TTL-pruned lookup map — so the audit row carries the
-  auto-approve reason even when the LLM judge daemon completes after
-  the synchronous approval cycle finished.  `resolve_approval` gains a
-  `timeout` kwarg writing `"timeout"` (the previous shape collapsed
-  passive timeouts and active denials into the same column).
- **`list_skills` empty `allowed_tools` misread as "no tool access"** —
-  the response previously emitted `"allowed_tools": []` for every skill
-  that hadn't declared an auto-approve allowlist, which a coordinator
-  model read as "this skill can't use any tools" (real misdiagnosis: a
-  code-review child appeared to have been spawned with zero tool
-  access).  The field is now omitted entirely when empty — absence
-  carries the unambiguous meaning "no tool is pre-approved for this
-  skill", presence (non-empty list) keeps the standard Claude Code
-  skill-spec shape.  The tool description rewrite makes the
-  auto-approve-allowlist semantics explicit so a future reader doesn't
-  re-derive the gating misread.
- **Watch terminal-fires silently dropped on backpressure** —
-  delivery now routes terminal events through the same path as
-  normal fires instead of being filtered out when the consumer was
-  saturated.
-
-### Documentation
-
- **Storage `LIKE_ESCAPE` contract** — clarify that callers passing
-  `.like(escape=...)` must use the same escape character that the
-  storage helper assumes; previous wording let a reader pass a
-  different escape and silently produce no matches.
-
-## [1.5.15]
-
-### Fixed
-
- **Admin console blank-page on MCP server rows with consented users** — a
-  Phase 9 (1.5.14) regression in `admin.js` used double-quote string
-  delimiters on the bulk-revoke button HTML literal, but the literal embeds
-  a `"` mid-attribute. JS closed the string early, turned `bulk-revoke (`
-  into bare tokens, and the resulting `SyntaxError` wiped out every global
-  in `admin.js` — `showAdmin` and all other admin entry points became
-  undefined, so the console UI was non-functional whenever the rendered MCP
-  server list contained at least one row with `consented_users_count > 0`.
-  Switch the literal to single-quote delimiters to match the surrounding
-  block.
-
-## [1.5.14]
-
-Backports OAuth-MCP Phase 9 from `main` to the `stable/1.5` track.
-
-### Added
-
- **OAuth-MCP Phase 9 — admin status, deferred-consent persistence, operator
-  docs** — completes the per-(user, server) OAuth-MCP build-out. The sync pool
-  dispatchers now upsert into a new `mcp_pending_consent` table on
-  `mcp_consent_required` / `mcp_insufficient_scope`, so a non-interactive run
-  (scheduled / channel) that hits an unconsented server surfaces the deferred
-  prompt to the user on their next dashboard load via the gear-icon badge —
-  rows are cleared automatically by the OAuth callback handler on consent
-  completion, or via new DELETE endpoints for manual dismiss. The MCP Servers
-  admin row gains a `consented_users_count` pill and a two-step-confirm
-  bulk-revoke button for `auth_type=oauth_user` servers (upstream RFC 7009
-  revoke is intentionally not attempted in bulk to avoid N synchronous
-  round-trips against the provider). Operator-facing docs land at
-  `docs/mcp-oauth.md` and `docs/operations/mcp-oauth-headless.md`.
-
-  Introduces forward-only migrations `054_mcp_pending_consent` and
-  `055_mcp_user_tokens_server_index`.
-
-## [1.5.13]
-
-This release introduces one forward-only schema migration:
-`053_services_notify_trigger` — installs the `services_notify` PostgreSQL
-trigger that backs the new LISTEN/NOTIFY dispatcher (no-op on SQLite, where
-the dispatcher uses in-process fan-out).
-
-### Added
-
- **Reactive node discovery via PG LISTEN/NOTIFY** — the console gains a
-  `NotifyDispatcher` that holds a dedicated session-mode PostgreSQL `LISTEN`
-  connection (bypasses pgbouncer transaction pooling) and fans wake-ups out to
-  per-channel handlers on a separate dispatch thread. The cluster collector
-  subscribes to a new `services` channel and reacts to node register /
-  deregister within ~500 ms instead of waiting up to 60 s for the next discovery
-  loop; the 60 s loop is retained as the backstop for crash-shaped loss
-  (NOTIFY only fires on real writes). The storage layer also gains a uniform
-  `notify` / `listen` API with an SQLite synthetic-sweep fallback so consumer
-  code is identical across backends. `TURNSTONE_DB_LISTEN_URL` (or
-  `[database] listen_url` in `config.toml`) points the dispatcher at a
-  direct-to-Postgres URL; defaults to the main DB URL when unset.
- **Event-driven `wait_for_workstream`** — coord's block-wait tool no longer
-  polls storage every 500 ms. A new in-process `ChildEventBus` notifies waiters
-  whenever a child state change is dispatched to the UI, and the wait loop
-  blocks on `threading.Event.wait` with a 2 s heartbeat cap (matching the
-  existing `wait_progress` SSE cadence). A 600 s wait that previously hit
-  storage ~2400 times now wakes only on real state transitions, with ~4× lower
-  SSE traffic in the quiescent case.
- **Memory tool audit trail** — the memory tool now emits `memory.save`,
-  `memory.update`, and `memory.delete` audit events (the admin-console DELETE
-  route previously emitted only `memory.delete`, so tool-initiated mutations
-  had no audit footprint). All emissions are best-effort and never break the
-  tool call itself.
- **`task_agent` per-call personas via `skill=`** — `task_agent` now accepts
-  an optional `skill=<name>` argument that loads the named skill's content as
-  the sub-agent's persona in place of the hardcoded identity statement. The
-  fixed operating-guidance block (one-shot, tool-use over narration,
-  no follow-up questions) is still layered on top of every persona. High- and
-  critical-risk skills surface their risk tier in the approval header and
-  emit a `task_agent.high_risk_skill` warning, matching the existing
-  session-load gate.
-
-### Fixed
-
- **Per-role plan / task model overrides could be bypassed by the LLM** — the
-  back-compat `default` alias auto-synthesised by `load_model_registry`
-  remained visible to the model even when an operator had configured
-  `model.task_alias` / `model.plan_alias`, so `task_agent(model="default")`
-  routed to whichever backend the synthesised alias was attached to at boot
-  instead of the configured per-role default. The synthesised alias is now
-  only added when neither the DB nor `[models.*]` populates the registry,
-  filtered out of the LLM-visible alias list, and explicitly rejected at the
-  validator chokepoint as defense-in-depth.
- **Mermaid streaming parse errors + progressive `hljs`** — live-streamed
-  mermaid blocks with bare `(`, `[`, `{` inside unquoted edge or rectangle
-  node labels were re-entering the shape parser and producing
-  `Parse error, got 'PS'` messages. The renderer now autoquotes the two
-  affected label forms (`|content|` and `ID[content]`) before the SVG cache
-  lookup; shapes whose syntax already nests delimiters (cylinders, subroutines,
-  trapezoids, etc.) are intentionally left alone. The companion `hljs` change
-  highlights code blocks progressively as they stream rather than only after
-  completion.
- **Re-auth from inside the proxy-prefixed UI** — on a proxied node page
-  (`/node/{id}/...`), an expiring JWT triggered an in-page login modal whose
-  POST went to `/v1/api/auth/login` and was rewritten to
-  `/node/{id}/v1/api/auth/login`. Two latent bugs both blocked re-auth: the
-  console's `AuthMiddleware` didn't recognise the `/node/{id}/` prefix over a
-  public path, and `proxy_api` would have forwarded the login request to the
-  upstream node (which mints `JWT_AUD_SERVER` tokens the console then rejects).
-  Both fixed: proxied public paths stay public, and `proxy_api` now dispatches
-  every entry in `_PROXY_AUTH_LOCAL_HANDLERS` (login, logout, setup, refresh,
-  status, whoami, oidc/authorize, oidc/callback) to the console's own auth
-  handlers. The dispatch table is a single `(method, path) → handler` mapping
-  so the test parametrize list can't drift from the implementation.
- **Appbar visibility + gear-icon dropdown on the dashboard** — the dashboard
-  overlay was covering the entire appbar, hiding the proxy-injected node
-  picker. The overlay now starts at `top: 48px` and the dashboard's role
-  downgrades from `dialog+aria-modal` to `region` so the appbar above it
-  remains reachable. The gear icon converts from a direct settings-panel
-  click into a dropdown with "MCP connections" and "Logout" (the latter with
-  `.destructive` styling). The settings-menu keydown handler is now attached
-  synchronously so `Escape` can't fall through the brief window between the
-  menu opening and its listeners being installed.
- **PostgreSQL test backend on the notify dispatcher suite** — migration 053's
-  `services_notify` trigger lives only in the alembic chain, but the test
-  fixture creates tables via `metadata.create_all`. The trigger function +
-  trigger are now declared in `_schema.py` and attached via
-  `sa.event.listen(services, "after_create", ...)` DDL events gated on the
-  PostgreSQL dialect, with the same SQL constants imported by migration 053
-  so there's a single source of truth.
-
-## [1.5.12]
-
-### Added
-
- **Enriched backend error messages** — provider name and attempted URL are now
-  included in session error responses, so operators can triage connectivity
-  failures without enabling debug logging.
-
-### Fixed
-
- **`/rewind` always emits a `history` SSE event** — pre-fix, if the session
-  had no messages remaining after a rewind the history event was skipped,
-  leaving connected UIs with stale content and blocking edit-and-resend flows.
-
-## [1.5.11]
-
-This release introduces one forward-only schema migration:
-`052_model_reasoning_persistence` — `surface_persisted_reasoning` and
-`replay_reasoning_to_model` flag columns on `model_definitions`.
-
-### Added
-
- **SSE refresh-resume** — clients that reload mid-stream (browser refresh, tab
-  restore) now receive an `in_progress_snapshot` event carrying the buffered
-  partial response, so the UI can resume rendering the in-flight turn without
-  losing content. The snapshot is keyed by a monotonic `_ws_inflight_seq`
-  counter so a reconnecting client can skip events it already saw.
- **Reasoning persistence** (Phases 1–4) — model reasoning text can now be
-  persisted to conversation history and optionally replayed to the model on
-  subsequent turns. Phase 1 persists reasoning text on the history payload.
-  Phase 2 wires a build-time shape filter and a per-model
-  `replay_reasoning_to_model` flag. Phases 3+4 add full OpenAI Responses API
-  (`include=["reasoning.encrypted_content"]`) and Chat Completions support;
-  an `ANTHROPIC_VALID_BLOCK_TYPES` shape filter guards the Anthropic path. Two
-  new per-model capability flags (`surface_persisted_reasoning`,
-  `replay_reasoning_to_model`) both default `False` on unknown and
-  local-server models.
- **Console home composer: placeholders + toggle** — the console landing-page
-  composer now shows context-aware placeholder text and a toggle component for
-  advanced options; an admin polish pass tightened spacing and focus behaviour
-  across the form.
-
-### Changed
-
- **`judge.model` now requires a named alias** — raw provider model IDs on
-  `judge.model` in config are no longer accepted; the judge must reference an
-  alias registered in the model registry. The session-provider raw-model
-  fallback is removed. Existing configs using an unregistered model ID need a
-  corresponding alias entry.
-
-### Fixed
-
- **`replay_reasoning_to_model` AND-gated with model capability** — setting the
-  flag for a model that does not declare reasoning-replay support now silently
-  no-ops instead of forwarding reasoning blocks and triggering a provider error.
- **Coordinator alias resolution unified across placeholder + factory** — a
-  placeholder coordinator and the real coordinator factory could previously
-  resolve to different model aliases, producing a visible mismatch in the model
-  display. Both paths now share the same resolution logic.
- **Console `cs=None` fallback in `/v1/api/models` placeholder** — an
-  under-initialised coordinator state no longer 500s when the models endpoint
-  is hit before the coordinator subsystem is fully bootstrapped.
- **SSE `_ws_inflight_seq` always advances** — sequence numbers were previously
-  skipped when an emit was past the buffer cap, leaving gaps in the monotonic
-  counter that broke `state_change` / `in_progress_snapshot` ordering on
-  reconnect.
- **Reasoning persistence shape + replay fixes** — per-block
-  `ANTHROPIC_VALID_BLOCK_TYPES` filter applied; `reasoning_text` is now
-  synthesised alongside non-reasoning `provider_blocks` so both appear
-  together in the history payload.
-
-## [1.5.10]
-
-This release introduces one forward-only schema migration:
-`051_skill_notify_on_complete_array_default` — backfills
-`prompt_templates.notify_on_complete` from `'{}'` to `'[]'`.
-
-### Added
-
- **Skills unlock action** — operators can unlock an installed skill to allow
-  local customisation. Once unlocked, the skill's resource content, system
-  prompt additions, and notify configuration are editable through the admin UI.
-  Skills shipped as part of a bundle remain locked (read-only) until explicitly
-  unlocked; the unlock is logged to the audit trail. A lock icon in the
-  top-right of the Skills detail pane doubles as the unlock trigger.
-
-### Fixed
-
- **`skills.sh` install endpoint** — the install script was targeting an
-  endpoint removed in an earlier refactor; switched to `/api/download`.
- **Skills `notify_on_complete` default** — the field defaulted to `{}`
-  (object) instead of `[]` (array), causing notify configurations to be
-  rejected at schema validation.
- **Skills admin UI modal errors** — `.is-visible` class used consistently
-  instead of inline `style.display`; stale error text is cleared on submit;
-  designer-review lock-icon UX applied.
-
-## [1.5.9]
-
-### Fixed
-
- **`repair=False` on all display-read `load_messages` call sites** —
-  passing `repair=True` on display paths was silently mutating the stored
-  message list, causing divergence between what the UI showed and what the
-  model received on the next turn.
-
-## [1.5.8]
-
-This release introduces two forward-only schema migrations:
-`049_mcp_oauth_schema` — OAuth token + consent tables for MCP servers;
-`050_conversations_source_and_reminders` — `_source` and `_reminders` columns
-on `conversations`.
-
-### Added
-
- **MCP OAuth 2.1 + PKCE** — MCP servers that require OAuth can now be
-  configured with a client ID and secret through the admin UI. The full token
-  lifecycle (acquire → refresh → rotate) is managed automatically; tokens are
-  stored encrypted at rest using a key derived from the JWT secret. The consent
-  flow runs in-browser via a provider redirect. Rolled out in phases:
-
-  - Minimum admin form and OAuth schema (`21663d15`).
-  - Token-at-rest AES-GCM encryption layer (`a4c335d7`).
-  - Per-(user, server) OAuth 2.1 + PKCE flow (`b0f7029f`).
-  - Per-(user, server) `ClientSession` pool with OAuth dispatch (`1a1043c4`).
-  - SDK 401/403 introspection via httpx response hook (`bde09134`).
-  - Phase 7 — per-user tool catalog scoping: each user sees only the tools
-    their OAuth token is permitted to call (`cfc8a6c8`).
-  - Phase 7b — per-user resource + prompt pool dispatch (`b368bdee`).
-  - Phase 8 — per-user MCP consent UX: users see a consent dialog on first
-    use of an OAuth-gated server and can revoke consent from their profile;
-    admins see per-server consent counts in the MCP Servers tab (`61051339`).
-
- **Metacognition NudgeQueue** — all advisory channels (repeat-tool nudges,
-  watch reminders, wake triggers) are unified into a pull-model `NudgeQueue`
-  that delivers at most one nudge per turn, preventing multi-channel pile-ups
-  that inflate context. Observable changes:
-
-  - Watch results carry metadata (watch ID, `valid_until`, trigger type)
-    through to the system message so the model can reason about recency.
-  - Coordinator idle-children observer: a coordinator with no in-flight
-    children for longer than the configured idle threshold receives a nudge.
-  - Wake trigger (`IdleNudgeWatcher`): sessions waiting on an external event
-    can be unblocked via `ChatSession.deliver_wake_nudge_from_queue`.
-  - Watch switchover: watch results are now enqueued on the `NudgeQueue`
-    rather than the previous `_watch_pending` list, giving them the same
-    delivery guarantees and priority handling as other advisories.
-
- **Structured watch-result card** — the UI renders watch results as a styled
-  card with a system-nudge marker, distinct from the assistant message body.
-  On history replay, system-nudge turns are visually distinguished from normal
-  assistant turns.
- **Side-channel persistence** — `_source` and `_reminders` side-channel
-  fields are persisted to the `conversations` storage table and restored on
-  session resume, so metacognitive context survives process restarts. A
-  `REMINDER_TEXT_STORAGE_CAP` byte clamp prevents unbounded growth.
-
-### Fixed
-
- **Replay consistency** — queued user messages captured mid-loop are now
-  persisted and replayed in the correct order on a subsequent `events`
-  subscription. Coordinator history replay fixed: blank assistant cards and
-  out-of-order tool results on the coordinator tree no longer occur when the
-  coordinator has mixed queued + delivered messages.
- **Session reminder preservation on fork + resume** — `_source` and
-  `_reminders` are carried through workstream fork and restored from storage
-  on resume.
- **NUL-byte sanitization in storage** — PostgreSQL rejects `\x00` in text
-  columns; `_source` and `_reminders` now strip NUL bytes on write.
- **Console coordinator subsystem bootstrap** — the coordinator subsystem is
-  now committed atomically on first model add; startup teardown is offloaded
-  to avoid blocking the event loop.
- **MCP `asyncio.timeout` over `asyncio.wait_for`** — Python 3.11's
-  `wait_for` wraps the coroutine in a fresh task, breaking anyio's `aclose`
-  scope exit. Replaced with `async with asyncio.timeout(N)` for safe cleanup.
- **MCP pool-reuse 401 recovery** — a reused `ClientSession` returning 401
-  now replaces the pool entry with a fresh session; the carrier token is
-  owned by the pool entry to prevent a race between the 401 handler and a
-  concurrent request.
- **OIDC hardening** — multiple security and correctness fixes:
-  SSRF + plaintext credential exfil via discovery document (sec-1, sec-3);
-  `TURNSTONE_OIDC_REDIRECT_BASE` now required, Host-header fallback removed
-  (sec-2); atomic user + identity provisioning prevents orphan rows (bug-1);
-  callback robustness — typed exceptions, shape checks, log sanitization, JS
-  race (bug-4–6, sec-4); role-mapping concurrency serialized (bug-2, perf-1);
-  stranded-user self-heal on role-mapping failure (cumulative bug-1).
-
-## [1.5.7]
-
-### Added
-
- **Inline node picker** — a compact node-switcher dropdown in the console
-  header replaces the "← Back to console" banner, so operators can switch
-  between nodes without a full navigation.
-
-### Fixed
-
- **Queued user messages injected mid-loop** — messages queued while a
-  generation was in progress were not being delivered at the correct seam and
-  could be dropped or reordered when the worker consumed the queue.
- **Search tool output bounded** — pathological inputs (very long lines with
-  no whitespace) could produce search results exceeding the context budget.
-  Output is now clamped before reaching the message.
-
-## [1.5.6]
-
-### Added
-
- **`api_surface` toggle** — model definitions gain an `api_surface` field
-  (`"chat"` | `"responses"`) that selects which OpenAI-compatible API surface
-  the provider client uses. Enables Mistral Medium reasoning via the Responses
-  surface; Chat Completions remains the default for all other models.
- **Healthy model aliases per node** — `GET /v1/api/cluster/nodes` now
-  includes a `healthy_aliases` list per node, so the coordinator and operators
-  can see which model aliases are currently reachable without a separate
-  per-model health probe.
- **Plan/task agent settings in Models → Roles** — the Models admin tab's
-  Roles sub-tab gains `plan_agent` and `task_agent` rows so operators can
-  configure per-kind reasoning effort and alias overrides from the UI rather
-  than editing `config.toml`. Live-refresh dropdowns update in place when
-  model definitions change.
-
-### Fixed
-
- **Memory candidate selection** — recall now uses OR-of-terms BM25 with
-  query-aware candidate-set selection, dramatically improving recall for
-  queries whose terms span multiple stored entries.
- **Workstream model + config preserved on rehydrate** — reopening a closed
-  workstream no longer overwrites the model alias and per-workstream config
-  with session defaults.
- **Console home composer: attachments + user-message pills** — multipart
-  attachments in the home composer were not forwarded correctly; user-message
-  pills in the coordinator chat pane were missing.
-
-## [1.5.5]
-
-### Fixed
-
- **Saved-workstream tool result rendering** — tool results in closed
-  workstreams were not rendering on history replay. Audit-trail decoration for
-  tool calls is now applied on the replay path.
-
-## [1.5.4]
-
-### Added
-
- **Stage 3 SessionManager Children primitive lift** — child workstreams are
-  first-class citizens in the cluster event bus. `child_ws_state` events are
-  pushed through the cluster SSE stream so the console tree view updates in
-  real time without polling. `list_children` and `get_child` primitives on
-  `SessionManager` provide a consistent cross-node view of the coordinator's
-  spawn tree.
- **Multi-select delete for Saved Coordinators** — the Saved Coordinators grid
-  in the console admin panel now supports checkbox multi-select with a
-  bulk-delete action.
-
-## [1.5.3]
-
-This release introduces one forward-only schema migration:
-`048_workstream_reaper_index` — partial composite index on `workstreams` for
-the orphan-reaper query.
-
-### Fixed
-
- **Coordinator orphan reaping scoped by heartbeat** — the session manager's
-  `close_idle` pass now scopes the DB-orphan reaper by
-  `services.last_heartbeat` so workstreams belonging to a live node are not
-  incorrectly reaped. `bulk_close_stale_orphans` and `touch_workstream`
-  storage primitives added; a partial composite index keeps the reaper scan
-  cheap.
- **Coordinator pool idle cleanup** — a periodic task on the console now
-  closes coordinator pool entries whose session has gone idle past the
-  configurable threshold, preventing pool exhaustion on long-running consoles.
-
-## [1.5.2]
-
-### Added
-
- **Metacognition themed reminder bubble** — repeat-tool and user-reminder
-  nudges are rendered as a distinct styled bubble rather than being injected
-  inline into the assistant message, making it easier to distinguish model
-  output from metacognitive annotations. The CLI REPL gains matching
-  `on_user_reminder` / `on_tool_reminder` callbacks.
-
-### Fixed
-
- **Metacog streak detector** — the N≥3 sequential-same-call streak detector
-  now fires correctly on the third repetition; a write-success-clear that
-  reset the counter after a successful tool call (preventing streaks across
-  mixed-outcome sequences) was removed.
- **Metacog reminders isolated to side-channel** — reminder text no longer
-  appears in the user content turn; it flows through a dedicated side-channel
-  the session injects into the system context, preventing the model from
-  attributing it to the user.
-
-## [1.5.1]
-
-### Added
-
- **`pending_approval_detail` on child `ws_state` SSE events** — coordinators
-  now receive the child's pending approval detail in `child_ws_state` events,
-  enabling the coordinator to surface approval prompts without a separate poll.
-
-### Fixed
-
- **Coordinator registry auto-refresh** — the console coordinator registry now
-  refreshes when model definitions change, so a newly added alias is visible
-  to coordinators without restarting.
- **Coordinator fan-out default** — coordinators now fan out to independent
-  child workstreams by default instead of serialising them, matching the
-  documented contract for parallel-work patterns.
- **`wait_for_workstream` message cap raised to 10 KiB** — large plan
-  summaries and tool results from child workstreams were silently truncated at
-  the previous 4 KiB cap.
- **Coordinator SSE isolated on dedicated thread pool** — coordinator SSE
-  polling now runs on a dedicated 200-thread executor, matching interactive's
-  `sse_executor`, so coordinator long-poll blocking no longer contends with
-  storage and routing workers on the default pool.
-
-## [1.5.0]
-
-User-visible additions: a unified workstream HTTP surface (interactive and
-coordinator under one URL family), inline child approvals, coordinator
-composer parity, progressive rendering, OIDC authentication, MCP OAuth
-foundations, and a redesigned UI built on the Design System v1 token layer.
-
-This release removes the pre-1.5 body-keyed and query-keyed URL family.
-See **Removed (BREAKING)** below before upgrading from a 1.x stable line.
-
-This release introduces the following forward-only schema migrations that the
-server applies automatically on first startup. All are additive; no data loss.
-
- `039_workstream_kind` — `kind` + `parent_ws_id` columns on `workstreams`.
- `040_coord_cluster_admin_perms` — grants `admin.coordinator` +
-  `admin.cluster.inspect` to the builtin-admin role.
- `041_workstream_index_tuning` — refined indexes for the workstream query mix
-  introduced by 039.
- `042_coord_trust_send_perm` — adds `coordinator.trust.send` permission to
-  builtin-admin.
- `043_skill_description_required` — backfills empty `description` rows in
-  `prompt_templates`.
- `044_skill_kind` — adds `kind` classifier column to `prompt_templates`
-  (`interactive` / `coordinator` / `any`).
- `045_skill_risk_level_rename` — renames `prompt_templates.scan_status` →
-  `risk_level`.
- `046_drop_hash_ring_tables` — drops the hash-ring bucket tables superseded
-  by rendezvous routing in 1.4.
- `047_drop_coord_spawn_quota_settings` — removes the spawn-quota settings
-  rows removed from the coordinator in 1.5.0a4.
-
-### Added
-
- **Inline child approvals** — pending tool approvals on coordinator child
-  workstreams surface directly in the coordinator tree view. A risk pill shows
-  the judge verdict (or "pending" while the judge evaluates); Approve/Deny
-  buttons appear inline so operators do not need to navigate to the child's
-  workstream. `pending_approval_detail` is exposed on
-  `GET /v1/api/dashboard` and passed through the cluster live-bulk SSE payload
-  so all connected clients render approval prompts simultaneously. LLM judge
-  verdicts are cached client-side and replayed on SSE reconnect.
- **Coordinator composer parity** — the coordinator composer now supports
-  Stop, Send-to-queue, and Attach (file upload), matching the interactive
-  workstream composer feature set.
- **Per-call model and judge override on coordinator composer** — operators
-  can override the model alias and judge model for a single coordinator send
-  from the composer, without changing the node-wide or role-wide defaults. Bad
-  aliases return a corrective error listing available choices.
- **Coordinator status bar + richer history replay** — each coordinator
-  workstream gains a per-coordinator status bar showing active children, token
-  spend, and generation state. History replay in the coordinator panel is
-  extended to include tool results and thinking blocks.
- **Coordinator child error surfacing + memory tool** — child workstream
-  errors are surfaced as distinct error rows in the coordinator tree view
-  rather than disappearing silently. The coordinator gains access to a
-  `memory` tool (same interface as interactive) for retrieving stored facts.
- **Coordinator inline tool-batch construct** — the coordinator tool approval
-  UI replaces the separate approval dock with an inline batch construct that
-  groups all pending tool calls for a given turn into a single review card.
- **Node capability auto-detection** — nodes report kernel-level capabilities
-  (available memory, CPU count, accelerator presence) via
-  `/v1/api/node/capabilities` at startup, enabling the console to filter model
-  aliases offered to coordinators routing to that node.
- **Skills: paste `SKILL.md` to auto-fill the Create Skill modal** — pasting
-  a `SKILL.md` file's content into the modal auto-populates the name,
-  description, and configuration fields.
- **Progressive mermaid rendering** — Mermaid diagrams begin rendering as
-  soon as a complete diagram block is detected in the stream rather than
-  waiting for the full response; the diagram re-renders in place as the model
-  extends it.
- **LaTeX and MathML delimiter support** — `\(…\)` inline and `\[…\]` block
-  math delimiters are now recognised alongside the existing `$$` fences.
+## [Unreleased]

 ### Removed (BREAKING — 1.5.0)

@@ -56,4 +56,4 @@ Open an issue at https://github.com/turnstonelabs/turnstone/issues with:
 ## License

 By contributing, you agree that your contributions will be licensed under the
-project's [Apache License 2.0](LICENSE).
+project's [Business Source License 1.1](LICENSE).
@@ -1,13 +0,0 @@
-# Contributors
-
-Turnstone is written and maintained by Patrick Buckley
-([@eous](https://github.com/eous)).
-
-The following people have contributed code to the project — thank you:
-
- Burhan ([@Burhan-Q](https://github.com/Burhan-Q))
- chrismuzyn ([@chrismuzyn](https://github.com/chrismuzyn))
- daoxley ([@daoxley](https://github.com/daoxley))
- Robert DeAngelis ([@OriginalOrangeXD](https://github.com/OriginalOrangeXD))
- William ([@sillyWillieBilly](https://github.com/sillyWillieBilly))
- [@pizzaandcheese](https://github.com/pizzaandcheese)
@@ -8,17 +8,14 @@ FROM python:3.14-slim
 LABEL org.opencontainers.image.title="turnstone" \
      org.opencontainers.image.description="Multi-node AI orchestration platform"

-COPY --from=ghcr.io/astral-sh/uv:0.11.21 /uv /usr/local/bin/uv
+COPY --from=ghcr.io/astral-sh/uv:0.11.8 /uv /usr/local/bin/uv

 # Remove the slim image's man page exclusion so man-db has actual content
 RUN rm -f /etc/dpkg/dpkg.cfg.d/docker

-# System dependencies: psycopg (libpq5), developer tooling for agent workflows.
-# ripgrep is the preferred backend for the search tool — natively bounds
-# per-line, per-file, and per-filesize so pathological inputs (minified
-# bundles, training-data JSONL with multi-MB single records) can't OOM us.
+# System dependencies: psycopg (libpq5), developer tooling for agent workflows
 RUN apt-get update && apt-get upgrade -y && apt-get install -y --no-install-recommends \
-    libpq5 git curl jq man-db manpages procps file ripgrep \
+    libpq5 git curl jq man-db manpages procps file \
    && rm -rf /var/lib/apt/lists/*

 # Node.js LTS (for npx-based MCP servers like @modelcontextprotocol/server-github)
@@ -33,7 +30,7 @@ RUN useradd --create-home --shell /bin/bash turnstone
 WORKDIR /app

 # Install dependencies first (cached layer — only re-runs when deps change)
-COPY pyproject.toml uv.lock README.md LICENSE NOTICE THIRD-PARTY-NOTICES ./
+COPY pyproject.toml uv.lock README.md LICENSE ./
 RUN uv sync --frozen --no-install-project --no-dev \
    --no-compile --extra all

@@ -1,201 +1,62 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
+License text copyright (c) 2020 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.

-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+Parameters

-   1. Definitions.
+Licensor:             Patrick Buckley
+Licensed Work:        Turnstone 0.2.0. The Licensed Work is (c) 2025-2026 Patrick Buckley.
+Additional Use Grant: You may make production use of the Licensed Work, provided
+                      your use does not include providing the Licensed Work to third
+                      parties as a hosted or managed service, where the service
+                      provides users with access to any substantial set of the
+                      features or functionality of the Licensed Work.
+Change Date:          2030-03-01
+Change License:       Apache License, Version 2.0

-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
+For information about alternative licensing arrangements for the Licensed Work,
+please contact buckleypm@gmail.com.

-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
+Notice

-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
+Business Source License 1.1

-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
+Terms

-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited production use.

-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.

-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.

-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.

-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.

-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.

-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).

-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright [yyyy] [name of copyright owner]
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
@@ -1,7 +0,0 @@
-Turnstone
-Copyright 2025-2026 Patrick Buckley
-
-Licensed under the Apache License, Version 2.0; see the LICENSE file.
-
-Third-party software bundled with this distribution is listed in the
-THIRD-PARTY-NOTICES file; each component remains under its own license.
@@ -42,13 +42,13 @@ That's it — no flags, no arguments. The wizard prompts for everything.

 ## Deployment Modes

- **Single-node production** — `docker compose up` against the bundled
-  `turnstone/deploy/compose.yaml`: 1 server + console + channel + PostgreSQL,
-  pulled from ghcr.io. Good for most deployments.
- **Local multi-node cluster** — clone the repo and run `docker compose up` at
-  the root for a 10-node fleet + console + Caddy + channel, built locally.
+The wizard supports two deployment modes:

-See [docs/docker.md](docs/docker.md) for both.
+- **Single-node production** (`docker compose --profile production up`) —
+  1 server + console + PostgreSQL. Good for most use cases.
+- **Multi-node cluster** (`docker compose --profile cluster up`) —
+  10-node server fleet + console + PostgreSQL. For high-throughput or
+  HA deployments.

 ## Example Session

@@ -3,10 +3,9 @@
 [![CI](https://github.com/turnstonelabs/turnstone/actions/workflows/ci.yml/badge.svg)](https://github.com/turnstonelabs/turnstone/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/turnstone)](https://pypi.org/project/turnstone/)
 [![Python](https://img.shields.io/pypi/pyversions/turnstone)](https://pypi.org/project/turnstone/)
-[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
-[![Discord](https://img.shields.io/badge/Discord-join%20us-5865F2?logo=discord&logoColor=white)](https://discord.gg/Nh3bWMacaq)
+[![License](https://img.shields.io/badge/license-BSL--1.1-blue)](LICENSE)

-Self-hosted, local-first orchestration for tool-using AI agents. Give LLMs real tools — shell, files, search, web — and run them across your own cluster with direct HTTP routing and interactive interfaces. Your code, your models, your data stay on hardware you control: no telemetry, no phone-home.
+Multi-node AI orchestration platform. Deploy tool-using AI agents across a cluster of servers with direct HTTP routing, interactive interfaces, and enterprise governance.

 <p align="center">
  <img src="docs/assets/hero.png" alt="Turnstone coordinator — parallel tool batches with judge-graded approval and child workstream tracking" width="960"/>
@@ -27,13 +26,12 @@ See [docs/releasing.md](docs/releasing.md) for the full release process.

 Turnstone gives LLMs tools — shell, files, search, web, planning — and orchestrates multi-turn conversations where the model investigates, acts, and reports.

- **Local-first & private** — runs entirely on hardware you control, with no telemetry and no phone-home. Point it at local models (vLLM, llama.cpp, Ollama) or commercial APIs you hold the keys to — your prompts and data never transit a third party you didn't choose.
- **Bring your own models** — OpenAI-compatible APIs (vLLM, llama.cpp, NIM), the Anthropic Messages API, and Google Gemini, mixed freely per role
 - **Interactive sessions** — terminal CLI or browser UI with parallel workstreams
- **Cluster dashboard** — real-time view of every node and workstream, with a rendezvous routing proxy
- **Intent validation** — an LLM judge (your model) grades every tool call with a risk assessment and evidence before it runs
+- **Cluster dashboard** — real-time view of all nodes and workstreams with console routing proxy
+- **Intent validation** — LLM judge evaluates every tool call with risk assessments and evidence
+- **Governance** — RBAC, OIDC SSO, tool policies, skills, usage tracking, audit logs
+- **Multi-provider** — OpenAI-compatible APIs (vLLM, llama.cpp, NIM), Anthropic Messages API, and Google Gemini
 - **MCP support** — external tool servers with native deferred loading (Anthropic/OpenAI) or BM25 fallback
- **Team controls when you need them** — optional RBAC, SSO, tool policies, and audit logs, all stored in your own database

 <p align="center">
  <img src="docs/diagrams/architecture-overview.svg" alt="Turnstone system architecture" width="960"/>
@@ -51,12 +49,14 @@ turnstone --base-url http://localhost:8000/v1
 turnstone-server --port 8080 --base-url http://localhost:8000/v1

 # Cluster dashboard
+pip install turnstone[console]
 turnstone-console --port 8090
 ```

 For PostgreSQL (recommended for production):

 ```bash
+pip install turnstone[postgres]
 export TURNSTONE_DB_BACKEND=postgresql
 export TURNSTONE_DB_URL="postgresql+psycopg://user:pass@localhost:5432/turnstone"
 turnstone-server --port 8080 --base-url http://localhost:8000/v1
@@ -64,29 +64,12 @@ turnstone-server --port 8080 --base-url http://localhost:8000/v1

 ### Docker

-One-line install — autodetects Ubuntu/Debian, Fedora/RHEL, Arch, and WSL,
-installs git + Docker if missing, generates secrets, and starts the stack:
-
 ```bash
-curl -fsSL https://raw.githubusercontent.com/turnstonelabs/turnstone/main/run.sh | bash
+cp .env.example .env  # edit LLM_BASE_URL, OPENAI_API_KEY, etc.
+docker compose --profile production up
 ```

-Or, if you already have Docker, clone the repo and run it yourself:
-
-```bash
-docker compose up
-```
-
-That builds one image and brings up a full local cluster — PostgreSQL, console,
-Caddy, channel gateway, and 10 server nodes — with no `.env` required (it ships
-with insecure dev defaults). Open the dashboard at https://localhost:8443 (Caddy
-serves it over TLS with its own local CA — trust it once). Nodes boot without an
-LLM; add model backends from the console UI.
-
-For production (released images from ghcr.io, real secrets required), use the
-bundled stack: `docker compose -f turnstone/deploy/compose.yaml up`.
-
-See [QUICKSTART.md](QUICKSTART.md) for the bootstrap wizard and [docs/docker.md](docs/docker.md) for Docker configuration.
+See [QUICKSTART.md](QUICKSTART.md) for the bootstrap wizard and [docs/docker.md](docs/docker.md) for Docker configuration and profiles.

 ### Programmatic (SDK)

@@ -159,14 +142,9 @@ UML diagrams in [`docs/diagrams/`](docs/diagrams/):

 - Python 3.11+
 - An OpenAI-compatible API endpoint, Anthropic API key, or Google Gemini API key
- Optional: Discord / Slack channel integrations (`pip install turnstone[discord,slack]`)
+- Optional: PostgreSQL (`pip install turnstone[postgres]`), Anthropic (`pip install turnstone[anthropic]`)
 - [Git LFS](https://git-lfs.com/) for cloning (diagram PNGs)

-## Community
-
-Questions, ideas, or want to show what you're building? Join us on Discord:
-**[discord.gg/Nh3bWMacaq](https://discord.gg/Nh3bWMacaq)**.
-
 ## License

-[Apache License 2.0](LICENSE), as of version 1.6.0. Versions 1.5.x and earlier remain under the Business Source License 1.1 they shipped with.
+[Business Source License 1.1](LICENSE) — free for all use except hosting as a managed service. Converts to Apache 2.0 on 2030-03-01.
@@ -2,11 +2,11 @@ Turnstone — Third-Party Notices

 This file contains the licenses and notices for third-party software bundled
 with Turnstone. Each bundled dependency retains its original license; the
-Turnstone Apache-2.0 license does not apply to these components.
+Turnstone BUSL-1.1 license does not apply to these components.

 ================================================================================

-KaTeX 0.17.0
+KaTeX 0.16.38
 https://katex.org/
 https://github.com/KaTeX/KaTeX

@@ -70,7 +70,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

 ================================================================================

-Mermaid 11.15.0
+Mermaid 11.13.0
 https://mermaid.js.org/
 https://github.com/mermaid-js/mermaid

@@ -98,7 +98,7 @@ SOFTWARE.

 ================================================================================

-hls.js 1.6.16
+hls.js 1.6.15
 https://github.com/video-dev/hls.js

 Copyright 2017 Dailymotion
@@ -1,50 +1,16 @@
 # =============================================================================
-# Turnstone — local cluster stack (docker compose)
+# Turnstone Docker Compose Stack — Development
 #
-# Clone the repo and run:
+# This file is for local development from a git clone. It builds images
+# locally from the Dockerfile. If you installed via pip/pipx, run
+# `turnstone-bootstrap` instead — it writes a production compose.yaml
+# that pulls pre-built images from ghcr.io.
 #
-#     docker compose up
-#
-# That builds one image and brings up a complete, console-visible cluster:
-# PostgreSQL + console + Caddy + channel gateway + 10 server nodes (node-1…10).
-#
-#   Dashboard: https://localhost:8443   (Caddy's local CA — trust it once)
-#
-# Access is via Caddy only — the console's plain-HTTP port is intentionally not
-# published (HTTP/2 from Caddy avoids the browser's 6-connection cap on the
-# dashboard's SSE streams). Trust Caddy's root once:
-#     docker compose exec caddy cat /data/caddy/pki/authorities/local/root.crt
-#
-# It works out of the box with INSECURE dev defaults (see the secret/password
-# values below) so there's nothing to configure first. A .env file still
-# overrides any value. For a real deployment use the bundled production stack
-# at turnstone/deploy/compose.yaml — it pulls released images from ghcr.io and
-# requires you to set real secrets.
-#
-# Bring your own LLM: nodes boot without one and show up in the console
-# immediately. Add model backends (OpenAI / Anthropic / local vLLM) from the
-# console UI's Models tab, or point LLM_BASE_URL / OPENAI_API_KEY (below) at an
-# OpenAI-compatible endpoint.
-#
-# Fewer nodes (lighter machines):
-#     docker compose up postgres console caddy channel node-1 node-2 node-3
-#
-# Join a bare-metal host: Postgres is published on 127.0.0.1:5432, so a
-# turnstone-server running directly on this machine (e.g. to use a local GPU)
-# can join the same cluster. Keep the secret + connection settings in
-# ~/.config/turnstone/config.toml (chmod 0600 — the loader warns otherwise):
-#     [auth]
-#     jwt_secret = "dev-only-insecure-jwt-secret-change-me-for-real-deployments"
-#     [database]
-#     backend = "postgresql"
-#     url = "postgresql+psycopg://turnstone:turnstone@localhost:5432/turnstone"
-#     [api]
-#     base_url = "http://localhost:8000/v1"
-#     api_key = "dummy"
-# then run (node identity isn't a secret, so it stays on the command line):
-#     TURNSTONE_NODE_ID=host-1 TURNSTONE_ADVERTISE_URL=http://host.docker.internal:8080 \
-#       turnstone-server --host 0.0.0.0 --port 8080
-# It registers in Postgres and the console reaches it back via host.docker.internal.
+# Usage:
+#   Infra only:           docker compose up
+#   Single node:          docker compose --profile production up
+#   Production (PG):      TURNSTONE_DB_BACKEND=postgresql docker compose --profile production up
+#   10-node cluster:      docker compose --profile cluster up
 # =============================================================================

 name: turnstone
@@ -57,30 +23,16 @@ volumes:
  turnstone-data:
  workspace:
  postgres-data:
-  caddy-data:
-  caddy-config:
-  searxng-cache:
-
-# -- Shared values (scalar anchors) -------------------------------------------
-# Defined once here, referenced (*alias) by every service so the dev defaults
-# can't drift. All `${VAR:-default}` values are still overridable via .env.
-x-shared:
-  # INSECURE dev default. Every service MUST share ONE secret — the console
-  # mints its own service token (signed with this) to reach the nodes. Override
-  # TURNSTONE_JWT_SECRET in .env for anything that isn't a local sandbox.
-  jwt-secret: &jwt-secret "${TURNSTONE_JWT_SECRET:-dev-only-insecure-jwt-secret-change-me-for-real-deployments}"
-  db-backend: &db-backend "${TURNSTONE_DB_BACKEND:-postgresql}"
-  # All services point at the same Postgres. Node discovery REQUIRES a shared
-  # DB: each server registers + heartbeats into a `services` table that the
-  # console polls. (SQLite-per-container can't see other containers.)
-  db-url: &db-url "${TURNSTONE_DB_URL:-postgresql+psycopg://${POSTGRES_USER:-turnstone}:${POSTGRES_PASSWORD:-turnstone}@postgres:5432/turnstone}"

 services:
  # -------------------------------------------------------------------
-  # PostgreSQL — the shared database that ties the cluster together.
+  # PostgreSQL — production database (profile: production)
  # -------------------------------------------------------------------
  postgres:
    image: pgautoupgrade/pgautoupgrade:18-alpine
+    profiles:
+      - production
+      - cluster
    command:
      - postgres
      - -c
@@ -90,16 +42,8 @@ services:
    environment:
      POSTGRES_DB: turnstone
      POSTGRES_USER: ${POSTGRES_USER:-turnstone}
-      # INSECURE dev default — override POSTGRES_PASSWORD in .env for real use.
-      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-turnstone}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required for production profile}
      PGDATA: /var/lib/postgresql/data
-    # Published on localhost so a bare-metal turnstone-server running on THIS
-    # host can join the cluster (see "Join a bare-metal host" in the header).
-    # Bound to 127.0.0.1 by default; set POSTGRES_BIND=0.0.0.0 to let another
-    # machine connect — but set a real POSTGRES_PASSWORD first, or you'll expose
-    # a database with the insecure default password to your network.
-    ports:
-      - "${POSTGRES_BIND:-127.0.0.1}:${POSTGRES_PORT:-5432}:5432"
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
@@ -113,21 +57,65 @@ services:
    deploy:
      resources:
        limits:
-          memory: 2G
+          memory: 4G
+          cpus: '4.0'
    restart: unless-stopped

  # -------------------------------------------------------------------
-  # turnstone-console — cluster dashboard. Reach it ONLY through Caddy at
-  # https://localhost:8443 (see the caddy service below).
-  #
-  # The console port (8090) is deliberately NOT published to the host: a plain
-  # HTTP/1.1 origin caps the browser at 6 connections, which starves the
-  # dashboard's per-pane SSE streams. Caddy serves the browser over HTTP/2
-  # (multiplexed) and proxies to console:8090 internally, so the cap is gone.
-  #
-  # The single `build:` here produces the turnstone:local image every other
-  # service reuses. extra_hosts lets the console reach a bare-metal server
-  # advertising http://host.docker.internal:8080 (see "Join a host" below).
+  # turnstone-server — Web UI + chat workstreams + LLM interaction
+  # -------------------------------------------------------------------
+  server:
+    image: turnstone:local
+    profiles:
+      - production
+    command:
+      - sh
+      - -c
+      - >-
+        turnstone-server
+        --host 0.0.0.0
+        --port 8080
+        --base-url "$${LLM_BASE_URL}"
+        --api-key "$${OPENAI_API_KEY}"
+        $${MODEL:+--model $$MODEL}
+        $${SKIP_PERMISSIONS:+--skip-permissions}
+        $${MCP_CONFIG:+--mcp-config $$MCP_CONFIG}
+    ports:
+      - "${SERVER_PORT:-8080}:8080"
+    volumes:
+      - turnstone-data:/data
+      - ${WORKSPACE_MOUNT:-workspace}:/workspace
+    environment:
+      - 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:-}
+      # Generate with: python -c "import secrets; print(secrets.token_hex(32))"
+      - TURNSTONE_JWT_SECRET=${TURNSTONE_JWT_SECRET:?Set TURNSTONE_JWT_SECRET in .env}
+      - MODEL=${MODEL:-}
+      - MCP_CONFIG=${MCP_CONFIG:-}
+      - TURNSTONE_DB_BACKEND=${TURNSTONE_DB_BACKEND:-sqlite}
+      - TURNSTONE_DB_URL=${TURNSTONE_DB_URL:-}
+      - TURNSTONE_NODE_ID=${TURNSTONE_NODE_ID:-}
+      - TURNSTONE_ADVERTISE_URL=${TURNSTONE_ADVERTISE_URL:-http://server:8080}
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    networks:
+      - turnstone-net
+    depends_on:
+      postgres:
+        condition: service_healthy
+        required: false
+    healthcheck:
+      test: ["CMD", "python", "/usr/local/bin/healthcheck.py", "http://127.0.0.1:8080/health"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 60s
+    restart: unless-stopped
+
+  # -------------------------------------------------------------------
+  # turnstone-console — Cluster dashboard
  # -------------------------------------------------------------------
  console:
    image: turnstone:local
@@ -138,18 +126,16 @@ services:
      - turnstone-console
      - --host=0.0.0.0
      - --port=8090
+    ports:
+      - "${CONSOLE_PORT:-8090}:8090"
    environment:
-      TURNSTONE_JWT_SECRET: *jwt-secret
-      TURNSTONE_DB_BACKEND: *db-backend
-      TURNSTONE_DB_URL: *db-url
-      TURNSTONE_CONSOLE_URL: http://console:8090
-    extra_hosts:
-      - "host.docker.internal:host-gateway"
+      # Generate with: python -c "import secrets; print(secrets.token_hex(32))"
+      - TURNSTONE_JWT_SECRET=${TURNSTONE_JWT_SECRET:?Set TURNSTONE_JWT_SECRET in .env}
+      - TURNSTONE_DB_BACKEND=${TURNSTONE_DB_BACKEND:-sqlite}
+      - TURNSTONE_DB_URL=${TURNSTONE_DB_URL:-}
+      - TURNSTONE_CONSOLE_URL=http://console:8090
    networks:
      - turnstone-net
-    depends_on:
-      postgres:
-        condition: service_healthy
    healthcheck:
      test: ["CMD", "python", "/usr/local/bin/healthcheck.py", "http://127.0.0.1:8090/health"]
      interval: 10s
@@ -159,33 +145,14 @@ services:
    restart: unless-stopped

  # -------------------------------------------------------------------
-  # caddy — browser TLS for the console dashboard.
-  # Terminates HTTPS (Caddy's own local CA, see turnstone/deploy/Caddyfile) → console:8090.
-  # Dashboard over TLS: https://localhost:${CONSOLE_HTTPS_PORT:-8443}
-  # -------------------------------------------------------------------
-  caddy:
-    image: caddy:2.11
-    depends_on:
-      - console
-    ports:
-      - "${CONSOLE_HTTPS_PORT:-8443}:443"
-      # SearxNG web UI — localhost-only (it has no auth). Browse https://localhost:8444.
-      - "127.0.0.1:${SEARXNG_HTTPS_PORT:-8444}:8444"
-    volumes:
-      - ./turnstone/deploy/Caddyfile:/etc/caddy/Caddyfile:ro
-      - caddy-data:/data # persist Caddy's local CA across restarts
-      - caddy-config:/config
-    networks:
-      - turnstone-net
-    restart: unless-stopped
-
-  # -------------------------------------------------------------------
-  # turnstone-channel — channel gateway (Discord and/or Slack).
-  # Runs HTTP-only with no adapters until you set a token, so it's safe
-  # to leave running. See docs/channels.md.
+  # turnstone-channel — Channel gateway (Discord, Slack, etc.)
+  # Requires TURNSTONE_DISCORD_TOKEN to enable Discord adapter
  # -------------------------------------------------------------------
  channel:
    image: turnstone:local
+    profiles:
+      - production
+      - cluster
    command:
      - sh
      - -c
@@ -194,59 +161,36 @@ services:
        --http-host=0.0.0.0
        $${TURNSTONE_DISCORD_GUILD:+--discord-guild $$TURNSTONE_DISCORD_GUILD}
    environment:
-      TURNSTONE_JWT_SECRET: *jwt-secret
-      TURNSTONE_DB_BACKEND: *db-backend
-      TURNSTONE_DB_URL: *db-url
-      TURNSTONE_DISCORD_TOKEN: ${TURNSTONE_DISCORD_TOKEN:-}
-      TURNSTONE_DISCORD_GUILD: ${TURNSTONE_DISCORD_GUILD:-0}
-      TURNSTONE_SLACK_TOKEN: ${TURNSTONE_SLACK_TOKEN:-}
-      TURNSTONE_SLACK_APP_TOKEN: ${TURNSTONE_SLACK_APP_TOKEN:-}
-      TURNSTONE_CHANNEL_ADVERTISE_URL: http://channel:8091
+      - TURNSTONE_DISCORD_TOKEN=${TURNSTONE_DISCORD_TOKEN:-}
+      - TURNSTONE_DISCORD_GUILD=${TURNSTONE_DISCORD_GUILD:-0}
+      # Generate with: python -c "import secrets; print(secrets.token_hex(32))"
+      - TURNSTONE_JWT_SECRET=${TURNSTONE_JWT_SECRET:?Set TURNSTONE_JWT_SECRET in .env}
+      - TURNSTONE_DB_BACKEND=${TURNSTONE_DB_BACKEND:-postgresql}
+      - TURNSTONE_DB_URL=${TURNSTONE_DB_URL:-postgresql+psycopg://${POSTGRES_USER:-turnstone}:${POSTGRES_PASSWORD:-turnstone}@postgres:5432/turnstone}
+      - TURNSTONE_CHANNEL_ADVERTISE_URL=http://channel:8091
    networks:
      - turnstone-net
    depends_on:
      postgres:
        condition: service_healthy
-    restart: unless-stopped
-
-  # -------------------------------------------------------------------
-  # searxng — self-hosted metasearch backing the web_search tool.
-  # Internal-network only (no published port): nodes reach it at
-  # http://searxng:8080. Config (JSON output on, limiter off) lives in
-  # turnstone/deploy/searxng/settings.yml, mounted read-only. Commercial
-  # models use native provider search and never hit this; it serves
-  # local/vLLM models. Override the tag with SEARXNG_IMAGE_TAG in .env.
-  # -------------------------------------------------------------------
-  searxng:
-    image: searxng/searxng:${SEARXNG_IMAGE_TAG:-latest}
-    volumes:
-      - ./turnstone/deploy/searxng:/etc/searxng:ro
-      - searxng-cache:/var/cache/searxng # favicon + internal SQLite cache (survives restarts)
-    networks:
-      - turnstone-net
-    healthcheck:
-      test: ["CMD", "wget", "-q", "--spider", "http://localhost:8080/healthz"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-      start_period: 20s
+        required: false
    restart: unless-stopped

  # ===================================================================
-  # Server fleet — node-1 … node-10
+  # 10-node cluster (profile: cluster)
  #
-  # Each node registers itself in Postgres on boot (unique
-  # TURNSTONE_NODE_ID + TURNSTONE_ADVERTISE_URL) and the console
-  # discovers it automatically — no static node list anywhere.
+  # All nodes share the same PostgreSQL instance.
+  # Access via console at :8090.
  #
-  # node-1 carries the shared definition (&node / &node-env); node-2…10
-  # inherit it and override only their identity.
+  # Start:  docker compose --profile cluster up
  # ===================================================================
-  node-1: &node
+
+  # -- cluster servers ------------------------------------------------
+
+  server-1: &cluster-server
    image: turnstone:local
-    build:
-      context: .
-      dockerfile: Dockerfile
+    build: { context: ., dockerfile: Dockerfile }
+    profiles: [cluster]
    command:
      - sh
      - -c
@@ -262,30 +206,23 @@ services:
    volumes:
      - turnstone-data:/data
      - ${WORKSPACE_MOUNT:-workspace}:/workspace
-    environment: &node-env
-      TURNSTONE_JWT_SECRET: *jwt-secret
-      TURNSTONE_DB_BACKEND: *db-backend
-      TURNSTONE_DB_URL: *db-url
-      # Bootstrap LLM defaults — real backends are configured in the console UI.
+    environment: &cluster-server-env
      LLM_BASE_URL: ${LLM_BASE_URL:-http://host.docker.internal:8000/v1}
      OPENAI_API_KEY: ${OPENAI_API_KEY:-dummy}
-      # web_search backend. Defaults to the bundled searxng service; point at an
-      # external SearxNG by setting TURNSTONE_SEARXNG_URL in .env (empty disables).
-      TURNSTONE_SEARXNG_URL: ${TURNSTONE_SEARXNG_URL:-http://searxng:8080}
+      TAVILY_API_KEY: ${TAVILY_API_KEY:-}
+      SKIP_PERMISSIONS: ${SKIP_PERMISSIONS:-}
+      # Generate with: python -c "import secrets; print(secrets.token_hex(32))"
+      TURNSTONE_JWT_SECRET: ${TURNSTONE_JWT_SECRET:?Set TURNSTONE_JWT_SECRET in .env}
      MODEL: ${MODEL:-}
      MCP_CONFIG: ${MCP_CONFIG:-}
-      SKIP_PERMISSIONS: ${SKIP_PERMISSIONS:-}
+      TURNSTONE_DB_BACKEND: ${TURNSTONE_DB_BACKEND:-postgresql}
+      TURNSTONE_DB_URL: ${TURNSTONE_DB_URL:-postgresql+psycopg://${POSTGRES_USER:-turnstone}:${POSTGRES_PASSWORD:?}@postgres:5432/turnstone}
      TURNSTONE_NODE_ID: node-1
-      TURNSTONE_ADVERTISE_URL: http://node-1:8080
-    extra_hosts:
-      - "host.docker.internal:host-gateway"
-    networks:
-      - turnstone-net
+      TURNSTONE_ADVERTISE_URL: http://server-1:8080
+    extra_hosts: ["host.docker.internal:host-gateway"]
+    networks: [turnstone-net]
    depends_on:
-      postgres:
-        condition: service_healthy
-      searxng:
-        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
@@ -294,34 +231,34 @@ services:
      start_period: 60s
    deploy:
      resources:
-        limits:
-          memory: 4G
+        limits: { memory: 4G, cpus: '4' }
    restart: unless-stopped

-  node-2:
-    <<: *node
-    environment: { <<: *node-env, TURNSTONE_NODE_ID: node-2, TURNSTONE_ADVERTISE_URL: "http://node-2:8080" }
-  node-3:
-    <<: *node
-    environment: { <<: *node-env, TURNSTONE_NODE_ID: node-3, TURNSTONE_ADVERTISE_URL: "http://node-3:8080" }
-  node-4:
-    <<: *node
-    environment: { <<: *node-env, TURNSTONE_NODE_ID: node-4, TURNSTONE_ADVERTISE_URL: "http://node-4:8080" }
-  node-5:
-    <<: *node
-    environment: { <<: *node-env, TURNSTONE_NODE_ID: node-5, TURNSTONE_ADVERTISE_URL: "http://node-5:8080" }
-  node-6:
-    <<: *node
-    environment: { <<: *node-env, TURNSTONE_NODE_ID: node-6, TURNSTONE_ADVERTISE_URL: "http://node-6:8080" }
-  node-7:
-    <<: *node
-    environment: { <<: *node-env, TURNSTONE_NODE_ID: node-7, TURNSTONE_ADVERTISE_URL: "http://node-7:8080" }
-  node-8:
-    <<: *node
-    environment: { <<: *node-env, TURNSTONE_NODE_ID: node-8, TURNSTONE_ADVERTISE_URL: "http://node-8:8080" }
-  node-9:
-    <<: *node
-    environment: { <<: *node-env, TURNSTONE_NODE_ID: node-9, TURNSTONE_ADVERTISE_URL: "http://node-9:8080" }
-  node-10:
-    <<: *node
-    environment: { <<: *node-env, TURNSTONE_NODE_ID: node-10, TURNSTONE_ADVERTISE_URL: "http://node-10:8080" }
+  server-2:
+    <<: *cluster-server
+    environment: { <<: *cluster-server-env, TURNSTONE_NODE_ID: node-2, TURNSTONE_ADVERTISE_URL: "http://server-2:8080" }
+  server-3:
+    <<: *cluster-server
+    environment: { <<: *cluster-server-env, TURNSTONE_NODE_ID: node-3, TURNSTONE_ADVERTISE_URL: "http://server-3:8080" }
+  server-4:
+    <<: *cluster-server
+    environment: { <<: *cluster-server-env, TURNSTONE_NODE_ID: node-4, TURNSTONE_ADVERTISE_URL: "http://server-4:8080" }
+  server-5:
+    <<: *cluster-server
+    environment: { <<: *cluster-server-env, TURNSTONE_NODE_ID: node-5, TURNSTONE_ADVERTISE_URL: "http://server-5:8080" }
+  server-6:
+    <<: *cluster-server
+    environment: { <<: *cluster-server-env, TURNSTONE_NODE_ID: node-6, TURNSTONE_ADVERTISE_URL: "http://server-6:8080" }
+  server-7:
+    <<: *cluster-server
+    environment: { <<: *cluster-server-env, TURNSTONE_NODE_ID: node-7, TURNSTONE_ADVERTISE_URL: "http://server-7:8080" }
+  server-8:
+    <<: *cluster-server
+    environment: { <<: *cluster-server-env, TURNSTONE_NODE_ID: node-8, TURNSTONE_ADVERTISE_URL: "http://server-8:8080" }
+  server-9:
+    <<: *cluster-server
+    environment: { <<: *cluster-server-env, TURNSTONE_NODE_ID: node-9, TURNSTONE_ADVERTISE_URL: "http://server-9:8080" }
+  server-10:
+    <<: *cluster-server
+    environment: { <<: *cluster-server-env, TURNSTONE_NODE_ID: node-10, TURNSTONE_ADVERTISE_URL: "http://server-10:8080" }
+
@@ -0,0 +1,40 @@
+# Bare-metal overlay — expose PostgreSQL and let the console reach
+# a turnstone-server running outside Docker on the host machine.
+#
+# Requires TURNSTONE_HOST_IP set to the host's routable IP address.
+#
+# Usage:
+#   export TURNSTONE_HOST_IP="$(hostname -I | awk '{print $1}')"
+#   docker compose --profile production \
+#     -f compose.yaml -f deploy/docker-compose.bare-metal.yml up
+#
+# Then on the host:
+#   export TURNSTONE_JWT_SECRET="<same as .env>"
+#   export TURNSTONE_DB_BACKEND=postgresql
+#   export TURNSTONE_DB_URL="postgresql://turnstone:<pw>@localhost:5432/turnstone"
+#   export TURNSTONE_NODE_ID="bare-metal-1"
+#   export TURNSTONE_ADVERTISE_URL="http://${TURNSTONE_HOST_IP}:8080"
+#   python -m turnstone.server --host 0.0.0.0 --port 8080 \
+#     --base-url http://localhost:8000/v1 --api-key "$OPENAI_API_KEY"
+
+services:
+  postgres:
+    ports:
+      - "${POSTGRES_PORT:-5432}:5432"
+
+  console:
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    environment:
+      # Console needs to reach the bare-metal server on the host
+      TURNSTONE_SERVER_URL: "http://${TURNSTONE_HOST_IP}:${SERVER_PORT:-8080}"
+
+  channel:
+    ports:
+      - "${CHANNEL_PORT:-8091}:8091"
+    environment:
+      # Channel gateway advertises with host-routable IP so the
+      # bare-metal server can reach it for schedule notifications
+      TURNSTONE_CHANNEL_ADVERTISE_URL: "http://${TURNSTONE_HOST_IP}:${CHANNEL_PORT:-8091}"
+      # Channel needs to reach the bare-metal server on the host
+      TURNSTONE_SERVER_URL: "http://${TURNSTONE_HOST_IP}:${SERVER_PORT:-8080}"
@@ -1,8 +1,7 @@
-# TLS overlay — enables mTLS across the turnstone deployment.
+# TLS overlay — enables mTLS across the turnstone cluster.
 #
-# Layers on the production stack (it patches the `server`, `console`, and
-# `channel` services that file defines):
-#   docker compose -f turnstone/deploy/compose.yaml -f deploy/docker-compose.tls.yml up
+# Usage (requires base compose.yaml with production profile):
+#   docker compose -f compose.yaml -f deploy/docker-compose.tls.yml --profile production up
 #
 # The tls-init service bootstraps a CA and issues certs.
 # All turnstone services auto-provision their own certs via the
@@ -13,7 +12,7 @@ services:
  # Runs as root to create directories in the volume, then chowns
  # to turnstone:turnstone with restrictive perms (keys 0600).
  tls-init:
-    image: ghcr.io/turnstonelabs/turnstone:${TURNSTONE_IMAGE_TAG:-latest}
+    build: .
    user: root
    command:
      - sh
@@ -7,6 +7,6 @@ appVersion: "0.3.0"

 dependencies:
  - name: postgresql
-    version: ~18.7.0
+    version: ~18.6.0
    repository: https://charts.bitnami.com/bitnami
    condition: postgresql.enabled
@@ -103,18 +103,13 @@ network_policies:
      - path: /usr/bin/python3*
      - path: /usr/local/bin/python3*

-  # --- Web search (SearxNG) ---
-  # Turnstone talks only to its SearxNG instance over HTTP; SearxNG itself makes
-  # the outbound calls to search engines (and is NOT governed by this policy —
-  # it runs as a separate service). The host/port below is the bundled compose
-  # service name; if your SearxNG runs elsewhere, set it to match
-  # TURNSTONE_SEARXNG_URL.
+  # --- Web search fallback (Tavily) ---

-  searxng:
-    name: searxng-search
+  tavily_api:
+    name: tavily-search
    endpoints:
-      - host: searxng
-        port: 8080
+      - host: api.tavily.com
+        port: 443
    binaries:
      - path: /usr/bin/python3*
      - path: /usr/local/bin/python3*
@@ -2,69 +2,13 @@
 """Health check for turnstone containers.

 Usage: healthcheck.py <url>
-Exit 0 if the endpoint returns {"status": "ok"} or {"status": "degraded"},
-exit 1 otherwise. Uses only stdlib — no pip dependencies required.
-
-When the node serves mTLS (tls.enabled), a plain-HTTP probe is rejected at
-the socket, so on failure this script retries over HTTPS, presenting the
-node's own certificate as the client cert and pinning the cluster CA. The
-PEM files are the ones the server writes at boot under
-$TURNSTONE_TLS_PEM_DIR (default: <tmpdir>/turnstone-tls). The host is
-rewritten to "localhost" for the TLS attempt because the internal CA issues
-DNS SANs only — certificate verification rejects a literal-IP dial.
-
-When mTLS is disabled (the default), the plain probe succeeds and nothing
-here changes: the PEM directory is never consulted.
+Exit 0 if the endpoint returns {"status": "ok"}, exit 1 otherwise.
+Uses only stdlib — no pip dependencies required.
 """

 import json
-import os
-import ssl
 import sys
-import tempfile
 import urllib.request
-from pathlib import Path
-from urllib.parse import urlsplit, urlunsplit
-
-
-def _check(url: str, context: ssl.SSLContext | None = None) -> None:
-    """Probe one URL; raise if unreachable or the payload is unhealthy."""
-    req = urllib.request.Request(url, method="GET")
-    with urllib.request.urlopen(req, timeout=5, context=context) as resp:
-        data = json.loads(resp.read().decode())
-    if data.get("status") not in ("ok", "degraded"):
-        raise RuntimeError(f"unhealthy payload: {data}")
-
-
-def _pem_root() -> Path:
-    """PEM runtime root.
-
-    Must mirror turnstone.core.tls.tls_pem_runtime_dir — this script is
-    standalone stdlib and cannot import turnstone; a drift-guard test in
-    tests/test_docker_healthcheck.py pins the two together.
-    """
-    root_env = os.environ.get("TURNSTONE_TLS_PEM_DIR")
-    return Path(root_env) if root_env else Path(tempfile.gettempdir()) / "turnstone-tls"
-
-
-def _find_pem_dir() -> Path | None:
-    """Locate the newest complete PEM dir written by the server at boot."""
-    root = _pem_root()
-    candidates = [
-        d
-        for d in root.glob("lacme-pem-*")
-        if all((d / name).is_file() for name in ("fullchain.pem", "key.pem", "ca.pem"))
-    ]
-    if not candidates:
-        return None
-    return max(candidates, key=lambda d: d.stat().st_mtime)
-
-
-def _tls_url(url: str) -> str:
-    """Rewrite scheme to https and host to localhost, keeping port and path."""
-    parts = urlsplit(url)
-    netloc = f"localhost:{parts.port}" if parts.port else "localhost"
-    return urlunsplit(("https", netloc, parts.path, parts.query, parts.fragment))


 def main() -> None:
@@ -74,24 +18,16 @@ def main() -> None:

    url = sys.argv[1]
    try:
-        _check(url)
-        sys.exit(0)
-    except Exception as plain_exc:
-        pem_dir = _find_pem_dir()
-        if pem_dir is None:
-            print(f"Health check failed: {plain_exc}", file=sys.stderr)
-            sys.exit(1)
-        try:
-            context = ssl.create_default_context(cafile=str(pem_dir / "ca.pem"))
-            context.load_cert_chain(str(pem_dir / "fullchain.pem"), str(pem_dir / "key.pem"))
-            _check(_tls_url(url), context=context)
-            sys.exit(0)
-        except Exception as tls_exc:
-            print(
-                f"Health check failed: plain: {plain_exc}; mtls: {tls_exc}",
-                file=sys.stderr,
-            )
+        req = urllib.request.Request(url, method="GET")
+        with urllib.request.urlopen(req, timeout=5) as resp:
+            data = json.loads(resp.read().decode())
+            if data.get("status") in ("ok", "degraded"):
+                sys.exit(0)
+            print(f"Unhealthy: {data}", file=sys.stderr)
            sys.exit(1)
+    except Exception as exc:
+        print(f"Health check failed: {exc}", file=sys.stderr)
+        sys.exit(1)


 if __name__ == "__main__":
@@ -281,7 +281,6 @@ Each message in the `messages` array has:
 | `role`       | string            | `"user"`, `"assistant"`, or `"tool"`          |
 | `content`    | string or null    | Text content of the message                   |
 | `tool_calls` | array or null     | Present only on assistant messages with calls  |
-| `reasoning`  | string (optional) | Concatenated reasoning / chain-of-thought text on assistant turns whose `provider_data` carried reasoning-bearing blocks (Anthropic `thinking`, OpenAI Responses `reasoning`, or synthetic `reasoning_text` from local-model servers). Present only when the active model's `surface_persisted_reasoning` flag is True. |

 Each entry in `tool_calls`:

@@ -326,44 +325,6 @@ finalize any in-progress assistant message.
 {"type": "stream_end"}
 ```

-**`state_change`** -- the worker thread transitioned to a new state. Drives
-the client's busy-mode (composer in send vs. stop, spinner indicators,
-auto-focus on idle). Sent live during normal operation AND on every fresh
-SSE subscribe (so a mid-stream page refresh restores the correct composer
-state without waiting for the next live transition).
-
-```json
-{"type": "state_change", "state": "running"}
-```
-
-| Field    | Type   | Description                                                          |
-|----------|--------|----------------------------------------------------------------------|
-| `state`  | string | One of `"running"`, `"thinking"`, `"attention"`, `"idle"`, `"error"` |
-
-**`in_progress_snapshot`** -- one-shot replay of the in-progress turn's
-content + reasoning text-so-far when this client connects mid-stream.
-Lets a refreshing browser tab restore partial assistant text immediately
-instead of waiting for the response to complete. Yielded once after the
-kind-specific replay phase (history + pending), only when at least one
-of `content` / `reasoning` is non-empty. Both halves render into the same
-assistant bubble the live `content` / `reasoning` events would target;
-clients should treat the snapshot as idempotent (skip overwrite if the
-current local buffer is already a superset prefix — covers EventSource
-auto-reconnect re-replays).
-
-```json
-{
-  "type": "in_progress_snapshot",
-  "content": "Here is the answer so far: it depends on ",
-  "reasoning": "The user is asking about a comparison; let me think about..."
-}
-```
-
-| Field        | Type   | Description                                                |
-|--------------|--------|------------------------------------------------------------|
-| `content`    | string | Joined assistant content text accumulated this turn        |
-| `reasoning`  | string | Joined reasoning / chain-of-thought text accumulated       |
-
 **`tool_info`** -- one or more tool calls that were auto-approved (no user
 action required).

@@ -455,6 +416,13 @@ Each item in `items` (shared by `tool_info` and `approve_request`):
 | `cache_creation_tokens`  | int    | Tokens written to prompt cache (Anthropic)           |
 | `cache_read_tokens`      | int    | Tokens served from prompt cache (Anthropic + OpenAI) |

+**`plan_review`** -- the model is proposing a plan and wants feedback. The
+client must respond via `POST /v1/api/plan`.
+
+```json
+{"type": "plan_review", "content": "Step 1: ...\nStep 2: ..."}
+```
+
 **`info`** -- an informational message (e.g. command output).

 ```json
@@ -554,13 +522,7 @@ Each SSE connection to a workstream receives its own delivery queue.  Events
 produced by the worker thread are fanned out to all registered listener queues,
 so multiple consumers (browser, console proxy, SDK) can connect
 simultaneously and each receives every event.  On reconnect the client receives
-the kind-specific replay (`connected` + `status` + `history` + pending
-approval / plan for interactive; `connected` + `status` + pending for coord)
-followed by a `state_change` carrying the current worker state and an
-optional `in_progress_snapshot` carrying any partial content / reasoning
-buffered for the in-progress turn — so a mid-stream refresh restores both
-the busy-mode UI and the partial assistant text without waiting for the
-response to complete.
+a full history replay, so no catch-up mechanism is needed.

 ---

@@ -772,6 +734,36 @@ automatically approved without prompting.

 ---

+### `POST /v1/api/plan`
+
+Responds to a plan review dialog. The SSE stream must have previously sent a
+`plan_review` event for the given workstream.
+
+**Request body:**
+
+```json
+{"feedback": "", "ws_id": "abc123"}
+```
+
+| Field      | Type   | Required | Description                                             |
+|------------|--------|----------|---------------------------------------------------------|
+| `feedback` | string | yes      | Feedback text; empty string means approval              |
+| `ws_id`    | string | yes      | Target workstream ID                                    |
+
+To approve the plan, send an empty string for `feedback`. To reject or request
+changes, send a non-empty feedback string (e.g. `"reject"` or specific
+revision instructions).
+
+**Response:**
+
+```json
+{"status": "ok"}
+```
+
+**Error:** `404` with `{"error": "Unknown workstream"}` if `ws_id` is invalid.
+
+---
+
 ### `POST /v1/api/command`

 Executes a slash command in the given workstream.
@@ -3,8 +3,8 @@
 Turnstone is an AI orchestration platform with tool use, parallel workstreams, and persistent
 memory. It connects to any OpenAI-compatible API (local vLLM, OpenAI, etc.) or
 Anthropic's native Messages API via pluggable provider adapters, and gives the
-model 16 built-in tools plus external tools via MCP (Model Context Protocol) for
-reading, writing, searching, and executing code.
+model 19 built-in tools plus external tools via MCP (Model Context Protocol) for
+reading, writing, searching, planning, and executing code.

 The core design principle is a **UI-agnostic engine with pluggable frontends**.
 The engine (`ChatSession`) drives the conversation loop -- streaming, tool
@@ -61,6 +61,7 @@ turnstone/
    ratelimit.py      Per-IP token-bucket rate limiter (RateLimiter, TokenBucket)
    edit.py           File edit utilities (find_occurrences, pick_nearest)
    safety.py         Command safety validation (blocked patterns, sanitization)
+    sandbox.py        Math code sandboxing (AST validation, subprocess execution)
    web.py            Web utilities (HTML stripping, SSRF prevention)
  api/
    schemas.py        Shared Pydantic v2 models (auth, errors, WorkstreamState)
@@ -90,7 +91,7 @@ turnstone/
    discord/          Discord adapter (bot, cog, views, streaming, config)
    slack/            Slack adapter (Socket Mode bot, DM routing, approval buttons)
  shared_static/      Shared design system (base.css, auth.js, theme.js, toast.js, utils.js, kb.js)
-    katex-0.17.0/    Vendored KaTeX math rendering library (MIT, woff2 fonts)
+    katex-0.16.45/    Vendored KaTeX math rendering library (MIT, woff2 fonts)
  ui/
    colors.py         ANSI color constants with NO_COLOR support
    markdown.py       Streaming terminal markdown renderer (line-buffered)
@@ -101,7 +102,7 @@ turnstone/
      renderer.js     Markdown + LaTeX renderer (tables, nested lists, blockquotes, KaTeX math)
      app.js          Split-pane UI (Pane class, binary layout tree, SSE, tool approval)
  tools/
-    *.json            16 tool schemas (OpenAI function-calling format + turnstone metadata)
+    *.json            19 tool schemas (OpenAI function-calling format + turnstone metadata)
 ```

 Both UIs share a common design system extracted into `turnstone/shared_static/`: design tokens, login overlay, toast notifications, theme toggle, keyboard shortcuts, and utility functions. Each UI imports `base.css` and the shared JS modules at `/shared/`, then adds only page-specific code at `/static/`.
@@ -189,6 +190,7 @@ Phase 3: EXECUTE (parallel)
    (cancel_event also checked per line — kills process group on cancel)
  Final output (stdout + stderr) delivered via ui.on_tool_result(call_id, name, output)
  call_id links tool_info items → streaming chunks → final result
+  For plan tool: post-execution gate via ui.on_plan_review()
 ```

 ### State Transitions
@@ -207,7 +209,7 @@ The engine emits state changes via `_emit_state()` which calls
  "running"   --->  tool execution
      |
      v
-  "attention"  --->  waiting for user approval
+  "attention"  --->  waiting for user approval / plan review
      |
      v
  "running"   --->  executing approved tools
@@ -229,13 +231,11 @@ The engine emits state changes via `_emit_state()` which calls

 > See also: [Core Engine Classes diagram](diagrams/png/03-core-engine-classes.png)

-Defined in `turnstone.core.session.SessionUI` as a `typing.Protocol` with 15
+Defined in `turnstone.core.session.SessionUI` as a `typing.Protocol` with 14
 methods. Every frontend must implement all of them.

 ```python
 class SessionUI(Protocol):
-    def on_turn_start(self) -> None: ...
-    def on_turn_committed(self) -> None: ...
    def on_thinking_start(self) -> None: ...
    def on_thinking_stop(self) -> None: ...
    def on_reasoning_token(self, text: str) -> None: ...
@@ -245,20 +245,13 @@ class SessionUI(Protocol):
    def on_tool_result(self, call_id: str, name: str, output: str, *, is_error: bool = False) -> None: ...
    def on_tool_output_chunk(self, call_id: str, chunk: str) -> None: ...
    def on_status(self, usage: dict, context_window: int, effort: str) -> None: ...
+    def on_plan_review(self, content: str) -> str: ...
    def on_info(self, message: str) -> None: ...
    def on_error(self, message: str) -> None: ...
    def on_state_change(self, state: str) -> None: ...
    def on_rename(self, name: str) -> None: ...  # propagate alias to tab/UI label
 ```

-`on_turn_start` fires at the top of each iteration of the send-loop;
-`on_turn_committed` fires immediately after `messages.append(assistant_msg)`.
-`SessionUIBase` uses both to reset the per-turn inflight buffers
-(`_ws_inflight_content` / `_ws_inflight_reasoning` / `_ws_inflight_seq`)
-that fuel the SSE refresh-resume `in_progress_snapshot` event — see
-the per-workstream events stream in
-[`docs/api-reference.md`](api-reference.md#get-v1apiworkstreamsws_idevents).
-
 `on_rename` is called by the `/name` command (on success) and after a successful `/resume` (if the resumed session has an alias or title). `WebUI.on_rename` broadcasts a `ws_rename` event on the global SSE channel and updates the in-memory `Workstream.name`; `TerminalUI.on_rename` is a no-op.

 ### Three Implementations
@@ -266,7 +259,7 @@ the per-workstream events stream in
 | Class | Module | Notes |
 |-------|--------|-------|
 | `TerminalUI` | `turnstone.cli` | ANSI colors, `MarkdownRenderer`, `Spinner`, readline-based `input()` for approval |
-| `WebUI` | `turnstone.server` | SSE event queue per workstream + global broadcast, `threading.Event` for blocking on approval. `on_state_change` sends to both per-workstream and global SSE (the browser UI uses per-workstream `state_change` events to manage busy/idle transitions; `stream_end` only finalizes markdown rendering). |
+| `WebUI` | `turnstone.server` | SSE event queue per workstream + global broadcast, `threading.Event` for blocking on approval/plan. `on_state_change` sends to both per-workstream and global SSE (the browser UI uses per-workstream `state_change` events to manage busy/idle transitions; `stream_end` only finalizes markdown rendering). |
 | `NullUI` | `turnstone.eval` | Discards all output; `approve_tools` always returns `(True, None)` |

 ### WorkstreamTerminalUI
@@ -278,9 +271,10 @@ awareness:
  are appended to `_output_buffer` instead of written to stdout. When the user
  switches to this workstream, `flush_buffer()` replays them.

- **Approval blocking**: `approve_tools()` calls `_fg_event.wait()` when in
-  background, blocking the worker thread until the workstream is foregrounded.
-  This ensures the user sees the approval prompt in the correct context.
+- **Approval blocking**: `approve_tools()` and `on_plan_review()` call
+  `_fg_event.wait()` when in background, blocking the worker thread until the
+  workstream is foregrounded. This ensures the user sees the approval prompt
+  in the correct context.

 - **Foreground/background toggle**: `set_foreground(bool)` sets or clears
  `_fg_event` (a `threading.Event`). The manager calls this during `/ws <N>`
@@ -417,6 +411,7 @@ turnstone metadata keys:

 | Metadata Key | Type | Meaning |
 |-------------|------|---------|
+| `agent` | `bool` | Include this tool when running as a plan/task sub-agent |
 | `task_agent` | `bool` | Include this tool when running as a task sub-agent |
 | `auto_approve` | `bool` | Tool is read-only; skip user approval |
 | `primary_key` | `str` | Fallback argument name for bare-string JSON recovery |
@@ -436,6 +431,7 @@ Example (`read_file.json`):
    },
    "required": ["path"]
  },
+  "agent": true,
  "task_agent": true,
  "auto_approve": true,
  "primary_key": "path"
@@ -446,17 +442,19 @@ At import time, `turnstone.core.tools._load_tools()` strips the metadata keys
 from each schema and builds:

 - `TOOLS` -- list of `{"type": "function", "function": {...}}` dicts for the API
+- `AGENT_TOOLS` -- subset with `agent: true`
 - `TASK_AGENT_TOOLS` -- subset with `task_agent: true`
- `TASK_AUTO_TOOLS` -- set of tool names with `auto_approve: true`
+- `AGENT_AUTO_TOOLS` / `TASK_AUTO_TOOLS` -- sets of tool names with `auto_approve: true`
 - `PRIMARY_KEY_MAP` -- `{name: primary_key}` for JSON fallback recovery
 - `merge_mcp_tools(builtin, mcp_tools)` -- merges built-in + MCP tools at session init

-### 16 Tools by Category
+### 19 Tools by Category

 **Read-only (auto-approve)**:
 - `read_file` -- read file contents with optional offset/limit
 - `diff_file` -- show diff between two files / versions
 - `search` -- ripgrep-based codebase search
+- `man` -- read man pages
 - `recall` -- search conversation history
 - `read_resource` -- read an MCP resource by URI

@@ -464,21 +462,23 @@ from each schema and builds:
 - `bash` -- execute shell commands (with safety checks via `turnstone.core.safety`)
 - `write_file` -- create or overwrite a file
 - `edit_file` -- string replacement in an existing file (requires prior `read_file`)
+- `math` -- execute Python in sandboxed subprocess (via `turnstone.core.sandbox`)
 - `web_fetch` -- fetch a URL (with SSRF protection via `turnstone.core.web`)
- `web_search` -- search the web (provider-native for Anthropic/OpenAI, self-hosted SearxNG fallback for local models)
+- `web_search` -- search the web (provider-native for Anthropic/OpenAI, Tavily fallback for local models)
 - `notify` -- send a user-facing notification (Discord/Slack, optional reply routing)
 - `watch` -- schedule a recurring poll with condition DSL

 **Agent (delegated sub-sessions)**:
 - `task_agent` -- delegate to a sub-agent with full tool access (`TASK_AGENT_TOOLS`)
+- `plan_agent` -- explore codebase and write a structured plan (`AGENT_TOOLS`)

 **Memory / skills / prompts**:
 - `memory` -- save, search, delete, or list memories (typed and scoped)
 - `skill` -- invoke a skill (governed, versioned procedure)
 - `use_prompt` -- fetch and apply a prompt template

-The tool name uses the `_agent` suffix — bare `task` collides with
-chat-template channels on some local models.
+Tool names are `plan_agent` / `task_agent` (not `plan` / `task`); bare words
+collide with chat-template channels on some local models.

 ### Prepare / Execute Pattern

@@ -497,11 +497,17 @@ separation allows the UI to show previews before any side effects occur.

 ### Agent Tools

-`task_agent` invokes `_run_agent()`, which runs a multi-turn loop with a
-subset of tools and its own system prompt. The sub-agent runs independently,
-then returns the final content as the tool result.
+`task_agent` and `plan_agent` invoke `_run_agent()`, which runs a multi-turn
+loop with a subset of tools and its own system prompt. The sub-agent runs
+independently, then returns the final content as the tool result.

 - **task_agent**: uses `self._task_tools` (`TASK_AGENT_TOOLS` + MCP tools)
+- **plan_agent**: uses `self._agent_tools` (`AGENT_TOOLS` + MCP tools). Writes output
+  to `.plan-<ws_id>.md` — unique per `ChatSession` so concurrent workstreams
+  don't collide. On repeat invocations the prior `plan_agent` tool call and its result
+  are forwarded from `self.messages` so the agent refines the existing plan rather
+  than starting over. Planning instructions are injected as a developer message
+  prepended to the agent's conversation.
 - **Turn limit**: controlled by `agent_max_turns` (default: `-1`, unlimited).
  When a limit is set and reached, the agent is forced to synthesize a final
  response without tools. When unlimited, the loop only exits when the model
@@ -540,16 +546,18 @@ adds, removes, or reconnects servers as needed.
 6. `_exec_mcp_tool()` calls `call_tool_sync()` which dispatches to the async loop
   via `asyncio.run_coroutine_threadsafe()`

-**Tool refresh:** Two mechanisms keep tools up-to-date without restart:
+**Tool refresh:** Three mechanisms keep tools up-to-date without restart:
 - **Push:** Servers declaring `tools.listChanged` send `ToolListChangedNotification`;
  the registered `message_handler` triggers immediate single-server refresh.
+- **Periodic:** Servers without push support are polled on a staggered interval
+  (default 4 h, configurable via `[mcp] refresh_interval` or `--mcp-refresh-interval`).
 - **Manual:** `/mcp refresh [server]` calls `refresh_sync()` for on-demand refresh
  (also attempts reconnection for disconnected servers).

 When tools change, `_rebuild_tools()` creates new `_tools`/`_tool_map` objects
 (copy-on-write for thread safety) and notifies listener callbacks. Each `ChatSession`
-rebuilds its `_tools` and `_task_tools` lists and reconstructs `ToolSearchManager`
-(preserving expanded tools).
+rebuilds its merged tool lists and reconstructs `ToolSearchManager` (preserving
+expanded tools).

 **Tool naming:** `mcp__{server}__{tool}` — double underscore delimiter, validated
 at connection time (server names with `__` are rejected).
@@ -564,11 +572,10 @@ from a healthy connection do not trip the breaker. When the cooldown expires
 (`call_tool_sync`, `read_resource_sync`, `get_prompt_sync`, `refresh_sync`)
 cancel orphaned futures on timeout to prevent coroutine accumulation on the
 background event loop. Push notification refreshes are debounced (5 s per
-server) to protect against notification storms. Operators can force a
-catalog refresh or full reconnect from the admin panel; reconnects clear
-the circuit breaker and run a fresh handshake. Transport stream references
-are pre-closed before stack teardown to work around the MCP SDK's anyio
-cancel-scope CPU busy-loop (SDK #2147).
+server) to protect against notification storms. The periodic refresh loop
+attempts reconnection for disconnected servers with exponential backoff
+(60 s–1 h). Transport stream references are pre-closed before stack teardown to
+work around the MCP SDK's anyio cancel-scope CPU busy-loop (SDK #2147).

 **Error isolation:** Per-server connection/refresh failures are caught and logged; other
 servers are unaffected. Tool execution errors return error strings to the LLM
@@ -613,15 +620,14 @@ LLMProvider (protocol)
 | `get_capabilities()` | Per-model flags (`ModelCapabilities`) |
 | `convert_tools()` | Translate OpenAI tool schemas to provider format |
 | `retryable_error_names` | Exception class names that trigger retry |
-| `extract_reasoning_text()` | Walk stored `provider_blocks`, return concatenated reasoning text for UI rehydration (per-provider block-type knowledge: Anthropic `thinking`, OpenAI Responses `reasoning`, OpenAI Chat synthetic `reasoning_text`) |

 **Normalized data types:**

 | Type | Fields |
 |------|--------|
-| `StreamChunk` | `content_delta`, `reasoning_delta`, `tool_call_deltas`, `info_delta`, `usage`, `finish_reason`, `provider_blocks` |
-| `CompletionResult` | `content`, `tool_calls`, `finish_reason`, `usage`, `provider_blocks` |
-| `ModelCapabilities` | `context_window`, `max_output_tokens`, `supports_temperature`, `token_param`, `thinking_mode`, `supports_effort`, `supports_web_search`, `supports_tool_search`, `supports_vision`, `supports_reasoning_replay` |
+| `StreamChunk` | `content_delta`, `reasoning_delta`, `tool_call_deltas`, `info_delta`, `usage`, `finish_reason` |
+| `CompletionResult` | `content`, `tool_calls`, `finish_reason`, `usage` |
+| `ModelCapabilities` | `context_window`, `max_output_tokens`, `supports_temperature`, `token_param`, `thinking_mode`, `supports_effort`, `supports_web_search`, `supports_tool_search`, `supports_vision` |
 | `UsageInfo` | `prompt_tokens`, `completion_tokens`, `total_tokens`, `cache_creation_tokens`, `cache_read_tokens` |

 **OpenAIProvider** (`_openai.py`): passes messages through unchanged (they are
@@ -634,7 +640,7 @@ annotations are formatted as footnotes. Extended prompt cache retention
 (`prompt_cache_retention: "24h"`) is enabled for GPT-5.x models at no
 additional cost. Cached token counts are extracted from
 `usage.prompt_tokens_details.cached_tokens`. Unknown models (local servers) get
-permissive defaults with `supports_vision=False` and use SearxNG for web search.
+permissive defaults with `supports_vision=False` and use Tavily for web search.

 **AnthropicProvider** (`_anthropic.py`): converts OpenAI-format messages to
 Anthropic content blocks, maps `system`/`developer` roles to the `system`
@@ -652,8 +658,9 @@ display). Automatic prompt caching is enabled via top-level `cache_control:
 cacheable block and advances it as conversations grow (90% input cost
 reduction on cache hits, 1.25x write on first turn). Cache metrics
 (`cache_creation_input_tokens`, `cache_read_input_tokens`) are extracted from
-both streaming and non-streaming responses. The `anthropic` SDK is a core
-dependency — the Anthropic provider is first-class alongside OpenAI.
+both streaming and non-streaming responses. The `anthropic` SDK is imported
+lazily so it remains an optional dependency (`pip install
+turnstone[anthropic]`).

 **GoogleProvider** (`_google.py`): extends `OpenAIChatCompletionsProvider` for
 the Gemini `/v1beta/openai/` endpoint. Uses a single default
@@ -702,41 +709,12 @@ agent_model = "claude"

 Each `[models.*]` entry produces a `ModelConfig` with a `provider` field
 (default: `"openai"`). Supported values: `"openai"`, `"anthropic"`, `"google"`,
-`"openai-compatible"`, and `"anthropic-compatible"`.
+and `"openai-compatible"`.

 **Per-model sampling overrides:** Each model can specify `temperature`,
 `max_tokens`, and `reasoning_effort` to override the global defaults from
 ConfigStore. When unset (`NULL`), the global default is used.

-**Per-model reasoning persistence:** Two booleans on `model_definitions`
-(migration 052) control how reasoning text round-trips:
-
-* `surface_persisted_reasoning` (default `True`) — gates whether stored
-  reasoning text is surfaced on `/history` payloads for UI rehydration.
-  **Storage of reasoning bytes happens regardless of this flag** — they
-  ride in `provider_data` independently. Phase-1 admin UI label "Surface
-  persisted reasoning."
-* `replay_reasoning_to_model` (default `False`) — gates whether stored
-  reasoning blocks are sent back to the provider on subsequent turns.
-  Capability-gated: `ModelCapabilities.supports_reasoning_replay` must
-  also be `True` for the wire path to actually replay (canonical OpenAI
-  gpt-5*/o-series and Anthropic Claude entries set it; unknown / local-
-  server models default to `False`).
-
-Three reasoning paths are recognised:
-
-| Path | Provider | Capture | Persist | Replay |
-|------|----------|---------|---------|--------|
-| 1 | Anthropic Messages API | `thinking_delta` | `provider_blocks` (`type="thinking"`) | Verbatim via `_provider_content` |
-| 2 | OpenAI Responses (gpt-5*, o-series) | `response.reasoning_text.delta` events | `provider_blocks` (`type="reasoning"`) — only when `include=["reasoning.encrypted_content"]` | `ResponseReasoningItemParam` input items |
-| 3 | OpenAI Chat Completions (vLLM, llama.cpp, Gemini-compat) | `delta.reasoning_content` Pydantic extras | Synthetic `{type: "reasoning_text", text, source}` block stamped at end-of-stream | None — no API surface for replay on Chat Completions |
-
-Cross-provider safety is enforced by `ANTHROPIC_VALID_BLOCK_TYPES` (a
-shape filter in `_anthropic.py:_convert_messages`): foreign blocks
-(OpenAI `reasoning`, synthetic `reasoning_text`) fall through to the
-text+tool_calls rebuild path rather than reaching Anthropic's input
-boundary as malformed content.
-
 ```toml
 [models.local]
 base_url = "http://localhost:8000/v1"
@@ -765,63 +743,6 @@ model = "qwen-3.5-vl"
 supports_vision = true
 ```

-**Anthropic-compatible local servers (vLLM `/v1/messages`):** the
-`"anthropic-compatible"` provider drives local servers that expose
-Anthropic's Messages API for arbitrary checkpoints — vLLM's
-`/v1/messages` endpoint, which requires a release with thinking-block
-support in the Anthropic endpoint (post-2026-02-28; verified against
-v0.22.1rc1). The lane reuses `AnthropicProvider` in compat mode: same
-wire translation as the real Anthropic lane, but every model resolves to
-the `_ANTHROPIC_COMPAT_DEFAULT` capabilities (200K context, 64K output,
-`token_param=max_tokens`, `thinking_mode=none`, no native
-web_search/tool_search, no vision) — the static Claude table never
-applies to local checkpoints. `base_url` is required — the server root
-WITHOUT `/v1` (the Anthropic SDK appends `/v1/messages`); a trailing
-`/v1` pasted out of openai-compatible habit is stripped automatically,
-and an empty value fails at client construction rather than falling
-back to the commercial endpoint. Set a
-placeholder `api_key` (e.g. `"dummy"`) for unauthenticated servers. Tool calling
-needs the server started with `--enable-auto-tool-choice
--tool-call-parser <family>` plus the matching reasoning parser.
-Per-model capability overrides opt in to what the checkpoint actually
-supports:
-
-```toml
-[models.vllm-claude]
-provider = "anthropic-compatible"
-base_url = "http://localhost:8000"   # no /v1 — the SDK appends /v1/messages
-api_key = "dummy"
-model = "deepseek-ai/DeepSeek-V4-Flash"
-
-[models.vllm-claude.capabilities]
-supports_vision = true                    # multimodal checkpoints only
-supports_mid_conversation_system = true   # template-dependent
-context_window = 131072
-```
-
-The reasoning toggle does NOT use Anthropic's `thinking` request param.
-Toggle it through the chat template instead: set `{"chat_template_kwargs":
-{"thinking": false}}` as extra body params in the admin Models
-server-compat section (for this provider the section shows only the
-extra-body field — server type, API surface, and thinking mode are
-openai-compatible-only knobs); the provider forwards it via the SDK's
-`extra_body`.
-
-Verified quirks of vLLM's Anthropic endpoint:
-
-* The `thinking` request param is silently dropped — use
-  `chat_template_kwargs` (above) to control reasoning.
-* `stop_sequences` cut the raw stream wherever the text appears —
-  including inside thinking — and report `end_turn` with
-  `stop_sequence=None`. Turnstone does not send stop sequences from
-  this provider.
-* No cache telemetry: `usage` carries input/output token counts only
-  (no `cache_creation_input_tokens` / `cache_read_input_tokens`).
-* Images require a multimodal checkpoint — text-only models return a
-  500 on image blocks, so `supports_vision` stays opt-in per model.
-* Mid-conversation `role: "system"` turns are template-dependent —
-  opt in per model via `supports_mid_conversation_system`.
-
 **Database model definitions:** On server entry points, models can also be
 defined in the `model_definitions` table (admin Models tab). DB models support
 the same per-model sampling overrides. Config.toml models override DB models
@@ -843,7 +764,7 @@ with the same alias in-memory (the DB rows are never modified).
   parameters
 6. `_create_stream_with_retry()` tries the primary model, then each fallback
   alias in order if the primary is unreachable
-7. `_run_agent()` resolves `registry.agent_model` (if set) for task
+7. `_run_agent()` resolves `registry.agent_model` (if set) for plan/task
   sub-agents, allowing a cheaper model for autonomous loops

 **Per-workstream selection:** `POST /v1/api/workstreams/new` accepts an optional
@@ -852,7 +773,7 @@ which can override the model before workstream creation.

 ### Tool Output Truncation

-Tool execution results (bash, read_file, search) are truncated by
+Tool execution results (bash, read_file, search, math, man) are truncated by
 `_truncate_output()` when they exceed `tool_truncation` characters. Truncation
 preserves the first half and last half of the output, with a message in
 between:
@@ -1098,12 +1019,11 @@ warns if the summary was truncated.
  unhandled promise rejections
 - **Pending approval across tab switches**: `WebUI._pending_approval` stores
  the `approve_request` event payload while the session is blocked waiting
-  for user response. On tab switch / reconnect the pane reloads history via
-  REST `GET /history` and then reconnects SSE; the live approval event is
-  re-injected. The server-side `project_history_messages` projection marks
-  the trailing orphan tool-call turn `"pending": true` so `replayHistory`
-  skips the false `✓ approved` badge; the live approval UI is rendered by
-  the re-injected event instead.
+  for user response. On SSE reconnect (e.g., switching back to the tab),
+  the event is re-injected after history replay. `_build_history` marks the
+  pending tool call as `"pending": true` so `replayHistory` skips the
+  false `✓ approved` badge; the live approval UI is rendered by the
+  re-injected event instead.
 - **Browser history integration**: `history.pushState` is called in
  `switchTab()` with `{turnstone: 'workstream', wsId}`. The initial state is
  seeded with `history.replaceState({turnstone: 'dashboard'})` on load. The
@@ -1280,6 +1200,7 @@ Starlette ASGI app (served by uvicorn)
  +-- Async request handlers (all under /v1/ prefix)
  |     POST /v1/api/workstreams/{ws_id}/send    -> starts worker thread per workstream
  |     POST /v1/api/workstreams/{ws_id}/approve -> unblocks WebUI._approval_event
+  |     POST /v1/api/plan                        -> unblocks WebUI._plan_event
  |     POST /v1/api/workstreams/new             -> creates workstream + worker
  |     GET  /v1/api/workstreams/{ws_id}/events  -> SSE via EventSourceResponse (per workstream)
  |     GET  /v1/api/events/global               -> SSE via EventSourceResponse (fan-out)
@@ -1289,7 +1210,7 @@ Starlette ASGI app (served by uvicorn)
  |
  +-- Worker thread per workstream (daemon)
  |     Runs session.send() synchronously -- ChatSession is fully blocking
-  |     Blocks on WebUI._approval_event (threading.Event)
+  |     Blocks on WebUI._approval_event / _plan_event (threading.Event)
  |
  +-- Background daemon threads
        Global SSE fan-out: reads global_queue, copies to per-client queues
@@ -1313,7 +1234,7 @@ registry).

 Each workstream's `WebUI` has:
 - `_listeners` (per-client SSE queues, fan-out on `_enqueue()`)
- `_approval_event` (`threading.Event` for blocking)
+- `_approval_event` / `_plan_event` (`threading.Event` for blocking)
 - `_global_queue` (class variable, shared, for state broadcasts)

 The SSE handlers bridge these sync queues to async via
@@ -1569,7 +1490,8 @@ implemented in `turnstone/core/judge.py`:
 The judge is session-scoped (`IntentJudge`), lazy-initialized on first
 approval, and configured via the `[judge]` config section or `--judge` CLI
 flags. By default it uses self-consistency (same model), but supports
-cross-model and cross-provider configurations. Task sub-agents are exempt. All verdicts are persisted to the `intent_verdicts` table
+cross-model and cross-provider configurations. Sub-agents (plan, task)
+are exempt. All verdicts are persisted to the `intent_verdicts` table
 (migration 012) with the user's final decision, enabling future calibration.
 The console exposes `GET /v1/api/admin/verdicts` for audit queries
 (requires `admin.judge` permission).
@@ -110,18 +110,11 @@ owns it; the node is just currently unreachable.

 ### Example — `spawn_batch`

-This is the coordinator-tool result shape (the JSON the LLM receives),
-not an HTTP API response — the table above keys it under "model tool"
-to distinguish it from the `/v1/api/...` endpoints in the same table.
-The underlying HTTP spawn endpoint still returns `ws_id`; the tool
-result re-keys it to `child_ws_id` to defuse a coordinator-LLM recency
-bias (see `docs/coordinator-skills.md`).
-
 ```json
 {
  "results": {
-    "0": {"child_ws_id": "d4e5f6...", "name": "csrf-audit", "node_id": "gpu-3"},
-    "2": {"child_ws_id": "f1a2b3...", "name": "xss-audit",  "node_id": "gpu-1"}
+    "0": {"ws_id": "d4e5f6...", "name": "csrf-audit", "node_id": "gpu-3"},
+    "2": {"ws_id": "f1a2b3...", "name": "xss-audit",  "node_id": "gpu-1"}
  },
  "denied": [
    {"idx": 1, "reason": "skill not found: nonexistent-skill"}
@@ -99,10 +99,10 @@ TURNSTONE_DISCORD_GUILD=123456789
 Then start the stack:

 ```bash
-docker compose up
+docker compose --profile production up
 ```

-The `channel` gateway runs by default; the Discord adapter activates once
+The `channel` service starts automatically when
 `TURNSTONE_DISCORD_TOKEN` is set.

 ### 3. Link User Accounts
@@ -179,6 +179,7 @@ both and the gateway hosts both adapters in one process.
  see starts a per-user channel session.
 - Tool approvals render as Slack **Block Kit** buttons; only the user
  who owns the workstream can approve/reject.
+- Plan reviews render as a modal with approve / request-changes actions.
 - Notifications and reply routing work identically to Discord.
 - Session recovery: persisted channel routes are re-subscribed when the
  bot restarts, so existing Slack conversations keep flowing.
@@ -234,6 +235,15 @@ config, the bot auto-responds with approval and posts a
 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 to the server via HTTP
+
 ---

 ## Configuration Reference
@@ -421,9 +431,9 @@ message with a `ws_id` so that user replies can be routed back to the
 originating workstream. Adapters must track the mapping from outgoing
 message ID to `(ws_id, target_user_id)` and handle DM replies.

-Platform-specific concerns — approval prompts, message edits, thread
-creation — live inside the adapter implementation and are not part of
-the protocol surface. Each adapter drives those via its
+Platform-specific concerns — approval prompts, plan reviews, message
+edits, thread creation — live inside the adapter implementation and are
+not part of the protocol surface. Each adapter drives those via its
 own `_on_ws_event` dispatcher using SDK-native APIs.

 To add a new platform:
@@ -115,8 +115,7 @@ with a `type` field.  The recurring shapes a UI has to handle:
 | `tool_output_chunk` | Streaming tool output (e.g. long bash command)                                             | `call_id`, `chunk` |
 | `approve_request`   | One or more tool calls need operator approval                                              | `items: [{call_id, header, preview, func_name, approval_label, needs_approval}]` |
 | `approval_resolved` | Operator answered the approval prompt                                                      | `approved`, `feedback` |
-| `state_change`      | Worker-thread state transition (also re-emitted with the current state on every fresh subscribe so refresh-mid-stream restores composer mode) | `state` ∈ `running`, `thinking`, `attention`, `idle`, `error` |
-| `in_progress_snapshot` | One-shot replay of the in-progress turn's content + reasoning when this client connects mid-stream                              | `content`, `reasoning` |
+| `state_change`      | Worker-thread state transition                                                             | `state` ∈ `running`, `thinking`, `attention`, `idle`, `error` |
 | `status`            | Token usage + context-window snapshot (fires on every streaming tick)                      | `prompt_tokens`, `completion_tokens`, `total_tokens`, `context_window`, `pct`, `effort`, `cache_creation_tokens`, `cache_read_tokens` |
 | `rename`            | Session's display name changed                                                             | `name` |
 | `intent_verdict`    | Intent judge produced a verdict on a pending tool call                                     | `risk_level`, `recommendation`, `reasons` |
@@ -131,13 +130,9 @@ with a `type` field.  The recurring shapes a UI has to handle:

 **Reconnection contract:** a freshly-opened SSE connection receives
 the current snapshot of any pending tool approval (`approve_request`
-is re-sent if unresolved), any in-flight `wait_*` / `batch_*`
-indicator, the worker's current `state_change`, and an
-`in_progress_snapshot` carrying any partial content / reasoning the
-model has produced for the in-progress turn — so a tab refresh
-mid-approval, mid-tool-execution, or mid-stream restores both the
-correct composer mode and the partial assistant text without waiting
-for the response to complete.
+is re-sent if unresolved) and any in-flight `wait_*` / `batch_*`
+indicator — so a tab refresh mid-approval doesn't strand the
+operator.

 ---

@@ -237,21 +232,14 @@ Key properties:
  tool with a fresh timeout.
 - **Modes** — `mode="any"` returns as soon as one child reaches a
  real terminal state (`idle` / `error` / `closed` / `deleted`);
-  `mode="all"` waits for every polled child to reach a real
-  terminal state.
+  `mode="all"` waits for every polled child.
 - **Progress throttling** — the poll loop runs every 500 ms but the
  SSE emission is diff-on-state-change plus a 5-second heartbeat.  A
  600 s wait generates O(dozens) of progress events, not 1200.
- **Unresolvable ids** — ws_ids are validated up front (exactly
-  32 hex chars; copy them verbatim): a malformed id fails the call
-  immediately with did-you-mean suggestions and a roster of the
-  coord's children.  An id the caller doesn't own, a missing row, or
-  a child hard-deleted mid-wait is reported as `state="not_found"`
-  and aborts the wait on the tick that observes it (top-level
-  `error` / `not_found` / `children` fields, `complete=false`) — the
-  LLM should fix the id and re-issue, not conclude the child died.
-  Foreign and missing collapse into one shape, so the wait can't be
-  used as an existence oracle.
+- **Denied rows** — an id the caller doesn't own (cross-tenant) or a
+  missing row is reported as a `denied` state in the results dict;
+  `mode="any"` won't satisfy on a pure-denied list (the LLM should
+  treat it as a config error, not a completion).

 Prefer `wait_for_workstream` over polling `inspect_workstream` in a
 loop — a wait consumes one assistant turn regardless of how long the
@@ -14,46 +14,34 @@ care about.

 ---

-## `kind` — authored audience metadata
+## The two-surface model

 A row in `prompt_templates` carries a `kind` column (see
 [`turnstone/core/skill_kind.py`](../turnstone/core/skill_kind.py);
 migration 044 added the column).  Three values:

-| `SkillKind` enum        | Stored as       | Meaning                                                                    |
-|-------------------------|-----------------|----------------------------------------------------------------------------|
-| `SkillKind.INTERACTIVE` | `"interactive"` | Authored for the interactive maker persona (single-workstream "do this"). |
-| `SkillKind.COORDINATOR` | `"coordinator"` | Authored for the orchestrator persona (delegate, monitor, synthesise).    |
-| `SkillKind.ANY`         | `"any"`         | Either surface (or audience-neutral).  Default on create.                 |
+| `SkillKind` enum     | Stored as                   | Visible in                                                                |
+|----------------------|-----------------------------|---------------------------------------------------------------------------|
+| `SkillKind.INTERACTIVE` | `"interactive"`          | Only the interactive-session activation path.  `list_skills` on a coord won't show it. |
+| `SkillKind.COORDINATOR` | `"coordinator"`          | Only the coordinator's `list_skills` tool.  Hidden from interactive activation pickers. |
+| `SkillKind.ANY`         | `"any"`                  | Both surfaces.  Default for legacy rows predating the classifier.        |

-The `kind` field is a `StrEnum` — drop-in `str` compatible — so DB
-rows, JSON payloads, and `==` comparisons all work without translation
-at the edge.
+The `kind` field is a `StrEnum` — drop-in ``str`` compatible — so
+DB rows, JSON payloads, and `==` comparisons all work without
+translation at the edge.

-**`kind` is metadata, not an enforcement boundary.**  The model can
-`skills(action='find')` across every kind from any session, `get` any
-row by name, and `load` any visible skill regardless of session kind.
-Actual runtime capability is gated by `allowed_tools` + `auto_approve`
-on the skill and the operator's approval card on every `load` /
-`spawn_workstream(skill=...)` decision — `kind` doesn't add or remove
-any of that.  It's a sorting / grouping / search-narrowing hint.
+When a coordinator calls `list_skills`, the SQL filter narrows to
+`kind IN ('coordinator', 'any')`.  When an interactive session picks
+a skill at activation, the filter narrows to
+`kind IN ('interactive', 'any')`.  A skill author tags once at
+creation; the two surfaces stay partitioned without any
+per-call filtering on the LLM side.

-The opt-in filter is on `skills(action='find', kind='coordinator')`
-(or `'interactive'`) — pass it when you want to narrow a catalog
-browse to a specific authored audience.  Omitting it (or passing
-`kind='any'`) returns the full catalog.  When supplied, the storage
-filter widens to `[<kind>, 'any']` so audience-neutral rows remain
-visible inside the narrowed view.
-
-**Tagging a new skill as coordinator-targeted** — set `kind` to
-`SkillKind.COORDINATOR` (or the literal `"coordinator"`) when you
-`skills(action='create', kind='coordinator', ...)` or POST to
-`/v1/api/admin/skills`.  Use this to signal intent to other skill
-authors and to make the orchestrator-targeted catalog easy to
-browse — not to hide the skill from interactive sessions.  Existing
-rows default to `SkillKind.ANY`; bump them to `COORDINATOR` if
-you've rewritten the prompt around the orchestrator toolset and
-want the kind filter to surface them as such.
+**Tagging a new skill as coordinator-only** — set `kind` to
+`SkillKind.COORDINATOR` (or the literal string `"coordinator"`) when
+you POST to `/v1/api/admin/skills`.  Existing rows default to
+`SkillKind.ANY`; bump them to `COORDINATOR` if you've rewritten the
+prompt around the orchestrator toolset.

 ---

@@ -76,9 +64,7 @@ or MCP config can do adds to it.  Current members:
 | `cancel_workstream`       | wind-down       | Drop the in-flight generation; leaves child idle for a fresh send.  |
 | `delete_workstream`       | wind-down       | Hard-delete one child.  Requires approval.                          |
 | `list_nodes`              | discover        | Enumerate live cluster nodes + capabilities.                        |
-| `skills` (action=find)    | discover        | Browse the skill catalog; opt-in `kind` filter narrows by audience. |
-| `memory`                  | persist         | Orchestration scratchpad keyed by the `coordinator` scope.          |
-| `notify`                  | broadcast       | Post a status update to a human channel at a narrative beat.        |
+| `list_skills`             | discover        | Coordinator-visible skills only (SkillKind filter above).           |
 | `tasks`                   | plan            | Orchestrator-only scratchpad.  Children don't see it.               |

 Explicitly **not** in the coordinator set:
@@ -86,8 +72,8 @@ Explicitly **not** in the coordinator set:
 - `bash` / `edit_file` / `write_file` / `append_file` / `diff_file` — no local FS.
 - `read_file` / `search` — no local FS reads.
 - `web_fetch` / `web_search` — no direct web access.
- `task_agent` — sub-agent tool is zeroed on coord sessions.
- `recall` / `watch` / `read_resource` / `use_prompt` — UX / persistence tools that belong to interactive sessions.  The dual-kind `memory` / `skills` / `notify` tools are available on both kinds (see the table above).
+- `task_agent` / `plan_agent` — sub-agent tools are zeroed on coord sessions.
+- `memory` / `recall` / `notify` / `watch` / `read_resource` / `use_prompt` / `skill` — the orchestrator's "memory" is its children's outputs; these UX / persistence tools belong to interactive sessions.

 If your skill needs a coordinator to "run a command" or "read a
 file", write the delegate pattern instead: spawn a child with an
@@ -168,50 +154,29 @@ Every ws_id returned by `spawn_workstream` / `spawn_batch` is a
 invent ws_ids — a model that hallucinates `"child-1"` or `"ws-abc"`
 hits the tenant guard in `CoordinatorClient._is_own_subtree`, which
 validates ws_id against `parent_ws_id=coord_ws_id` AND
-`user_id=owner` in storage.  The rejection shape is uniform and
-recovery-oriented:
+`user_id=owner` in storage.  The rejection shape varies by tool:

 - **Mutating ops** (`send_to_workstream`, `close_workstream`,
-  `cancel_workstream`, `delete_workstream`) and
-  **`inspect_workstream`** return
-  `{"error": "no workstream matching '<ref>' among your children; …",
-  "status": 404, "ws_id": "<ref>", "did_you_mean": [...],
-  "children": [...], "children_truncated": bool}` — a did-you-mean
-  (edit distance ≤ 3 against the coord's own children, which catches
-  the garbled-hex incident class: a 32-char id whose `aaa` run
-  collapsed to `a`) plus a roster of the coord's children.  A ref
-  that matches a child's display NAME is called out explicitly with
-  the right id (names are mutable labels, not addresses).  Foreign
-  and nonexistent ids produce the same payload (no existence
-  oracle), every hint references only the coord's own children, and
-  near-miss ids are never auto-resolved — the skill should fix the
-  id and re-issue, not treat the child as dead.
- **`wait_for_workstream`** validates ids before waiting: a
-  malformed id fails the whole call immediately (`invalid_ws_ids`
-  carries the per-id payloads above, `elapsed=0`); a well-formed id
-  that is foreign, nonexistent, or hard-deleted mid-wait surfaces as
-  `state="not_found"` and aborts the wait on that tick with
-  top-level `error` / `not_found` / `children` fields.
-  `complete=true` therefore means every polled lane really finished
-  — an unobservable id can neither burn the timeout nor ride along
-  to a "complete" result.
+  `cancel_workstream`, `delete_workstream`) return
+  `{"error": "workstream not in coordinator subtree: <ws_id>", "status": 404}`
+  — the skill should treat this as a tool error, not an empty result.
+- **`inspect_workstream`** returns `{"error": "workstream not found", "ws_id": "<ws_id>"}`
+  (same shape as a genuinely missing row, so the guard can't be
+  used as an existence oracle).
+- **`wait_for_workstream`** reports the offending id with
+  `state="denied"` in its `results` dict; `mode="any"` won't
+  satisfy on a pure-denied list, so a hallucinated id won't trick
+  the wait into reporting "complete".

 Pattern: capture each spawn result in the next tool call's input.
-The JSON tool-result carries `{"child_ws_id": "...", "name": "...",
+The JSON tool-result carries `{"ws_id": "...", "name": "...",
 "node_id": "...", "routing_strategy": "..."}`; the model should
-extract the `child_ws_id` and pass it as `ws_id` (or in the `ws_ids`
-list) to `inspect_workstream` / `wait_for_workstream` /
-`send_to_workstream` / `close_workstream` verbatim.  The asymmetry
-— spawn returns `child_ws_id` but the other tools accept `ws_id` /
-`ws_ids` — is intentional: it defuses a coordinator-LLM recency
-bias where seeing `ws_id` in a spawn return primed re-spawn loops
-instead of progression to the wait phase.
+extract the ws_id and pass it to `inspect_workstream` /
+`wait_for_workstream` / `send_to_workstream` / `close_workstream`
+verbatim.

 A UI that wants human-readable identifiers should render the `name`
-field and keep the workstream id as the click-through key — note
-that the id *value* is the same regardless of whether it arrived
-under the `child_ws_id` key (spawn return) or the `ws_id` key
-(every other tool's input/output); only the field name differs.
+field and keep the ws_id as the click-through key.

 ---

@@ -34,12 +34,13 @@ package "turnstone/core/" <<Rectangle>> {
    component [metrics.py\nPrometheus metrics] as metrics <<core>>
    component [config.py\nTOML config] as config <<core>>
    component [safety.py\nPath validation] as safety <<core>>
+    component [sandbox.py\nCommand sandbox] as sandbox <<core>>
    component [edit.py\nFile editing] as edit <<core>>
    component [web.py\nWeb helpers] as web <<core>>
    component [auth.py\nAuthentication] as auth <<core>>
    component [healthcheck.py\nBackendHealthMonitor] as healthcheck <<core>>
    component [ratelimit.py\nRateLimiter] as ratelimit <<core>>
-    component [mcp_client.py\nMCPClientManager\n(push + manual refresh)] as mcp <<core>>
+    component [mcp_client.py\nMCPClientManager\n(push + periodic refresh)] as mcp <<core>>
    component [tool_search.py\nToolSearchManager, BM25] as toolsearch <<core>>
    component [model_registry.py\nModelRegistry] as registry <<core>>
 }
@@ -122,6 +123,7 @@ session --> tools
 session --> memory
 memory --> storage
 session --> safety
+session --> sandbox
 session --> edit
 session --> web
 session --> healthcheck
@@ -15,6 +15,7 @@ interface "SessionUI" as SessionUI <<Protocol>> {
    + on_tool_result(call_id: str, name: str, output: str, *, is_error: bool = False)
    + on_tool_output_chunk(call_id: str, chunk: str)
    + on_status(usage: dict, ctx_window: int, effort: str)
+    + on_plan_review(content: str) → str
    + on_info(message: str)
    + on_error(message: str)
    + on_state_change(state: str)
@@ -42,13 +43,15 @@ class "WorkstreamTerminalUI" as WsTermUI {
 class "WebUI" as WebUI {
    - _listeners: list[Queue]
    - _approval_event: Event
+    - _plan_event: Event
    - _ws_prompt_tokens: int
    - _ws_tool_calls: dict
    + resolve_approval(approved, feedback)
+    + resolve_plan(feedback)
    --
    Enqueues JSON events for SSE.
    Blocks on threading.Event for
-    approval.
+    approval/plan review.
    SSE handlers bridge Queue to
    async via run_in_executor().
    --
@@ -66,10 +69,9 @@ class "NullUI" as NullUI {
 interface "LLMProvider" as LLMProvider <<Protocol>> {
    + provider_name: str {property}
    + get_capabilities(model) → ModelCapabilities
-    + create_streaming(client, model, messages, ..., replay_reasoning_to_model) → Iterator[StreamChunk]
-    + create_completion(client, model, messages, ..., replay_reasoning_to_model) → CompletionResult
+    + create_streaming(client, model, messages, ...) → Iterator[StreamChunk]
+    + create_completion(client, model, messages, ...) → CompletionResult
    + convert_tools(tools) → list[dict]
-    + extract_reasoning_text(provider_blocks) → str
    + retryable_error_names: frozenset[str] {property}
    --
    core/providers/_protocol.py
@@ -124,7 +126,6 @@ class "ModelCapabilities" as ModelCaps <<frozen>> {
    + supports_web_search: bool
    + supports_tool_search: bool
    + supports_vision: bool
-    + supports_reasoning_replay: bool
 }

 ' ChatSession
@@ -142,6 +143,7 @@ class "ChatSession" as ChatSession {
    + model_alias: str | None {property}
    - _tools: list[dict]
    - _task_tools: list[dict]
+    - _agent_tools: list[dict]
    - _read_files: set[str]
    - system_messages: list[dict]
    --
@@ -251,7 +253,7 @@ class "MCPClientManager" as MCPMgr {
    Background asyncio event loop
    bridges async MCP SDK to
    sync ChatSession dispatch.
-    Push + manual refresh.
+    Push + periodic + manual refresh.
    Resources + prompts discovered
    alongside tools at startup.
    --
@@ -24,14 +24,6 @@ CS -> DB : save_message(ws_id, "user", input)

 group loop [while tool_calls present]

-    CS -> UI : on_turn_start()
-    note right of UI
-      SessionUIBase resets the per-turn inflight
-      buffers (_ws_inflight_content / reasoning /
-      seq) that fuel the SSE in_progress_snapshot
-      event for mid-stream refresh resume.
-    end note
-
    CS -> UI : on_state_change("thinking")
    CS -> UI : on_thinking_start()

@@ -81,14 +73,6 @@ group loop [while tool_calls present]

    CS -> CS : _update_token_table()\ncalibrate chars_per_token ratio
    CS -> CS : messages.append(assistant_msg)
-    CS -> UI : on_turn_committed()
-    note right of UI
-      Drops the per-turn inflight buffers — the
-      assistant message is now in the history
-      list, so the in_progress_snapshot must
-      not re-render it during the next tool-
-      execution window or the next streaming turn.
-    end note
    CS -> DB : save_message(ws_id, "assistant", content)
    CS -> DB : save_message(ws_id, "tool_call", ...) ×N

@@ -139,9 +123,10 @@ group loop [while tool_calls present]
          read_file → open().read() or base64 image
          search → grep subprocess
          edit_file → string replace
-          task → _run_agent() sub-loop
+          task/plan → _run_agent() sub-loop
+          math → sandboxed subprocess
          web_fetch → httpx + LLM summarize
-          web_search → provider-native or SearxNG fallback
+          web_search → provider-native or Tavily fallback
          memory/recall → SQLite
        end note

@@ -24,7 +24,7 @@ partition "Phase 1: Prepare" #E8F5E9 {
        :Dispatch to _prepare_{func_name}();

        note right
-            **Dispatch table (16 built-in + tool_search):**
+            **Dispatch table (19 built-in + tool_search):**
            ┌───────────────┬──────────────────┐
            │ Tool          │ Needs Approval?  │
            ├───────────────┼──────────────────┤
@@ -34,10 +34,13 @@ partition "Phase 1: Prepare" #E8F5E9 {
            │ edit_file     │ ✓ Yes            │
            │ search        │ ✗ Auto-approve   │
            │ diff_file     │ ✗ Auto-approve   │
+            │ math          │ ✗ Auto-approve   │
+            │ man           │ ✗ Auto-approve   │
            │ web_fetch     │ ✗ Auto-approve   │
            │ web_search    │ ✗ Auto-approve   │
            │ tool_search   │ ✗ Auto-approve   │
            │ task_agent    │ ✓ Yes            │
+            │ plan_agent    │ ✓ Yes            │
            │ memory        │ ✗ Auto-approve   │
            │ recall        │ ✗ Auto-approve   │
            │ notify        │ ✗ Auto-approve   │
@@ -107,10 +110,13 @@ partition "Phase 3: Execute" #E3F2FD {
          ├─ _exec_write_file: makedirs + write
          ├─ _exec_edit_file: find_occurrences + replace
          ├─ _exec_search: grep subprocess
+          ├─ _exec_math: sandboxed subprocess
+          ├─ _exec_man: man/info subprocess
          ├─ _exec_web_fetch: httpx.get + LLM summary
-          ├─ _exec_web_search: SearxNG JSON GET (fallback for local models)
+          ├─ _exec_web_search: Tavily API POST (fallback for local models)
          ├─ _exec_tool_search: BM25 search + expand_visible()
          ├─ _exec_task: _run_agent(TASK_AGENT_TOOLS)
+          ├─ _exec_plan: _run_agent(AGENT_TOOLS, read-only)
          ├─ _exec_notify: HTTP POST to channel gateway
          ├─ _exec_memory: structured memory save/search/delete/list
          ├─ _exec_recall: conversation history FTS5 search
@@ -125,6 +131,11 @@ partition "Phase 3: Execute" #E3F2FD {

    :bash: ui.on_tool_output_chunk(call_id, line) per stdout line;
    :ui.on_tool_result(call_id, name, output, is_error) for each;
+
+    if (plan tool was executed?) then (yes)
+        :ui.on_plan_review(output);
+        :Block for user review/feedback;
+    endif
 }

 :Return (results, user_feedback);
@@ -13,7 +13,7 @@ skinparam state {
 state "IDLE" as idle <<idle>> : Waiting for user input.\nNo active LLM call or tool execution.
 state "THINKING" as thinking <<thinking>> : LLM streaming response.\nTokens flowing (reasoning + content).
 state "RUNNING" as running <<running>> : Tools executing.\nThreadPoolExecutor active.
-state "ATTENTION" as attention <<attention>> : Blocked on user action.\nTool approval needed.
+state "ATTENTION" as attention <<attention>> : Blocked on user action.\nTool approval or plan review needed.
 state "ERROR" as error <<error>> : Exception occurred.\nRecoverable on next send().

 [*] --> idle : Session created
@@ -34,6 +34,8 @@ attention --> running : User denies\n(denial recorded)\n_emit_state("running")

 running --> thinking : Tool results appended,\nnext LLM call\n_emit_state("thinking")

+running --> attention : Plan tool complete,\non_plan_review()\n_emit_state("attention")
+
 running --> error : Exception during\ntool execution

 error --> thinking : New send() call\n_emit_state("thinking")
@@ -42,7 +44,7 @@ thinking --> idle : cancel() called\nstream aborted\n_emit_state("idle")

 running --> idle : cancel() called\n_emit_state("idle")

-attention --> idle : cancel() unblocks\napproval wait\n_emit_state("idle")
+attention --> idle : cancel() unblocks\napproval/plan wait\n_emit_state("idle")

 note left of idle
  **Cancel escalation:**
@@ -30,6 +30,7 @@ package "turnstone/sdk/ (Python)" {
        + close_workstream()
        + send(message, ws_id)
        + approve()
+        + plan_feedback()
        + command()
        + cancel(ws_id)
        + stream_events(ws_id)
@@ -190,25 +190,21 @@ group Push Notifications (debounced 5s per server)
  MCPMgr -> Storage : sync_prompts_to_storage()
 end

-group Manual Refresh
-  Session -> MCPMgr : refresh_sync()
+group Periodic Polling (default 4h)
+  MCPMgr -> MCPMgr : _periodic_refresh()
  note right
-    /mcp refresh [server] —
-    re-fetches catalog and
-    attempts reconnect for
-    disconnected servers.
+    Only polls capabilities
+    without push support.
+    Staggered per-server.
+    Disconnected servers get
+    reconnect attempts with
+    exponential backoff (60s-1h).
  end note
 end

-group Manual Reconnect
-  Session -> MCPMgr : reconnect_sync(name)
-  note right
-    Operator-driven via the
-    console admin panel —
-    tears down session, clears
-    circuit breaker, runs a
-    fresh handshake.
-  end note
+group Manual Refresh
+  Session -> MCPMgr : refresh_sync()
+  note right: /mcp refresh [server]
 end

 == Policy Evaluation ==
@@ -202,7 +202,7 @@ note over Session, Judge
  Cross-model: separate provider/client from [judge] config.

  **Sub-agent exemption:**
-  Task sub-agents skip intent validation entirely.
+  Plan agent and task agent skip intent validation entirely.

  **Output guard:**
  Runs when judge_config.output_guard is true (default).
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:95dd5ebc899a1261d516686a5aa3319a7f45015d411302825fa28afbfc82e1ce
-size 326766
+oid sha256:a3b5c59403a6febd81667fc8fd2a7d22bc59da6130eba0dea5449c42668d0ede
+size 387044
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:9857db23fe3c4316d492073aac69c7e7558b1abe3b95ad7756d4a5933bd0ece7
-size 620214
+oid sha256:474b900448ec04d1117b48a2b55614524721b2f04ac4bda66170bd0a06aae0f2
+size 624573
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:d9c7769a600c38e6387390e6c42db8152e0f80c31d17b2218f7f636b71c7b868
-size 355459
+oid sha256:3aa8d972bba40d78152f9f0c762b9f5ec616d8052c45fa52b7dd1c679ed81d61
+size 325245
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:23ca090b5656baaf70820cbe4ab6c27f0a3a02e18b4db0695614cf9489c23980
-size 281440
+oid sha256:674712a0563f51837383184652efeb28b7bec13378be636e89d2959bfba39d1e
+size 281519
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:d6aff446a062aa08f316985d00c2183148694f786d7f22172bc50b30046c728b
-size 379259
+oid sha256:7623df33be9baf7647ca1c2450640df57e1cd73e8be1f8168aae16e546ad683c
+size 459941
@@ -1,266 +1,164 @@
 # Docker Deployment

-Turnstone ships two Docker Compose stacks:
+Docker Compose stack for running the full turnstone platform.

-| Stack | File | Use it for |
-|-------|------|------------|
-| **Dev cluster** | `compose.yaml` (repo root) | Clone-and-run. Builds locally, zero config, full 10-node cluster. |
-| **Production** | `turnstone/deploy/compose.yaml` | Pip/pipx installs. Pulls released images from ghcr.io, requires real secrets. |
-
-## Quick start — local cluster
+## Quick Start

 ```bash
-git clone https://github.com/turnstonelabs/turnstone
-cd turnstone
+# Copy and edit environment config
+cp .env.example .env
+
+# Full stack (needs an LLM API on the host)
 docker compose up
 ```

-That builds one image and brings up the whole stack: PostgreSQL, the console,
-Caddy, the channel gateway, and **10 server nodes** (`node-1`…`node-10`). No
-`.env` is required — it ships with insecure dev defaults so it just works.
+Console dashboard: http://localhost:8090

-Open the dashboard at **https://localhost:8443**. It's served by Caddy with its
-own local CA, so trust the root certificate once (or click through the browser
-warning):
+> See also: [Deployment diagram](diagrams/png/12-deployment.png)
+
+## Services
+
+| Service | Port | Profile | Description |
+|---------|------|---------|-------------|
+| `server` | 8080 | default | Web UI + chat workstreams + LLM |
+| `console` | 8090 | default | Cluster dashboard |
+| `channel` | — | production | Channel gateway (Discord and/or Slack adapters) |
+| `server-1`…`server-10` | — | cluster | 10-node server fleet (PostgreSQL required) |
+
+## Profiles
+
+**Default** (no flag) — starts `server` and `console`. Requires an OpenAI-compatible LLM API running on the host (default: `http://localhost:8000/v1`).

 ```bash
-docker compose exec caddy cat /data/caddy/pki/authorities/local/root.crt
+docker compose up
 ```

-Create your first admin user (any node works — they share one database):
+**Production** — adds PostgreSQL and the channel gateway. Requires `POSTGRES_PASSWORD` and (for Discord) `TURNSTONE_DISCORD_TOKEN`:

 ```bash
-docker compose exec node-1 turnstone-admin create-user --username admin --name "Admin"
+docker compose --profile production up
 ```

-### Bring your own LLM
-
-Nodes boot **without** an LLM and appear in the console immediately. Add real
-model backends (OpenAI, Anthropic, or a local/vLLM endpoint) from the console
-UI's **Models** tab. To set a node's bootstrap default instead, point
-`LLM_BASE_URL` / `OPENAI_API_KEY` at an OpenAI-compatible endpoint in `.env`.
-
-### Fewer nodes
-
-Ten nodes is heavy on a laptop. Start a subset by naming the services (always
-include `postgres`, `console`, and `caddy`):
+**Cluster** — 10-node server fleet sharing PostgreSQL. Access all nodes via the console at `:8090`. Requires `POSTGRES_PASSWORD`:

 ```bash
-docker compose up postgres console caddy channel node-1 node-2 node-3
+docker compose --profile cluster up
 ```

-## Why HTTPS-only?
-
-The console's plain-HTTP port (8090) is **not** published to the host. A plain
-HTTP/1.1 origin caps the browser at 6 connections, which starves the
-dashboard's per-pane SSE streams. Caddy serves the browser over HTTP/2
-(multiplexed) and proxies to `console:8090` on the internal network, so the cap
-is gone. Everything goes through `https://localhost:8443`.
-
-## Join a bare-metal host
-
-PostgreSQL is published on `127.0.0.1:5432`, so a `turnstone-server` running
-directly on the same machine — for example to use a local GPU — can join the
-same cluster and show up in the console alongside the containerized nodes.
-
-Put the secret and connection settings in `~/.config/turnstone/config.toml`
-(secrets belong in this file, not the process environment — keep it `0600`,
-the loader warns otherwise):
-
-```toml
-[auth]
-jwt_secret = "dev-only-insecure-jwt-secret-change-me-for-real-deployments"
-
-[database]
-backend = "postgresql"
-url = "postgresql+psycopg://turnstone:turnstone@localhost:5432/turnstone"
-
-[api]
-base_url = "http://localhost:8000/v1"   # your local model endpoint
-api_key = "dummy"
-```
-
-Then start the server. The node identity isn't a secret, so it stays on the
-command line:
-
-```bash
-chmod 600 ~/.config/turnstone/config.toml
-TURNSTONE_NODE_ID=host-1 TURNSTONE_ADVERTISE_URL=http://host.docker.internal:8080 \
-  turnstone-server --host 0.0.0.0 --port 8080
-```
-
-The host server registers itself in PostgreSQL; the console reaches it back via
-`host.docker.internal`. The `jwt_secret` and DB credentials above are the
-dev-stack defaults — match whatever you set in `.env` if you changed them. To
-let a **different** machine join, start the stack with `POSTGRES_BIND=0.0.0.0`
-and use the host's routable IP in the `url` and `TURNSTONE_ADVERTISE_URL` —
-but **set a strong `POSTGRES_PASSWORD` first**, or you'll expose a database with
-the insecure default password (and every user account + API-token hash in it) to
-your network.
-
-## Production stack
-
-For a real deployment use the bundled stack, which pulls released images
-instead of building:
-
-```bash
-docker compose -f turnstone/deploy/compose.yaml up
-```
-
-It's the same shape as the dev stack — Caddy-fronted console, channel, and a
-PostgreSQL all share one database so the console discovers the node — but it
-pulls released images, runs a single server node, and has **no baked-in
-secrets**. Set these in `.env` first (`turnstone-bootstrap` generates them):
-
-```bash
-TURNSTONE_JWT_SECRET=<python -c "import secrets; print(secrets.token_hex(32))">
-POSTGRES_PASSWORD=<a strong password>
-```
-
-The dashboard is at **https://localhost:8443** (Caddy, same as the dev stack);
-the console's HTTP port isn't published. For a real domain and a publicly
-trusted cert, edit `turnstone/deploy/Caddyfile` to point Caddy at Let's Encrypt
-(see [tls.md](tls.md)). Pin the image with `TURNSTONE_IMAGE_TAG` (default:
-`latest`).
-
-### mTLS
-
-Layer the TLS overlay on the production stack to enable mutual TLS between
-services. A bootstrap container creates a CA and every service auto-provisions
-certs via the console's ACME endpoint:
-
-```bash
-docker compose -f turnstone/deploy/compose.yaml -f deploy/docker-compose.tls.yml up
-```
-
-See [tls.md](tls.md) for details.
-
 ## Configuration

-Everything is configured with environment variables in `.env` (copy from
-[`.env.example`](../.env.example)). The dev stack needs none of them — they're
-overrides.
+All configuration is via environment variables in `.env` (copy from `.env.example`):

-### LLM backend
+### LLM Backend

 | Variable | Default | Description |
 |----------|---------|-------------|
-| `LLM_BASE_URL` | `http://host.docker.internal:8000/v1` | Bootstrap OpenAI-compatible API URL (real backends go in the UI) |
+| `LLM_BASE_URL` | `http://host.docker.internal:8000/v1` | OpenAI-compatible API URL |
 | `OPENAI_API_KEY` | `dummy` | API key (`dummy` for local servers) |
-| `TURNSTONE_SEARXNG_URL` | `http://searxng:8080` | SearxNG URL for the `web_search` tool (local/vLLM models only; Anthropic/OpenAI use native search). Defaults to the bundled `searxng` service; set to an external instance's URL. To turn web search off, clear `tools.searxng_url` in the admin Settings tab. |
-| `SEARXNG_IMAGE_TAG` | `latest` | Tag for the bundled `searxng/searxng` image |
-| `MODEL` | — | Override the default model alias |
+| `TAVILY_API_KEY` | — | Web search API key (only needed for local/vLLM models; Anthropic and OpenAI search models use native search) |

-### Auth & database
-
-| Variable | Default (dev / prod) | Description |
-|----------|----------------------|-------------|
-| `TURNSTONE_JWT_SECRET` | insecure default / **required** | JWT signing secret. Every service must share one value. |
-| `TURNSTONE_DB_BACKEND` | `postgresql` | `sqlite` or `postgresql`. Multi-node discovery requires `postgresql`. |
-| `TURNSTONE_DB_URL` | bundled Postgres | SQLAlchemy URL. Override to use an external database. |
-| `POSTGRES_USER` | `turnstone` | PostgreSQL username |
-| `POSTGRES_PASSWORD` | `turnstone` / **required** | PostgreSQL password |
-| `POSTGRES_MAX_CONNECTIONS` | `300` | `max_connections` for the bundled Postgres |
-
-> **Discovery needs a shared database.** Each server registers and heartbeats
-> into a `services` table that the console polls. All services in these stacks
-> point at the same PostgreSQL by default; SQLite-per-container can't see other
-> containers.
-
-> **Large clusters:** each process keeps a small pool (5 max). Beyond ~50 nodes,
-> put [PgBouncer](pgbouncer.md) (transaction pooling) between turnstone and
-> PostgreSQL.
-
-### Ports
-
-Both stacks publish Caddy (dashboard) and PostgreSQL; the dev stack additionally
-publishes the SearxNG UI on localhost. Everything else is reached through Caddy or
-proxied by the console:
+### Server

 | Variable | Default | Description |
 |----------|---------|-------------|
-| `CONSOLE_HTTPS_PORT` | `8443` | Host port for Caddy (dashboard HTTPS) |
-| `SEARXNG_HTTPS_PORT` | `8444` | Host port for the SearxNG UI via Caddy (dev: localhost-only; prod: opt-in) |
-| `POSTGRES_PORT` | `5432` | Host port for PostgreSQL (for bare-metal joins) |
-| `POSTGRES_BIND` | `127.0.0.1` | Interface PostgreSQL binds on; set `0.0.0.0` for LAN access |
+| `SERVER_PORT` | `8080` | Host port mapping |
+| `SKIP_PERMISSIONS` | — | Set to any value to auto-approve all tools |

-### Channel gateway
+### Console

 | Variable | Default | Description |
 |----------|---------|-------------|
-| `TURNSTONE_DISCORD_TOKEN` | — | Discord bot token (enables the Discord adapter) |
-| `TURNSTONE_DISCORD_GUILD` | `0` | Restrict to one guild (0 = all) |
-| `TURNSTONE_SLACK_TOKEN` | — | Slack Bot User OAuth token `xoxb-…` |
-| `TURNSTONE_SLACK_APP_TOKEN` | — | Slack App-Level token `xapp-…` (with the Slack token) |
+| `CONSOLE_PORT` | `8090` | Host port mapping |

-The channel runs HTTP-only with no adapters until a token is set, so it's safe
-to leave running. See [Channel Integrations](channels.md) for app setup.
+### Auth

-### Web search (SearxNG)
-
-The `web_search` tool for local/vLLM models is backed by a self-hosted
-[SearxNG](https://searxng.org) metasearch service, bundled into both stacks as the
-`searxng` service. The Turnstone nodes reach it over the internal docker network at
-`http://searxng:8080` — its API port is **not** published. Its config —
-[`turnstone/deploy/searxng/settings.yml`](../turnstone/deploy/searxng/settings.yml),
-mounted read-only — enables the JSON API and leaves the rate limiter off (the
-limiter would need a separate Valkey/Redis instance). A `searxng-cache` volume
-persists its favicon + internal cache across restarts. Commercial providers
-(Anthropic, OpenAI) use their own native search and never touch this service.
-
-Point at an existing SearxNG instead of the bundled one with `TURNSTONE_SEARXNG_URL`,
-or narrow the engines via `tools.searxng_engines` in the admin Settings tab (e.g.
-`duckduckgo,wikipedia`).
-
-**SearxNG web UI.** Caddy can also serve SearxNG's own search/Preferences UI on a
-dedicated port. The dev stack publishes it at **`https://localhost:8444`** bound to
-localhost only; the production stack does **not** publish it by default (uncomment
-the `8444` port on the `caddy` service to opt in). Change the port with
-`SEARXNG_HTTPS_PORT`. **SearxNG has no authentication** — never bind this to a public
-interface, or anyone who can reach it can search through your instance.
-
-> **AGPL note for operators.** SearxNG is licensed AGPL-3.0. Kept on the internal
-> network (or bound to localhost), no external user interacts with it — so the AGPL
-> §13 (remote network interaction) source-offer obligation does not attach. If you
-> publish SearxNG to remote users (bind its port to a public interface, or front it
-> with your own reverse proxy) you become the operator of a network-reachable AGPL
-> service and must offer its corresponding source; that is trivially satisfied by
-> linking to upstream <https://github.com/searxng/searxng>. Turnstone's own license is
-> unaffected: it talks to SearxNG over HTTP as a separate process (mere aggregation),
-> not by linking.
-
-### Other
+Auth is always enabled. `TURNSTONE_JWT_SECRET` is required.

 | Variable | Default | Description |
 |----------|---------|-------------|
-| `WORKSPACE_MOUNT` | empty volume | Host directory bind-mounted at `/workspace` for the model to read/write |
-| `SKIP_PERMISSIONS` | — | Set to any value to auto-approve all tool calls (dev only) |
-| `MCP_CONFIG` | — | Path to an MCP server config file |
-| `TURNSTONE_IMAGE_TAG` | `latest` | ghcr.io image tag — production stack |
+| `TURNSTONE_JWT_SECRET` | — | Secret key for signing JWTs (required) |

-## Building
+### Database

-Both stacks install all entry points into a single image (`turnstone`,
-`turnstone-server`, `turnstone-console`, `turnstone-channel`, `turnstone-admin`,
-`turnstone-eval`, `turnstone-bootstrap`):
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `TURNSTONE_DB_BACKEND` | `sqlite` | Storage backend: `sqlite` or `postgresql` |
+| `TURNSTONE_DB_URL` | — | Database URL (e.g. `postgresql+psycopg://user:pass@postgres:5432/turnstone`). For SQLite, defaults to `/data/.turnstone.db` |
+| `TURNSTONE_DB_POOL_SIZE` | `2` | PostgreSQL connection pool size per process (default: 2 base + 3 overflow = 5 max) |
+| `POSTGRES_USER` | `turnstone` | PostgreSQL container username (used in default `TURNSTONE_DB_URL` for cluster/channel) |
+| `POSTGRES_PASSWORD` | — | PostgreSQL container password (required for production and cluster profiles) |
+
+The database stores workstream history, user accounts, and API tokens. When using JWT auth, a database backend is required for user storage.
+
+> **Upgrading from <1.3.0a4:** Earlier versions used `DB_BACKEND` and `DATABASE_URL` in `.env`, which `compose.yaml` mapped to the `TURNSTONE_`-prefixed names internally. These short aliases have been removed. Rename `DB_BACKEND` → `TURNSTONE_DB_BACKEND` and `DATABASE_URL` → `TURNSTONE_DB_URL` in your `.env` file.
+
+> **Large clusters:** Each turnstone process maintains a small connection pool (5 max). At hundreds of nodes this adds up — use [PgBouncer](pgbouncer.md) in transaction pooling mode between turnstone and PostgreSQL.
+
+> **First-time setup:** After deploying with auth enabled, create an initial admin user by running `turnstone-admin create-user` inside the container:
+>
+> ```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) |
+| `TURNSTONE_SLACK_TOKEN` | — | Slack Bot User OAuth token `xoxb-…` (required to enable Slack adapter) |
+| `TURNSTONE_SLACK_APP_TOKEN` | — | Slack App-Level token `xapp-…` (required with `TURNSTONE_SLACK_TOKEN`) |
+| `TURNSTONE_SLACK_CHANNELS` | — | Comma-separated Slack channel IDs to allow (empty = all) |
+| `TURNSTONE_SLACK_SLASH_COMMAND` | `/turnstone` | Slash command registered in the Slack app |
+
+The channel service runs in the `production` profile. When
+`TURNSTONE_DISCORD_TOKEN` or the Slack pair is set the gateway starts the
+corresponding adapter; both can run in one process. See
+[Channel Integrations](channels.md) for platform app setup and user
+account linking.
+
+## Scaling
+
+For multi-node testing, use the `cluster` profile which provides 10 server instances with unique node IDs (`node-1` through `node-10`), resource limits, and shared PostgreSQL:

 ```bash
-docker compose build            # build the dev image
-docker compose build --no-cache # rebuild from scratch
+POSTGRES_PASSWORD=secret docker compose --profile cluster up
 ```

+The default `server` also runs alongside the cluster nodes (11 total). All nodes are accessible via the console dashboard at `:8090`.
+
+For production clusters beyond ~50 nodes, add PgBouncer between turnstone services and PostgreSQL. See [PgBouncer Connection Pooling](pgbouncer.md) for Docker Compose and Helm configuration.
+
 ## Volumes

-| Volume | Purpose |
-|--------|---------|
-| `postgres-data` | PostgreSQL data directory |
-| `turnstone-data` | `/data` per node (SQLite fallback, local state) |
-| `workspace` | `/workspace` (unless `WORKSPACE_MOUNT` is set) |
-| `caddy-data` / `caddy-config` | Caddy's local CA and config (dev stack) |
+| Volume | Mount | Purpose |
+|--------|-------|---------|
+| `turnstone-data` | `/data` | SQLite database (`.turnstone.db`) |
+
+## Building
+
+The image uses a multi-stage Dockerfile:
+
+```bash
+# Build all services
+docker compose build
+
+# Rebuild without cache
+docker compose build --no-cache
+```
+
+All entry points are installed in a single image: `turnstone`,
+`turnstone-server`, `turnstone-console`, `turnstone-channel`,
+`turnstone-admin`, `turnstone-eval`, and `turnstone-bootstrap`.

 ## Cleanup

 ```bash
-docker compose down       # stop and remove containers
-docker compose down -v    # also remove volumes (database, certs)
+# Stop and remove containers
+docker compose down
+
+# Stop, remove containers and volumes
+docker compose down -v
 ```
@@ -274,7 +274,8 @@ for iteration in 0..max_iterations:

 ### Phase 1: Analyst (`_run_analyst`)

-A multi-turn agent with a `bash` tool for computing statistics. It receives per-case results with failure classifications and
+A multi-turn agent with `math` (Python) and `bash` tools for computing
+statistics. It receives per-case results with failure classifications and
 produces a structured diagnosis:

 - **Failure patterns**: Shared root causes across failing cases
@@ -37,31 +37,13 @@ model = ""                    # empty = same as session model
 provider = ""                 # empty = same as session provider
 base_url = ""
 api_key = ""
-smart_approvals = false       # auto-approve high-confidence "approve" LLM verdicts (opt-in)
-confidence_threshold = 0.95   # Smart Approvals auto-approve bar (LLM recommendation=approve)
+confidence_threshold = 0.7   # reserved for v2 smart approvals (not used in v1)
 max_context_ratio = 0.5       # max % of judge context window for history
 timeout = 60.0                # seconds (generous for local models)
 read_only_tools = true        # judge can use read_file/list_directory
 cancel_on_approval = false    # stop judging remaining tool calls once user decides
 ```

-### Smart Approvals
-
-With `smart_approvals = true` (off by default) a tool call is approved
-automatically — no operator prompt — when the intent judge's **LLM** verdict
-recommends `approve` with confidence at or above `confidence_threshold`. Every
-other outcome still reaches a human: `review` / `deny` recommendations,
-confidence below the threshold, judge errors or timeouts (`llm_fallback`), and
-any call the deterministic heuristic rules explicitly flagged `deny` or
-`critical`. That heuristic floor blocks only those explicit danger verdicts — it
-is **not** a general "never lower the heuristic" rule: the heuristic's default
-for an unmatched tool is `review`, and letting a confident LLM `approve` upgrade
-a `review` is exactly what Smart Approvals is for. Only `deny` / `critical`
-findings are off-limits to auto-approval. Requires the judge to be enabled;
-auto-approved calls are tagged `smart_approval` in the dashboard and audit trail.
-Smart Approvals applies to the web and coordinator surfaces, not the interactive
-CLI.
-
 All fields are optional. The judge is enabled by default; use `enabled = false`
 (or `--no-judge` on the command line) to disable it.

@@ -72,12 +54,9 @@ All fields are optional. The judge is enabled by default; use `enabled = false`
 --judge-model MODEL            Model for judge
 --judge-provider PROVIDER      Provider for judge
 --judge-timeout SECONDS        LLM judge timeout (default: 60)
--judge-confidence FLOAT       Confidence threshold, 0-1 (default: 0.95)
+--judge-confidence FLOAT       Confidence threshold (default: 0.7)
 ```

-(Smart Approvals is configured via `[judge] smart_approvals` / the admin Judge
-settings, not a CLI flag — the interactive CLI prompts for approval directly.)
-
 CLI flags override `config.toml` values.

 ---
@@ -125,7 +104,7 @@ last) and returns the first matching rule. Each rule has:
 | Critical | 0.90      | deny           | `rm -rf /`, `mkfs`, `dd if=`, pipe-to-shell, chmod 777 on root, write/edit to `/etc/` or `.ssh/`, download-then-execute chains (`curl -o file && chmod +x && bash`) |
 | High     | 0.80      | review         | `sudo`, `kill -9`, destructive git, DROP TABLE, write/edit secrets, HTTP mutations, `ssh`/`scp`, credential file access, browser automation + data export, transitive installs (`npx skills add`, `pip install git+`), control plane mutations (`crontab`, `systemctl enable/start/stop`) |
 | Medium   | 0.70      | review         | Content ingestion pipelines (`curl \| python3`), interpreter execution (`python3 script.py`, `node build.js`), cloud CLI mutations (`az/gcloud/aws/kubectl/terraform` with create/delete/destroy verbs), package installs, `write_file`, MCP tools, Docker operations |
-| Low      | 0.85      | approve        | `read_file`, `list_directory`, `search`, `recall`, `use_prompt`, `tool_search`, `read_resource`, `web_search`, read-only bash (`ls`, `cat`, `head`, `grep`, `find`, etc.) |
+| Low      | 0.85      | approve        | `read_file`, `list_directory`, `search`, `recall`, `man`, `use_prompt`, `tool_search`, `read_resource`, `web_search`, read-only bash (`ls`, `cat`, `head`, `grep`, `find`, etc.) |

 When no rule matches, the heuristic returns a default verdict: medium risk,
 0.50 confidence, "review" recommendation.
@@ -231,23 +210,6 @@ calls for approval, it calls `_evaluate_intent()` which:
 4. Attaches each heuristic verdict to its item as `_heuristic_verdict`
 5. The daemon thread runs the LLM judge and delivers results via `ui.on_intent_verdict()`

-The daemon evaluates items sequentially, so a large parallel batch can outlive
-its approval gate. With `cancel_on_approval = false` (the default) the daemon
-runs every item to completion: verdicts that land after the operator decided
-still stream to the UI and persist, stamped with the decision. The daemon is
-aborted only when the next tool batch supersedes it or the session closes —
-then each unfinished item degrades to an `llm_fallback` verdict. With
-`cancel_on_approval = true` the abort additionally fires the moment the gate
-resolves, trading verdict completeness for inference savings — recommended
-when the judge shares a single local inference backend with the session model,
-where a large batch's remaining judge calls would otherwise compete with the
-next turn's completion.
-
-Verdicts that arrive after a *newer batch* has replaced the judge generation
-are withheld from the live surfaces (a reused call_id must never ride a stale
-`approve` into Smart Approvals) but still persist with
-`user_decision = "superseded"` so the audit trail records the judge's answer.
-
 Sub-agents (plan agent, task agent) are exempt from intent validation -- they
 always get full tool visibility without judge evaluation.

@@ -259,13 +221,7 @@ All verdicts are persisted to the `intent_verdicts` table (migration 012):

 - Heuristic verdicts are stored when the `approve_request` event is emitted
 - LLM verdicts are stored when the `intent_verdict` event is delivered
- The `user_decision` column is updated when the user approves or denies;
-  auto-approved rows carry the bypass reason (`policy`, `blanket`,
-  `auto_approve_tools`, `smart_approval`), and rows whose verdict landed only
-  after a newer batch replaced the judge generation carry `superseded`
- Every stored verdict — including the benign `risk_level = "none"` majority —
-  is re-attached to its tool call on history replay, so a reloaded workstream
-  shows the same verdict badges the live stream did
+- The `user_decision` column is updated when the user approves or denies

 The console admin panel exposes verdict history via:

@@ -416,36 +372,10 @@ redact_secrets = true  # auto-redact detected credentials (default)

 Configurable at runtime via the admin Settings tab.

-### Merge semantics (heuristic + LLM judge)
-
-The chip is a **merge** of the two detectors (issue #560, "show, annotated"),
-not a winner-take-all:
-
- `risk_level` = **max**(heuristic, llm) and `flags` = **union**. A positive
-  from either detector surfaces; a negative ("none") or failed/absent LLM
-  **never lowers** a heuristic positive. The judge reads adversarial tool
-  output, so it may raise the alarm but must not be able to hide a
-  deterministic regex finding — defeating the judge can't erase the tripwire.
- Credential **redaction** is a heuristic-only signal the LLM cannot override.
- When the judge returned a verdict, its OWN verdict rides along as
-  annotation (`judge_risk` / `confidence` / `reasoning` / `judge_model`) so
-  the operator sees the judge's opinion even when it disagrees with the
-  displayed (merged) risk.
-
-The same merge runs live and on reconnect (both call
-`output_guard.merge_guard_display_payload`), so the chip can't drift between
-the two surfaces.
-
-The MODEL on the other side of the conversation is shown the merged
-`risk_level` + `flags` (via the `GuardAdvisory` spliced into the tool-result
-envelope), but is **never** told the judge cleared a finding — a judge fooled
-into "none" must not get to talk the model out of caution. The judge's
-"benign" verdict is operator-facing only.
-
 ### SSE event: `output_warning`

-When the merged finding is non-clean (or credentials were redacted), an
-`output_warning` SSE event is emitted to the frontend. A regex-only finding:
+When the output guard detects risk signals, an `output_warning` SSE event is
+emitted to the frontend:

 ```json
 {
@@ -456,50 +386,17 @@ When the merged finding is non-clean (or credentials were redacted), an
  "flags": ["credential_leak"],
  "annotations": ["API key detected (sk-proj-...)"],
  "output_length": 1024,
-  "redacted": true,
-  "tier": "heuristic"
+  "redacted": true
 }
 ```

-When the LLM judge returned a verdict, `tier` is `"llm"` and the event carries
-the judge's own verdict as annotation. Here the regex flagged MEDIUM but the
-judge assessed the output benign — the finding still surfaces (`risk_level`
-stays MEDIUM), annotated with the judge's dissent (`judge_risk: "none"`):
+The web UI renders this as an inline warning after the tool result. The CLI
+shows a colored terminal warning. The server forwards it as an
+`OutputWarningEvent` for console subscribers.

-```json
-{
-  "type": "output_warning",
-  "call_id": "call_def456",
-  "func_name": "web_fetch",
-  "risk_level": "medium",
-  "flags": ["camouflaged_injection"],
-  "annotations": ["Authority-framed directive embedded in the document."],
-  "output_length": 8192,
-  "redacted": false,
-  "tier": "llm",
-  "judge_risk": "none",
-  "confidence": 0.92,
-  "reasoning": "Legitimate analyst commentary; no injection.",
-  "judge_model": "gpt-5-mini"
-}
-```
-
-`judge_risk` (the judge's OWN risk verdict, which may differ from the merged
-`risk_level`), `confidence` (0.0–1.0), `reasoning`, and `judge_model` are
-present only on the `"llm"` tier. The identical shape is projected onto
-history replay by `build_merged_output_assessment_payload`, so the inline chip
-renders the same live and on refresh.
-
-The web UI renders this as an inline warning after the tool result — the
-`"llm"` tier adds a `⚖ LLM · NN%` badge (showing the judge's verdict when it
-differs from the displayed risk, e.g. `⚖ LLM: none · 92%`) and the judge's
-rationale. The CLI shows a colored terminal warning. The server forwards it as
-an `OutputWarningEvent` for console subscribers.
-
-Assessments are persisted to the `output_assessments` table (one row per
-`(call_id, tier)`) for calibration. Raw tool output is never stored — only
-metadata: flags, risk level, annotations, output length, redaction status,
-and — for the LLM tier — confidence, reasoning, judge model, and latency.
+Assessments are persisted to the `output_assessments` table for v2
+calibration. Raw tool output is never stored — only metadata (flags, risk
+level, annotations, output length, redaction status).

 ### Session-level skill scan warning

@@ -1,117 +0,0 @@
-# MCP OAuth — per-user authorization for MCP servers
-
-Turnstone supports **per-(user, MCP server) OAuth 2.1 + PKCE** delegation so each Turnstone user authorizes a remote MCP server with their own identity, rather than sharing a single bearer token across the deployment. This is the right shape for MCP servers that expose user-specific data (a personal CRM, an email inbox, a calendar) and for MCP servers that want per-user audit attribution.
-
-Per-user OAuth is opt-in per `mcp_servers` row. Local-auth Turnstone installs with no `oauth_user` rows exercise zero new code paths — the entire feature is dark by default.
-
-> **Note**: This is a separate authorization layer from Turnstone's own user authentication. A user who logs into Turnstone with a local username + password can still authorize a per-server OAuth MCP server. OIDC SSO and per-server OAuth are orthogonal.
-
---
-
-## When to use which `auth_type`
-
-The MCP server admin form exposes three authorization modes ("Multitenant Authorization"):
-
-| `auth_type` | What it means | When to use |
-|---|---|---|
-| `none` | No headers attached. Open MCP server (or one gated by network policy only). | Internal MCP servers on a trusted network. |
-| `static` | One static bearer token, configured per server, sent on every request from every user. | Service-to-service MCP servers where per-user attribution doesn't matter, or single-tenant deployments. |
-| `oauth_user` *(recommended for user-data servers)* | Each user authorizes separately via OAuth 2.1 + PKCE; Turnstone stores per-user tokens encrypted at rest. | MCP servers that expose user-specific data or that want per-user audit attribution. |
-
-Switching `auth_type` away from `oauth_user` orphans existing per-user tokens. Use the admin **bulk-revoke** affordance on the server row (Phase 9) to clear them, or let them expire naturally — they're inert without the matching `auth_type` value.
-
---
-
-## Prerequisites for `auth_type=oauth_user`
-
-1. **Encryption key**. Tokens are stored encrypted with Fernet. Set `[security] mcp_token_encryption_key` in `config.toml` (Turnstone won't start with an `oauth_user` row configured but no key installed). Rotate via `MultiFernet` — add the new key first, then later remove the old one once all rows have been re-encrypted.
-
-2. **MCP server publishes RFC 9728 PRM and RFC 8414 AS metadata** *or* you configure the AS URL override on the server row. PKCE S256 is mandatory; Turnstone refuses to connect to authorization servers that don't advertise `code_challenge_methods_supported: ["S256"]`.
-
-3. **OAuth client registration**. Two paths:
-   - **Pre-registered** (most common): you create an OAuth client at the authorization server (manually, via admin console, or via Terraform), then paste the `client_id` / `client_secret` into the Turnstone admin form.
-   - **Dynamic client registration** (RFC 7591): if the AS supports it and you select that mode in the admin form, Turnstone registers a client at first use and persists the `client_id` automatically.
-
-4. **Redirect URI** registered at the authorization server: `https://your-turnstone-host/v1/api/mcp/oauth/callback`.
-
---
-
-## Configuration
-
-### Per-server fields (admin UI)
-
-| Field | Required | Description |
-|---|---|---|
-| Server URL | Yes | The MCP server's `streamable-http` base URL. |
-| Multitenant Authorization | Yes | `none` / `static` / `oauth_user` (recommended). |
-| Authorization Server URL | No | Override for RFC 9728 PRM discovery. Set when your AS endpoint differs from the MCP server URL (e.g., corporate AS protecting a third-party MCP). When unset, Turnstone falls back to PRM discovery against the MCP server itself. |
-| Client Registration | Yes (oauth_user) | `preregistered` or `dynamic`. |
-| Client ID | Yes (preregistered) | OAuth 2.0 client ID. Stored unencrypted. |
-| Client Secret | Optional (write-only) | OAuth 2.0 client secret (confidential client). Encrypted at rest. Written but never re-read by the API; field stays masked. |
-| Scopes | No | Space-separated default scope set requested at the authorize endpoint. Per-tool step-up may union additional scopes from a server's `insufficient_scope` response. |
-| Audience | No | RFC 8707 `resource=` parameter sent on every authorize and token request. Defaults to the MCP server URL when unset. Validate against the `aud` claim in returned JWT tokens. |
-
-### Encryption key
-
-```toml
-[security]
-mcp_token_encryption_key = "base64-fernet-key"
-# For rotation, list the keys in priority order — first is used for new
-# writes, all are tried for reads.
-# mcp_token_encryption_keys = ["new-key", "old-key"]
-```
-
-Keep this in `config.toml` rather than environment variables. An in-process LLM with shell-tool access can read the server's environment via `env` / `os.environ` and exfiltrate any secret stored there; secrets in `config.toml` are only loaded into the server at startup and never re-read on a tool-driven path, so a prompt-injection attack against the agent cannot reach them.
-
---
-
-## Lifecycle
-
-1. **First tool call** for a user against an `oauth_user` MCP server: pool dispatch finds no stored token, returns `mcp_consent_required` to the agent. Dashboard renders an inline "Connect" action card.
-
-2. **User clicks Connect**: opens `/v1/api/mcp/oauth/start?server=<name>` in a popup. Browser redirects through the AS authorize endpoint, user grants consent, AS redirects back to `/v1/api/mcp/oauth/callback`. Turnstone exchanges code → tokens via PKCE, validates audience, encrypts, persists in `mcp_user_tokens`, redirects user back to the originating URL.
-
-3. **Subsequent tool calls** by the same user against the same server reuse the persisted token via the per-(user, server) session pool. Tokens auto-refresh via the refresh-token grant when expired; failed refresh emits `mcp_consent_required` to drive re-consent.
-
-4. **Step-up scope**: when a tool call hits `403` with `WWW-Authenticate: error="insufficient_scope"`, Turnstone emits `mcp_insufficient_scope` with the parsed scope set; the dashboard offers a "Connect with additional scopes" affordance that opens `/v1/api/mcp/oauth/start?server=<name>&scopes=<extra>` so the union of original + new scopes flows into the AS authorize request.
-
-5. **User revoke** (settings modal): `DELETE /v1/api/mcp/oauth/connections/{server_name}` runs the authoritative local delete + best-effort RFC 7009 upstream revoke (fire-and-forget, capped at 256 concurrent in-flight tasks).
-
-6. **Admin bulk-revoke** (Phase 9): `POST /v1/api/admin/mcp-servers/{name}/bulk-revoke` drops every user's token for the server. Upstream RFC 7009 revoke is intentionally **not** attempted in bulk (avoids N upstream HTTP calls per admin click); tokens at the AS expire naturally. Use the per-user revoke endpoint if you need guaranteed upstream invalidation.
-
---
-
-## Admin status indicators
-
-The MCP Servers admin tab shows per-server status pills (Phase 9):
-
- **Consented users count** — distinct users with a non-expired token for this server. Surfaced as a `bulk-revoke (N)` button when ≥1; clicking it opens a confirmation dialog. Hidden when 0.
- **Last refresh** — timestamp + outcome (`ok` / `error:ClassName`) of the most recent manual or auto-reconnect refresh. Per node. Absent until at least one refresh has occurred (renders as "never" in the admin UI).
-
-Additional indicators (circuit-breaker state, encryption-key mismatch) are exposed via `get_server_status` on the API but do not yet have a dedicated admin pill — operators see them today via the per-server status text + error tooltip and in audit logs. A future phase may surface these as discrete pills.
-
---
-
-## Auth-type transitions
-
-| From | To | What happens |
-|---|---|---|
-| `none` / `static` → `oauth_user` | — | New code path activates for this server. Existing static headers (if any) are no longer sent. Users must authorize on first use. |
-| `oauth_user` → `none` / `static` | — | Existing `mcp_user_tokens` rows are **orphaned** — inert without a matching `auth_type`. Use admin bulk-revoke to drop them, or let them expire. Switching back to `oauth_user` later re-activates the orphaned rows if they haven't been deleted. |
-| OAuth `client_id` or `client_secret` rotated | — | Existing tokens may stop refreshing if the AS treats them as bound to the previous client. Bulk-revoke after rotation. |
-
-The orphan-by-default behavior is chosen so switching back to `oauth_user` is non-destructive. Bulk-revoke is the explicit cleanup path.
-
---
-
-## Troubleshooting
-
-| Symptom | Likely cause | Action |
-|---|---|---|
-| `mcp_consent_required` even after consenting | Token persistence failed, or refresh-token rejected by AS | Check audit log for `mcp_server.oauth.persist_failed` or `mcp_server.oauth.token_revoked`. Re-consent via settings modal. |
-| `mcp_token_undecryptable_key_unknown` | Encryption key rotated without keeping the previous key in the keyring | Add the previous key back to `mcp_token_encryption_keys` until all rows have been re-encrypted, then drop. |
-| `mcp_oauth_url_insecure` | MCP server URL is `http://` (not `https://`) on a non-loopback host | Use `https://`. Per-user bearers must not transit cleartext. |
-| Tools fail in scheduled / Discord / Slack runs | OAuth-MCP requires browser-based consent | Users must pre-consent via the web UI. Phase 9 dashboard badge surfaces deferred consents from these runs on next login. |
-| Circuit breaker open repeatedly | Transport-level errors on the MCP server (DNS, TLS, 5xx) | Check the per-server error pill; auth errors do not trip the breaker. |
-
-See also: `docs/operations/mcp-oauth-headless.md` for the cron / channel-driven run caveat.
@@ -39,19 +39,18 @@ are set.
 | `TURNSTONE_OIDC_ROLE_CLAIM` | No | — | ID token claim containing role/group values (see [Role Mapping](#role-mapping)) |
 | `TURNSTONE_OIDC_ROLE_MAP` | No | — | Mapping from claim values to Turnstone role IDs (see [Role Mapping](#role-mapping)) |
 | `TURNSTONE_OIDC_PASSWORD_ENABLED` | No | `true` | Set to `false` to hide the password form and block all username/password logins (including admin). API tokens continue to work. |
-| `TURNSTONE_OIDC_REDIRECT_BASE` | Yes | — | Externally-reachable origin for the OIDC redirect URI (e.g. `https://app.example.com`). Without this, OIDC will refuse to start. The previous Host-header fallback was unsafe under permissive reverse proxies. |
-| `TURNSTONE_OIDC_TRUSTED_ENDPOINT_HOSTS` | No | — | Comma-separated list of additional hostnames whose endpoints the IdP discovery document is allowed to reference. See [Cross-host endpoints](#cross-host-endpoints). |
+| `TURNSTONE_OIDC_REDIRECT_BASE` | No | — | Externally-reachable origin for the OIDC redirect URI (e.g. `https://app.example.com`). Recommended when running behind a reverse proxy. When unset, derived from the request Host header. |

-All four required fields — issuer, client ID, client secret, and
-`TURNSTONE_OIDC_REDIRECT_BASE` — must be set. If any are missing OIDC
-is disabled at startup (an error is logged when only `redirect_base`
-is missing) and the login screen shows only the password form.
+OIDC is enabled when all three required fields (issuer, client ID, client
+secret) are non-empty. If any is missing, OIDC is silently disabled and
+the login screen shows only the password form.

-### Redirect base (required)
+### Reverse Proxy / Load Balancer

-`TURNSTONE_OIDC_REDIRECT_BASE` pins the redirect URI sent to the identity
-provider to a known externally-visible origin. Set it to the public origin
-of your Turnstone deployment:
+When Turnstone runs behind a reverse proxy, the internal `Host` header may
+not match the externally-reachable URL. Set `TURNSTONE_OIDC_REDIRECT_BASE`
+to the public origin so the redirect URI sent to the identity provider is
+correct:

 ```bash
 TURNSTONE_OIDC_REDIRECT_BASE=https://app.example.com
@@ -61,44 +60,6 @@ The resulting callback URL will be
 `https://app.example.com/v1/api/auth/oidc/callback` — register this as the
 authorized redirect URI in your identity provider.

-OIDC will refuse to start when this variable is unset. There is no
-Host-header fallback: a permissive reverse proxy or direct backend access
-would otherwise let an attacker spoof `Host` and steer the IdP redirect
-to a callback origin they control.
-
-### Cross-host endpoints
-
-By default, every endpoint in the IdP discovery document
-(`token_endpoint`, `jwks_uri`, `userinfo_endpoint`) must share the
-issuer's `(scheme, host, port)`. This prevents a hostile or compromised
-IdP from redirecting the token-exchange POST (which carries
-`client_secret`) to an arbitrary host, and prevents JWKS fetches from
-being aimed at internal services.
-
-A few public IdPs legitimately split endpoints across hostnames. Google
-is the canonical example:
-
-| Field | Hostname |
-|-------|----------|
-| issuer | `accounts.google.com` |
-| token_endpoint | `oauth2.googleapis.com` |
-| jwks_uri | `www.googleapis.com` |
-| userinfo_endpoint | `openidconnect.googleapis.com` |
-
-Google's set is built in — operators using `https://accounts.google.com`
-need no extra configuration.
-
-For other IdPs whose discovery document references a non-issuer host,
-extend the allow-list explicitly:
-
-```bash
-TURNSTONE_OIDC_TRUSTED_ENDPOINT_HOSTS=token.example.com,keys.example.com
-```
-
-The same scheme / no-userinfo / SSRF rules apply to allow-listed hosts —
-this knob only relaxes the same-origin check, not the security gates.
-Each entry is a hostname (no scheme, no path).
-
 ### config.toml alternative

 ```toml
@@ -237,19 +198,6 @@ TURNSTONE_OIDC_ROLE_MAP="admin:builtin-admin,engineering:builtin-operator,viewer
  the user authenticates via OIDC, so new group memberships are picked
  up on the next login.

-### `assigned_by` markers
-
-Role assignments record an `assigned_by` value that controls how the
-sync logic treats them. OIDC-driven flows use two distinct markers:
-
- `oidc` — set by claim-driven role mapping; revoked automatically on
-  the next login when the corresponding claim value is no longer
-  present.
- `oidc-default` — applied to brand-new OIDC users who have no
-  claim-mapped roles, as a safety net so they still get
-  `builtin-viewer` access on first login. Survives subsequent logins
-  regardless of claim contents and is never revoked by `apply_role_mapping`.
-
 ### Built-in Roles

 | Role ID | Permissions |
@@ -427,27 +375,10 @@ callback validation. Entries are automatically cleaned up after 5 minutes.

 ### "OIDC not configured"

-All four required environment variables must be set:
-`TURNSTONE_OIDC_ISSUER`, `TURNSTONE_OIDC_CLIENT_ID`,
-`TURNSTONE_OIDC_CLIENT_SECRET`, and `TURNSTONE_OIDC_REDIRECT_BASE`.
-Check that none are empty or whitespace-only.
-
-### "OIDC enabled but TURNSTONE_OIDC_REDIRECT_BASE is unset"
-
-This error is logged when the three credential variables are set but
-`TURNSTONE_OIDC_REDIRECT_BASE` is missing. OIDC is disabled at startup
-to prevent Host-header-derived redirect URI spoofing. Set the variable
-to your service's externally-visible origin (e.g.
-`https://app.example.com`) and restart the server. See
-[Redirect base](#redirect-base-required) for the rationale.
-
-### Discovery silently disables OIDC with "host does not match issuer"
-
-The IdP discovery document points `token_endpoint`, `jwks_uri`, or
-`userinfo_endpoint` at a hostname that doesn't share the issuer's
-origin. If the IdP is legitimate, add the additional hostname(s) to
-`TURNSTONE_OIDC_TRUSTED_ENDPOINT_HOSTS`. Google is allow-listed
-automatically; see [Cross-host endpoints](#cross-host-endpoints).
+All three required environment variables must be set:
+`TURNSTONE_OIDC_ISSUER`, `TURNSTONE_OIDC_CLIENT_ID`, and
+`TURNSTONE_OIDC_CLIENT_SECRET`. Check that none are empty or
+whitespace-only.

 ### "Login session expired"

@@ -94,7 +94,7 @@ cannot bypass the proxy.
 |--------|-------|---------|
 | `openai_api` | `api.openai.com` | OpenAI LLM API |
 | `anthropic_api` | `api.anthropic.com` | Anthropic LLM API |
-| `searxng` | `searxng:8080` (bundled service) | Web search backend |
+| `tavily_api` | `api.tavily.com` | Web search fallback |
 | `skills_registry` | `skills.sh` | Skill discovery |
 | `github_api` | `api.github.com` (read-only L7), `raw.githubusercontent.com` | Skill fetch, GitHub API |
 | `mcp_registry` | `registry.modelcontextprotocol.io` (read-only L7) | MCP server discovery |
@@ -1,29 +0,0 @@
-# MCP OAuth in headless / scheduled / channel-driven runs
-
-**Constraint**: OAuth-MCP servers (`auth_type=oauth_user`) require browser-based user consent. Users must pre-consent via the web UI before any run that cannot drive a browser redirect.
-
-**Affected surfaces**:
-
- Scheduled workstreams (`turnstone-console` task scheduler).
- Discord adapter runs.
- Slack adapter runs.
- Any future channel adapter without an interactive browser session.
-
-**What happens when consent is missing**:
-
-A tool call against an `oauth_user` server returns a structured `mcp_consent_required` error to the agent. The agent surfaces the deferred work in its output. Turnstone persists a record to `mcp_pending_consent` so the dashboard badge surfaces the deferred consent need to the user on next login.
-
-**Recovery**:
-
-The user opens the dashboard, sees the gear-icon badge counting pending consents, opens the settings modal, clicks Connect for each affected server, and completes the OAuth dance. The pending-consent record is cleared by the OAuth callback handler on success. Subsequent scheduled / channel runs use the freshly-stored token.
-
-**Pre-consent recipe**:
-
-Before scheduling a workstream that depends on an `oauth_user` MCP server, the user should:
-
-1. Open the dashboard.
-2. Open the settings modal (gear icon).
-3. Click Connect on each MCP server the schedule will use.
-4. Confirm consent in the popup.
-
-This stores tokens that the scheduled run will reuse. Refresh-token rotation is handled transparently on the run side; only the first consent requires browser interaction.
@@ -108,7 +108,7 @@ pgbouncer:
  maxClientConn: 5000
  maxDbConnections: 80
 ```
-
+:
 ---

 ## Configuration reference
@@ -199,28 +199,4 @@ does not support prepared statements. Turnstone's SQLAlchemy layer does
 not use server-side prepared statements by default, so this is not an
 issue.

-**LISTEN / NOTIFY not supported in transaction mode** — PgBouncer's
-transaction pooling assigns a real server connection only for the
-duration of each transaction, then returns it to the pool. PostgreSQL
-`LISTEN` is session state — a transaction-pooled client can't hold the
-multi-statement session a long-lived `LISTEN` needs. The console's
-`NotifyDispatcher` (reactive node discovery via the `services` channel)
-therefore opens a **dedicated, direct-to-Postgres** connection that
-bypasses PgBouncer.
-
-Configure via `config.toml` `[database] listen_url` (preferred —
-co-located with the main `url`) or the `TURNSTONE_DB_LISTEN_URL` env var
-(config.toml wins when both are set). Defaults to the main DB URL when
-unset.
-
-| Setting | Behaviour |
-|---|---|
-| unset | Listener uses `TURNSTONE_DB_URL` as-is. Fine when PgBouncer is in **session** mode, or when there's no pooler in front of Postgres. With transaction-mode PgBouncer the listener's `LISTEN` will fail and the dispatcher retries with exponential backoff (1 s → 30 s cap) without ever succeeding. Reactive NOTIFY-driven node discovery is silently lost; the cluster collector's 60 s `_discovery_loop` is the only remaining backstop. |
-| set to direct-to-PG URL (e.g. `postgresql://…/turnstone`) | Listener bypasses PgBouncer for its one dedicated connection. Reactive discovery latency drops from up-to-60 s to ~500 ms. The rest of the storage layer continues to go through PgBouncer in transaction mode. |
-
-Set this whenever PgBouncer is in transaction mode (the recommended
-setting per this doc). The override only adds one long-lived PG
-connection per console process — sized into the cluster's
-`max_connections` budget alongside the pool.
-
 See also: [Docker deployment](docker.md) · [Security](security.md)
@@ -6,9 +6,10 @@ Turnstone ships several parallel release tracks from a single PyPI package.

 | Track | Versions | Branch | Docker tags | PyPI install |
 |-------|----------|--------|-------------|--------------|
-| **Stable 1.5** | `1.5.x` | `stable/1.5` | `:1.5.x`, `:1.5` | `pip install 'turnstone==1.5.*'` |
-| **Stable 1.6** | `1.6.x` | `stable/1.6` | `:1.6.x`, `:1.6`, `:stable`, `:latest` | `pip install turnstone` |
-| **Experimental** | `1.7.0aN` | `main` | `:1.7.0aN`, `:experimental` | `pip install turnstone --pre` |
+| **Legacy 1.0** | `1.0.x` | `stable/1.0` | `:1.0.x`, `:1.0` | `pip install 'turnstone==1.0.*'` |
+| **Stable 1.3** | `1.3.x` | `stable/1.3` | `:1.3.x`, `:1.3` | `pip install 'turnstone==1.3.*'` |
+| **Stable 1.4** | `1.4.x` | `stable/1.4` | `:1.4.x`, `:1.4`, `:stable`, `:latest` | `pip install turnstone` |
+| **Experimental** | `1.5.0aN` | `main` | `:1.5.0aN`, `:experimental` | `pip install turnstone --pre` |

 - **Stable** tracks receive bugfixes only.  The most-recent stable minor
  owns the `:stable` / `:latest` Docker tags and the default PyPI
@@ -16,10 +17,8 @@ Turnstone ships several parallel release tracks from a single PyPI package.
 - **Experimental** (always on `main`) receives new features. May be
  rough around the edges.
 - When experimental matures, it is promoted to a new stable minor via
-  a `stable/X.Y` branch. One prior stable track is maintained alongside
-  the current one; at each promotion the oldest track is retired — its
-  branch is deleted, while its tags and released artifacts remain
-  available.
+  a `stable/X.Y` branch; older stable branches continue to receive
+  security fixes until explicitly retired.

 ## Version Scheme

@@ -34,17 +33,17 @@ Turnstone ships several parallel release tracks from a single PyPI package.
 ## Releasing an Experimental Version (from main)

 ```bash
-scripts/release.sh 1.7.0a2 --push
+scripts/release.sh 1.5.0a2 --push
 ```

-This bumps `pyproject.toml` + `turnstone/__init__.py`, regenerates `uv.lock`, commits, tags `v1.7.0a2`, and pushes. CI runs, then publish + Docker workflows fire automatically.
+This bumps `pyproject.toml` + `turnstone/__init__.py`, regenerates `uv.lock`, commits, tags `v1.5.0a2`, and pushes. CI runs, then publish + Docker workflows fire automatically.

 ## Releasing a Stable Patch (from stable/X.Y)

 ```bash
-git checkout stable/1.6
+git checkout stable/1.4
 git cherry-pick <commit-hash>    # bugfix from main
-scripts/release.sh 1.6.1 --push
+scripts/release.sh 1.4.1 --push
 ```

 ## Promoting Experimental to Stable
@@ -53,19 +52,19 @@ When `main` is ready for a stable release:

 ```bash
 # 1. Tag the stable release on main
-scripts/release.sh 1.6.0 --push
+scripts/release.sh 1.5.0 --push

 # 2. Create the stable maintenance branch from that tag
-git branch stable/1.6 v1.6.0
-git push origin stable/1.6
+git branch stable/1.5 v1.5.0
+git push origin stable/1.5

 # 3. Start the next experimental cycle on main
-scripts/release.sh 1.7.0a1 --push
+scripts/release.sh 1.6.0a1 --push
 ```

-The previous stable branch continues to receive security-only patches;
-the track before it is retired at each promotion (at 1.6.0:
-`stable/1.5` stays maintained, `stable/1.4` is retired).
+The previous stable branch (`stable/1.4`) continues to receive
+security-only patches; older tracks (`stable/1.0`, `stable/1.3`) are
+retired when they fall out of support.

 ## CI/CD Pipeline

@@ -77,6 +77,7 @@ Both `TurnstoneServer` (sync) and `AsyncTurnstoneServer` (async) expose:
 | | `delete_attachment(ws_id, attachment_id)` | `StatusResponse` |
 | **Chat** | `send(message, ws_id)` | `SendResponse` |
 | | `approve(*, ws_id, approved, feedback, always)` | `StatusResponse` |
+| | `plan_feedback(*, ws_id, feedback)` | `StatusResponse` |
 | | `command(*, ws_id, command)` | `StatusResponse` |
 | | `cancel(ws_id, *, force=False)` | `StatusResponse` |
 | **Streaming** | `stream_events(ws_id)` | `Iterator[ServerEvent]` |
@@ -133,12 +134,10 @@ SSE events are deserialized into typed dataclasses. Use `event.type` to discrimi
 | `tool_result` | `ToolResultEvent` | `call_id`, `name`, `output`, `is_error` |
 | `tool_output_chunk` | `ToolOutputChunkEvent` | `call_id`, `chunk` |
 | `status` | `StatusEvent` | `prompt_tokens`, `total_tokens`, `pct`, `effort`, `cache_creation_tokens`, `cache_read_tokens` |
+| `plan_review` | `PlanReviewEvent` | `content` |
 | `error` | `ErrorEvent` | `message` |
 | `info` | `InfoEvent` | `message` |
 | `stream_end` | `StreamEndEvent` | — |
-| `state_change` | `StateChangeEvent` | `state` ∈ `running`/`thinking`/`attention`/`idle`/`error` |
-| `in_progress_snapshot` | `InProgressSnapshotEvent` | `content`, `reasoning` (one-shot mid-stream refresh resume) |
-| `approval_resolved` | `ApprovalResolvedEvent` | `approved`, `feedback` |
 | `cancelled` | `CancelledEvent` | — |

 **Global events** (from `stream_global_events()`):
@@ -67,7 +67,7 @@ Scopes are hierarchical — higher scopes imply all lower ones.
 | Method | Path pattern | Required scope |
 |--------|-------------|----------------|
 | GET | Any protected path | `read` |
-| POST | `/api/command` | `write` |
+| POST | `/api/plan`, `/api/command` | `write` |
 | POST | `/api/workstreams/new`, `/api/cluster/workstreams/new` | `write` |
 | POST | `/api/workstreams/{ws_id}/{send,cancel,close,delete,open,refresh-title,title,attachments}` | `write` |
 | DELETE | `/api/workstreams/{ws_id}/send` (dequeue), `/api/workstreams/{ws_id}/attachments/{attachment_id}` | `write` |
@@ -59,32 +59,20 @@ from ConfigStore. Model names and context windows are now configured per-model
 in the Models tab. A startup warning is logged if these keys appear in
 `config.toml`.

-### Reasoning persistence (per-model)
+### Plan / task agent overrides

-Two boolean flags on `model_definitions` (migration 052) control how
-reasoning text round-trips per model:
-
-| Flag | Default | Effect |
-|------|---------|--------|
-| `surface_persisted_reasoning` | `True` | Surface stored reasoning text on `/history` payloads so a page reload re-renders the reasoning bubble. **Storage of reasoning bytes is independent of this flag** — they ride in `provider_data` regardless. |
-| `replay_reasoning_to_model` | `False` | Send stored reasoning blocks back to the provider on subsequent turns. Capability-gated: only takes effect when the model's `ModelCapabilities.supports_reasoning_replay` is also `True`. Set on canonical OpenAI gpt-5*/o-series and Anthropic Claude entries; unknown / local-server models default to `False` so an operator who flips the flag on a model whose API doesn't understand reasoning replay silently no-ops rather than 400-ing. |
-
-Edit both via the admin Models tab. See the architecture doc for the
-provider-side mechanics (Anthropic `thinking`, OpenAI Responses
-`reasoning` + `include=["reasoning.encrypted_content"]`, synthetic
-`reasoning_text` for Chat Completions / vLLM / llama.cpp / Gemini-compat).
-
-### Task agent overrides
-
-`task_agent` sub-sessions resolve independently from the conversation model
-so operators can pick a cheaper/faster model for autonomous loops:
+`plan_agent` and `task_agent` sub-sessions resolve independently from the
+conversation model so operators can pick a cheaper/faster model for
+autonomous loops:

 | Setting | Purpose |
 |---------|---------|
-| `model.task_alias` | Alias used for `task_agent` sub-sessions. Falls back to `[model].agent_model` in config.toml, then the session's active model. |
+| `model.plan_alias` | Alias used for `plan_agent` sub-sessions. Falls back to `[model].plan_model` in config.toml, then `[model].agent_model`, then the session's active model. |
+| `model.task_alias` | Alias used for `task_agent` sub-sessions. Same fallback chain as `plan_alias`. |
+| `model.plan_effort` | Reasoning effort for `plan_agent` (`none` / `minimal` / `low` / `medium` / `high` / `xhigh` / `max`). Defaults to `high`. |
 | `model.task_effort` | Reasoning effort for `task_agent`. Empty string means "inherit from the session". |

-Both are live-editable from the Settings tab and take effect on the
+All four are live-editable from the Settings tab and take effect on the
 next sub-agent invocation — no restart required.

 ---
@@ -107,12 +95,12 @@ initialization:

 | Section | Settings |
 |---------|----------|
-| `model` | default_alias, temperature, max_tokens, reasoning_effort, task_alias, task_effort |
+| `model` | default_alias, temperature, max_tokens, reasoning_effort, plan_alias, task_alias, plan_effort, task_effort |
 | `session` | instructions, retention_days, compact_max_tokens, auto_compact_pct |
 | `tools` | timeout, truncation, agent_max_turns, skip_permissions, search, search_threshold, search_max_results |
 | `server` | workstream_idle_timeout, max_workstreams |
 | `cluster` | node_fan_out_limit, mcp_max_servers |
-| `mcp` | config_path, registry_url |
+| `mcp` | config_path, refresh_interval, registry_url |
 | `ratelimit` | enabled, requests_per_second, burst, trusted_proxies |
 | `health` | backend_probe_interval, backend_probe_timeout, circuit_breaker_threshold, circuit_breaker_cooldown |
 | `judge` | enabled, model, provider, base_url, api_key, confidence_threshold, max_context_ratio, timeout, read_only_tools, output_guard, redact_secrets, cancel_on_approval |
@@ -1,233 +0,0 @@
---
-name: import-conversation-history
-description: Use this skill when the user wants to import or migrate conversation history from another LLM chat or coding tool (e.g. ChatGPT, Claude.ai, Cursor, Copilot Chat, Aider, Gemini, a custom JSON export) into Turnstone. The skill teaches Turnstone's destination contracts — workstream identity, the OpenAI-shaped message rows, tool-call/result pairing, provider-fidelity blobs, attachments, and archive-vs-resumable choice — so the agent can map any source format onto them. Trigger phrases: "import my chats", "migrate this transcript into Turnstone", "bring my Claude.ai history over", "load this export as a workstream".
-version: 1.0.0
---
-
-# Importing Conversation History into Turnstone
-
-## Overview
-
-Source formats vary; the destination does not. Your job is to translate whatever the user hands you (JSON dump, ZIP export, scraped HTML, screenshot OCR, raw transcript) into Turnstone's internal shape: **one workstream row** plus an ordered sequence of **conversation rows** in OpenAI message format. This skill documents the destination so you can write a correct mapper for any source.
-
-Two questions to settle with the user before writing anything:
-
-1. **Archive or resumable?** An archive ("saved" workstream — `state="closed"`) is read-only history. A resumable workstream (`state="idle"`) lets the user continue the conversation; this only works cleanly when the source LLM matches a Turnstone-supported provider/model and tool definitions still resolve.
-2. **One workstream per source thread, or merge?** Default to one-to-one unless the user explicitly asks to merge.
-
-Default to **archive** when in doubt — resuming a foreign transcript with mismatched tool schemas or stale provider signatures will fail at the next turn.
-
-## Turnstone Data Model (the destination)
-
-Two tables carry the conversation:
-
-### `workstreams` (one row per imported thread)
-
-| Column | Required | Notes |
-|---|---|---|
-| `ws_id` | yes | 32-char lowercase hex. Auto-generate with `secrets.token_hex(16)` if you don't already have one. **First 4 hex chars are the routing bucket** — see "Identity & Routing" below. |
-| `name` | yes | Short title. Pull from source thread title; fall back to first ~60 chars of first user message. |
-| `state` | yes | `"closed"` for archive, `"idle"` for resumable. Never set `"running"` on import. |
-| `kind` | yes | `"interactive"` for normal threads. Do NOT use `"coordinator"` for imports — that's reserved for cluster-spawned coordinator workstreams. |
-| `parent_ws_id` | no | Leave NULL. Only set if you're importing a coordinator-spawned subtree and re-parenting it; rare. |
-| `user_id` | yes | Owner. Must exist in `users`; importer must know which Turnstone user owns the imported history. |
-| `node_id` | yes (multi-node) | Denormalized cache of the node that owns this `ws_id`'s bucket. Single-node deployments can leave it NULL or set it to the only node. |
-| `alias` | no | Human-typeable short name. Optional; must be unique cluster-wide if set. |
-| `title` | no | Auto-titled later by the LLM; safe to leave NULL on import. |
-| `skill_id`, `skill_version` | yes | Default `""` and `0` unless the source thread was scoped to a Turnstone skill. |
-| `created`, `updated` | yes | ISO8601 strings. Use the source's first/last message timestamps when available. |
-
-### `conversations` (many rows per thread, ordered by `id`/`timestamp`)
-
-| Column | Notes |
-|---|---|
-| `ws_id` | The workstream this row belongs to. |
-| `timestamp` | ISO8601 string. Preserve source timestamps; fall back to monotonically increasing values if unknown. **Order is canonical via `id` (autoincrement), not `timestamp`** — but always insert in conversational order so both agree. |
-| `role` | One of `system`, `user`, `assistant`, `tool`, `developer`. See role mapping below. |
-| `content` | Text. May be NULL for assistant rows that are *only* tool calls. |
-| `tool_name` | Set on `role="tool"` rows (the tool whose result this is). NULL otherwise. |
-| `tool_call_id` | Set on `role="tool"` rows (matches the assistant row's `tool_calls[].id`). NULL otherwise. |
-| `tool_calls` | JSON-encoded list, on `role="assistant"` rows that issued tool calls. OpenAI shape — see "Tool Calls" below. |
-| `provider_data` | JSON blob preserving provider-native content blocks (Anthropic `signature`, Gemini `thought_signature`, etc.). Optional; only matters for **resumable** imports against the same provider. Skip for archives. |
-
-The internal format is **OpenAI-shaped**, even when the source was Anthropic or Gemini. Providers translate at their own API boundary; storage stays uniform.
-
-## Identity & Routing (`ws_id`)
-
- `ws_id` is **32-char lowercase hex** (i.e. `secrets.token_hex(16)`).
- The **routing bucket** is `int(ws_id[:4], 16)` — the first 4 hex chars place this workstream on a specific node via the consistent hash ring.
- For multi-node imports: either insert through the console's routing proxy (which forwards to the owning node), or generate `ws_id`s and write directly to each node's database in batches grouped by bucket.
- For single-node imports: bucket math is irrelevant; any `ws_id` works.
- **Do not reuse the source platform's IDs as `ws_id`** unless they happen to be 32-char hex. Generate fresh; if you need the old ID for traceability, store it in `workstream_config` under a key like `import.source_id`.
-
-## Recommended Import Path
-
-Three options, in order of preference:
-
-### 1. Storage protocol (recommended for full history)
-
-Use `turnstone.core.storage.Storage.save_messages_bulk(rows)`. This is the canonical bulk-insert primitive and bypasses the LLM round-trip entirely.
-
-```python
-from turnstone.core.storage import get_storage  # construct via the same path the server uses
-
-storage = get_storage(...)  # see turnstone.core.storage.__init__ for the project's wiring
-
-storage.create_workstream(  # or whatever the project's exposed creator is — check turnstone/core/storage/_protocol.py
-    ws_id=ws_id,
-    user_id=user_id,
-    name=name,
-    state="closed",
-    kind="interactive",
-    ...
-)
-
-storage.save_messages_bulk([
-    {"ws_id": ws_id, "role": "user", "content": "Hello"},
-    {"ws_id": ws_id, "role": "assistant", "content": "Hi! What can I help with?"},
-    {"ws_id": ws_id, "role": "assistant", "content": None,
-     "tool_calls": json.dumps([{"id": "call_1", "type": "function",
-                                "function": {"name": "search", "arguments": "{\"q\":\"x\"}"}}])},
-    {"ws_id": ws_id, "role": "tool", "tool_name": "search", "tool_call_id": "call_1",
-     "content": "result text"},
-    # ...
-])
-```
-
-`save_messages_bulk` handles `timestamp` and the workstream's `updated` column internally, so you don't need to compute them per row. **Verify the exact creator signature** by reading `turnstone/core/storage/_protocol.py` — table layout has shifted across migrations and the Storage protocol is the source of truth.
-
-### 2. SDK `create_workstream(resume_ws=...)` (when the source is already a Turnstone workstream)
-
-Only useful for *Turnstone → Turnstone* re-parenting. Not relevant for foreign sources.
-
-### 3. SDK `create_workstream(initial_message=...)` + `send()` per turn (last resort)
-
-Only fits archives where the source had **no tool calls** and you don't care about preserving assistant turns verbatim. Each `send()` triggers a real LLM round-trip, which is expensive and rewrites assistant content. Don't use this for full history.
-
-## Role Mapping
-
-Common source-role conventions and how they map to Turnstone:
-
-| Source role | Turnstone `role` | Notes |
-|---|---|---|
-| `user`, `human` | `user` | Direct map. |
-| `assistant`, `ai`, `model`, `bot` | `assistant` | Direct map. |
-| `system` | `system` | Preserve only if it's content the user wrote (custom instructions). Drop boilerplate provider preambles — Turnstone composes its own system message. |
-| `developer` (OpenAI o-series) | `developer` | Preserve. |
-| `tool`, `function`, `tool_result` | `tool` | Must carry `tool_name` and `tool_call_id` matching the prior assistant row's `tool_calls[].id`. |
-| `tool_use` (Anthropic) | `assistant` with `tool_calls` | Anthropic emits tool calls *inside* an assistant message; flatten to OpenAI shape. |
-| `human_feedback`, `revision` | `user` | Treat as a follow-up user turn. |
-
-## Tool Calls (the most error-prone part)
-
-Turnstone stores tool calls in OpenAI's nested-function shape on the assistant row, and matches them with `role="tool"` result rows by `tool_call_id`.
-
-### Assistant row with tool calls
-
-```json
-{
-  "role": "assistant",
-  "content": null,
-  "tool_calls": [
-    {
-      "id": "call_abc123",
-      "type": "function",
-      "function": {
-        "name": "search_web",
-        "arguments": "{\"query\":\"turnstone import\"}"
-      }
-    }
-  ]
-}
-```
-
-`tool_calls[].function.arguments` is **a JSON-encoded string**, not an object. Source formats commonly get this wrong — Anthropic stores arguments as a parsed object, Gemini as a struct. Always re-serialize to a string.
-
-### Tool result row
-
-```json
-{
-  "role": "tool",
-  "tool_name": "search_web",
-  "tool_call_id": "call_abc123",
-  "content": "..."
-}
-```
-
-Pairing rules:
- Every assistant `tool_calls[].id` MUST be followed by exactly one `role="tool"` row with the matching `tool_call_id`, before the next user/assistant turn.
- If the source dropped the tool result (cut-off transcript), insert a synthetic `role="tool"` row with `content="[tool result missing in source]"` to keep the chain valid. An assistant row with an unanswered `tool_calls[].id` will break replay and any LLM round-trip.
- Multi-tool assistant turns: one `role="tool"` row per call, in any order, all before the next non-tool row.
-
-### Tool ID generation
-
-If the source used opaque tool IDs that aren't unique within a thread (some platforms reuse them), regenerate with a stable scheme like `f"call_{i}"` where `i` is a per-thread counter. Update both the assistant and tool rows together.
-
-## Provider Fidelity (`provider_data`)
-
-Skip this entirely for **archive** imports.
-
-For **resumable** imports against the same provider, populate `provider_data` to preserve provider-specific tool-call metadata that the next API round-trip will require:
-
- **Anthropic**: `signature` field on thinking blocks; required for round-tripping extended-thinking responses.
- **Gemini**: `thought_signature` on tool calls; required for fidelity.
- **OpenAI**: typically nothing to preserve.
-
-The runtime-side dict key is `_provider_content` (a list of provider-native blocks); the persisted column is `provider_data` (the same list, JSON-encoded). If you don't have provider-native blocks from the source — and you usually won't, because a foreign export won't include them — leave `provider_data` NULL. The first new turn will succeed without it, but the previous assistant turn's reasoning won't replay back to the model.
-
-## Attachments
-
-If the source thread had image or file attachments:
-
- **Size limits**: images ≤ 4 MiB, text documents ≤ 512 KiB. Reject or downsample anything bigger.
- **Allowed types**: server validates magic bytes for images and UTF-8-decodes for text. Binary blobs that aren't images won't pass.
- **Lifecycle**: pending → reserved → consumed. For imports, the cleanest path is to upload as pending and immediately consume by attaching to the relevant `conversations.id`.
-
-Two import paths:
-
-1. **Bulk-insert + post-attach**: insert messages first, get back the assistant/user `conversations.id`, then write `workstream_attachments` rows linking the file to `message_id`.
-2. **SDK multipart create**: `create_workstream(attachments=[...], initial_message=...)` for the *first* turn only — the server reserves and consumes them onto that turn. Doesn't help for mid-thread attachments.
-
-For full-history imports with multiple attachments at different turns, path (1) is the only option.
-
-## Validation Checklist
-
-Before declaring success, verify:
-
- [ ] `ws_id` is 32-char lowercase hex.
- [ ] `workstreams` row exists with the right `user_id`, `state`, `kind`.
- [ ] Conversation rows are inserted **in order** (autoincrement `id` will reflect insert order).
- [ ] Every assistant `tool_calls[].id` has a matching `role="tool"` row with the same `tool_call_id`.
- [ ] `tool_calls[].function.arguments` is a JSON-encoded **string**, not a parsed object.
- [ ] First message is typically `role="user"` (not `system`) — Turnstone composes its own system prompt at runtime.
- [ ] No empty assistant rows (`content=NULL` AND `tool_calls=NULL` is invalid).
- [ ] If multi-node: the `ws_id`'s bucket maps to a node that exists; `workstreams.node_id` matches.
- [ ] Round-trip test: run `Storage.load_messages(ws_id)` and confirm the reconstructed list matches what you inserted (modulo timestamps).
-
-## Anti-patterns
-
- **Don't import the source provider's system prompt verbatim.** Provider boilerplate ("You are Claude...", "You are ChatGPT...") will conflict with Turnstone's composed system message and confuse the model on resume. Drop it; preserve only user-authored custom instructions.
- **Don't preserve foreign tool definitions as Turnstone tools.** If the source had custom tools that don't exist in Turnstone, the assistant rows that called them are still valid history (archive), but the workstream is **not resumable** — mark `state="closed"`.
- **Don't fabricate `tool_call_id`s without re-pairing.** Mismatched ids silently break the replay chain on the next turn.
- **Don't skip the `tool_name` field on `role="tool"` rows.** Some load paths use it for display and audit; NULL there will render as "unknown tool".
- **Don't write through the LLM (`send()` per turn) for full history.** It's expensive, rewrites assistant turns, and rate-limits will bite long imports.
-
-## Quick Reference
-
-| Task | Path |
-|---|---|
-| Generate ws_id | `secrets.token_hex(16)` |
-| Bulk insert messages | `Storage.save_messages_bulk(rows)` |
-| Archive (read-only) | `state="closed"`, skip `provider_data` |
-| Resumable | `state="idle"`, populate `provider_data` if same provider |
-| Tool call id | OpenAI shape: `{"id": ..., "type": "function", "function": {"name": ..., "arguments": "<json string>"}}` |
-| Tool result row | `role="tool"`, `tool_name`, `tool_call_id`, `content` |
-| Source role → Turnstone role | See "Role Mapping" table |
-| Per-thread metadata | Store source IDs in `workstream_config` under `import.*` keys |
-
-## Files to read before writing the importer
-
- `turnstone/core/storage/_schema.py` — authoritative table definitions.
- `turnstone/core/storage/_protocol.py` — `save_message`, `save_messages_bulk`, `load_messages` signatures.
- `turnstone/core/session.py` (around the message-save section) — how the runtime constructs in-memory message dicts; mirror this shape on import to round-trip cleanly.
- `turnstone/api/server_schemas.py` — Pydantic shapes for the SDK paths if you go through HTTP.
@@ -8,7 +8,7 @@ inter-service communication, powered by [lacme](https://pypi.org/project/lacme/)
 ## Quick Start (Docker Compose)

 ```bash
-docker compose -f turnstone/deploy/compose.yaml -f deploy/docker-compose.tls.yml up
+docker compose -f compose.yaml -f deploy/docker-compose.tls.yml up
 ```

 This:
@@ -19,53 +19,6 @@ This:

 ---

-## Browser access (dashboard HTTPS)
-
-The mTLS above secures **service-to-service** traffic (node↔node, collector and
-routing proxy → nodes). The **console dashboard itself serves plain HTTP** — and
-must, because it is the cluster's ACME bootstrap endpoint: new nodes fetch
-`/acme/ca.pem` and provision their first cert over HTTP, before they have the CA
-to verify TLS. So the console cannot be HTTPS-only on its port.
-
-To put the **browser → console** hop on HTTPS, terminate TLS at a reverse proxy
-in front of the console. The dev stack (root `compose.yaml`) ships a `caddy`
-service that does exactly this — and it's the only published entry point, so the
-dashboard is HTTPS by default:
-
-```bash
-docker compose up
-# dashboard: https://localhost:${CONSOLE_HTTPS_PORT:-8443}
-```
-
-The production stack (`turnstone/deploy/compose.yaml`) bundles the same `caddy`
-service, so the dashboard is HTTPS there too. For a real domain and a publicly
-trusted cert, point Caddy at Let's Encrypt by editing `turnstone/deploy/Caddyfile`.
-
-```
-browser  --h2 / HTTPS-->  caddy:443  --h1.1 / HTTP-->  console:8090
-```
-
-Caddy uses its **own local CA** (`tls internal`, see `turnstone/deploy/Caddyfile`), so the
-setup is self-contained with no dependency on the console's ACME path. Trust the
-local root once to silence the browser warning:
-
-```bash
-docker compose exec caddy \
-  cat /data/caddy/pki/authorities/local/root.crt   # import into your OS/browser
-```
-
-**Can Caddy get its cert from the console's internal CA instead?** Technically
-yes — the console exposes a real ACME directory (`/acme/directory`) with
-auto-approval, so Caddy's `tls { ca http://console:8090/acme/directory }` would
-mint a cert for any name. It's not recommended as the default: lacme's ACME
-responder is built for turnstone's own client (interop with Caddy's client is
-unverified), it couples Caddy startup to the console, and the browser must trust
-a private CA either way — so it buys nothing over `tls internal`. For a publicly
-trusted cert (no warning), point Caddy at Let's Encrypt with a real domain
-instead.
-
---
-
 ## Architecture

 ```
@@ -88,32 +41,6 @@ Console (CA + ACME Server)
 - **Frontend cert** (HTTPS): From an external ACME CA (e.g. Let's Encrypt)
  if `tls.acme_directory` is set, otherwise self-issued from the internal CA.

-### Boot, retry, and fallback
-
-With `tls.enabled`, a node fetches the CA cert and requests its own cert
-during startup, retrying with exponential backoff (6 attempts, ~31 s total)
-— enough to absorb a whole-stack restart where every node races the console
-for its listener. If all attempts fail, the node **falls back to plain
-HTTP** (availability over confidentiality) and reports `"tls": "fallback"`
-in `GET /health`; a node serving HTTPS reports `"tls": "active"`, and the
-key is absent when TLS is disabled. Fallback persists until the next
-restart — it is not upgraded in place.
-
-### Container healthcheck under mTLS
-
-An mTLS listener rejects plain-HTTP probes at the socket, so
-`docker/healthcheck.py` falls back to HTTPS when the plain probe fails:
-it presents the node's own cert as the client cert and pins the cluster
-CA, using the PEM files the server writes at boot under
-`$TURNSTONE_TLS_PEM_DIR` (default `<tmpdir>/turnstone-tls`). The probe
-dials `localhost` for the TLS attempt — the internal CA issues DNS SANs
-only, so a literal-IP URL would fail verification. Cert renewal rewrites
-the PEM dir alongside the live listener swap, so the probe's client cert
-never outlives the served cert. With TLS disabled the plain probe succeeds
-and the PEM directory is never consulted. On bare metal with multiple
-nodes per host, set `TURNSTONE_TLS_PEM_DIR` per node (each boot clears
-stale `lacme-pem-*` dirs under its root).
-
 ---

 ## Configuration
@@ -246,15 +173,8 @@ const client = new TurnstoneServer({
 1. Node starts, connects to shared database (plain connection)
 2. Discovers console URL from `services` table
 3. Fetches CA root cert from `http://console/acme/ca.pem` (plain HTTP, TOFU)
-4. Requests a service cert via ACME (plain HTTP, JWS-signed). The cert's
-   primary domain / SAN is the node's **advertised host** (the host of
-   `TURNSTONE_ADVERTISE_URL`, e.g. `node-1`) — the name peers actually dial,
-   not the container hostname. This makes mTLS hostname verification succeed
-   and keys the cert by a stable name that survives container recreation.
-5. Starts auto-renewal (24h interval, re-issues before expiry) **scoped to its
-   own certificate**. Each node renews only its own cert; the shared store is
-   never swept wholesale. Renewed certs are hot-swapped into the live HTTPS
-   listener with no restart.
+4. Requests service cert via ACME protocol (plain HTTP, JWS-signed)
+5. Starts auto-renewal (24h interval, re-issues before expiry)
 6. All subsequent inter-service communication uses mTLS

 ### Console Startup Flow
@@ -263,9 +183,7 @@ const client = new TurnstoneServer({
 2. Initialize CA (load from DB or generate new root key)
 3. Mount ACME responder at `/acme` (serves `/ca.pem` natively)
 4. Issue console certs (internal + optional frontend)
-5. Start CA-direct auto-renewal (no network, signs directly), scoped to the
-   console's own cert, plus a periodic GC that reclaims cert rows for
-   long-departed nodes
+5. Start CA-direct auto-renewal (no network, signs directly)
 6. Register console URL in services table with heartbeat

 ---
@@ -277,31 +195,17 @@ const client = new TurnstoneServer({
 Certs are valid for 48 hours. If auto-renewal stopped (e.g. console was down),
 restart the service to re-request a cert.

-### Collector/proxy can't reach a node (TLS hostname mismatch)
-
-mTLS verifies a node's advertised host against the cert's SANs. Each node's
-cert is issued for the host in its `TURNSTONE_ADVERTISE_URL`, so that name is
-always a SAN automatically — you do **not** need to set `TURNSTONE_TLS_SANS`
-per node. Only set `TURNSTONE_TLS_SANS` to add *extra* names (e.g. a node
-fronted under a second hostname). Symptom if this is wrong: the console
-dashboard shows nodes as unreachable and `openssl s_client` reports the served
-cert's SANs don't include the dialed name.
-
 ### "No console service found"

 The console registers itself in the `services` table on startup. If the console
 hasn't started or the registration expired (1 hour TTL), nodes can't discover
 it. Use `--console-url` explicitly.

-### Browser HTTPS to the console
+### Let's Encrypt for console frontend

-The console serves plain HTTP (it's the ACME bootstrap endpoint — see
-[Browser access](#browser-access-dashboard-https)). Put browser traffic on
-HTTPS by terminating TLS at a reverse proxy; the `cluster` profile's `caddy`
-service does this with Caddy's local CA. For a publicly trusted cert, front the
-console with a proxy pointed at Let's Encrypt using a real domain. The
-`tls.acme_directory` setting only governs the console's internal/frontend cert
-material — it does **not** make the console listen on HTTPS itself.
+Set `tls.acme_directory` to `https://acme-v02.api.letsencrypt.org/directory`
+in the admin Settings tab. The console will request a publicly trusted cert
+for its HTTPS endpoint. Internal mTLS still uses the private CA.

 ### Verifying the cert chain

@@ -1,6 +1,6 @@
 # Tools Reference

-turnstone exposes 16 built-in tools plus any number of external MCP tools to the
+turnstone exposes 19 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
@@ -22,6 +22,7 @@ schema plus turnstone-specific metadata keys:
    "properties": { ... },
    "required": ["param1"]
  },
+  "agent": true,
  "task_agent": true,
  "auto_approve": true,
  "primary_key": "param1"
@@ -32,7 +33,8 @@ schema plus turnstone-specific metadata keys:

 | Key            | Type | Meaning |
 |----------------|------|---------|
-| `task_agent`   | bool | Tool is available to task sub-agents. |
+| `agent`        | bool | Tool is available to plan/task sub-agents (read-only subset). |
+| `task_agent`   | bool | Tool is available to task sub-agents (broader subset). |
 | `auto_approve` | bool | Tool runs without user confirmation (read-only, safe operations). |
 | `primary_key`  | str  | When the model sends a bare string instead of JSON args, map it to this parameter name. |

@@ -44,10 +46,12 @@ schema plus turnstone-specific metadata keys:

 | Name                | Description |
 |---------------------|-------------|
-| `TOOLS`             | All 28 loaded built-in tool definitions (interactive + coordinator union). Sessions send a kind-specific subset (`INTERACTIVE_TOOLS` or `COORDINATOR_TOOLS`). |
+| `TOOLS`             | All 19 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. |
-| `TASK_AUTO_TOOLS`   | Set of all tool names with `auto_approve: true` -- used by task-agent sub-sessions to skip confirmation for matching available tools. |
-| `BUILTIN_TOOL_NAMES`| Frozenset of all 28 built-in tool names (interactive + coordinator union). Used by tool search to distinguish always-on tools from deferrable MCP tools. |
+| `AGENT_AUTO_TOOLS`  | Set of tool names with `auto_approve: true` -- no user confirmation needed. |
+| `TASK_AUTO_TOOLS`   | Same as `AGENT_AUTO_TOOLS` (identical filter). |
+| `BUILTIN_TOOL_NAMES`| Frozenset of all 19 built-in tool names. Used by tool search to distinguish always-on tools from deferrable MCP tools. |
 | `PRIMARY_KEY_MAP`   | Dict mapping tool name to its `primary_key` parameter name. |

 ---
@@ -65,7 +69,7 @@ Tool execution follows a three-phase pipeline inside `ChatSession._execute_tools
 - Parses the JSON arguments (with fallback for malformed JSON).
 - If JSON parsing fails entirely, uses `PRIMARY_KEY_MAP` to map a bare string
  to the correct parameter.
- Dispatches to the matching `_prepare_{func_name}()` handler. There are 16
+- Dispatches to the matching `_prepare_{func_name}()` handler. There are 19
  built-in tools plus `tool_search` (synthetic, client-side BM25 fallback) and
  the generic `_prepare_mcp_tool()` handler for MCP tools.
 - Validates arguments and builds a preview dict containing:
@@ -107,6 +111,9 @@ Each item's `execute` callable is invoked:
  denials are tracked separately. This removes the need for text-prefix heuristics.
  Other tools deliver results atomically via
  `ui.on_tool_result(call_id, name, output, is_error=...)` only.
+- Special post-execution gate for `plan`: the plan output is shown to the user
+  for review, and the user can reject or annotate it.
+
 ---

 ## Tool Approval Flow
@@ -114,6 +121,7 @@ Each item's `execute` callable is invoked:
 **Auto-approved** (no user confirmation needed at runtime):
 - `read_file` -- reads files, no side effects
 - `search` -- grep-style search, no side effects
+- `man` -- reads man pages, no side effects
 - `memory` -- structured persistent memory (save/search/delete/list)
 - `recall` -- searches conversation history
 - `notify` -- sends notifications to linked channels (time-sensitive, auto-approved for urgency)
@@ -122,14 +130,16 @@ Each item's `execute` callable is invoked:
 - `bash` -- arbitrary command execution
 - `write_file` -- creates or overwrites files
 - `edit_file` -- modifies file content
+- `math` -- sandboxed computation (confirmation required despite being sandboxed)
 - `web_fetch` -- fetches a URL (SSRF-protected, but makes network requests)
- `web_search` -- web search via self-hosted SearxNG (makes network requests)
- `task_agent` -- spawns an autonomous sub-agent
+- `web_search` -- web search via Tavily API (makes network requests)
+- `task` -- spawns an autonomous sub-agent
+- `plan` -- spawns a planning sub-agent, plus post-execution review gate

 Note: The JSON schema metadata key `auto_approve` controls membership in
-`TASK_AUTO_TOOLS` (used for task agent sub-sessions). The actual runtime
-approval behavior is determined by the `needs_approval` field set in each
-`_prepare_*` method on `ChatSession`. These two mechanisms can differ.
+`AGENT_AUTO_TOOLS`/`TASK_AUTO_TOOLS` (used for agent sub-sessions). The actual
+runtime approval behavior is determined by the `needs_approval` field set in
+each `_prepare_*` method on `ChatSession`. These two mechanisms can differ.

 ---

@@ -155,9 +165,12 @@ Every tool defines a `primary_key`. The mapping is:
 | `write_file` | `content`   |
 | `edit_file`  | `old_string`|
 | `search`     | `query`     |
+| `math`       | `code`      |
+| `man`        | `page`      |
 | `web_fetch`  | `url`       |
 | `web_search` | `query`     |
 | `task_agent` | `prompt`    |
+| `plan_agent` | `goal`      |
 | `memory`     | `name`      |
 | `recall`     | `query`     |
 | `notify`     | `message`   |
@@ -181,7 +194,7 @@ Execute a bash command and return stdout + stderr.
 - **What it does**: Runs the command in a subprocess with a configurable timeout. Commands are sanitized and checked against a blocklist (e.g. `rm -rf /`). Environment variables containing secrets are scrubbed (`*_KEY`, `*_SECRET`, `*_TOKEN`, etc.).
 - **Output format**: Stdout is returned directly. Stderr lines are prefixed with `[stderr]` so the model can distinguish them. When the command itself redirects stderr to stdout (`2>&1`), no prefix is added. Output exceeding 256KB is truncated (head + tail preserved, middle replaced with a truncation notice).
 - **Auto-approve**: No -- requires user confirmation.
- **Agent availability**: `task_agent` only.
+- **Agent availability**: `task_agent` only (not available to plan sub-agents).

 ---

@@ -199,7 +212,7 @@ base64-encoded image data for supported image formats.
 - **What it does**: For text files, reads and returns content with line numbers. For image files (PNG, JPEG, GIF, WebP, BMP, TIFF, ICO), returns image data as multi-part content when the model supports vision, or a text description when it does not. SVG files are read as text. Images larger than 4 MB are rejected. Must be called before `edit_file` on the same path (the session tracks which files have been read).
 - **Vision support**: Controlled by `ModelCapabilities.supports_vision`. All commercial OpenAI and Anthropic models have vision enabled. Local models (vLLM, llama.cpp, NIM) default to off — enable via `[models.*.capabilities] supports_vision = true` in config.toml.
 - **Auto-approve**: Yes.
- **Agent availability**: `task_agent`.
+- **Agent availability**: `agent` and `task_agent`.

 ---

@@ -255,7 +268,7 @@ Show a unified diff between two files, or between a file and a provided string.

 - **What it does**: Returns unified diff output using Python's `difflib`. Binary files (containing null bytes) are rejected with a clear error. Files read through `diff_file` satisfy `edit_file`'s read guard — you can diff then edit without a separate `read_file` call. Large diffs are streamed with early cutoff at the tool truncation limit.
 - **Auto-approve**: Yes (read-only).
- **Agent availability**: `task_agent`.
+- **Agent availability**: `agent` and `task_agent`.

 ---

@@ -270,12 +283,44 @@ Search file contents for a regex pattern.

 - **What it does**: Recursively searches for the pattern using `grep -rn`. Returns matching lines with file paths and line numbers.
 - **Auto-approve**: Yes.
- **Agent availability**: `task_agent`.
+- **Agent availability**: `agent` and `task_agent`.
+
+---
+
+## Computation
+
+### math
+
+Execute Python code for math and computation in a sandbox.
+
+| Parameter | Type   | Required | Description |
+|-----------|--------|----------|-------------|
+| `code`    | string | yes      | Python code to execute. Must use `print()` for output. |
+
+- **What it does**: Runs Python code in a sandboxed environment with pre-imported libraries: `sympy`, `numpy`, `scipy`, `math`, `fractions`, `itertools`, `functools`, `collections`, `decimal`, `operator`, `random`, `re`, `string`. Common sympy names (`symbols`, `solve`, `simplify`, `sqrt`, `Matrix`, etc.) are pre-imported. `pytest` is also available for import.
+- **Installation**: `sympy`, `numpy`, `scipy`, and `pytest` require the `[sandbox]` extras group: `pip install turnstone[sandbox]` (included in `[all]`).
+- **Auto-approve**: Yes.
+- **Agent availability**: `agent` and `task_agent`.

 ---

 ## Information

+### man
+
+Read a man page.
+
+| Parameter | Type   | Required | Description |
+|-----------|--------|----------|-------------|
+| `page`    | string | yes      | The man page name (e.g. `grep`, `socket`, `printf`). |
+| `section` | string | no       | Manual section (e.g. `1` commands, `2` syscalls, `3` library). |
+
+- **What it does**: Returns the full formatted manual entry. Preferred over `bash('man ...')` or `web_search` for command/API documentation.
+- **Auto-approve**: Yes.
+- **Agent availability**: `agent` and `task_agent`.
+
+---
+
 ### web_fetch

 Fetch a URL and extract specific information from it.
@@ -287,7 +332,7 @@ Fetch a URL and extract specific information from it.

 - **What it does**: Fetches the URL, strips HTML to plain text, and uses the LLM to extract the answer to the question from the page content. Protected against SSRF (blocks private/internal IPs).
 - **Auto-approve**: No -- requires user confirmation (makes network requests).
- **Agent availability**: `task_agent`.
+- **Agent availability**: `agent` and `task_agent`.

 ---

@@ -299,55 +344,20 @@ Search the web using a text query.
 |---------------|---------|----------|-------------|
 | `query`       | string  | yes      | The search query. |
 | `max_results` | integer | no       | Max results to return (default 5, max 20). |
-| `category`    | string  | no       | Search category: `general` (default), `news`, `it` (code/tech), or `science`. Maps to SearxNG categories; the model picks per query. |
+| `topic`       | string  | no       | Search topic: `general`, `news`, or `finance` (default `general`). |

 - **What it does**: Searches the web and returns ranked results with titles, URLs, and content snippets. Uses provider-native search when available:
-  - **Anthropic**: Replaced at the API boundary with Anthropic's `web_search_20250305` server-side tool. Claude decides when to search; the API executes it and returns results with citations inline. No backend needed.
+  - **Anthropic**: Replaced at the API boundary with Anthropic's `web_search_20250305` server-side tool. Claude decides when to search; the API executes it and returns results with citations inline. No Tavily key needed.
  - **OpenAI search models** (`gpt-5-search-api`): Replaced with `web_search_options` parameter. The model always searches and returns `url_citation` annotations.
-  - **Local/vLLM models**: Falls back to a self-hosted [SearxNG](https://searxng.org) instance. Set `searxng_url` in `config.toml` `[tools]` or `$TURNSTONE_SEARXNG_URL` (the docker-compose stack bundles a `searxng` service and points at it by default). Operators with a custom MCP search server can instead set `web_search_backend = "mcp:server:tool"`.
+  - **Local/vLLM models**: Falls back to the Tavily API. Requires `tavily_key` in `config.toml` or `$TAVILY_API_KEY`.
 - **Auto-approve**: Yes (auto-approved for all tool dispatch paths).
- **Agent availability**: `task_agent`.
-
---
-
-### Reranking (optional)
-
-`web_search` can use an external **reranker** to re-order the backend's result pool by relevance to the query before returning the top hits. Turnstone runs no reranker model itself; it POSTs to a Cohere/Jina-compatible `/rerank` endpoint (self-hosted [vLLM](https://docs.vllm.ai) / [TEI](https://github.com/huggingface/text-embeddings-inference) / llama.cpp, or hosted Cohere/Jina/Voyage).
-
-**Disabled by default.** In the console **Models** tab, add a model definition whose `base_url` is a Cohere/Jina-compatible `/rerank` endpoint and whose capabilities include `{"supports_rerank": true}`, then select it under **Models → Roles → Reranker**. It's managed like every other model (write-only key, enable/disable, calibration). The reranker is purely this per-model definition — there is no global `rerank_url`-style endpoint setting.
-
-The `rerank_web_search` toggle defaults on once a reranker is selected. If the endpoint is unreachable or errors, web_search falls back silently to the backend's native result order — reranking never makes a search fail.
-
-When `rerank_bm25` is enabled, the candidate text for memory, tool, and skill retrieval (memory name/description/content and tool/skill names + descriptions) is also sent to the rerank endpoint — a self-hosted endpoint (vLLM/TEI/llama.cpp) keeps it on your infrastructure, a hosted provider (Cohere/Jina/Voyage) sends it off-box.
-
-**Serving a Qwen3-Reranker with vLLM.** The model is instruction-aware, so vLLM **must** apply its chat template — pass `--chat-template` explicitly. Without it the bare query produces near-random scores and reranking actively *hurts* retrieval (verified: an irrelevant passage outscored the correct one):
-
-```bash
-vllm serve /models/Qwen3-Reranker-0.6B \
-  --runner pooling \
-  --hf-overrides '{"architectures":["Qwen3ForSequenceClassification"],"classifier_from_token":["no","yes"],"is_original_qwen3_reranker":true}' \
-  --chat-template /models/Qwen3-Reranker-0.6B/chat_template.jinja \
-  --served-model-name qwen3-reranker --port 8000
-```
-
-Then add a reranker model in the **Models** tab with `base_url` `http://vllm:8000/rerank` (model name `qwen3-reranker`) and select it under **Models → Roles → Reranker**.
-
-For an endpoint that does *not* apply the model's template, set `rerank_instruction` instead — Turnstone then wraps each query as `<Instruct>: {instruction}` / `<Query>: {query}` (Qwen3's own default is `Given a web search query, retrieve relevant passages that answer the query`). Use the chat template **or** the instruction, not both (they double-wrap).
-
-**Picking `rerank_bm25_threshold`.** The relevance floor that gates proactive memory injection is a probability in `[0, 1]`, but the right value differs per model (a sharp 0.6B reranker may want ~0.95; a broader 4B ~0.33). Calibrate it against your endpoint:
-
-```bash
-turnstone-admin rerank-calibrate           # probe the endpoint, recommend a floor
-turnstone-admin rerank-calibrate --apply   # ...and write tools.rerank_bm25_threshold
-```
-
-It reports the score scale, whether the endpoint cleanly separates relevant from irrelevant probes (a **"no clean separation"** result flags a mis-served or weak reranker), and the suggested floor. Leave the threshold at `0` to rerank-without-filtering.
+- **Agent availability**: `agent` and `task_agent`.

 ---

 ## Agent

-The tool name uses the `_agent` suffix — bare `task` collides with
+Tool names use the `_agent` suffix — bare `plan` / `task` collide with
 chat-template channel names on some local models.

 ### task_agent
@@ -358,9 +368,23 @@ Delegate a general-purpose task to an autonomous sub-agent.
 |-----------|--------|----------|-------------|
 | `prompt`  | string | yes      | Complete task description for the sub-agent. |

- **What it does**: Spawns a sub-agent that inherits the `TASK_AGENT_TOOLS` set (read, write, edit, search, bash, web tools, memory tools). The sub-agent runs autonomously to completion. Use for work that requires file modifications or command execution.
+- **What it does**: Spawns a sub-agent that inherits the `TASK_AGENT_TOOLS` set (read, write, edit, search, bash, math, man, web tools, memory tools). The sub-agent runs autonomously to completion. Use for work that requires file modifications or command execution.
 - **Auto-approve**: No -- requires user confirmation.
- **Agent availability**: Top-level only.
+- **Agent availability**: Not available to sub-agents (top-level only).
+
+---
+
+### plan_agent
+
+Plan before implementing -- an autonomous agent explores the codebase and writes a structured plan.
+
+| Parameter | Type   | Required | Description |
+|-----------|--------|----------|-------------|
+| `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-<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).

 ---

@@ -421,7 +445,7 @@ Provide either `username` for user-based targeting or `channel_type` +

 - **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**: `task_agent`.
+- **Agent availability**: `agent` and `task_agent`.

 > See [Channel Integrations: Notifications](channels.md#notifications)
 > for the full delivery flow, service registry details, and security
@@ -497,7 +521,7 @@ data.get("mergedAt") is not None
 - Duplicate names rejected within the same workstream.

 - **Auto-approve**: `create` requires approval; `list` and `cancel` are auto-approved.
- **Agent availability**: Main session only — not available to task sub-agents.
+- **Agent availability**: Main session only — not available to plan/task sub-agents.

 > See [Watch Architecture](diagrams/png/18-watch-architecture.png) for the
 > full poll → evaluate → dispatch flow.
@@ -530,30 +554,33 @@ pre-configure skills at workstream creation.

 - **Auto-approve**: `load` requires approval (changes session behavior); `search`
  is auto-approved (read-only).
- **Agent availability**: Main session only — not available to task sub-agents.
+- **Agent availability**: Main session only — not available to plan/task sub-agents.

 ---

 ## Summary Table

-| Tool         | Category   | Auto-approve | task_agent | primary_key |
-|--------------|------------|--------------|------------|-------------|
-| `bash`       | File Ops   | No           | Yes        | `command`   |
-| `read_file`  | File Ops   | Yes          | Yes        | `path`      |
-| `write_file` | File Ops   | No           | Yes        | `content`   |
-| `edit_file`  | File Ops   | No           | Yes        | `old_string`|
-| `search`     | File Ops   | Yes          | Yes        | `query`     |
-| `web_fetch`  | Info       | No           | Yes        | `url`       |
-| `web_search` | Info       | No           | Yes        | `query`     |
-| `task_agent` | Agent      | No           | No         | `prompt`    |
-| `memory`     | Memory     | Yes          | No         | `name`      |
-| `recall`     | Memory     | Yes          | No         | `query`     |
-| `notify`     | Notify     | Yes          | Yes        | `message`   |
-| `watch`      | Monitor    | No (create)  | No         | `command`   |
-| `read_resource`| MCP      | No           | Yes        | `uri`       |
-| `use_prompt` | MCP        | No           | Yes        | `name`      |
-| `skill`      | Skills     | No (load)    | No         | `name`      |
-| `tool_search`| Search     | Yes          | No         | `query`     |
+| Tool         | Category   | Auto-approve | agent | task_agent | primary_key |
+|--------------|------------|--------------|-------|------------|-------------|
+| `bash`       | File Ops   | No           | No    | Yes        | `command`   |
+| `read_file`  | File Ops   | Yes          | Yes   | Yes        | `path`      |
+| `write_file` | File Ops   | No           | No    | Yes        | `content`   |
+| `edit_file`  | File Ops   | No           | No    | Yes        | `old_string`|
+| `search`     | File Ops   | Yes          | Yes   | Yes        | `query`     |
+| `math`       | Compute    | No           | Yes   | Yes        | `code`      |
+| `man`        | Info       | Yes          | Yes   | Yes        | `page`      |
+| `web_fetch`  | Info       | No           | Yes   | Yes        | `url`       |
+| `web_search` | Info       | No           | Yes   | Yes        | `query`     |
+| `task_agent` | Agent      | No           | No    | No         | `prompt`    |
+| `plan_agent` | Agent      | No           | No    | No         | `goal`      |
+| `memory`     | Memory     | Yes          | No    | No         | `name`      |
+| `recall`     | Memory     | Yes          | No    | No         | `query`     |
+| `notify`     | Notify     | Yes          | Yes   | Yes        | `message`   |
+| `watch`      | Monitor    | No (create)  | No    | No         | `command`   |
+| `read_resource`| MCP      | No           | Yes   | Yes        | `uri`       |
+| `use_prompt` | MCP        | No           | Yes   | Yes        | `name`      |
+| `skill`      | Skills     | No (load)    | No    | No         | `name`      |
+| `tool_search`| Search     | Yes          | No    | No         | `query`     |

 ---

@@ -605,9 +632,8 @@ CLI flags override the config file:
   directly.

 2. **Partitioning**: When active, tools are split into two sets:
-   - **Always-on** -- the built-in tools present in the current session
-     (interactive sessions currently have 16; `BUILTIN_TOOL_NAMES` is the
-     28-tool built-in union). These are always visible to the model.
+   - **Always-on** -- the 19 built-in tools (members of `BUILTIN_TOOL_NAMES`).
+     These are always visible to the model.
   - **Deferred** -- all MCP tools. These are not sent in the tool list unless
     the model searches for them.

@@ -621,10 +647,10 @@ CLI flags override the config file:

 ### Agent exemption

-Task sub-agents do not use tool search. They operate on the scoped tool set
-(`TASK_AGENT_TOOLS`) with MCP tools merged in. Tool search is only active for
-the top-level session, where the model can interactively search for tools it
-needs.
+Plan and task sub-agents do not use tool search. They operate on scoped tool
+sets (`AGENT_TOOLS` for plan agents, `TASK_AGENT_TOOLS` for task agents) with
+MCP tools merged in. Tool search is only active for the top-level session,
+where the model can interactively search for tools it needs.

 ---

@@ -649,7 +675,7 @@ MCP-compatible service.
 3. **Schema conversion**: Each MCP tool's `inputSchema` is converted to OpenAI
   function-calling format. The tool name is prefixed: `mcp__{server}__{tool}`.

-4. **Merging**: MCP tools are appended after the 16 built-in tools via
+4. **Merging**: MCP tools are appended after the 19 built-in tools via
   `merge_mcp_tools()`. Built-in tools appear first, giving them natural LLM priority.
   When dynamic tool search is active, MCP tools are deferred rather than directly
   visible -- the model discovers them via search as needed (see
@@ -675,6 +701,7 @@ gives per-tool-type granularity (e.g., all `use_prompt` calls).
 MCP tools are available to:
 - **Main session** — full access
 - **Task sub-agents** — via `self._task_tools` (merged list)
+- **Plan sub-agents** — via `self._agent_tools` (merged list)

 ### Naming convention

@@ -731,25 +758,34 @@ MCP tools (3):

 ### Dynamic tool refresh

-MCP tool lists stay up-to-date without restart through two mechanisms:
+MCP tool lists stay up-to-date without restart through three mechanisms:

 1. **Push notifications** -- MCP servers that declare `tools.listChanged: true` in
   their capabilities send `notifications/tools/list_changed` when their tool list
   changes. `MCPClientManager` registers a `message_handler` on each `ClientSession`
   that triggers an immediate refresh for that server.

-2. **Manual** -- `/mcp refresh` re-fetches tools from all servers immediately.
+2. **Periodic timer** -- Servers that do *not* support push notifications are polled
+   on a configurable interval (default 4 hours). The timer is staggered using a
+   launch-time seed (`monotonic_ns ^ pid`) so cluster nodes don't all hit MCP
+   servers simultaneously. Configure via `[mcp] refresh_interval` in `config.toml`
+   or `--mcp-refresh-interval SECONDS` on the CLI. Set to `0` to disable.
+
+3. **Manual** -- `/mcp refresh` re-fetches tools from all servers immediately.
   `/mcp refresh <server>` targets a single server. If a server has disconnected,
-   manual refresh attempts reconnection. The console admin panel exposes the
-   same controls (refresh / reconnect buttons per server) for cluster-wide
-   fan-out.
+   manual refresh attempts reconnection.

 When tools change, `MCPClientManager` rebuilds its merged tool list using copy-on-write
 (new list/dict objects assigned atomically) and notifies all active `ChatSession`
 instances via registered listener callbacks. Each session rebuilds its `_tools`,
-`_task_tools`, and reconstructs its `ToolSearchManager` (if active),
+`_task_tools`, `_agent_tools`, and reconstructs its `ToolSearchManager` (if active),
 preserving the set of previously expanded (discovered) tools.

+```toml
+[mcp]
+refresh_interval = 14400  # seconds (default 4h), 0 to disable
+```
+
 ```
 /mcp refresh
 MCP refresh complete:
@@ -803,7 +839,7 @@ Use read_resource(uri='...') to access the resources listed above.

 - **What it does**: Reads the resource from its MCP server via `MCPClientManager.read_resource_sync()`. Returns text content for text resources or base64-encoded data for binary resources. Output is truncated by the standard tool output limiter.
 - **Auto-approve**: No -- requires user confirmation (reads external data).
- **Agent availability**: `task_agent`.
+- **Agent availability**: `agent` and `task_agent`.

 ### Capability guards

@@ -845,7 +881,7 @@ the `initialize` handshake. Each prompt is stored with its prefixed name

 - **What it does**: Invokes an MCP prompt by name via `MCPClientManager.get_prompt_sync()`, expanding it into messages. Returns the expanded prompt content formatted as `[role]: content` blocks joined with blank lines. The prompt catalog is listed in the system message so the model knows which prompts are available. Output is truncated by the standard tool output limiter.
 - **Auto-approve**: No -- requires user confirmation (invokes external prompt servers).
- **Agent availability**: `task_agent`.
+- **Agent availability**: `agent` and `task_agent`.

 ### Invocation

@@ -7,7 +7,7 @@ name = "mcp-cluster-ops"
 version = "0.1.0"
 description = "MCP server for Turnstone cluster operations — reference implementation."
 requires-python = ">=3.11"
-license = "Apache-2.0"
+license = "BUSL-1.1"
 dependencies = [
    "turnstone",
    "mcp>=1.6",
@@ -4,11 +4,10 @@ build-backend = "hatchling.build"

 [project]
 name = "turnstone"
-version = "1.6.3"
+version = "1.5.4"
 description = "Multi-node AI orchestration platform with tool use, agent routing, and cluster simulation."
 readme = "README.md"
-license = "Apache-2.0"
-license-files = ["LICENSE", "NOTICE", "THIRD-PARTY-NOTICES"]
+license = "BUSL-1.1"
 requires-python = ">=3.11"
 authors = [{name = "Patrick Buckley", email = "buckleypm@gmail.com"}]
 keywords = ["ai", "chat", "llm", "agent", "tools", "openai"]
@@ -23,24 +22,19 @@ classifiers = [
    "Topic :: Scientific/Engineering :: Artificial Intelligence",
 ]
 dependencies = [
-    "openai>=2.37",
-    "anthropic>=0.108",  # claude-fable-5 support; hard runtime floor is 0.105 (mid-conversation system blocks)
+    "openai>=2.24",
    "httpx>=0.28",
-    "mcp>=1.27,<2",  # v2 is a breaking rewrite (2.0.0a1 live 2026-06-11; stable ~2026-07-27) — streamablehttp_client removed, 2-tuple transport, snake_case types; migrate deliberately
-    "starlette>=1.0.1",  # PYSEC-2026-161: host-header path-injection in URL reconstruction (auth-bypass on apps comparing reconstructed URL paths)
+    "mcp>=1.6",
+    "starlette>=0.45",
    "uvicorn>=0.34",
    "sse-starlette>=2.0",
    "httpx-sse>=0.4",
    "pydantic>=2.0",
    "sqlalchemy>=2.0",
    "alembic>=1.14",
-    "psycopg[binary]>=3.2",
-    "croniter>=3.0",
    "structlog>=24.1",
    "PyJWT>=2.8",
    "bcrypt>=4.0",
-    "cryptography>=42",
-    "lacme>=1.0.5",
    "python-frontmatter>=1.0",
 ]

@@ -50,11 +44,17 @@ Repository = "https://github.com/turnstonelabs/turnstone"
 Issues = "https://github.com/turnstonelabs/turnstone/issues"

 [project.optional-dependencies]
-test = ["pytest>=9.0", "pytest-cov>=6.0", "slack-bolt>=1.18", "aiohttp>=3.9"]
+test = ["pytest>=9.0", "pytest-cov>=6.0", "croniter>=3.0", "slack-bolt>=1.18", "aiohttp>=3.9"]
 dev = ["ruff>=0.9", "mypy>=1.14"]
+console = ["croniter>=3.0"]
+anthropic = ["anthropic>=0.39"]
+postgres = ["psycopg[binary]>=3.2"]
+ddg = ["ddgs>=9.0"]
 discord = ["discord.py>=2.4"]
+tls = ["lacme>=1.0.5"]
+sandbox = ["sympy>=1.13", "numpy>=2.0", "scipy>=1.14", "pytest>=9.0"]
 slack = ["slack-bolt>=1.18", "aiohttp>=3.9"]
-all = ["turnstone[discord,slack]"]
+all = ["turnstone[console,anthropic,postgres,discord,ddg,tls,sandbox,slack]"]

 [project.scripts]
 turnstone = "turnstone.cli:main"
@@ -81,28 +81,17 @@ include = [
  "turnstone/console/static/coordinator/*.js",
  "turnstone/shared_static/*.css",
  "turnstone/shared_static/*.js",
-  "turnstone/shared_static/katex-0.17.0/**/*",
+  "turnstone/shared_static/katex-0.16.45/**/*",
  "turnstone/shared_static/hljs-11.11.1/**/*",
-  "turnstone/shared_static/mermaid-11.15.0/**/*",
+  "turnstone/shared_static/mermaid-11.14.0/**/*",
  "turnstone/shared_static/hls-1.6.16/**/*",
  "turnstone/sdk/py.typed",
  "turnstone/deploy/*.yaml",
-  "turnstone/deploy/Caddyfile",
-  "turnstone/deploy/searxng/settings.yml",
 ]

 [tool.pytest.ini_options]
 testpaths = ["tests"]
 markers = ["live: requires a running LLM backend"]
-filterwarnings = [
-    # mcp v1 deprecates streamablehttp_client for an entry point whose call
-    # shape only settles in v2 — adoption rides the deliberate v2 migration
-    # (pin capped <2); silence exactly this message until then.
-    "ignore:Use `streamable_http_client` instead",
-    # starlette deprecates the httpx-backed TestClient; revisit at the next
-    # starlette floor bump.
-    "ignore:Using `httpx` with `starlette.testclient` is deprecated",
-]

 [tool.ruff]
 target-version = "py311"
@@ -111,6 +100,7 @@ line-length = 100
 [tool.ruff.lint]
 select = ["E", "F", "W", "I", "N", "UP", "B", "A", "SIM", "TCH"]
 ignore = ["E501"]
+per-file-ignores = { "turnstone/core/sandbox.py" = ["N802"] }

 [tool.ruff.format]
 quote-style = "double"
@@ -140,6 +130,10 @@ exclude_lines = [
    'if __name__ == "__main__"',
 ]

+[[tool.mypy.overrides]]
+module = ["sympy", "sympy.*", "numpy", "numpy.*"]
+ignore_missing_imports = true
+
 [[tool.mypy.overrides]]
 module = ["mcp", "mcp.*"]
 ignore_missing_imports = true
@@ -176,6 +170,10 @@ ignore_missing_imports = true
 module = ["frontmatter", "frontmatter.*"]
 ignore_missing_imports = true

+[[tool.mypy.overrides]]
+module = ["ddgs", "ddgs.*"]
+ignore_missing_imports = true
+
 [[tool.mypy.overrides]]
 module = ["lacme", "lacme.*"]
 ignore_missing_imports = true
@@ -1,418 +0,0 @@
-#!/usr/bin/env bash
-#
-# Turnstone one-line installer.
-#
-#   curl -fsSL https://raw.githubusercontent.com/turnstonelabs/turnstone/main/run.sh | bash
-#
-# Autodetects your distro (Ubuntu/Debian, Fedora/RHEL, Arch, and WSL on any of
-# them) and:
-#   1. ensures git is installed, then clones the repo
-#   2. ensures Docker + the compose plugin are installed and the daemon is usable
-#   3. asks how many server nodes to run (1-10)
-#   4. builds the image
-#   5. picks free host ports for Caddy (prefers 443) and PostgreSQL
-#   6. writes a .env with a generated JWT secret + Postgres password
-#   7. pins the node count and runs `docker compose up -d`, then prints how to
-#      finish setup in the UI
-#
-# Re-running is safe: it updates the checkout and keeps an existing .env.
-#
-# Env overrides:
-#   TURNSTONE_DIR   where to clone (default: $HOME/turnstone)
-#   TURNSTONE_REPO  git URL (default: https://github.com/turnstonelabs/turnstone.git)
-
-set -Eeuo pipefail
-
-REPO_URL="${TURNSTONE_REPO:-https://github.com/turnstonelabs/turnstone.git}"
-INSTALL_DIR="${TURNSTONE_DIR:-$HOME/turnstone}"
-
-# -- output helpers -----------------------------------------------------------
-if [ -t 1 ]; then
-    BOLD=$'\033[1m'; DIM=$'\033[2m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'
-    RED=$'\033[31m'; RESET=$'\033[0m'
-else
-    BOLD=""; DIM=""; GREEN=""; YELLOW=""; RED=""; RESET=""
-fi
-info() { printf '%s==>%s %s\n' "$GREEN" "$RESET" "$*"; }
-warn() { printf '%swarning:%s %s\n' "$YELLOW" "$RESET" "$*" >&2; }
-die()  { printf '%serror:%s %s\n' "$RED" "$RESET" "$*" >&2; exit 1; }
-have() { command -v "$1" >/dev/null 2>&1; }
-
-# Any *unhandled* failure (set -Ee) lands here with an actionable note instead of
-# a bare non-zero exit. `die` exits explicitly and does not trigger this.
-on_error() {
-    local rc=$?
-    printf '\n%serror:%s the installer stopped unexpectedly (exit %s). The output above shows why.\n' \
-        "$RED" "$RESET" "$rc" >&2
-    printf '       Fix the issue and re-run this script — it resumes the parts already done.\n' >&2
-}
-trap on_error ERR
-
-# Ask a yes/no question, reading from the terminal even under `curl | bash`
-# (where stdin is the script). Defaults to "$2" when non-interactive.
-ask() {
-    local prompt="$1" default="${2:-y}" ans hint
-    [ "$default" = y ] && hint="Y/n" || hint="y/N"
-    if [ ! -r /dev/tty ]; then
-        warn "non-interactive shell; assuming '$default' for: $prompt"
-        [ "$default" = y ]; return
-    fi
-    printf '%s%s%s [%s] ' "$BOLD" "$prompt" "$RESET" "$hint" >/dev/tty
-    read -r ans </dev/tty || ans=""
-    ans="${ans:-$default}"
-    case "$ans" in [Yy]*) return 0 ;; *) return 1 ;; esac
-}
-
-# -- distro / package manager detection --------------------------------------
-OS_ID=""; OS_LIKE=""; PKG=""; IS_WSL=0; SUDO=""
-
-detect_os() {
-    if [ -r /etc/os-release ]; then
-        # shellcheck disable=SC1091
-        . /etc/os-release
-        OS_ID="${ID:-}"; OS_LIKE="${ID_LIKE:-}"
-    fi
-    if grep -qiE 'microsoft|wsl' /proc/version 2>/dev/null || [ -n "${WSL_DISTRO_NAME:-}" ]; then
-        IS_WSL=1
-    fi
-    case " $OS_ID $OS_LIKE " in
-        *" arch "*|*manjaro*)                 PKG=pacman ;;
-        *" ubuntu "*|*" debian "*)            PKG=apt ;;
-        *" fedora "*|*" rhel "*|*" centos "*) PKG=dnf ;;
-        *)  if   have apt-get; then PKG=apt
-            elif have dnf;     then PKG=dnf
-            elif have yum;     then PKG=yum
-            elif have pacman;  then PKG=pacman
-            fi ;;
-    esac
-    [ -n "$PKG" ] || die "could not detect a supported package manager (apt/dnf/yum/pacman). Install git + Docker manually, then re-run."
-    [ "$PKG" = dnf ] && ! have dnf && have yum && PKG=yum
-    if [ "$(id -u)" -ne 0 ]; then
-        have sudo || die "this script needs root for package installs — install sudo or run as root."
-        SUDO="sudo"
-    fi
-    local where="$OS_ID"; [ "$IS_WSL" -eq 1 ] && where="$OS_ID (WSL)"
-    info "Detected ${where:-linux} — using ${PKG}."
-}
-
-pkg_install() {
-    info "Installing: $*"
-    case "$PKG" in
-        apt)    $SUDO apt-get update -y && $SUDO apt-get install -y "$@" ;;
-        dnf)    $SUDO dnf install -y "$@" ;;
-        yum)    $SUDO yum install -y "$@" ;;
-        pacman) $SUDO pacman -Sy --needed --noconfirm "$@" ;;
-    esac
-}
-
-# -- git ----------------------------------------------------------------------
-ensure_git() {
-    have git && return
-    warn "git is not installed."
-    ask "Install git now?" y || die "git is required to clone the repo."
-    pkg_install git || die "git installation failed — see the output above."
-    have git || die "git installation reported success but 'git' is not on PATH."
-}
-
-clone_repo() {
-    if [ -d "$INSTALL_DIR/.git" ]; then
-        info "Updating existing checkout at $INSTALL_DIR"
-        git -C "$INSTALL_DIR" pull --ff-only || warn "could not fast-forward; using the existing checkout."
-    else
-        [ -e "$INSTALL_DIR" ] && [ -n "$(ls -A "$INSTALL_DIR" 2>/dev/null)" ] \
-            && die "$INSTALL_DIR exists and is not a turnstone checkout. Set TURNSTONE_DIR to an empty path."
-        info "Cloning $REPO_URL into $INSTALL_DIR"
-        # Skip Git LFS smudge — the LFS objects are only diagram PNGs, not needed to run.
-        GIT_LFS_SKIP_SMUDGE=1 git clone --depth 1 "$REPO_URL" "$INSTALL_DIR"
-    fi
-}
-
-# -- docker -------------------------------------------------------------------
-DOCKER="docker"
-
-install_docker() {
-    case "$PKG" in
-        apt|dnf|yum)
-            info "Installing Docker via the official get.docker.com script"
-            curl -fsSL https://get.docker.com | $SUDO sh ;;
-        pacman)
-            pkg_install docker docker-compose ;;
-    esac
-    # Best-effort: start the daemon and let the current user run docker.
-    if have systemctl; then
-        $SUDO systemctl enable --now docker 2>/dev/null || true
-    fi
-    if [ "$(id -u)" -ne 0 ] && getent group docker >/dev/null 2>&1; then
-        $SUDO usermod -aG docker "$USER" 2>/dev/null || true
-    fi
-}
-
-start_docker_daemon() {
-    if have systemctl; then
-        $SUDO systemctl start docker 2>/dev/null || true
-    elif have service; then
-        $SUDO service docker start 2>/dev/null || true
-    fi
-}
-
-# Resolve how to invoke docker (direct / via sudo) and make sure the daemon runs.
-ensure_docker_usable() {
-    if ! have docker; then
-        warn "Docker is not installed."
-        ask "Install Docker now?" y || die "Docker is required."
-        install_docker
-        have docker || die "Docker installation failed."
-    fi
-
-    docker info >/dev/null 2>&1 && { DOCKER="docker"; return; }
-
-    # Maybe the daemon just isn't running yet.
-    start_docker_daemon
-    docker info >/dev/null 2>&1 && { DOCKER="docker"; return; }
-
-    # Maybe we lack permission (not in the docker group yet, group change not
-    # active in this shell) — fall back to sudo for this run.
-    if [ "$(id -u)" -ne 0 ] && have sudo && sudo docker info >/dev/null 2>&1; then
-        DOCKER="sudo docker"
-        warn "Using 'sudo docker' for this run. To drop the sudo: 'sudo usermod -aG docker $USER' then log out and back in."
-        return
-    fi
-
-    if [ "$IS_WSL" -eq 1 ]; then
-        die "Docker isn't usable inside WSL. Install Docker Desktop on Windows and enable WSL integration for this distro (Settings -> Resources -> WSL integration), then re-run."
-    fi
-    die "Docker is installed but not usable — the daemon may be stopped or you lack permission. Try: 'sudo systemctl start docker', then re-run."
-}
-
-ensure_compose() {
-    $DOCKER compose version >/dev/null 2>&1 && return
-    warn "The Docker Compose v2 plugin is missing."
-    case "$PKG" in
-        apt|dnf|yum) ask "Install docker-compose-plugin?" y && pkg_install docker-compose-plugin || true ;;
-        pacman)      ask "Install docker-compose?" y && pkg_install docker-compose || true ;;
-    esac
-    $DOCKER compose version >/dev/null 2>&1 \
-        || die "'docker compose' is unavailable. Install Docker Compose v2 and re-run."
-}
-
-# -- node count ---------------------------------------------------------------
-NODE_COUNT=10
-
-pick_node_count() {
-    if [ ! -r /dev/tty ]; then
-        info "Non-interactive shell — starting the recommended 10-node cluster."
-        return
-    fi
-    cat >/dev/tty <<EOF
-
-${BOLD}How many server nodes? (1-10)${RESET}
-The full 10-node cluster is recommended — it best shows off routing across
-nodes. Each node uses on the order of a few hundred MB of RAM at idle; MCP
-stdio servers that a node launches can raise that. Pick fewer on a small
-machine — you can always add nodes later.
-EOF
-    local ans
-    while :; do
-        printf '%sNodes [default 10]:%s ' "$BOLD" "$RESET" >/dev/tty
-        read -r ans </dev/tty || ans=""
-        ans="${ans:-10}"
-        case "$ans" in
-            [1-9]|10) NODE_COUNT="$ans"; break ;;
-            *) printf 'Please enter a whole number from 1 to 10.\n' >/dev/tty ;;
-        esac
-    done
-    info "Will start ${NODE_COUNT} server node(s)."
-}
-
-# Pin the chosen count: park nodes above NODE_COUNT behind the "extra" profile in
-# an auto-loaded compose.override.yaml, so a later *plain* `docker compose up -d`
-# keeps the same count (Compose merges compose.override.yaml automatically). A
-# full (10) choice removes the file. Never clobbers an override we didn't write.
-OVERRIDE_MARKER="# turnstone run.sh — node-count limiter (safe to delete)"
-write_node_override() {
-    local f="$INSTALL_DIR/compose.override.yaml" k
-    if [ -f "$f" ] && ! head -1 "$f" 2>/dev/null | grep -qF "$OVERRIDE_MARKER"; then
-        warn "$f exists and isn't managed by this installer — leaving it as-is."
-        warn "A plain 'docker compose up -d' may not match your ${NODE_COUNT}-node choice."
-        return
-    fi
-    if [ "$NODE_COUNT" -ge 10 ]; then
-        rm -f "$f"
-        return
-    fi
-    {
-        echo "$OVERRIDE_MARKER"
-        echo "# Keeps 'docker compose up -d' at ${NODE_COUNT} node(s). Nodes above"
-        echo "# node-${NODE_COUNT} are parked behind the 'extra' profile:"
-        echo "#   docker compose --profile extra up -d        # start all 10"
-        echo "#   docker compose up -d node-$((NODE_COUNT + 1))                 # start one more"
-        echo "services:"
-        for k in $(seq $((NODE_COUNT + 1)) 10); do
-            printf '  node-%s: { profiles: ["extra"] }\n' "$k"
-        done
-    } >"$f"
-    info "Pinned ${NODE_COUNT} node(s) in $f (a later 'docker compose up -d' honors it)."
-}
-
-# -- ports --------------------------------------------------------------------
-port_in_use() {
-    local p="$1"
-    if have ss; then
-        ss -ltnH 2>/dev/null | awk '{print $4}' | grep -qE "[:.]${p}\$" && return 0 || return 1
-    fi
-    if have lsof; then
-        lsof -iTCP:"$p" -sTCP:LISTEN >/dev/null 2>&1 && return 0 || return 1
-    fi
-    # bash fallback: a successful connect means something is listening.
-    (exec 3<>"/dev/tcp/127.0.0.1/$p") 2>/dev/null && { exec 3>&- 3<&-; return 0; }
-    return 1
-}
-port_free() { ! port_in_use "$1"; }
-
-random_high_port() {
-    local p
-    for _ in $(seq 1 25); do
-        p=$(( (RANDOM % 64000) + 1024 ))
-        port_free "$p" && { echo "$p"; return; }
-    done
-    echo ""  # caller handles
-}
-
-pick_caddy_port() {
-    # Prefer 443; rootless Docker can't bind privileged ports, so skip it there.
-    if [ "$ROOTLESS" -eq 0 ] && port_free 443; then echo 443; return; fi
-    port_free 8443 && { echo 8443; return; }
-    local p; p="$(random_high_port)"
-    [ -n "$p" ] && { echo "$p"; return; }
-    echo 8443
-}
-
-pick_pg_port() {
-    port_free 5432 && { echo 5432; return; }
-    local p; p="$(random_high_port)"
-    [ -n "$p" ] && { echo "$p"; return; }
-    echo 5432
-}
-
-# -- secrets / .env -----------------------------------------------------------
-gen_hex() {
-    # $1 = number of bytes → 2*$1 hex chars
-    if   have openssl; then openssl rand -hex "$1"
-    elif have python3; then python3 -c 'import secrets,sys; print(secrets.token_hex(int(sys.argv[1])))' "$1"
-    else head -c "$1" /dev/urandom | od -An -tx1 | tr -d ' \n'
-    fi
-}
-
-_env_get() {  # _env_get KEY DEFAULT → value from $INSTALL_DIR/.env, else DEFAULT
-    local v
-    v="$(grep -E "^$1=" "$INSTALL_DIR/.env" 2>/dev/null | tail -1 | cut -d= -f2- || true)"
-    printf '%s' "${v:-$2}"
-}
-
-# Resolve CADDY_PORT + PG_PORT and ensure a .env exists. On re-run the existing
-# .env (secrets + ports) is reused so the rest of the script reports the ports
-# the stack actually binds, not freshly-picked ones.
-prepare_env() {
-    if [ -f "$INSTALL_DIR/.env" ]; then
-        info "Keeping existing $INSTALL_DIR/.env (secrets and ports preserved)."
-        chmod 600 "$INSTALL_DIR/.env" 2>/dev/null || true
-        CADDY_PORT="$(_env_get CONSOLE_HTTPS_PORT 8443)"
-        PG_PORT="$(_env_get POSTGRES_PORT 5432)"
-        return
-    fi
-    CADDY_PORT="$(pick_caddy_port)"
-    PG_PORT="$(pick_pg_port)"
-    local jwt pgpw
-    jwt="$(gen_hex 32)"   # 64 hex chars — comfortably over the 32-char minimum
-    pgpw="$(gen_hex 18)"  # hex keeps it URL-safe in the Postgres DSN
-    # Write 0600 from the start (umask scoped to the subshell so it doesn't leak).
-    (
-        umask 077
-        cat >"$INSTALL_DIR/.env" <<EOF
-# Generated by run.sh — keep this private.
-TURNSTONE_JWT_SECRET=$jwt
-POSTGRES_USER=turnstone
-POSTGRES_PASSWORD=$pgpw
-POSTGRES_BIND=127.0.0.1
-POSTGRES_PORT=$PG_PORT
-CONSOLE_HTTPS_PORT=$CADDY_PORT
-EOF
-    )
-    chmod 600 "$INSTALL_DIR/.env"
-    info "Wrote $INSTALL_DIR/.env (generated JWT secret + Postgres password, mode 600)."
-}
-
-# -- summary ------------------------------------------------------------------
-print_done() {
-    local url scale
-    [ "$CADDY_PORT" = 443 ] && url="https://localhost" || url="https://localhost:${CADDY_PORT}"
-    if [ "$NODE_COUNT" -lt 10 ]; then
-        scale="${NODE_COUNT} of 10 nodes — pinned in compose.override.yaml, so a plain
-              'docker compose up -d' keeps it. Start all 10 anytime:
-              ${DIM}cd $INSTALL_DIR && $DOCKER compose --profile extra up -d${RESET}"
-    else
-        scale="all 10 nodes. To run fewer, stop some:
-              ${DIM}cd $INSTALL_DIR && $DOCKER compose stop node-8 node-9 node-10${RESET}"
-    fi
-    cat <<EOF
-
-${GREEN}${BOLD}Turnstone is running${RESET} (${NODE_COUNT} node$([ "$NODE_COUNT" = 1 ] || echo s)).
-
-  Dashboard   ${BOLD}${url}${RESET}
-              Caddy serves it with its own local CA, so your browser warns once.
-              Trust it (optional):
-              ${DIM}cd $INSTALL_DIR && $DOCKER compose exec caddy cat /data/caddy/pki/authorities/local/root.crt${RESET}
-
-  Finish setup
-    1. Create the first admin user:
-       ${DIM}cd $INSTALL_DIR && $DOCKER compose exec node-1 turnstone-admin create-user --username admin --name "Admin"${RESET}
-    2. Open ${url}, log in, and add a model backend in the ${BOLD}Models${RESET} tab —
-       a local server (vLLM / llama.cpp / Ollama) or an OpenAI / Anthropic / Gemini key.
-       Nodes boot without a model and pick it up live; no restart needed.
-
-  Scale       Running ${scale}
-
-  Manage      ${DIM}cd $INSTALL_DIR${RESET}
-              ${DIM}$DOCKER compose ps${RESET}        status
-              ${DIM}$DOCKER compose logs -f${RESET}   logs
-              ${DIM}$DOCKER compose down${RESET}      stop (add -v to wipe data)
-
-  Config      $INSTALL_DIR/.env   (generated secrets + ports)
-EOF
-}
-
-# -- main ---------------------------------------------------------------------
-main() {
-    printf '%s%sTurnstone installer%s\n\n' "$BOLD" "$GREEN" "$RESET"
-
-    detect_os
-    ensure_git
-    clone_repo
-    ensure_docker_usable
-    ensure_compose
-
-    ROOTLESS=0
-    $DOCKER info 2>/dev/null | grep -qi 'rootless' && ROOTLESS=1
-
-    pick_node_count
-
-    info "Building the image (first run pulls dependencies — this can take a few minutes)…"
-    if ! ( cd "$INSTALL_DIR" && $DOCKER compose build ); then
-        die "image build failed (see output above). Common causes: low memory or disk, or the Docker daemon stopped. Free up resources and re-run — it resumes."
-    fi
-
-    prepare_env
-    info "Ports — dashboard (Caddy): ${CADDY_PORT}, PostgreSQL: 127.0.0.1:${PG_PORT}"
-    write_node_override
-
-    info "Starting the stack…"
-    # Plain `up -d` (honoring compose.override.yaml) + --remove-orphans so a
-    # re-run that lowers the count also stops the now-excluded nodes.
-    if ! ( cd "$INSTALL_DIR" && $DOCKER compose up -d --remove-orphans ); then
-        die "the stack failed to start (see output above). Inspect logs: cd $INSTALL_DIR && $DOCKER compose logs"
-    fi
-
-    print_done
-}
-
-main "$@"
@@ -1,260 +0,0 @@
-#!/usr/bin/env python3
-"""Manual BM25-vs-BM25→rerank benchmark for the retrieval surfaces.
-
-Run this by hand on a host that has a Cohere/Jina-compatible rerank endpoint
-configured (vLLM, TEI, llama.cpp, or a hosted Cohere/Jina/Voyage key). It is NOT
-a pytest test and is never collected by the test suite — it needs a live endpoint
-to do anything useful.
-
-It compares plain BM25 top-k against the two-stage BM25→rerank path on two small
-in-file labeled corpora (tool-like docs and synthetic memory dicts), printing
-precision@k, MRR, a ranking diff, and the relevant-vs-irrelevant score
-distribution so you can pick a sensible ``tools.rerank_bm25_threshold`` default.
-
-The endpoint bearer token (for hosted providers) is read from the
-``$TURNSTONE_RERANK_API_KEY`` environment variable, never a flag, so it does not
-land in shell history or the process listing.
-
-Example::
-
-    TURNSTONE_RERANK_API_KEY=... \
-        .venv/bin/python scripts/bench_bm25_rerank.py \
-        --rerank-url http://localhost:8000/rerank \
-        --rerank-model BAAI/bge-reranker-v2-m3 --k 3 --threshold 0.0
-"""
-
-from __future__ import annotations
-
-import argparse
-import os
-import statistics
-from typing import TYPE_CHECKING
-
-from turnstone.core.bm25 import BM25Index
-from turnstone.core.rerank import resolve_rerank_client
-
-if TYPE_CHECKING:
-    from collections.abc import Callable
-
-    from turnstone.core.rerank import RerankClient
-
-# (query, relevant-doc-name) labels over a handful of tool-like docs.
-TOOL_DOCS: list[dict[str, str]] = [
-    {"name": "read_file", "description": "Read the contents of a file from disk"},
-    {"name": "write_file", "description": "Write or overwrite a file on disk"},
-    {"name": "list_dir", "description": "List the entries in a directory"},
-    {"name": "web_search", "description": "Search the web and return result snippets"},
-    {"name": "send_email", "description": "Send an email message to a recipient"},
-    {"name": "run_bash", "description": "Execute a shell command and capture output"},
-    {"name": "create_issue", "description": "Open a new issue in the bug tracker"},
-    {"name": "query_db", "description": "Run a SQL query against the database"},
-]
-TOOL_LABELS: list[tuple[str, str]] = [
-    ("open a file and show me what's inside", "read_file"),
-    ("look something up on the internet", "web_search"),
-    ("send a message by email", "send_email"),
-    ("run a terminal command", "run_bash"),
-    ("file a bug report", "create_issue"),
-    ("fetch rows from the database", "query_db"),
-]
-
-# Synthetic memory dicts (name + description + content) with labeled queries.
-MEMORY_DOCS: list[dict[str, str]] = [
-    {
-        "name": "postgres_conn",
-        "description": "database connection settings",
-        "content": "host=db.internal port=5432 user=app sslmode=require",
-    },
-    {
-        "name": "redis_cache",
-        "description": "cache server config",
-        "content": "host=redis port=6379 maxmemory 2gb eviction allkeys-lru",
-    },
-    {
-        "name": "deploy_runbook",
-        "description": "production deploy steps",
-        "content": "build image, push to registry, roll nodes one at a time",
-    },
-    {
-        "name": "oncall_rotation",
-        "description": "who is on call",
-        "content": "primary alice, secondary bob, escalate to carol after 30m",
-    },
-    {
-        "name": "tls_certs",
-        "description": "certificate renewal",
-        "content": "acme renews every 60 days; caddy reloads the SSLContext in place",
-    },
-    {
-        "name": "api_ratelimits",
-        "description": "rate limit policy",
-        "content": "100 req/min per token, burst 20, 429 with retry-after header",
-    },
-    {
-        "name": "backup_schedule",
-        "description": "nightly backups",
-        "content": "pg_dump at 02:00 UTC, retained 14 days, offsite copy weekly",
-    },
-    {
-        "name": "feature_flags",
-        "description": "rollout toggles",
-        "content": "rerank_bm25 default on, voice_io default off, smart_approvals off",
-    },
-    {
-        "name": "smtp_settings",
-        "description": "outbound email",
-        "content": "relay smtp.internal port 587 starttls from noreply@example.com",
-    },
-    {
-        "name": "log_retention",
-        "description": "log storage policy",
-        "content": "structured logs to loki, 30 day retention, audit logs 1 year",
-    },
-    {
-        "name": "node_placement",
-        "description": "routing config",
-        "content": "rendezvous hashing fnv-1a, ~100 node ceiling, hrw weights",
-    },
-    {
-        "name": "jwt_secret_rotation",
-        "description": "auth secret",
-        "content": "TURNSTONE_JWT_SECRET in config.toml, rotate quarterly, hs256",
-    },
-]
-MEMORY_LABELS: list[tuple[str, str]] = [
-    ("what is the postgres database host and port", "postgres_conn"),
-    ("how often do we rotate the jwt signing secret", "jwt_secret_rotation"),
-    ("when do nightly database backups run", "backup_schedule"),
-    ("who do I escalate an incident to", "oncall_rotation"),
-    ("how are nodes placed for routing", "node_placement"),
-    ("what is the per token api rate limit", "api_ratelimits"),
-]
-
-
-def _doc_text(d: dict[str, str]) -> str:
-    return " ".join(
-        filter(None, (d.get("name", ""), d.get("description", ""), d.get("content", "")))
-    )
-
-
-def _make_rank(client: RerankClient, threshold: float) -> Callable[[str, list[str]], list[int]]:
-    def _rank(query: str, docs: list[str]) -> list[int]:
-        return [
-            h.index for h in client.rerank(query, docs) if threshold <= 0 or h.score >= threshold
-        ]
-
-    return _rank
-
-
-def _precision_at_k(result_names: list[str], relevant: str, k: int) -> float:
-    return 1.0 / k if relevant in result_names[:k] else 0.0
-
-
-def _reciprocal_rank(result_names: list[str], relevant: str) -> float:
-    for i, name in enumerate(result_names, 1):
-        if name == relevant:
-            return 1.0 / i
-    return 0.0
-
-
-def _bench_corpus(
-    title: str,
-    docs: list[dict[str, str]],
-    labels: list[tuple[str, str]],
-    client: RerankClient,
-    threshold: float,
-    k: int,
-) -> None:
-    print(f"\n=== {title} ({len(docs)} docs, {len(labels)} queries, k={k}) ===")
-    texts = [_doc_text(d) for d in docs]
-    names = [d["name"] for d in docs]
-    plain = BM25Index(texts)
-    # Filter mode when a floor is set (mirrors the memory composition call site)
-    # so --threshold actually suppresses below-floor hits rather than being
-    # masked by reorder-mode backfill; reorder mode at threshold 0.
-    reranked = BM25Index(
-        texts, reranker=_make_rank(client, threshold), rerank_filters=threshold > 0
-    )
-
-    bm25_p = bm25_mrr = rr_p = rr_mrr = 0.0
-    for query, relevant in labels:
-        b_names = [names[i] for i in plain.search(query, k=k)]
-        r_names = [names[i] for i in reranked.search(query, k=k)]
-        bm25_p += _precision_at_k(b_names, relevant, k)
-        rr_p += _precision_at_k(r_names, relevant, k)
-        bm25_mrr += _reciprocal_rank([names[i] for i in plain.search(query, k=len(docs))], relevant)
-        rr_mrr += _reciprocal_rank(
-            [names[i] for i in reranked.search(query, k=len(docs))], relevant
-        )
-        flag = "" if b_names[:k] == r_names[:k] else "  <-- reordered"
-        print(f"  q: {query!r}")
-        print(f"     want={relevant}  bm25={b_names[:k]}  rerank={r_names[:k]}{flag}")
-
-    n = len(labels)
-    print(f"  -- precision@{k}: bm25={bm25_p / n:.3f}  rerank={rr_p / n:.3f}")
-    print(f"  -- MRR:          bm25={bm25_mrr / n:.3f}  rerank={rr_mrr / n:.3f}")
-
-
-def _score_distribution(
-    docs: list[dict[str, str]],
-    labels: list[tuple[str, str]],
-    client: RerankClient,
-) -> None:
-    """Print rerank-score stats for labeled relevant vs irrelevant pairs.
-
-    A threshold default should sit above the irrelevant max / below the relevant
-    min where those separate; this prints both so you can eyeball the gap.
-    """
-    texts = [_doc_text(d) for d in docs]
-    names = [d["name"] for d in docs]
-    relevant_scores: list[float] = []
-    irrelevant_scores: list[float] = []
-    for query, relevant in labels:
-        for hit in client.rerank(query, texts):
-            bucket = relevant_scores if names[hit.index] == relevant else irrelevant_scores
-            bucket.append(hit.score)
-
-    print("\n=== rerank score distribution (memory corpus) ===")
-    for label, scores in (("relevant", relevant_scores), ("irrelevant", irrelevant_scores)):
-        if not scores:
-            print(f"  {label}: (no scores)")
-            continue
-        print(
-            f"  {label:<10} n={len(scores):>3}  "
-            f"min={min(scores):.4f}  median={statistics.median(scores):.4f}  "
-            f"max={max(scores):.4f}"
-        )
-    if relevant_scores and irrelevant_scores:
-        suggested = (min(relevant_scores) + max(irrelevant_scores)) / 2
-        sep = "separable" if min(relevant_scores) > max(irrelevant_scores) else "overlapping"
-        print(f"  -> classes are {sep}; midpoint threshold candidate ~= {suggested:.4f}")
-
-
-def main() -> int:
-    ap = argparse.ArgumentParser(description=__doc__)
-    ap.add_argument("--rerank-url", required=True, help="full Cohere/Jina-compatible /rerank URL")
-    ap.add_argument("--rerank-model", default="", help="model name sent in the request body")
-    ap.add_argument("--threshold", type=float, default=0.0, help="relevance floor (0 disables)")
-    ap.add_argument("--k", type=int, default=3, help="top-k to score precision@k over")
-    args = ap.parse_args()
-
-    # Bearer token comes from the environment, not a flag, to keep it out of
-    # shell history and the process listing.
-    api_key = os.environ.get("TURNSTONE_RERANK_API_KEY", "")
-    client = resolve_rerank_client(args.rerank_url, model=args.rerank_model, api_key=api_key)
-    if client is None:
-        print("No rerank endpoint resolved (empty --rerank-url?). Nothing to do.")
-        return 1
-
-    print(
-        f"reranker: url={args.rerank_url} model={args.rerank_model or '(default)'} "
-        f"threshold={args.threshold}"
-    )
-    _bench_corpus("tool search", TOOL_DOCS, TOOL_LABELS, client, args.threshold, args.k)
-    _bench_corpus("memory composition", MEMORY_DOCS, MEMORY_LABELS, client, args.threshold, args.k)
-    _score_distribution(MEMORY_DOCS, MEMORY_LABELS, client)
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())
@@ -61,10 +61,7 @@ CSS_FILES = [
    "turnstone/shared_static/base.css",
    "turnstone/shared_static/ui-base.css",
    "turnstone/shared_static/chat.css",
-    "turnstone/shared_static/conversation.css",
    "turnstone/shared_static/cards.css",
-    "turnstone/shared_static/shell.css",
-    "turnstone/shared_static/interactive.css",
    "turnstone/console/static/style.css",
    "turnstone/console/static/coordinator/coordinator.css",
    "turnstone/ui/static/style.css",
@@ -90,18 +87,12 @@ PAGE_STYLESHEETS: dict[str, list[str]] = {
        "turnstone/console/static/style.css",
        "turnstone/console/static/coordinator/coordinator.css",
    ],
-    # Standalone turnstone-server now serves the L-shell (step 6): same shared
-    # sheets the console loads, in <link> order, plus the (slimmed) ui/static
-    # style.css.  No coordinator sheets (orchestration off).
    "turnstone/ui/static/index.html": [
        "turnstone/shared_static/base.css",
        "turnstone/shared_static/ui-base.css",
        "turnstone/shared_static/chat.css",
-        "turnstone/shared_static/conversation.css",
        "turnstone/shared_static/cards.css",
        "turnstone/ui/static/style.css",
-        "turnstone/shared_static/shell.css",
-        "turnstone/shared_static/interactive.css",
    ],
 }

@@ -1,645 +0,0 @@
-#!/usr/bin/env python3
-"""Build the livepass harnesses — render real hatch dialogs/shelves headlessly.
-
-The livepass is how converted modal surfaces get verified without booting a
-server: a minimal page that symlinks the REAL stylesheets and scripts, embeds
-the REAL markup (extracted fresh from the index files at build time), stubs
-``window.authFetch`` with canned fixtures, and drives surfaces via ``?open=``
-query params — including click-driving submits so dead buttons can't hide
-(the model-Save bug class).
-
-Usage:
-    python3 scripts/livepass.py                # build into /tmp/livepass/
-    python3 scripts/livepass.py --out DIR      # build elsewhere
-    python3 scripts/livepass.py --serve 8950   # build + serve (Ctrl+C stops)
-
-Then screenshot states (file:// blocks ES modules — always serve over http;
-the reduced-motion flag is REQUIRED, entrance animations race the capture):
-
-    google-chrome --headless --disable-gpu --hide-scrollbars \\
-      --force-prefers-reduced-motion --window-size=1440,900 \\
-      --virtual-time-budget=9000 --screenshot=out.png \\
-      "http://localhost:8950/ui/livepass.html?open=new-ws&theme=light"
-
-UI harness (?open=): new-ws · new-ws-fork · edit-title · delete-ws ·
-  revoke-mcp · ws-delete · ws-delete-results   (+ &theme=light, &busy=1)
-Console harness (?open=): schedule-create · schedule-edit · model-create ·
-  model-edit · model-save (drives a Save click; document.title becomes
-  PUT-OK-<n> on success) · policy · confirm · token
-  Plus &tall=1 (90-row users panel — the .admin-content scroll state; the
-  synthetic rows wrap to two lines, so judge overflow geometry, not row
-  cadence) · &scrolled=1 lands mid-list, &scrolled=bottom shows the 24px
-  scroll tail · &focuslast=1 focuses the last shelf-body control (the
-  displaced-dock regression probe: only .sh-body may scroll; head/foot stay
-  pinned).  All combinable with ?open=.  The console page wraps the fragment
-  in the REAL L-shell chain — pane-pinned height, interior scroller — so
-  scroll/dock geometry matches production; keep it that way.  Body-level
-  dialogs (confirm/install/coord-delete) are injected as riders; a driven
-  ?open= that ends with no open dialog stamps OPEN-FAILED-<state> into the
-  title instead of passing silently.
-  Governance surfaces (roles/HR/OGP/memory/skill) need fixtures that are not
-  canned yet — add a fixture + driver branch below when you need one.
-Shell harness (?split=): right (default) · down · three · none — boots the
-  REAL shell.js + pane.js split-view engine over stubbed seams (two demo
-  conversational panes; ?split=three adds the Dashboard cell).  + &theme=light.
-  document.title stamps SPLIT-READY-<visible cells> on success and
-  SPLIT-FAILED-<reason> when a driven split was denied — judge the focused
-  cell's top accent bar, the separators, and the .shown tab marker.
-
-Rebuild after ANY markup change: the dialog blocks are embedded at build
-time. Assets are symlinked, so CSS/JS edits are live on refresh.
-"""
-
-from __future__ import annotations
-
-import argparse
-import re
-from pathlib import Path
-
-ROOT = Path(__file__).resolve().parent.parent
-UI_INDEX = ROOT / "turnstone/ui/static/index.html"
-CONSOLE_INDEX = ROOT / "turnstone/console/static/index.html"
-
-
-def extract_dialogs(index: Path, only_id: str | None = None) -> list[str]:
-    """Every <dialog class="hatch ..."> block, verbatim from the tree."""
-    html = index.read_text(encoding="utf-8")
-    blocks = []
-    for m in re.finditer(r"[ \t]*<dialog\s[^>]*class=\"[^\"]*\bhatch\b[^\"]*\"", html):
-        end = html.index("</dialog>", m.start()) + len("</dialog>")
-        block = html[m.start() : end]
-        if only_id and f'id="{only_id}"' not in block:
-            continue
-        blocks.append(block)
-    if not blocks:
-        raise SystemExit(f"no dialog.hatch blocks found in {index}")
-    return blocks
-
-
-def extract_admin_fragment() -> str:
-    """The console admin pane — the hatch-host all shelves live inside."""
-    html = CONSOLE_INDEX.read_text(encoding="utf-8")
-    start = html.index('<div id="admin-layout"')
-    end = html.index("<!-- /admin-layout -->") + len("<!-- /admin-layout -->")
-    return html[start:end]
-
-
-def inject(template: str, marker: str, payload: str) -> str:
-    begin = template.index(f"<!-- {marker}:BEGIN -->") + len(f"<!-- {marker}:BEGIN -->")
-    end = template.index(f"<!-- {marker}:END -->")
-    return template[:begin] + "\n" + payload + "\n" + template[end:]
-
-
-def symlink(link: Path, target: Path) -> None:
-    if link.is_symlink() or link.exists():
-        link.unlink()
-    link.symlink_to(target)
-
-
-# --------------------------------------------------------------------------
-# UI harness — the standalone app's dialog tier.  Drives the REAL cards.js
-# controller for the batch surfaces so the production code path renders.
-# --------------------------------------------------------------------------
-UI_TEMPLATE = """<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>ui livepass</title>
-    <link rel="stylesheet" href="shared/base.css" />
-    <link rel="stylesheet" href="shared/ui-base.css" />
-    <link rel="stylesheet" href="shared/chat.css" />
-    <link rel="stylesheet" href="shared/conversation.css" />
-    <link rel="stylesheet" href="shared/cards.css" />
-    <link rel="stylesheet" href="static/style.css" />
-    <link rel="stylesheet" href="shared/shell.css" />
-    <link rel="stylesheet" href="shared/interactive.css" />
-    <link rel="stylesheet" href="shared/hatch.css" />
-  </head>
-  <body>
-    <!-- DIALOGS:BEGIN -->
-    <!-- DIALOGS:END -->
-    <div id="toast" role="status" aria-live="polite"></div>
-    <script>
-      window.authFetch = function (url) {
-        // One canned failure so the results view shows the mixed state.
-        var fail = url && url.indexOf("c3d4e5f6a1b2") !== -1;
-        return Promise.resolve({
-          ok: !fail,
-          status: fail ? 409 : 200,
-          headers: { get: function () { return "application/json"; } },
-          json: function () { return Promise.resolve({}); },
-          text: function () {
-            return Promise.resolve(
-              fail ? '{"error": "workstream is still running"}' : "",
-            );
-          },
-        });
-      };
-      window.showToast = function (msg) { console.log("toast:", msg); };
-    </script>
-    <script type="module">
-      import { openDialog, setBusy } from "./shared/hatch.js";
-      const q = new URLSearchParams(location.search);
-      if (q.get("theme") === "light")
-        document.documentElement.dataset.theme = "light";
-      const open = q.get("open") || "";
-      function fill(id, text) {
-        const el = document.getElementById(id);
-        if (el) el.textContent = text;
-      }
-      if (open === "new-ws" || open === "new-ws-fork") {
-        const dlg = document.getElementById("new-ws-dialog");
-        const canned = {
-          "new-ws-model": ["sonnet-4-6", "gpt-5-2", "qwen3-32b"],
-          "new-ws-judge-model": ["sonnet-4-6", "qwen3-32b"],
-          "new-ws-skill": ["code-review (default)", "deep-research"],
-        };
-        for (const id in canned) {
-          const s = document.getElementById(id);
-          for (const n of canned[id]) {
-            const o = document.createElement("option");
-            o.value = n;
-            o.textContent = n;
-            s.appendChild(o);
-          }
-        }
-        if (open === "new-ws-fork") {
-          fill("new-ws-title", "Fork workstream");
-          fill("new-ws-tag", "WS-FORK");
-          document.getElementById("new-ws-submit").textContent = "Fork";
-          const skillLabel = document.querySelector('label[for="new-ws-skill"]');
-          if (skillLabel) skillLabel.hidden = true;
-          document.getElementById("new-ws-skill").hidden = true;
-          document.getElementById("new-ws-attach-row").hidden = true;
-        }
-        openDialog(dlg);
-      } else if (open === "edit-title") {
-        document.getElementById("edit-title-input").value =
-          "lshell renovation pass 3";
-        openDialog(document.getElementById("edit-title-dialog"));
-      } else if (open === "delete-ws") {
-        fill(
-          "delete-ws-message",
-          'Delete "lshell renovation pass 3"? This cannot be undone.',
-        );
-        openDialog(document.getElementById("delete-ws-dialog"));
-      } else if (open === "revoke-mcp") {
-        fill(
-          "revoke-mcp-message",
-          "Revoke the connection to github? Tools that need this server will require re-consent.",
-        );
-        openDialog(document.getElementById("revoke-mcp-dialog"));
-      } else if (open === "ws-delete" || open === "ws-delete-results") {
-        // Drive the REAL shared controller so the dialog renders through
-        // the production code path (cards.js confirmSelection/confirm).
-        const mod = await import("./shared/cards.js");
-        const c = mod.createSavedCardsController({
-          idPrefix: "ws-delete",
-          buttonId: "ws-delete-btn",
-          noun: "workstream",
-          activateLabel: (s) => "Resume: " + (s.title || s.ws_id),
-          render: () => {},
-          buildDeleteRequest: (wsId) => ({
-            url: "/v1/api/workstreams/" + encodeURIComponent(wsId) + "/delete",
-            options: { method: "POST" },
-          }),
-        });
-        c.setItems([
-          { ws_id: "a1b2c3d4e5f6", title: "lshell renovation pass 3" },
-          { ws_id: "b2c3d4e5f6a1", title: "canonical trajectory spike" },
-          {
-            ws_id: "c3d4e5f6a1b2",
-            title:
-              "a very long workstream title that should wrap " +
-              "rather than punch out of the dialog box entirely",
-          },
-        ]);
-        c.toggleAll();
-        c.confirmSelection();
-        if (open === "ws-delete-results") c.confirm();
-      }
-      if (q.get("busy")) {
-        const d = document.querySelector("dialog[open]");
-        if (d) setBusy(d, true);
-      }
-    </script>
-  </body>
-</html>
-"""
-
-# --------------------------------------------------------------------------
-# Console harness — the admin pane fragment hosts the shelves (token-created
-# included); dialog-tier markup outside the fragment (confirm/install/
-# coord-delete) is injected via the RIDERS marker in build().
-# model-save click-drives the submit: document.title flips to PUT-OK-<n>.
-# --------------------------------------------------------------------------
-CONSOLE_TEMPLATE = """<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <title>console livepass</title>
-    <link rel="stylesheet" href="shared/base.css" />
-    <link rel="stylesheet" href="shared/ui-base.css" />
-    <link rel="stylesheet" href="console-static/style.css" />
-    <link rel="stylesheet" href="shared/shell.css" />
-    <link rel="stylesheet" href="shared/hatch.css" />
-  </head>
-  <body>
-    <!-- The REAL L-shell chain (shell.js buildShell + pane.js DOM, verbatim
-         class names) so the harness inherits production scroll geometry:
-         .pane-body > #view-admin > .admin-layout height-pin the hatch-host
-         and .admin-content is the pane's interior scroller.  Never replace
-         this with bespoke height overrides — the clipped-pane / displaced-
-         shelf regressions were invisible to the harness precisely because
-         it used to pin #admin-layout with its own CSS. -->
-    <div class="app">
-      <aside class="rail" id="shell-rail">
-        <div class="rail-brand">
-          <button class="brand-home" type="button">
-            <div class="brand-mark"></div>
-            <span class="brand-name">turnstone</span>
-            <span class="brand-sub">console</span>
-          </button>
-        </div>
-      </aside>
-      <main class="content">
-        <div class="tabbar"></div>
-        <div class="panes">
-          <section class="pane">
-            <!-- no .pane-head: PaneManager._mount builds section.pane >
-                 div.pane-body only -->
-            <div class="pane-body">
-              <div id="view-admin">
-                <!-- FRAGMENT:BEGIN -->
-                <!-- FRAGMENT:END -->
-              </div>
-            </div>
-          </section>
-        </div>
-      </main>
-    </div>
-    <!-- Body-level dialog tier (confirm / install / coord-delete): their
-         markup sits OUTSIDE #admin-layout in index.html, so the fragment
-         extraction misses them — build() injects every hatch dialog the
-         fragment does not already contain. -->
-    <!-- RIDERS:BEGIN -->
-    <!-- RIDERS:END -->
-    <div id="toast" role="status" aria-live="polite"></div>
-    <script>
-      (function () {
-        function reply(data) {
-          return Promise.resolve({
-            ok: true,
-            status: 200,
-            headers: { get: function () { return "application/json"; } },
-            json: function () { return Promise.resolve(data); },
-            text: function () { return Promise.resolve(JSON.stringify(data)); },
-          });
-        }
-        var SCHED = {
-          task_id: "t1", name: "nightly-digest", description: "Morning digest",
-          schedule_type: "cron", cron_expr: "0 6 * * 1,3,5", at_time: "",
-          target_mode: "auto", model: "fable-5", skill: "daily-digest",
-          initial_message: "Summarize overnight cluster activity.",
-          auto_approve: false, enabled: true,
-          notify_targets: [{ channel_type: "discord", channel_id: "8675309" }],
-          next_run: "2026-06-10T06:00:00",
-        };
-        var MODEL = {
-          definition_id: "def1", alias: "fable-5", model: "claude-fable-5",
-          provider: "anthropic", base_url: "", context_window: 200000,
-          capabilities: JSON.stringify({ supports_vision: true }),
-          enabled: true, temperature: null, max_tokens: null,
-          reasoning_effort: null, surface_persisted_reasoning: true,
-          replay_reasoning_to_model: false,
-        };
-        window.__putCount = 0;
-        window.authFetch = function (url, opts) {
-          var method = (opts && opts.method) || "GET";
-          if (method === "PUT" && url.indexOf("/model-definitions/def1") >= 0) {
-            window.__putCount++;
-            document.title = "PUT-OK-" + window.__putCount;
-            return reply({ ok: true });
-          }
-          if (url.indexOf("/schedules/preview") >= 0)
-            return reply({
-              valid: true, error: "",
-              next: [
-                "2026-06-10T06:00:00+00:00",
-                "2026-06-12T06:00:00+00:00",
-                "2026-06-15T06:00:00+00:00",
-              ],
-            });
-          if (url.indexOf("/schedules/t1") >= 0) return reply(SCHED);
-          if (url.indexOf("/schedules") >= 0) return reply({ schedules: [SCHED] });
-          if (url.indexOf("/model-capabilities/known") >= 0)
-            return reply({ models: ["claude-fable-5", "claude-opus-4-8"] });
-          if (url.indexOf("/model-capabilities?") >= 0)
-            return reply({
-              known: true,
-              capabilities: {
-                context_window: 200000, supports_tools: true,
-                supports_streaming: true, supports_vision: true,
-                supports_web_search: true, supports_temperature: true,
-                supports_effort: true,
-              },
-            });
-          if (url.indexOf("/model-definitions/def1") >= 0) return reply(MODEL);
-          if (url.indexOf("/model-definitions") >= 0) return reply({ models: [] });
-          if (url.indexOf("/api/models") >= 0)
-            return reply({ models: [
-              { alias: "fable-5", model: "claude-fable-5" },
-              { alias: "gpt-5.2", model: "gpt-5.2" },
-            ] });
-          if (url.indexOf("/skills") >= 0)
-            return reply({ skills: [{ name: "daily-digest" }, { name: "ops-runbook" }] });
-          if (url.indexOf("/policies") >= 0)
-            return reply({ policies: [
-              { policy_id: "p1", name: "deny-rm", tool_pattern: "bash*rm*",
-                action: "deny", priority: 900, enabled: true },
-              { policy_id: "p2", name: "default-ask", tool_pattern: "*",
-                action: "ask", priority: 0, enabled: true },
-            ] });
-          return reply({});
-        };
-        window.showToast = function (m) {
-          console.log("toast:", m);
-          var t = document.getElementById("toast");
-          t.textContent = m;
-          t.classList.add("show");
-        };
-      })();
-    </script>
-    <script type="module" src="shared/utils.js"></script>
-    <script type="module" src="shared/hatch.js"></script>
-    <script src="console-static/admin.js"></script>
-    <script src="console-static/governance.js"></script>
-    <script>
-      window.addEventListener("load", function () {
-        var q = new URLSearchParams(location.search);
-        if (q.get("theme") === "light")
-          document.documentElement.dataset.theme = "light";
-        var open = q.get("open") || "";
-        // ?tall=1 — the scroll state: one panel visible with enough rows to
-        // overflow the pane, so a screenshot shows .admin-content scrolling
-        // (and a shelf staying docked above it).  Mirrors switchAdminTab's
-        // one-panel-visible invariant without booting the tab loaders.
-        if (q.get("tall")) {
-          var panels = document.querySelectorAll(".admin-panel");
-          for (var i = 0; i < panels.length; i++)
-            panels[i].style.display =
-              panels[i].id === "admin-users" ? "" : "none";
-          // No fallback: a fragment rename must fail loudly, not misplace rows.
-          var rowHost = document.querySelector("#admin-users [role=list]");
-          rowHost.textContent = ""; // drop the static "Loading users…" stub
-          for (var r = 0; r < 90; r++) {
-            var row = document.createElement("div");
-            row.className = "admin-row"; // real row chrome — geometry tracks production
-            row.textContent =
-              "user-" + String(r).padStart(3, "0") + " \\u00b7 synthetic row";
-            rowHost.appendChild(row);
-          }
-          var content = document.getElementById("admin-content");
-          if (content && q.get("scrolled"))
-            content.scrollTop =
-              q.get("scrolled") === "bottom"
-                ? content.scrollHeight // the 24px scroll-tail state
-                : content.scrollHeight / 2; // land mid-list
-        }
-        setTimeout(function () {
-          if (open === "schedule-create") showCreateScheduleModal();
-          else if (open === "schedule-edit") showEditScheduleModal("t1");
-          else if (open === "model-create") showCreateModelModal();
-          else if (open === "model-edit" || open === "model-save")
-            showEditModelModal("def1");
-          else if (open === "policy") {
-            window._govPolicies && _govPolicies.length === 0 &&
-              loadGovPolicies && loadGovPolicies();
-            showCreatePolicyModal();
-          } else if (open === "confirm")
-            showConfirmModal(
-              "Delete schedule",
-              "Delete nightly-digest? Its run history is removed with it. This cannot be undone.",
-              "Delete",
-              function () {},
-            );
-          else if (open === "token")
-            showTokenCreatedModal(
-              "tsk_9f2e41c7a8b35d60e1f4a2b89c7d3e5f6a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d",
-            );
-          if (open === "model-save")
-            setTimeout(function () {
-              document.getElementById("model-create-submit").click();
-            }, 900);
-          if (q.get("busy"))
-            setTimeout(function () {
-              var d = document.querySelector("dialog[open]");
-              if (d) window.TurnstoneHatch.setBusy(d, true);
-            }, 400);
-          // A driven state that ends with nothing open must fail LOUDLY in
-          // the screenshot pipeline, not render a quietly dialog-less page.
-          setTimeout(function () {
-            var top = document.querySelector("dialog[open]");
-            if (open && !top) document.title = "OPEN-FAILED-" + open;
-            // &focuslast=1 — the displaced-dock regression probe: focus the
-            // last form control in the shelf BODY (the visually-hidden
-            // toggle/radio inputs live there).  Only .sh-body may scroll;
-            // the head/foot strips must stay pinned in the screenshot.
-            if (top && q.get("focuslast")) {
-              var els = top.querySelectorAll(
-                ".sh-body input, .sh-body select, .sh-body textarea",
-              );
-              if (els.length) els[els.length - 1].focus();
-            }
-          }, 600);
-        }, 150);
-      });
-    </script>
-  </body>
-</html>
-"""
-
-
-# --------------------------------------------------------------------------
-# Shell harness — the SPLIT-VIEW surface.  Unlike the ui/console pages (which
-# embed extracted markup), this one boots the REAL shell.js + pane.js over
-# stubbed classic seams and drives the split engine via ?split=.  Two demo
-# conversational panes give the cells plausible content; the Dashboard pane
-# (registered by the shell itself) fills the third cell in ?split=three.
-# Loud-failure rule: the title stamps SPLIT-READY-<cells> only when the built
-# state matches the request — a denied/failed split stamps SPLIT-FAILED-<why>.
-# --------------------------------------------------------------------------
-SHELL_TEMPLATE = """<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>shell livepass</title>
-    <link rel="stylesheet" href="shared/base.css" />
-    <link rel="stylesheet" href="shared/ui-base.css" />
-    <link rel="stylesheet" href="shared/chat.css" />
-    <link rel="stylesheet" href="shared/conversation.css" />
-    <link rel="stylesheet" href="shared/cards.css" />
-    <link rel="stylesheet" href="static/style.css" />
-    <link rel="stylesheet" href="shared/shell.css" />
-    <link rel="stylesheet" href="shared/interactive.css" />
-  </head>
-  <body>
-    <div id="header"><div id="status-bar"></div><button id="theme-toggle">☾</button></div>
-    <div id="breadcrumb"></div>
-    <div id="main" style="padding: 18px">
-      <h2 style="margin: 0 0 8px">Dashboard</h2>
-      <p style="color: var(--ink-3)">
-        Launcher + workstreams table live here (livepass stub).
-      </p>
-    </div>
-    <div id="view-admin" style="display: none"></div>
-    <script>
-      window.TURNSTONE_SHELL_CAPS = { cluster: false, brandSub: "console" };
-      window.TS_APP = {
-        boot() {},
-        getClusterState() { return { nodes: {} }; },
-        onRender() {},
-      };
-      window.TS_ADMIN = {};
-      var q = new URLSearchParams(location.search);
-      if (q.get("theme") === "light")
-        document.documentElement.dataset.theme = "light";
-    </script>
-    <script type="module" src="shared/shell.js"></script>
-    <script type="module">
-      const q = new URLSearchParams(location.search);
-      for (let i = 0; i < 100 && !window.TS_SHELL; i++)
-        await new Promise((r) => setTimeout(r, 20));
-      if (!window.TS_SHELL) {
-        document.title = "SPLIT-FAILED-no-shell";
-      } else {
-        sessionStorage.clear();
-        const pm = window.TS_SHELL.panes;
-        const { ShellPane } = await import("./shared/pane.js");
-        const mkConv = (type, title, lines) => {
-          pm.registerType(type, () => {
-            const p = new ShellPane({ type, title });
-            p.tabMenu = () => [
-              { label: "Close pane", action: () => pm.close(p.id) },
-            ];
-            p.onMount = function () {
-              const wrap = document.createElement("div");
-              wrap.style.cssText =
-                "flex:1;min-height:0;padding:16px;display:flex;flex-direction:column;gap:10px;overflow:auto;";
-              for (const [role, text] of lines) {
-                const d = document.createElement("div");
-                d.className = "msg " + role;
-                d.textContent = text;
-                wrap.append(d);
-              }
-              // Edge-touching opaque chrome — the strip that occluded the
-              // focus ring before the ::after overlay; keeps the bug class
-              // visible in every future pass.
-              const sb = document.createElement("div");
-              sb.className = "ws-status-bar";
-              sb.textContent = "17,418 / 393,216 (4.4%) · max 9 tools";
-              this.bodyEl.append(wrap, sb);
-            };
-            return p;
-          });
-        };
-        mkConv("repro", "repro-flaky-suite", [
-          ["user", "Track down the flaky retry in the channel gateway tests."],
-          [
-            "assistant",
-            "Three suspects so far — the debounce window in mcp_client, the " +
-              "circuit-breaker reset, and the socket-mode reconnect. Bisecting now.",
-          ],
-          [
-            "assistant",
-            "Found it: the breaker reset races the stream pre-close. Patch incoming.",
-          ],
-        ]);
-        mkConv("relnotes", "draft-1.6.2-notes", [
-          ["user", "Draft the 1.6.2 patch notes from the merged PR list."],
-          [
-            "assistant",
-            "Pulling #657–#662. Consent badge, orphan verb, MCP task hygiene, " +
-              "the anthropic-compatible lane, and the mcp<2 cap.",
-          ],
-        ]);
-        pm.openPane("repro");
-        pm.openPane("relnotes");
-        const want = q.get("split") || "right";
-        let failed = null;
-        if (want !== "none") {
-          const r1 = pm.splitFocused("right");
-          if (!r1.ok) failed = r1.reason;
-          if (!failed && (want === "three" || want === "down")) {
-            const r2 = pm.splitFocused("down");
-            if (!r2.ok) failed = r2.reason;
-          }
-        }
-        const cells = document.querySelectorAll(
-          ".panes > section.pane:not([hidden])",
-        ).length;
-        document.title = failed
-          ? "SPLIT-FAILED-" + failed
-          : "SPLIT-READY-" + cells;
-      }
-    </script>
-  </body>
-</html>
-"""
-
-
-def build(out: Path) -> None:
-    ui = out / "ui"
-    con = out / "console"
-    ui.mkdir(parents=True, exist_ok=True)
-    con.mkdir(parents=True, exist_ok=True)
-
-    symlink(ui / "shared", ROOT / "turnstone/shared_static")
-    symlink(ui / "static", ROOT / "turnstone/ui/static")
-    blocks = extract_dialogs(UI_INDEX)
-    # the coordinator batch dialog shares the cards.js builder — ride along
-    blocks += extract_dialogs(CONSOLE_INDEX, only_id="coord-delete-dialog")
-    (ui / "livepass.html").write_text(
-        inject(UI_TEMPLATE, "DIALOGS", "\n".join(blocks)), encoding="utf-8"
-    )
-    print(f"{ui}/livepass.html — {len(blocks)} dialogs")
-
-    symlink(con / "shared", ROOT / "turnstone/shared_static")
-    symlink(con / "console-static", ROOT / "turnstone/console/static")
-    frag = extract_admin_fragment()
-    # Dialog-tier markup living OUTSIDE #admin-layout (confirm, install,
-    # coord-delete) would otherwise be silently absent — and ?open=confirm
-    # would screenshot a dialog-less page while the gate stayed green.
-    riders = [b for b in extract_dialogs(CONSOLE_INDEX) if b not in frag]
-    page = inject(CONSOLE_TEMPLATE, "FRAGMENT", frag)
-    page = inject(page, "RIDERS", "\n".join(riders))
-    (con / "livepass.html").write_text(page, encoding="utf-8")
-    print(f"{con}/livepass.html — admin fragment + {len(riders)} rider dialogs")
-
-    sh = out / "shell"
-    sh.mkdir(parents=True, exist_ok=True)
-    symlink(sh / "shared", ROOT / "turnstone/shared_static")
-    symlink(sh / "static", ROOT / "turnstone/console/static")
-    (sh / "livepass.html").write_text(SHELL_TEMPLATE, encoding="utf-8")
-    print(f"{sh}/livepass.html — split-view shell surface")
-
-
-def main() -> None:
-    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
-    ap.add_argument("--out", type=Path, default=Path("/tmp/livepass"))
-    ap.add_argument("--serve", type=int, metavar="PORT")
-    args = ap.parse_args()
-    build(args.out)
-    if args.serve:
-        import functools
-        import http.server
-
-        handler = functools.partial(http.server.SimpleHTTPRequestHandler, directory=str(args.out))
-        print(f"serving {args.out} on http://localhost:{args.serve}/ — Ctrl+C stops")
-        http.server.ThreadingHTTPServer(("127.0.0.1", args.serve), handler).serve_forever()
-
-
-if __name__ == "__main__":
-    main()
@@ -50,14 +50,11 @@ update_refs() {
    local old_pattern="$1"  # e.g. katex-0.16.38
    local new_pattern="$2"  # e.g. katex-0.16.39

-    # Find all files with version references. Excludes the old versioned vendor
-    # directory itself (about to be rm -rf'd anyway) so we don't bother rewriting
-    # self-references inside it — but does NOT exclude all of shared_static/,
-    # because shared_static/renderer.js loads the vendored libs and needs the bump.
+    # Find all files with version references (excludes vendored JS and worktrees)
    local files
-    files=$(grep -rl --include='*.toml' --include='*.html' --include='*.js' --include='*.md' --include='*.py' \
+    files=$(grep -rl --include='*.toml' --include='*.html' --include='*.js' --include='*.md' \
        -F "$old_pattern" . \
-        --exclude-dir='.claude' --exclude-dir='node_modules' --exclude-dir="$old_pattern" \
+        --exclude-dir='.claude' --exclude-dir='node_modules' --exclude-dir='shared_static' \
        2>/dev/null || true)
    for f in $files; do
        sed -i "s|${old_pattern}|${new_pattern}|g" "$f"
@@ -7,7 +7,7 @@
    "": {
      "name": "@turnstone/sdk",
      "version": "0.4.0",
-      "license": "Apache-2.0",
+      "license": "BUSL-1.1",
      "devDependencies": {
        "typescript": "^6.0.0",
        "vitest": "^4.1"
@@ -74,9 +74,9 @@
      }
    },
    "node_modules/@oxc-project/types": {
-      "version": "0.133.0",
-      "resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.133.0.tgz",
-      "integrity": "sha512-KzkdCd6Uxqnf6l3HOw1xfatAlUURA0g14cvBYFyJ5SaNOQbOUvBr9PKArcPcrNIeRsBdgcUzOGrhKveVpvOIGA==",
+      "version": "0.127.0",
+      "resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.127.0.tgz",
+      "integrity": "sha512-aIYXQBo4lCbO4z0R3FHeucQHpF46l2LbMdxRvqvuRuW2OxdnSkcng5B8+K12spgLDj93rtN3+J2Vac/TIO+ciQ==",
      "dev": true,
      "license": "MIT",
      "funding": {
@@ -84,9 +84,9 @@
      }
    },
    "node_modules/@rolldown/binding-android-arm64": {
-      "version": "1.0.3",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm64/-/binding-android-arm64-1.0.3.tgz",
-      "integrity": "sha512-454rs7jHngixp/NMxd5srYD57OnzSlZ/eFTETjORQHLwJG1lRtmNOJcBerZlfu4GjKqeq8aCCIQrMdHyhI51Hw==",
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm64/-/binding-android-arm64-1.0.0-rc.17.tgz",
+      "integrity": "sha512-s70pVGhw4zqGeFnXWvAzJDlvxhlRollagdCCKRgOsgUOH3N1l0LIxf83AtGzmb5SiVM4Hjl5HyarMRfdfj3DaQ==",
      "cpu": [
        "arm64"
      ],
@@ -101,9 +101,9 @@
      }
    },
    "node_modules/@rolldown/binding-darwin-arm64": {
-      "version": "1.0.3",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-arm64/-/binding-darwin-arm64-1.0.3.tgz",
-      "integrity": "sha512-PcAhP+ynjURNyy8SKGl5DQP94aGuB/7JrXJb/t7P+hanXvQVMWzUvRRhBAcg/lNRadBhoUPqSoP4xw5tR/KBEA==",
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-arm64/-/binding-darwin-arm64-1.0.0-rc.17.tgz",
+      "integrity": "sha512-4ksWc9n0mhlZpZ9PMZgTGjeOPRu8MB1Z3Tz0Mo02eWfWCHMW1zN82Qz/pL/rC+yQa+8ZnutMF0JjJe7PjwasYw==",
      "cpu": [
        "arm64"
      ],
@@ -118,9 +118,9 @@
      }
    },
    "node_modules/@rolldown/binding-darwin-x64": {
-      "version": "1.0.3",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-x64/-/binding-darwin-x64-1.0.3.tgz",
-      "integrity": "sha512-9YpfeUvSE2RS7wysJ81uOZkXJz7f7Q55H2Gvp3VEw/EsahqDtrphrZ0EwDLK5vvKOzaCrBsjF8JmnMLcUt78Gg==",
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-x64/-/binding-darwin-x64-1.0.0-rc.17.tgz",
+      "integrity": "sha512-SUSDOI6WwUVNcWxd02QEBjLdY1VPHvlEkw6T/8nYG322iYWCTxRb1vzk4E+mWWYehTp7ERibq54LSJGjmouOsw==",
      "cpu": [
        "x64"
      ],
@@ -135,9 +135,9 @@
      }
    },
    "node_modules/@rolldown/binding-freebsd-x64": {
-      "version": "1.0.3",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-freebsd-x64/-/binding-freebsd-x64-1.0.3.tgz",
-      "integrity": "sha512-yB1IlAsSNHncV6SCTL27/MVGR5htvQsoGxIv5KMGXALp+Ll1wYsn+x98M9MW7qa+NdSbvrrY7ANI4wLJ0n1e6g==",
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-freebsd-x64/-/binding-freebsd-x64-1.0.0-rc.17.tgz",
+      "integrity": "sha512-hwnz3nw9dbJ05EDO/PvcjaaewqqDy7Y1rn1UO81l8iIK1GjenME75dl16ajbvSSMfv66WXSRCYKIqfgq2KCfxw==",
      "cpu": [
        "x64"
      ],
@@ -152,9 +152,9 @@
      }
    },
    "node_modules/@rolldown/binding-linux-arm-gnueabihf": {
-      "version": "1.0.3",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-1.0.3.tgz",
-      "integrity": "sha512-Yi30IVAAfLUCy2MseFjbB1jAMDl1VMCAas5StnYp8da9+CKvMd2H2cbEjWcw5NPaPqzvYkVIaF1nNUG+b7u/sw==",
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-1.0.0-rc.17.tgz",
+      "integrity": "sha512-IS+W7epTcwANmFSQFrS1SivEXHtl1JtuQA9wlxrZTcNi6mx+FDOYrakGevvvTwgj2JvWiK8B29/qD9BELZPyXQ==",
      "cpu": [
        "arm"
      ],
@@ -169,9 +169,9 @@
      }
    },
    "node_modules/@rolldown/binding-linux-arm64-gnu": {
-      "version": "1.0.3",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.0.3.tgz",
-      "integrity": "sha512-jsO7R8To+AdlYgUmN5sHSCZbfhtMBkO0WUx8iORQnPcMMdgr7qM2DQmMwgabs3GhNztdmoKkMKQFHD6DTMCIQw==",
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.0.0-rc.17.tgz",
+      "integrity": "sha512-e6usGaHKW5BMNZOymS1UcEYGowQMWcgZ71Z17Sl/h2+ZziNJ1a9n3Zvcz6LdRyIW5572wBCTH/Z+bKuZouGk9Q==",
      "cpu": [
        "arm64"
      ],
@@ -189,9 +189,9 @@
      }
    },
    "node_modules/@rolldown/binding-linux-arm64-musl": {
-      "version": "1.0.3",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.0.3.tgz",
-      "integrity": "sha512-VWkUHwWriDciit80wleYwKILoR/KMvxh/IdwS/paX+ZgpuRpCrKLUdadJbc0NpBEiyhpYawsJ73j9aCvOH+f7Q==",
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.0.0-rc.17.tgz",
+      "integrity": "sha512-b/CgbwAJpmrRLp02RPfhbudf5tZnN9nsPWK82znefso832etkem8H7FSZwxrOI9djcdTP7U6YfNhbRnh7djErg==",
      "cpu": [
        "arm64"
      ],
@@ -209,9 +209,9 @@
      }
    },
    "node_modules/@rolldown/binding-linux-ppc64-gnu": {
-      "version": "1.0.3",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-1.0.3.tgz",
-      "integrity": "sha512-5f1laC0SlIR0yDbFCd8acUhvJIag6N3zC5P7oUPN6wX0aOma+uKJ0wBDH5aq7I1PVI2ttTlhJwzwRIBnLiSGEg==",
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-1.0.0-rc.17.tgz",
+      "integrity": "sha512-4EII1iNGRUN5WwGbF/kOh/EIkoDN9HsupgLQoXfY+D1oyJm7/F4t5PYU5n8SWZgG0FEwakyM8pGgwcBYruGTlA==",
      "cpu": [
        "ppc64"
      ],
@@ -229,9 +229,9 @@
      }
    },
    "node_modules/@rolldown/binding-linux-s390x-gnu": {
-      "version": "1.0.3",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-1.0.3.tgz",
-      "integrity": "sha512-Iq4ko0r4XsgbrF/LunNgHtAGLRRVE2kXonAXQ/MV0mC6jQpMOhW1SvtZja2EhC/kd05++bP78dsqBeIQyYJ6Yg==",
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-1.0.0-rc.17.tgz",
+      "integrity": "sha512-AH8oq3XqQo4IibpVXvPeLDI5pzkpYn0WiZAfT05kFzoJ6tQNzwRdDYQ45M8I/gslbodRZwW8uxLhbSBbkv96rA==",
      "cpu": [
        "s390x"
      ],
@@ -249,9 +249,9 @@
      }
    },
    "node_modules/@rolldown/binding-linux-x64-gnu": {
-      "version": "1.0.3",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.0.3.tgz",
-      "integrity": "sha512-B8m6tD5+/N5FeNQFbKlLA/2yVq9ycQP1SeedyEYYKWBNR3ZQbkvIUcNnDNM03lO1l5F2roiiFJGgvoLLyZXtSg==",
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.0.0-rc.17.tgz",
+      "integrity": "sha512-cLnjV3xfo7KslbU41Z7z8BH/E1y5mzUYzAqih1d1MDaIGZRCMqTijqLv76/P7fyHuvUcfGsIpqCdddbxLLK9rA==",
      "cpu": [
        "x64"
      ],
@@ -269,9 +269,9 @@
      }
    },
    "node_modules/@rolldown/binding-linux-x64-musl": {
-      "version": "1.0.3",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-musl/-/binding-linux-x64-musl-1.0.3.tgz",
-      "integrity": "sha512-pSdpdUJHkuCxun9LE7jvgUB9qsRgaiyNNCX7m/AvHTcq67AiT/Yhoxvw5zPfhrM8k/BfP8ce/hMOpthKDpEUow==",
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-musl/-/binding-linux-x64-musl-1.0.0-rc.17.tgz",
+      "integrity": "sha512-0phclDw1spsL7dUB37sIARuis2tAgomCJXAHZlpt8PXZ4Ba0dRP1e+66lsRqrfhISeN9bEGNjQs+T/Fbd7oYGw==",
      "cpu": [
        "x64"
      ],
@@ -289,9 +289,9 @@
      }
    },
    "node_modules/@rolldown/binding-openharmony-arm64": {
-      "version": "1.0.3",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-openharmony-arm64/-/binding-openharmony-arm64-1.0.3.tgz",
-      "integrity": "sha512-OXXS3RKJgX2uLwM+gYyuH5omcH8fL1LJs96pZGgtetVCahON57+d4SJHzTgZiOjxgGkSnpXpOsWuPDGAKAigEg==",
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-openharmony-arm64/-/binding-openharmony-arm64-1.0.0-rc.17.tgz",
+      "integrity": "sha512-0ag/hEgXOwgw4t8QyQvUCxvEg+V0KBcA6YuOx9g0r02MprutRF5dyljgm3EmR02O292UX7UeS6HzWHAl6KgyhA==",
      "cpu": [
        "arm64"
      ],
@@ -306,9 +306,9 @@
      }
    },
    "node_modules/@rolldown/binding-wasm32-wasi": {
-      "version": "1.0.3",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-wasm32-wasi/-/binding-wasm32-wasi-1.0.3.tgz",
-      "integrity": "sha512-JTtb8BWFynicNSoPrehsCzBtOKjZ6jhMiPFEmOiuXg1Fl8dn2KHQob+GuPSGR0dryQa1PQJbzjF3dqO/whhjLg==",
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-wasm32-wasi/-/binding-wasm32-wasi-1.0.0-rc.17.tgz",
+      "integrity": "sha512-LEXei6vo0E5wTGwpkJ4KoT3OZJRnglwldt5ziLzOlc6qqb55z4tWNq2A+PFqCJuvWWdP53CVhG1Z9NtToDPJrA==",
      "cpu": [
        "wasm32"
      ],
@@ -325,9 +325,9 @@
      }
    },
    "node_modules/@rolldown/binding-win32-arm64-msvc": {
-      "version": "1.0.3",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.0.3.tgz",
-      "integrity": "sha512-gEdFFEN70A/jxb2svrWsN3aDL7OUtmvlOy+6fa2jxG8K0wQ1ZbdeLGnidov6Yu5/733dI5ySfzFlQ/cb0bSz1g==",
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.0.0-rc.17.tgz",
+      "integrity": "sha512-gUmyzBl3SPMa6hrqFUth9sVfcLBlYsbMzBx5PlexMroZStgzGqlZ26pYG89rBb45Mnia+oil6YAIFeEWGWhoZA==",
      "cpu": [
        "arm64"
      ],
@@ -342,9 +342,9 @@
      }
    },
    "node_modules/@rolldown/binding-win32-x64-msvc": {
-      "version": "1.0.3",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.0.3.tgz",
-      "integrity": "sha512-eXB7CHuaQdqmJcc3koCNtNPmT/bj2gc999kUFgBxG8Ac0NdgXc4rkCHhqrgrhN3zddvvvrgzj1e90SuSfmyIXA==",
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.0.0-rc.17.tgz",
+      "integrity": "sha512-3hkiolcUAvPB9FLb3UZdfjVVNWherN1f/skkGWJP/fgSQhYUZpSIRr0/I8ZK9TkF3F7kxvJAk0+IcKvPHk9qQg==",
      "cpu": [
        "x64"
      ],
@@ -359,9 +359,9 @@
      }
    },
    "node_modules/@rolldown/pluginutils": {
-      "version": "1.0.1",
-      "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.1.tgz",
-      "integrity": "sha512-2j9bGt5Jh8hj+vPtgzPtl72j0yRxHAyumoo6TNfAjsLB04UtpSvPbPcDcBMxz7n+9CYB0c1GxQFxYRg2jimqGw==",
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.0-rc.17.tgz",
+      "integrity": "sha512-n8iosDOt6Ig1UhJ2AYqoIhHWh/isz0xpicHTzpKBeotdVsTEcxsSA/i3EVM7gQAj0rU27OLAxCjzlj15IWY7bg==",
      "dev": true,
      "license": "MIT"
    },
@@ -373,9 +373,9 @@
      "license": "MIT"
    },
    "node_modules/@tybys/wasm-util": {
-      "version": "0.10.2",
-      "resolved": "https://registry.npmjs.org/@tybys/wasm-util/-/wasm-util-0.10.2.tgz",
-      "integrity": "sha512-RoBvJ2X0wuKlWFIjrwffGw1IqZHKQqzIchKaadZZfnNpsAYp2mM0h36JtPCjNDAHGgYez/15uMBpfGwchhiMgg==",
+      "version": "0.10.1",
+      "resolved": "https://registry.npmjs.org/@tybys/wasm-util/-/wasm-util-0.10.1.tgz",
+      "integrity": "sha512-9tTaPJLSiejZKx+Bmog4uSubteqTvFrVrURwkmHixBo0G4seD0zUxp98E1DzUBJxLQ3NPwXrGKDiVjwx/DpPsg==",
      "dev": true,
      "license": "MIT",
      "optional": true,
@@ -402,23 +402,23 @@
      "license": "MIT"
    },
    "node_modules/@types/estree": {
-      "version": "1.0.9",
-      "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.9.tgz",
-      "integrity": "sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==",
+      "version": "1.0.8",
+      "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.8.tgz",
+      "integrity": "sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==",
      "dev": true,
      "license": "MIT"
    },
    "node_modules/@vitest/expect": {
-      "version": "4.1.8",
-      "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-4.1.8.tgz",
-      "integrity": "sha512-h3nDO677RDLEGlBxyQ5CW8RlMThSKSRLUePLOx09gNIWRL40edgA1GCZSZgf1W55MFAG6/Sw14KeaAnqv0NKdQ==",
+      "version": "4.1.5",
+      "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-4.1.5.tgz",
+      "integrity": "sha512-PWBaRY5JoKuRnHlUHfpV/KohFylaDZTupcXN1H9vYryNLOnitSw60Mw9IAE2r67NbwwzBw/Cc/8q9BK3kIX8Kw==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
        "@standard-schema/spec": "^1.1.0",
        "@types/chai": "^5.2.2",
-        "@vitest/spy": "4.1.8",
-        "@vitest/utils": "4.1.8",
+        "@vitest/spy": "4.1.5",
+        "@vitest/utils": "4.1.5",
        "chai": "^6.2.2",
        "tinyrainbow": "^3.1.0"
      },
@@ -427,13 +427,13 @@
      }
    },
    "node_modules/@vitest/mocker": {
-      "version": "4.1.8",
-      "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-4.1.8.tgz",
-      "integrity": "sha512-LEiN/xe4OSIbKe9HQIp5OC24agGD9J5CnmMgsLohVVoOPWL9a2sBoR6VBx43jQZb7Kr1l4RCuyCJzcAa0+dojw==",
+      "version": "4.1.5",
+      "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-4.1.5.tgz",
+      "integrity": "sha512-/x2EmFC4mT4NNzqvC3fmesuV97w5FC903KPmey4gsnJiMQ3Be1IlDKVaDaG8iqaLFHqJ2FVEkxZk5VmeLjIItw==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
-        "@vitest/spy": "4.1.8",
+        "@vitest/spy": "4.1.5",
        "estree-walker": "^3.0.3",
        "magic-string": "^0.30.21"
      },
@@ -454,9 +454,9 @@
      }
    },
    "node_modules/@vitest/pretty-format": {
-      "version": "4.1.8",
-      "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-4.1.8.tgz",
-      "integrity": "sha512-9GasEBxpZ1VYIpqHf/0+YGg121uSNwCKOJqIrTwWP/TB7DmFCiaBpNl3aPZzoLWfWkuqhbH8vJIVobZkvdo2cA==",
+      "version": "4.1.5",
+      "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-4.1.5.tgz",
+      "integrity": "sha512-7I3q6l5qr03dVfMX2wCo9FxwSJbPdwKjy2uu/YPpU3wfHvIL4QHwVRp57OfGrDFeUJ8/8QdfBKIV12FTtLn00g==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
@@ -467,13 +467,13 @@
      }
    },
    "node_modules/@vitest/runner": {
-      "version": "4.1.8",
-      "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-4.1.8.tgz",
-      "integrity": "sha512-EmVxeBAfMJvycdjd6Hm+RbFBbA9fKvo0Kx37hNpBYoYeavH3RNsBXWDooR1mgD52dCrxIIuP7UotpfiwOikvcg==",
+      "version": "4.1.5",
+      "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-4.1.5.tgz",
+      "integrity": "sha512-2D+o7Pr82IEO46YPpoA/YU0neeyr6FTerQb5Ro7BUnBuv6NQtT/kmVnczngiMEBhzgqz2UZYl5gArejsyERDSQ==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
-        "@vitest/utils": "4.1.8",
+        "@vitest/utils": "4.1.5",
        "pathe": "^2.0.3"
      },
      "funding": {
@@ -481,14 +481,14 @@
      }
    },
    "node_modules/@vitest/snapshot": {
-      "version": "4.1.8",
-      "resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-4.1.8.tgz",
-      "integrity": "sha512-acfZboRmAIf05DEKcBQy33VXojFJjtUdLyo7oOmV9kebb2xdU01UknNiPuPZoJZQyO7DF0gZdTGTpeAzET9QPQ==",
+      "version": "4.1.5",
+      "resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-4.1.5.tgz",
+      "integrity": "sha512-zypXEt4KH/XgKGPUz4eC2AvErYx0My5hfL8oDb1HzGFpEk1P62bxSohdyOmvz+d9UJwanI68MKwr2EquOaOgMQ==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
-        "@vitest/pretty-format": "4.1.8",
-        "@vitest/utils": "4.1.8",
+        "@vitest/pretty-format": "4.1.5",
+        "@vitest/utils": "4.1.5",
        "magic-string": "^0.30.21",
        "pathe": "^2.0.3"
      },
@@ -497,9 +497,9 @@
      }
    },
    "node_modules/@vitest/spy": {
-      "version": "4.1.8",
-      "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-4.1.8.tgz",
-      "integrity": "sha512-6EevtBp6OZOPF7bmz36HrGMeP3txgVSrgebWxHOafDXGkhIzfXK14f8KF6MuFfgXXUeHxmpD3BQxkV00/3s5mA==",
+      "version": "4.1.5",
+      "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-4.1.5.tgz",
+      "integrity": "sha512-2lNOsh6+R2Idnf1TCZqSwYlKN2E/iDlD8sgU59kYVl+OMDmvldO1VDk39smRfpUNwYpNRVn3w4YfuC7KfbBnkQ==",
      "dev": true,
      "license": "MIT",
      "funding": {
@@ -507,13 +507,13 @@
      }
    },
    "node_modules/@vitest/utils": {
-      "version": "4.1.8",
-      "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-4.1.8.tgz",
-      "integrity": "sha512-uOJamYALNhfJ6iolExyQM40yIQwDqYnkKtQ5VCiSe17E33H0aQ/u+1GlRuz4LZBk6Mm3sg90G9hEbmEt37C1Zg==",
+      "version": "4.1.5",
+      "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-4.1.5.tgz",
+      "integrity": "sha512-76wdkrmfXfqGjueGgnb45ITPyUi1ycZ4IHgC2bhPDUfWHklY/q3MdLOAB+TF1e6xfl8NxNY0ZYaPCFNWSsw3Ug==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
-        "@vitest/pretty-format": "4.1.8",
+        "@vitest/pretty-format": "4.1.5",
        "convert-source-map": "^2.0.0",
        "tinyrainbow": "^3.1.0"
      },
@@ -902,9 +902,9 @@
      }
    },
    "node_modules/nanoid": {
-      "version": "3.3.12",
-      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.12.tgz",
-      "integrity": "sha512-ZB9RH/39qpq5Vu6Y+NmUaFhQR6pp+M2Xt76XBnEwDaGcVAqhlvxrl3B2bKS5D3NH3QR76v3aSrKaF/Kiy7lEtQ==",
+      "version": "3.3.11",
+      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.11.tgz",
+      "integrity": "sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w==",
      "dev": true,
      "funding": [
        {
@@ -921,18 +921,15 @@
      }
    },
    "node_modules/obug": {
-      "version": "2.1.2",
-      "resolved": "https://registry.npmjs.org/obug/-/obug-2.1.2.tgz",
-      "integrity": "sha512-AWGB9WFcRXOQs48Z/udjI5ZcZMHXwX8XPByNpOydgcGsDLIzjGizhoMWJyKAWze7AVW/2W1i+/gPX4YtKe5cyg==",
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/obug/-/obug-2.1.1.tgz",
+      "integrity": "sha512-uTqF9MuPraAQ+IsnPf366RG4cP9RtUi7MLO1N3KEc+wb0a6yKpeL0lmk2IB1jY5KHPAlTc6T/JRdC/YqxHNwkQ==",
      "dev": true,
      "funding": [
        "https://github.com/sponsors/sxzz",
        "https://opencollective.com/debug"
      ],
-      "license": "MIT",
-      "engines": {
-        "node": ">=12.20.0"
-      }
+      "license": "MIT"
    },
    "node_modules/pathe": {
      "version": "2.0.3",
@@ -962,9 +959,9 @@
      }
    },
    "node_modules/postcss": {
-      "version": "8.5.15",
-      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.15.tgz",
-      "integrity": "sha512-FfR8sjd4em2T6fb3I2MwAJU7HWVMr9zba+enmQeeWFfCbm+UOC/0X4DS8XtpUTMwWMGbjKYP7xjfNekzyGmB3A==",
+      "version": "8.5.12",
+      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.12.tgz",
+      "integrity": "sha512-W62t/Se6rA0Az3DfCL0AqJwXuKwBeYg6nOaIgzP+xZ7N5BFCI7DYi1qs6ygUYT6rvfi6t9k65UMLJC+PHZpDAA==",
      "dev": true,
      "funding": [
        {
@@ -982,7 +979,7 @@
      ],
      "license": "MIT",
      "dependencies": {
-        "nanoid": "^3.3.12",
+        "nanoid": "^3.3.11",
        "picocolors": "^1.1.1",
        "source-map-js": "^1.2.1"
      },
@@ -991,14 +988,14 @@
      }
    },
    "node_modules/rolldown": {
-      "version": "1.0.3",
-      "resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.0.3.tgz",
-      "integrity": "sha512-i00lAJ2ks1BYr7rjNjKC7BcqAS7nVfiT3QX1SI5aY+AFHblCmaUf9OE9dbdzDvW6dJxbi2ZCZiy9v3CcwOiX3g==",
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.0.0-rc.17.tgz",
+      "integrity": "sha512-ZrT53oAKrtA4+YtBWPQbtPOxIbVDbxT0orcYERKd63VJTF13zPcgXTvD4843L8pcsI7M6MErt8QtON6lrB9tyA==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
-        "@oxc-project/types": "=0.133.0",
-        "@rolldown/pluginutils": "^1.0.0"
+        "@oxc-project/types": "=0.127.0",
+        "@rolldown/pluginutils": "1.0.0-rc.17"
      },
      "bin": {
        "rolldown": "bin/cli.mjs"
@@ -1007,21 +1004,21 @@
        "node": "^20.19.0 || >=22.12.0"
      },
      "optionalDependencies": {
-        "@rolldown/binding-android-arm64": "1.0.3",
-        "@rolldown/binding-darwin-arm64": "1.0.3",
-        "@rolldown/binding-darwin-x64": "1.0.3",
-        "@rolldown/binding-freebsd-x64": "1.0.3",
-        "@rolldown/binding-linux-arm-gnueabihf": "1.0.3",
-        "@rolldown/binding-linux-arm64-gnu": "1.0.3",
-        "@rolldown/binding-linux-arm64-musl": "1.0.3",
-        "@rolldown/binding-linux-ppc64-gnu": "1.0.3",
-        "@rolldown/binding-linux-s390x-gnu": "1.0.3",
-        "@rolldown/binding-linux-x64-gnu": "1.0.3",
-        "@rolldown/binding-linux-x64-musl": "1.0.3",
-        "@rolldown/binding-openharmony-arm64": "1.0.3",
-        "@rolldown/binding-wasm32-wasi": "1.0.3",
-        "@rolldown/binding-win32-arm64-msvc": "1.0.3",
-        "@rolldown/binding-win32-x64-msvc": "1.0.3"
+        "@rolldown/binding-android-arm64": "1.0.0-rc.17",
+        "@rolldown/binding-darwin-arm64": "1.0.0-rc.17",
+        "@rolldown/binding-darwin-x64": "1.0.0-rc.17",
+        "@rolldown/binding-freebsd-x64": "1.0.0-rc.17",
+        "@rolldown/binding-linux-arm-gnueabihf": "1.0.0-rc.17",
+        "@rolldown/binding-linux-arm64-gnu": "1.0.0-rc.17",
+        "@rolldown/binding-linux-arm64-musl": "1.0.0-rc.17",
+        "@rolldown/binding-linux-ppc64-gnu": "1.0.0-rc.17",
+        "@rolldown/binding-linux-s390x-gnu": "1.0.0-rc.17",
+        "@rolldown/binding-linux-x64-gnu": "1.0.0-rc.17",
+        "@rolldown/binding-linux-x64-musl": "1.0.0-rc.17",
+        "@rolldown/binding-openharmony-arm64": "1.0.0-rc.17",
+        "@rolldown/binding-wasm32-wasi": "1.0.0-rc.17",
+        "@rolldown/binding-win32-arm64-msvc": "1.0.0-rc.17",
+        "@rolldown/binding-win32-x64-msvc": "1.0.0-rc.17"
      }
    },
    "node_modules/siginfo": {
@@ -1063,9 +1060,9 @@
      "license": "MIT"
    },
    "node_modules/tinyexec": {
-      "version": "1.2.4",
-      "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-1.2.4.tgz",
-      "integrity": "sha512-SHf/r48b7vOrjve9PxJo3MN5v5yuyjHvdUcrQffT3WXMUfnGmHDVbC4k3sHJaJTgZCwpUplIaAo5ANtMyp3YHg==",
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-1.1.1.tgz",
+      "integrity": "sha512-VKS/ZaQhhkKFMANmAOhhXVoIfBXblQxGX1myCQ2faQrfmobMftXeJPcZGp0gS07ocvGJWDLZGyOZDadDBqYIJg==",
      "dev": true,
      "license": "MIT",
      "engines": {
@@ -1073,9 +1070,9 @@
      }
    },
    "node_modules/tinyglobby": {
-      "version": "0.2.17",
-      "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.17.tgz",
-      "integrity": "sha512-wXR/dYpcqKmfWpEdZjiKJOwCNFndD0DMnrW/cYjVGttEkBfVgcLFHoNrlj47mjOVic9yyNu65alsgF4NQyTa2g==",
+      "version": "0.2.16",
+      "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.16.tgz",
+      "integrity": "sha512-pn99VhoACYR8nFHhxqix+uvsbXineAasWm5ojXoN8xEwK5Kd3/TrhNn1wByuD52UxWRLy8pu+kRMniEi6Eq9Zg==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
@@ -1122,17 +1119,17 @@
      }
    },
    "node_modules/vite": {
-      "version": "8.0.16",
-      "resolved": "https://registry.npmjs.org/vite/-/vite-8.0.16.tgz",
-      "integrity": "sha512-h9bXPmJichP5fLmVQo3PyaGSDE2n3aPuomeAlVRm0JLmt4rY6zmPKd59HYI4LNW8oTK7tlTsuC7l/m7awx9Jcw==",
+      "version": "8.0.10",
+      "resolved": "https://registry.npmjs.org/vite/-/vite-8.0.10.tgz",
+      "integrity": "sha512-rZuUu9j6J5uotLDs+cAA4O5H4K1SfPliUlQwqa6YEwSrWDZzP4rhm00oJR5snMewjxF5V/K3D4kctsUTsIU9Mw==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
        "lightningcss": "^1.32.0",
        "picomatch": "^4.0.4",
-        "postcss": "^8.5.15",
-        "rolldown": "1.0.3",
-        "tinyglobby": "^0.2.17"
+        "postcss": "^8.5.10",
+        "rolldown": "1.0.0-rc.17",
+        "tinyglobby": "^0.2.16"
      },
      "bin": {
        "vite": "bin/vite.js"
@@ -1148,7 +1145,7 @@
      },
      "peerDependencies": {
        "@types/node": "^20.19.0 || >=22.12.0",
-        "@vitejs/devtools": "^0.1.18",
+        "@vitejs/devtools": "^0.1.0",
        "esbuild": "^0.27.0 || ^0.28.0",
        "jiti": ">=1.21.0",
        "less": "^4.0.0",
@@ -1200,19 +1197,19 @@
      }
    },
    "node_modules/vitest": {
-      "version": "4.1.8",
-      "resolved": "https://registry.npmjs.org/vitest/-/vitest-4.1.8.tgz",
-      "integrity": "sha512-flY6ScbCIt9HThs+C5HS7jvGOB560DJtk/Z15IQROTA6zEy49Nh8T/dofWTQL+n3vswqn87sbJNiuqw1SDp5Ig==",
+      "version": "4.1.5",
+      "resolved": "https://registry.npmjs.org/vitest/-/vitest-4.1.5.tgz",
+      "integrity": "sha512-9Xx1v3/ih3m9hN+SbfkUyy0JAs72ap3r7joc87XL6jwF0jGg6mFBvQ1SrwaX+h8BlkX6Hz9shdd1uo6AF+ZGpg==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
-        "@vitest/expect": "4.1.8",
-        "@vitest/mocker": "4.1.8",
-        "@vitest/pretty-format": "4.1.8",
-        "@vitest/runner": "4.1.8",
-        "@vitest/snapshot": "4.1.8",
-        "@vitest/spy": "4.1.8",
-        "@vitest/utils": "4.1.8",
+        "@vitest/expect": "4.1.5",
+        "@vitest/mocker": "4.1.5",
+        "@vitest/pretty-format": "4.1.5",
+        "@vitest/runner": "4.1.5",
+        "@vitest/snapshot": "4.1.5",
+        "@vitest/spy": "4.1.5",
+        "@vitest/utils": "4.1.5",
        "es-module-lexer": "^2.0.0",
        "expect-type": "^1.3.0",
        "magic-string": "^0.30.21",
@@ -1240,12 +1237,12 @@
        "@edge-runtime/vm": "*",
        "@opentelemetry/api": "^1.9.0",
        "@types/node": "^20.0.0 || ^22.0.0 || >=24.0.0",
-        "@vitest/browser-playwright": "4.1.8",
-        "@vitest/browser-preview": "4.1.8",
-        "@vitest/browser-webdriverio": "4.1.8",
-        "@vitest/coverage-istanbul": "4.1.8",
-        "@vitest/coverage-v8": "4.1.8",
-        "@vitest/ui": "4.1.8",
+        "@vitest/browser-playwright": "4.1.5",
+        "@vitest/browser-preview": "4.1.5",
+        "@vitest/browser-webdriverio": "4.1.5",
+        "@vitest/coverage-istanbul": "4.1.5",
+        "@vitest/coverage-v8": "4.1.5",
+        "@vitest/ui": "4.1.5",
        "happy-dom": "*",
        "jsdom": "*",
        "vite": "^6.0.0 || ^7.0.0 || ^8.0.0"
@@ -30,7 +30,7 @@
    "sdk",
    "client"
  ],
-  "license": "Apache-2.0",
+  "license": "BUSL-1.1",
  "devDependencies": {
    "typescript": "^6.0.0",
    "vitest": "^4.1"
@@ -13,25 +13,6 @@ export interface ConnectedEvent {

 export interface HistoryEvent {
  type: "history";
-  /**
-   * Per-message dicts the frontend consumes directly. Notable optional keys:
-   * - `role`: "user" | "assistant" | "tool" | "system"
-   * - `content`: string for text turns, list for image/document parts
-   * - `tool_calls`: assistant turns — list of `{id, name, arguments, verdict?, output_assessment?}`
-   * - `tool_call_id`: tool turns — id of the originating call
-   * - `source`: the operator-context kind on a `system` turn (`output_guard` /
-   *   `user_interjection` / `tool_error` / ...), or `system_nudge` on a
-   *   wake-driven empty user turn
-   * - `meta`: structured per-kind fields on an operator-context `system` turn
-   *   (e.g. `watch_triggered`'s `{watch_name, command, poll_count, max_polls,
-   *   is_final}`) so the renderer can rebuild per-kind UI (the watch-result
-   *   card); absent for kinds with no structured data
-   * - `attachments`: per-attachment metadata `{kind, filename, mime_type}`
-   * - `reasoning`: concatenated reasoning text for assistant turns that
-   *   round-tripped a thinking-block lane (Anthropic-with-thinking today;
-   *   OpenAI Responses + Gemini in later phases). Present only when the
-   *   active model's `surface_persisted_reasoning` flag is true.
-   */
  messages: Array<Record<string, unknown>>;
 }

@@ -57,14 +38,6 @@ export interface StreamEndEvent {
  type: "stream_end";
 }

-/** One-shot replay of the in-progress turn's content + reasoning emitted
- *  by the events SSE handler when a fresh subscriber connects mid-stream. */
-export interface InProgressSnapshotEvent {
-  type: "in_progress_snapshot";
-  content: string;
-  reasoning: string;
-}
-
 export interface StateChangeEvent {
  type: "state_change";
  state: "idle" | "thinking" | "running" | "attention" | "error";
@@ -114,6 +87,16 @@ export interface StatusEvent {
  turn_count?: number;
 }

+export interface PlanReviewEvent {
+  type: "plan_review";
+  content: string;
+}
+
+export interface PlanResolvedEvent {
+  type: "plan_resolved";
+  feedback: string;
+}
+
 export interface InfoEvent {
  type: "info";
  message: string;
@@ -179,7 +162,6 @@ export type ServerEvent =
  | ContentEvent
  | ReasoningEvent
  | StreamEndEvent
-  | InProgressSnapshotEvent
  | StateChangeEvent
  | ToolInfoEvent
  | ApproveRequestEvent
@@ -187,6 +169,8 @@ export type ServerEvent =
  | ToolResultEvent
  | ToolOutputChunkEvent
  | StatusEvent
+  | PlanReviewEvent
+  | PlanResolvedEvent
  | InfoEvent
  | ErrorEvent
  | BusyErrorEvent
@@ -277,12 +261,6 @@ export function isStreamEndEvent(e: ServerEvent): e is StreamEndEvent {
  return e.type === "stream_end";
 }

-export function isInProgressSnapshotEvent(
-  e: ServerEvent,
-): e is InProgressSnapshotEvent {
-  return e.type === "in_progress_snapshot";
-}
-
 export function isStateChangeEvent(e: ServerEvent): e is StateChangeEvent {
  return e.type === "state_change";
 }
@@ -307,6 +285,14 @@ export function isApprovalResolvedEvent(
  return e.type === "approval_resolved";
 }

+export function isPlanReviewEvent(e: ServerEvent): e is PlanReviewEvent {
+  return e.type === "plan_review";
+}
+
+export function isPlanResolvedEvent(e: ServerEvent): e is PlanResolvedEvent {
+  return e.type === "plan_resolved";
+}
+
 export function isCancelledEvent(e: ServerEvent): e is CancelledEvent {
  return e.type === "cancelled";
 }
@@ -42,6 +42,7 @@ export type {
  ToolResultEvent,
  ToolOutputChunkEvent,
  StatusEvent,
+  PlanReviewEvent,
  InfoEvent,
  ErrorEvent,
  BusyErrorEvent,
@@ -70,6 +71,7 @@ export {
  isWsStateEvent,
  isApproveRequestEvent,
  isApprovalResolvedEvent,
+  isPlanReviewEvent,
  isCancelledEvent,
 } from "./events.js";

@@ -78,6 +80,7 @@ export type {
  SendRequest,
  SendResponse,
  ApproveRequest,
+  PlanFeedbackRequest,
  CommandRequest,
  CreateWorkstreamRequest,
  CreateWorkstreamResponse,
@@ -180,6 +180,15 @@ export class TurnstoneServer extends BaseClient {
    );
  }

+  async planFeedback(opts: {
+    wsId: string;
+    feedback?: string;
+  }): Promise<StatusResponse> {
+    return this.request("POST", "/v1/api/plan", {
+      json: { ws_id: opts.wsId, feedback: opts.feedback ?? "" },
+    });
+  }
+
  async command(opts: {
    wsId: string;
    command: string;
@@ -202,24 +211,6 @@ export class TurnstoneServer extends BaseClient {
    );
  }

-  /** Drop the last `turns` conversation turns. Emits a `clear_ui` event. */
-  async rewind(wsId: string, turns: number): Promise<StatusResponse> {
-    return this.request(
-      "POST",
-      `/v1/api/workstreams/${encodeURIComponent(wsId)}/rewind`,
-      { json: { turns } },
-    );
-  }
-
-  /** Drop the last response and re-send the last user message. */
-  async retry(wsId: string): Promise<StatusResponse> {
-    return this.request(
-      "POST",
-      `/v1/api/workstreams/${encodeURIComponent(wsId)}/retry`,
-      { json: {} },
-    );
-  }
-
  // -- Streaming ------------------------------------------------------------

  async *streamEvents(wsId: string): AsyncIterableIterator<ServerEvent> {
@@ -120,6 +120,11 @@ export interface ApproveRequest {
  ws_id: string;
 }

+export interface PlanFeedbackRequest {
+  feedback: string;
+  ws_id: string;
+}
+
 export interface CommandRequest {
  command: string;
  ws_id: string;
@@ -240,16 +245,6 @@ export interface SavedWorkstreamInfo {
  created: string;
  updated: string;
  message_count: number;
-  // Enriched fields — all optional (defaulted server-side, so an older
-  // server may omit them).
-  state?: string;
-  kind?: string;
-  node_id?: string;
-  model_alias?: string | null;
-  launch_skill?: string | null;
-  child_count?: number;
-  context_tokens?: number;
-  context_ratio?: number;
 }

 export interface ListSavedWorkstreamsResponse {
@@ -7,6 +7,8 @@ import {
  isWsStateEvent,
  isApproveRequestEvent,
  isApprovalResolvedEvent,
+  isPlanReviewEvent,
+  isPlanResolvedEvent,
  isReasoningEvent,
 } from "../src/events.js";
 import type { ServerEvent } from "../src/events.js";
@@ -70,4 +72,14 @@ describe("event type guards", () => {
    };
    expect(isApprovalResolvedEvent(e)).toBe(true);
  });
+
+  it("isPlanReviewEvent", () => {
+    const e: ServerEvent = { type: "plan_review", content: "## Plan" };
+    expect(isPlanReviewEvent(e)).toBe(true);
+  });
+
+  it("isPlanResolvedEvent", () => {
+    const e: ServerEvent = { type: "plan_resolved", feedback: "approved" };
+    expect(isPlanResolvedEvent(e)).toBe(true);
+  });
 });
@@ -290,6 +290,34 @@
        "Spin up a README.md with a project title and description in it"
      ]
    },
+    {
+      "id": "plan-when-asked",
+      "description": "Call the plan tool when the user asks to plan",
+      "user_prompt": "Plan how to add user authentication to this app.",
+      "setup": {
+        "files": {
+          "app.py": "from flask import Flask, jsonify\n\napp = Flask(__name__)\n\n@app.route('/users')\ndef list_users():\n    return jsonify([{'id': 1, 'name': 'Alice'}])\n\nif __name__ == '__main__':\n    app.run(port=8000)\n"
+        }
+      },
+      "expected_actions": [
+        {
+          "tool": "plan_agent"
+        }
+      ],
+      "match_mode": "subset",
+      "user_prompts": [
+        "Plan how to add user authentication to this app.",
+        "Make a plan for adding pagination to the API endpoints.",
+        "Plan out how to add error handling to this application.",
+        "I need a plan for adding logging to this codebase.",
+        "Plan the approach for adding unit tests to this app.",
+        "How would you approach adding user authentication to this app? Lay out a plan.",
+        "I'd like you to outline a strategy for implementing user authentication in this application.",
+        "Could you come up with a plan for integrating user authentication into this app?",
+        "Think through the steps needed to add user auth to this app and present a plan.",
+        "Draft a plan for incorporating user authentication functionality into this application."
+      ]
+    },
    {
      "id": "edit-not-rewrite",
      "description": "Use edit_file for small changes, not write_file to rewrite the entire file",
@@ -384,6 +412,58 @@
        "Hit https://example.com and let me know what's there in summary form"
      ]
    },
+    {
+      "id": "man-page-lookup",
+      "description": "Use man tool to look up command documentation",
+      "user_prompt": "Look up the man page for tar and tell me what the --xattrs flag does",
+      "expected_actions": [
+        {
+          "tool": "man",
+          "args_pattern": {
+            "page": "tar"
+          }
+        }
+      ],
+      "match_mode": "subset",
+      "user_prompts": [
+        "Look up the man page for tar and tell me what the --xattrs flag does",
+        "What does the --xattrs flag do in tar? Check the man page for me.",
+        "Could you pull up the man page for tar and explain the --xattrs option?",
+        "I need to know what --xattrs does in tar \u2014 can you check the man page?",
+        "Check tar's man page and let me know the purpose of the --xattrs flag.",
+        "Please consult the tar man page and describe what the --xattrs flag is for.",
+        "Hey, look at the tar man page real quick \u2014 what's --xattrs do?",
+        "I'd like you to read the tar man page and summarize the --xattrs option for me.",
+        "Would you mind checking the man page for tar to find out what --xattrs means?",
+        "Look into the tar manual and explain the --xattrs flag to me."
+      ]
+    },
+    {
+      "id": "math-calculation",
+      "description": "Use the math tool for precise calculations, not bash or mental math",
+      "user_prompt": "What is 2^64 - 1? Use the math tool to calculate it precisely.",
+      "expected_actions": [
+        {
+          "tool": "math",
+          "args_pattern": {
+            "code": "2.*64"
+          }
+        }
+      ],
+      "match_mode": "subset",
+      "user_prompts": [
+        "What is 2^64 - 1? Use the math tool to calculate it precisely.",
+        "Calculate 2^64 - 1 for me using the math tool, please.",
+        "I need the exact value of 2^64 - 1. Please use the math tool.",
+        "Could you use the math tool to compute 2^64 minus 1 precisely?",
+        "Use the math tool to tell me what 2^64 - 1 equals.",
+        "I'm curious: what's 2^64 - 1? Compute it with the math tool.",
+        "Please precisely determine 2^64 - 1 via the math tool.",
+        "Mind using the math tool to figure out 2^64 - 1 exactly?",
+        "I'd like to know the precise result of 2^64 - 1 \u2014 use the math tool for this.",
+        "Leverage the math tool to give me an exact answer for 2^64 - 1."
+      ]
+    },
    {
      "id": "web-search-query",
      "description": "Use web_search for general knowledge lookups, not web_fetch",
@@ -1,53 +0,0 @@
-"""Shared test helpers — kept out of conftest.py since these are factories,
-not fixtures, and several test files want to import them directly."""
-
-from __future__ import annotations
-
-from typing import Any
-from unittest.mock import MagicMock
-
-
-def make_chat_session(**overrides: Any) -> Any:
-    """Build a minimal ``ChatSession`` with sane test defaults.
-
-    Caller passes any constructor arg as a kwarg to override the default —
-    e.g. ``make_chat_session(memory_config=MemoryConfig(fetch_limit=5))``.
-    """
-    from turnstone.core.session import ChatSession
-
-    defaults: dict[str, Any] = {
-        "client": MagicMock(),
-        "model": "test-model",
-        "ui": MagicMock(),
-        "instructions": None,
-        "temperature": 0.5,
-        "max_tokens": 4096,
-        "tool_timeout": 30,
-    }
-    defaults.update(overrides)
-    return ChatSession(**defaults)
-
-
-def patch_session_storage(
-    monkeypatch: Any,
-    *,
-    active: bool = True,
-    raise_on_is_active: bool = False,
-) -> list[str]:
-    """Patch ``session.get_storage`` to a stub whose ``is_watch_active``
-    returns *active* (or raises if *raise_on_is_active*).  Returns the
-    list of ``watch_id``s the predicate was called with.
-    """
-    from turnstone.core import session as session_mod
-
-    calls: list[str] = []
-
-    class _Stub:
-        def is_watch_active(self, watch_id: str) -> bool:
-            calls.append(watch_id)
-            if raise_on_is_active:
-                raise RuntimeError("storage down")
-            return active
-
-    monkeypatch.setattr(session_mod, "get_storage", lambda: _Stub())
-    return calls
@@ -32,8 +32,8 @@ def make_replay_mocks(
            don't have to reach into the nested mock; when ``None``
            (default), the status replay branch stays inert.
        **ui_overrides: Additional attributes set directly on the ``ui``
-            mock (e.g. ``_pending_approval``, ``_llm_verdicts``,
-            ``_ws_turn_tool_calls``, ``_ws_messages``).
+            mock (e.g. ``_pending_approval``, ``_pending_plan_review``,
+            ``_llm_verdicts``, ``_ws_turn_tool_calls``, ``_ws_messages``).
    """
    session = MagicMock()
    session.model = "gpt-5"
@@ -45,6 +45,7 @@ def make_replay_mocks(
    ui = MagicMock()
    ui.auto_approve = False
    ui._pending_approval = None
+    ui._pending_plan_review = None
    ui._llm_verdicts = {}
    ui._ws_lock = threading.Lock()
    ui._ws_turn_tool_calls = 0
@@ -1,45 +0,0 @@
-"""Shared session-test helpers.
-
-Two reasoning-test modules (``test_session_replay_reasoning.py`` and
-``test_session_synth_reasoning_block.py``) need the same minimal
-``ChatSession`` factory + a ``SessionUIBase`` no-op subclass.  Hoisting
-keeps a future third caller from drifting on the defaults — the third
-existing ``_make_session`` (``test_model_registry.py``) deliberately
-takes a different signature (registry / model_alias / reasoning_effort
-+ ``_FakeUI``) and is NOT a candidate for sharing this helper.
-
-Module is named with a leading underscore so pytest doesn't try to
-collect it as a test file — it's an importable utility, not a test.
-"""
-
-from __future__ import annotations
-
-from typing import Any
-from unittest.mock import MagicMock
-
-from turnstone.core.session import ChatSession
-from turnstone.core.session_ui_base import SessionUIBase
-
-
-class NullUI(SessionUIBase):
-    """Bare-bones UI satisfying the SessionUIBase contract for tests
-    that don't care about UI side effects."""
-
-    def __init__(self) -> None:
-        super().__init__()
-
-
-def make_session(**kwargs: Any) -> ChatSession:
-    """Build a ChatSession with minimal defaults; tests override
-    individual fields via kwargs."""
-    defaults: dict[str, Any] = {
-        "client": MagicMock(),
-        "model": "test-model",
-        "ui": NullUI(),
-        "instructions": None,
-        "temperature": 0.5,
-        "max_tokens": 4096,
-        "tool_timeout": 30,
-    }
-    defaults.update(kwargs)
-    return ChatSession(**defaults)
@@ -1,79 +1,10 @@
 from __future__ import annotations

 import os
-from typing import TYPE_CHECKING, Any
 from unittest.mock import MagicMock

 import pytest

-if TYPE_CHECKING:
-    from turnstone.core.mcp_client import MCPClientManager, StaticServerState
-    from turnstone.core.mcp_crypto import MCPTokenCipher
-    from turnstone.core.oidc import OIDCConfig
-
-
-def make_mcp_token_cipher() -> MCPTokenCipher:
-    """Build a single-key MCP token cipher for tests.
-
-    Used by test files that need to exercise ``MCPTokenStore`` round-
-    trips without the lifespan-side configuration loader; centralised
-    here so the key/material defaults stay aligned across files.
-    """
-    import base64
-
-    from cryptography.fernet import Fernet
-
-    from turnstone.core.mcp_crypto import MCPTokenCipher, MCPTokenCipherConfig
-
-    raw = base64.urlsafe_b64decode(Fernet.generate_key())
-    return MCPTokenCipher(MCPTokenCipherConfig(keys=(raw,)))
-
-
-def _seed_static_state(mgr: MCPClientManager, name: str, **overrides: Any) -> StaticServerState:
-    """Get-or-create a ``StaticServerState`` on ``mgr`` and apply ``overrides``.
-
-    Shared across MCP test files so the helper stays in one place. Imported
-    where needed; ``StaticServerState`` is constructed lazily so non-MCP
-    tests don't pay the import cost.
-    """
-    from turnstone.core.mcp_client import StaticServerState
-
-    state = mgr._static_servers.get(name)
-    if state is None:
-        state = StaticServerState(name=name)
-        mgr._static_servers[name] = state
-    for k, v in overrides.items():
-        setattr(state, k, v)
-    return state
-
-
-def make_oidc_test_config(**overrides: Any) -> OIDCConfig:
-    """Build a test ``OIDCConfig`` with sensible defaults.
-
-    Shared between ``test_oidc.py`` and ``test_oidc_handlers.py`` so the
-    defaults (including the now-required ``redirect_base``) stay aligned.
-    """
-    from turnstone.core.oidc import OIDCConfig
-
-    defaults: dict[str, Any] = {
-        "enabled": True,
-        "issuer": "https://idp.example.com",
-        "client_id": "my-client",
-        "client_secret": "my-secret",
-        "scopes": "openid email profile",
-        "provider_name": "TestIDP",
-        "role_claim": "",
-        "role_map": {},
-        "password_enabled": True,
-        "redirect_base": "https://app.example.com",
-        "authorization_endpoint": "https://idp.example.com/authorize",
-        "token_endpoint": "https://idp.example.com/token",
-        "userinfo_endpoint": "https://idp.example.com/userinfo",
-        "jwks_uri": "https://idp.example.com/.well-known/jwks.json",
-    }
-    defaults.update(overrides)
-    return OIDCConfig(**defaults)
-

 def pytest_addoption(parser: pytest.Parser) -> None:
    parser.addoption(
@@ -1,78 +0,0 @@
-{
-  "cache_control": {
-    "type": "ephemeral"
-  },
-  "max_tokens": 4096,
-  "messages": [
-    {
-      "content": "Weather in Paris and London?",
-      "role": "user"
-    },
-    {
-      "content": [
-        {
-          "id": "call_1",
-          "input": {
-            "city": "Paris"
-          },
-          "name": "get_weather",
-          "type": "tool_use"
-        },
-        {
-          "id": "call_2",
-          "input": {
-            "city": "London"
-          },
-          "name": "get_weather",
-          "type": "tool_use"
-        }
-      ],
-      "role": "assistant"
-    },
-    {
-      "content": [
-        {
-          "content": "18C, clear.",
-          "tool_use_id": "call_1",
-          "type": "tool_result"
-        },
-        {
-          "content": "Tool execution was cancelled.",
-          "is_error": true,
-          "tool_use_id": "call_2",
-          "type": "tool_result"
-        },
-        {
-          "text": "Actually, never mind London.",
-          "type": "text"
-        }
-      ],
-      "role": "user"
-    }
-  ],
-  "model": "claude-sonnet-4-6",
-  "output_config": {
-    "effort": "medium"
-  },
-  "temperature": 1.0,
-  "thinking": {
-    "type": "adaptive"
-  },
-  "tools": [
-    {
-      "description": "Look up the weather for a city.",
-      "input_schema": {
-        "properties": {
-          "city": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "city"
-        ],
-        "type": "object"
-      },
-      "name": "get_weather"
-    }
-  ]
-}
@@ -1,33 +0,0 @@
-{
-  "cache_control": {
-    "type": "ephemeral"
-  },
-  "max_tokens": 4096,
-  "messages": [
-    {
-      "content": [
-        {
-          "text": "What's in this image?",
-          "type": "text"
-        },
-        {
-          "source": {
-            "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==",
-            "media_type": "image/png",
-            "type": "base64"
-          },
-          "type": "image"
-        }
-      ],
-      "role": "user"
-    }
-  ],
-  "model": "claude-sonnet-4-6",
-  "output_config": {
-    "effort": "medium"
-  },
-  "temperature": 1.0,
-  "thinking": {
-    "type": "adaptive"
-  }
-}
@@ -1,70 +0,0 @@
-{
-  "cache_control": {
-    "type": "ephemeral"
-  },
-  "max_tokens": 4096,
-  "messages": [
-    {
-      "content": "Think about the weather.",
-      "role": "user"
-    },
-    {
-      "content": [
-        {
-          "signature": "sig-abc",
-          "thinking": "The user wants weather.",
-          "type": "thinking"
-        },
-        {
-          "text": "Let me check.",
-          "type": "text"
-        },
-        {
-          "id": "call_1",
-          "input": {
-            "city": "Paris"
-          },
-          "name": "get_weather",
-          "type": "tool_use"
-        }
-      ],
-      "role": "assistant"
-    },
-    {
-      "content": [
-        {
-          "content": "Tool execution was cancelled.",
-          "is_error": true,
-          "tool_use_id": "call_1",
-          "type": "tool_result"
-        }
-      ],
-      "role": "user"
-    }
-  ],
-  "model": "claude-sonnet-4-6",
-  "output_config": {
-    "effort": "medium"
-  },
-  "temperature": 1.0,
-  "thinking": {
-    "type": "adaptive"
-  },
-  "tools": [
-    {
-      "description": "Look up the weather for a city.",
-      "input_schema": {
-        "properties": {
-          "city": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "city"
-        ],
-        "type": "object"
-      },
-      "name": "get_weather"
-    }
-  ]
-}
@@ -1,69 +0,0 @@
-{
-  "cache_control": {
-    "type": "ephemeral"
-  },
-  "max_tokens": 4096,
-  "messages": [
-    {
-      "content": "Think about the weather.",
-      "role": "user"
-    },
-    {
-      "content": [
-        {
-          "signature": "sig-abc",
-          "thinking": "The user wants weather.",
-          "type": "thinking"
-        },
-        {
-          "text": "Let me check.",
-          "type": "text"
-        },
-        {
-          "id": "call_1",
-          "input": {
-            "city": "Paris"
-          },
-          "name": "get_weather",
-          "type": "tool_use"
-        }
-      ],
-      "role": "assistant"
-    },
-    {
-      "content": [
-        {
-          "content": "18C, clear.",
-          "tool_use_id": "call_1",
-          "type": "tool_result"
-        }
-      ],
-      "role": "user"
-    }
-  ],
-  "model": "claude-sonnet-4-6",
-  "output_config": {
-    "effort": "medium"
-  },
-  "temperature": 1.0,
-  "thinking": {
-    "type": "adaptive"
-  },
-  "tools": [
-    {
-      "description": "Look up the weather for a city.",
-      "input_schema": {
-        "properties": {
-          "city": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "city"
-        ],
-        "type": "object"
-      },
-      "name": "get_weather"
-    }
-  ]
-}
@@ -1,63 +0,0 @@
-{
-  "cache_control": {
-    "type": "ephemeral"
-  },
-  "max_tokens": 4096,
-  "messages": [
-    {
-      "content": "Run the deploy.",
-      "role": "user"
-    },
-    {
-      "content": [
-        {
-          "id": "call_1",
-          "input": {},
-          "name": "deploy",
-          "type": "tool_use"
-        }
-      ],
-      "role": "assistant"
-    },
-    {
-      "content": [
-        {
-          "content": "deployed",
-          "tool_use_id": "call_1",
-          "type": "tool_result"
-        },
-        {
-          "text": "Great, what's next?",
-          "type": "text"
-        }
-      ],
-      "role": "user"
-    }
-  ],
-  "model": "claude-sonnet-4-6",
-  "output_config": {
-    "effort": "medium"
-  },
-  "system": "Output-guard: deploy output looked clean.",
-  "temperature": 1.0,
-  "thinking": {
-    "type": "adaptive"
-  },
-  "tools": [
-    {
-      "description": "Look up the weather for a city.",
-      "input_schema": {
-        "properties": {
-          "city": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "city"
-        ],
-        "type": "object"
-      },
-      "name": "get_weather"
-    }
-  ]
-}
@@ -1,33 +0,0 @@
-{
-  "cache_control": {
-    "type": "ephemeral"
-  },
-  "max_tokens": 4096,
-  "messages": [
-    {
-      "content": "Hi there.",
-      "role": "user"
-    },
-    {
-      "content": [
-        {
-          "text": "Hello! How can I help?",
-          "type": "text"
-        }
-      ],
-      "role": "assistant"
-    },
-    {
-      "content": "What's the weather in Paris?",
-      "role": "user"
-    }
-  ],
-  "model": "claude-sonnet-4-6",
-  "output_config": {
-    "effort": "medium"
-  },
-  "temperature": 1.0,
-  "thinking": {
-    "type": "adaptive"
-  }
-}
@@ -1,69 +0,0 @@
-{
-  "cache_control": {
-    "type": "ephemeral"
-  },
-  "max_tokens": 4096,
-  "messages": [
-    {
-      "content": "Weather in Paris?",
-      "role": "user"
-    },
-    {
-      "content": [
-        {
-          "id": "call_1",
-          "input": {
-            "city": "Paris"
-          },
-          "name": "get_weather",
-          "type": "tool_use"
-        }
-      ],
-      "role": "assistant"
-    },
-    {
-      "content": [
-        {
-          "content": "18C, clear.",
-          "tool_use_id": "call_1",
-          "type": "tool_result"
-        }
-      ],
-      "role": "user"
-    },
-    {
-      "content": [
-        {
-          "text": "It's 18C and clear in Paris.",
-          "type": "text"
-        }
-      ],
-      "role": "assistant"
-    }
-  ],
-  "model": "claude-sonnet-4-6",
-  "output_config": {
-    "effort": "medium"
-  },
-  "temperature": 1.0,
-  "thinking": {
-    "type": "adaptive"
-  },
-  "tools": [
-    {
-      "description": "Look up the weather for a city.",
-      "input_schema": {
-        "properties": {
-          "city": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "city"
-        ],
-        "type": "object"
-      },
-      "name": "get_weather"
-    }
-  ]
-}
@@ -1,61 +0,0 @@
-{
-  "cache_control": {
-    "type": "ephemeral"
-  },
-  "max_tokens": 4096,
-  "messages": [
-    {
-      "content": "Weather in Paris?",
-      "role": "user"
-    },
-    {
-      "content": [
-        {
-          "id": "call_1",
-          "input": {
-            "city": "Paris"
-          },
-          "name": "get_weather",
-          "type": "tool_use"
-        }
-      ],
-      "role": "assistant"
-    },
-    {
-      "content": [
-        {
-          "content": "Tool execution was cancelled.",
-          "is_error": true,
-          "tool_use_id": "call_1",
-          "type": "tool_result"
-        }
-      ],
-      "role": "user"
-    }
-  ],
-  "model": "claude-sonnet-4-6",
-  "output_config": {
-    "effort": "medium"
-  },
-  "temperature": 1.0,
-  "thinking": {
-    "type": "adaptive"
-  },
-  "tools": [
-    {
-      "description": "Look up the weather for a city.",
-      "input_schema": {
-        "properties": {
-          "city": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "city"
-        ],
-        "type": "object"
-      },
-      "name": "get_weather"
-    }
-  ]
-}
@@ -1,78 +0,0 @@
-{
-  "cache_control": {
-    "type": "ephemeral"
-  },
-  "max_tokens": 4096,
-  "messages": [
-    {
-      "content": "Weather in Paris and London?",
-      "role": "user"
-    },
-    {
-      "content": [
-        {
-          "id": "call_1",
-          "input": {
-            "city": "Paris"
-          },
-          "name": "get_weather",
-          "type": "tool_use"
-        },
-        {
-          "id": "call_2",
-          "input": {
-            "city": "London"
-          },
-          "name": "get_weather",
-          "type": "tool_use"
-        }
-      ],
-      "role": "assistant"
-    },
-    {
-      "content": [
-        {
-          "content": "18C, clear.",
-          "tool_use_id": "call_1",
-          "type": "tool_result"
-        },
-        {
-          "content": "Tool execution was cancelled.",
-          "is_error": true,
-          "tool_use_id": "call_2",
-          "type": "tool_result"
-        },
-        {
-          "text": "Actually, never mind London.",
-          "type": "text"
-        }
-      ],
-      "role": "user"
-    }
-  ],
-  "model": "claude-opus-4-8",
-  "output_config": {
-    "effort": "medium"
-  },
-  "thinking": {
-    "display": "summarized",
-    "type": "adaptive"
-  },
-  "tools": [
-    {
-      "description": "Look up the weather for a city.",
-      "input_schema": {
-        "properties": {
-          "city": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "city"
-        ],
-        "type": "object"
-      },
-      "name": "get_weather"
-    }
-  ]
-}
@@ -1,33 +0,0 @@
-{
-  "cache_control": {
-    "type": "ephemeral"
-  },
-  "max_tokens": 4096,
-  "messages": [
-    {
-      "content": [
-        {
-          "text": "What's in this image?",
-          "type": "text"
-        },
-        {
-          "source": {
-            "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==",
-            "media_type": "image/png",
-            "type": "base64"
-          },
-          "type": "image"
-        }
-      ],
-      "role": "user"
-    }
-  ],
-  "model": "claude-opus-4-8",
-  "output_config": {
-    "effort": "medium"
-  },
-  "thinking": {
-    "display": "summarized",
-    "type": "adaptive"
-  }
-}
@@ -1,70 +0,0 @@
-{
-  "cache_control": {
-    "type": "ephemeral"
-  },
-  "max_tokens": 4096,
-  "messages": [
-    {
-      "content": "Think about the weather.",
-      "role": "user"
-    },
-    {
-      "content": [
-        {
-          "signature": "sig-abc",
-          "thinking": "The user wants weather.",
-          "type": "thinking"
-        },
-        {
-          "text": "Let me check.",
-          "type": "text"
-        },
-        {
-          "id": "call_1",
-          "input": {
-            "city": "Paris"
-          },
-          "name": "get_weather",
-          "type": "tool_use"
-        }
-      ],
-      "role": "assistant"
-    },
-    {
-      "content": [
-        {
-          "content": "Tool execution was cancelled.",
-          "is_error": true,
-          "tool_use_id": "call_1",
-          "type": "tool_result"
-        }
-      ],
-      "role": "user"
-    }
-  ],
-  "model": "claude-opus-4-8",
-  "output_config": {
-    "effort": "medium"
-  },
-  "thinking": {
-    "display": "summarized",
-    "type": "adaptive"
-  },
-  "tools": [
-    {
-      "description": "Look up the weather for a city.",
-      "input_schema": {
-        "properties": {
-          "city": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "city"
-        ],
-        "type": "object"
-      },
-      "name": "get_weather"
-    }
-  ]
-}
@@ -1,69 +0,0 @@
-{
-  "cache_control": {
-    "type": "ephemeral"
-  },
-  "max_tokens": 4096,
-  "messages": [
-    {
-      "content": "Think about the weather.",
-      "role": "user"
-    },
-    {
-      "content": [
-        {
-          "signature": "sig-abc",
-          "thinking": "The user wants weather.",
-          "type": "thinking"
-        },
-        {
-          "text": "Let me check.",
-          "type": "text"
-        },
-        {
-          "id": "call_1",
-          "input": {
-            "city": "Paris"
-          },
-          "name": "get_weather",
-          "type": "tool_use"
-        }
-      ],
-      "role": "assistant"
-    },
-    {
-      "content": [
-        {
-          "content": "18C, clear.",
-          "tool_use_id": "call_1",
-          "type": "tool_result"
-        }
-      ],
-      "role": "user"
-    }
-  ],
-  "model": "claude-opus-4-8",
-  "output_config": {
-    "effort": "medium"
-  },
-  "thinking": {
-    "display": "summarized",
-    "type": "adaptive"
-  },
-  "tools": [
-    {
-      "description": "Look up the weather for a city.",
-      "input_schema": {
-        "properties": {
-          "city": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "city"
-        ],
-        "type": "object"
-      },
-      "name": "get_weather"
-    }
-  ]
-}
@@ -1,66 +0,0 @@
-{
-  "cache_control": {
-    "type": "ephemeral"
-  },
-  "max_tokens": 4096,
-  "messages": [
-    {
-      "content": "Run the deploy.",
-      "role": "user"
-    },
-    {
-      "content": [
-        {
-          "id": "call_1",
-          "input": {},
-          "name": "deploy",
-          "type": "tool_use"
-        }
-      ],
-      "role": "assistant"
-    },
-    {
-      "content": [
-        {
-          "content": "deployed",
-          "tool_use_id": "call_1",
-          "type": "tool_result"
-        }
-      ],
-      "role": "user"
-    },
-    {
-      "content": "Output-guard: deploy output looked clean.",
-      "role": "system"
-    },
-    {
-      "content": "Great, what's next?",
-      "role": "user"
-    }
-  ],
-  "model": "claude-opus-4-8",
-  "output_config": {
-    "effort": "medium"
-  },
-  "thinking": {
-    "display": "summarized",
-    "type": "adaptive"
-  },
-  "tools": [
-    {
-      "description": "Look up the weather for a city.",
-      "input_schema": {
-        "properties": {
-          "city": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "city"
-        ],
-        "type": "object"
-      },
-      "name": "get_weather"
-    }
-  ]
-}
@@ -1,33 +0,0 @@
-{
-  "cache_control": {
-    "type": "ephemeral"
-  },
-  "max_tokens": 4096,
-  "messages": [
-    {
-      "content": "Hi there.",
-      "role": "user"
-    },
-    {
-      "content": [
-        {
-          "text": "Hello! How can I help?",
-          "type": "text"
-        }
-      ],
-      "role": "assistant"
-    },
-    {
-      "content": "What's the weather in Paris?",
-      "role": "user"
-    }
-  ],
-  "model": "claude-opus-4-8",
-  "output_config": {
-    "effort": "medium"
-  },
-  "thinking": {
-    "display": "summarized",
-    "type": "adaptive"
-  }
-}
@@ -1,69 +0,0 @@
-{
-  "cache_control": {
-    "type": "ephemeral"
-  },
-  "max_tokens": 4096,
-  "messages": [
-    {
-      "content": "Weather in Paris?",
-      "role": "user"
-    },
-    {
-      "content": [
-        {
-          "id": "call_1",
-          "input": {
-            "city": "Paris"
-          },
-          "name": "get_weather",
-          "type": "tool_use"
-        }
-      ],
-      "role": "assistant"
-    },
-    {
-      "content": [
-        {
-          "content": "18C, clear.",
-          "tool_use_id": "call_1",
-          "type": "tool_result"
-        }
-      ],
-      "role": "user"
-    },
-    {
-      "content": [
-        {
-          "text": "It's 18C and clear in Paris.",
-          "type": "text"
-        }
-      ],
-      "role": "assistant"
-    }
-  ],
-  "model": "claude-opus-4-8",
-  "output_config": {
-    "effort": "medium"
-  },
-  "thinking": {
-    "display": "summarized",
-    "type": "adaptive"
-  },
-  "tools": [
-    {
-      "description": "Look up the weather for a city.",
-      "input_schema": {
-        "properties": {
-          "city": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "city"
-        ],
-        "type": "object"
-      },
-      "name": "get_weather"
-    }
-  ]
-}
@@ -1,61 +0,0 @@
-{
-  "cache_control": {
-    "type": "ephemeral"
-  },
-  "max_tokens": 4096,
-  "messages": [
-    {
-      "content": "Weather in Paris?",
-      "role": "user"
-    },
-    {
-      "content": [
-        {
-          "id": "call_1",
-          "input": {
-            "city": "Paris"
-          },
-          "name": "get_weather",
-          "type": "tool_use"
-        }
-      ],
-      "role": "assistant"
-    },
-    {
-      "content": [
-        {
-          "content": "Tool execution was cancelled.",
-          "is_error": true,
-          "tool_use_id": "call_1",
-          "type": "tool_result"
-        }
-      ],
-      "role": "user"
-    }
-  ],
-  "model": "claude-opus-4-8",
-  "output_config": {
-    "effort": "medium"
-  },
-  "thinking": {
-    "display": "summarized",
-    "type": "adaptive"
-  },
-  "tools": [
-    {
-      "description": "Look up the weather for a city.",
-      "input_schema": {
-        "properties": {
-          "city": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "city"
-        ],
-        "type": "object"
-      },
-      "name": "get_weather"
-    }
-  ]
-}
@@ -1,71 +0,0 @@
-{
-  "max_tokens": 4096,
-  "messages": [
-    {
-      "content": "Weather in Paris and London?",
-      "role": "user"
-    },
-    {
-      "content": "",
-      "role": "assistant",
-      "tool_calls": [
-        {
-          "function": {
-            "arguments": "{\"city\": \"Paris\"}",
-            "name": "get_weather"
-          },
-          "id": "call_1",
-          "type": "function"
-        },
-        {
-          "function": {
-            "arguments": "{\"city\": \"London\"}",
-            "name": "get_weather"
-          },
-          "id": "call_2",
-          "type": "function"
-        }
-      ]
-    },
-    {
-      "content": "18C, clear.",
-      "role": "tool",
-      "tool_call_id": "call_1"
-    },
-    {
-      "content": "Tool execution was cancelled.",
-      "role": "tool",
-      "tool_call_id": "call_2"
-    },
-    {
-      "content": "Actually, never mind London.",
-      "role": "user"
-    }
-  ],
-  "model": "gemini-2.5-pro",
-  "stream": true,
-  "stream_options": {
-    "include_usage": true
-  },
-  "temperature": 0.5,
-  "tools": [
-    {
-      "function": {
-        "description": "Look up the weather for a city.",
-        "name": "get_weather",
-        "parameters": {
-          "properties": {
-            "city": {
-              "type": "string"
-            }
-          },
-          "required": [
-            "city"
-          ],
-          "type": "object"
-        }
-      },
-      "type": "function"
-    }
-  ]
-}
@@ -1,26 +0,0 @@
-{
-  "max_tokens": 4096,
-  "messages": [
-    {
-      "content": [
-        {
-          "text": "What's in this image?",
-          "type": "text"
-        },
-        {
-          "image_url": {
-            "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg=="
-          },
-          "type": "image_url"
-        }
-      ],
-      "role": "user"
-    }
-  ],
-  "model": "gemini-2.5-pro",
-  "stream": true,
-  "stream_options": {
-    "include_usage": true
-  },
-  "temperature": 0.5
-}
@@ -1,54 +0,0 @@
-{
-  "max_tokens": 4096,
-  "messages": [
-    {
-      "content": "Think about the weather.",
-      "role": "user"
-    },
-    {
-      "content": "Let me check.",
-      "role": "assistant",
-      "tool_calls": [
-        {
-          "function": {
-            "arguments": "{\"city\": \"Paris\"}",
-            "name": "get_weather"
-          },
-          "id": "call_1",
-          "type": "function"
-        }
-      ]
-    },
-    {
-      "content": "Tool execution was cancelled.",
-      "role": "tool",
-      "tool_call_id": "call_1"
-    }
-  ],
-  "model": "gemini-2.5-pro",
-  "stream": true,
-  "stream_options": {
-    "include_usage": true
-  },
-  "temperature": 0.5,
-  "tools": [
-    {
-      "function": {
-        "description": "Look up the weather for a city.",
-        "name": "get_weather",
-        "parameters": {
-          "properties": {
-            "city": {
-              "type": "string"
-            }
-          },
-          "required": [
-            "city"
-          ],
-          "type": "object"
-        }
-      },
-      "type": "function"
-    }
-  ]
-}
@@ -1,54 +0,0 @@
-{
-  "max_tokens": 4096,
-  "messages": [
-    {
-      "content": "Think about the weather.",
-      "role": "user"
-    },
-    {
-      "content": "Let me check.",
-      "role": "assistant",
-      "tool_calls": [
-        {
-          "function": {
-            "arguments": "{\"city\": \"Paris\"}",
-            "name": "get_weather"
-          },
-          "id": "call_1",
-          "type": "function"
-        }
-      ]
-    },
-    {
-      "content": "18C, clear.",
-      "role": "tool",
-      "tool_call_id": "call_1"
-    }
-  ],
-  "model": "gemini-2.5-pro",
-  "stream": true,
-  "stream_options": {
-    "include_usage": true
-  },
-  "temperature": 0.5,
-  "tools": [
-    {
-      "function": {
-        "description": "Look up the weather for a city.",
-        "name": "get_weather",
-        "parameters": {
-          "properties": {
-            "city": {
-              "type": "string"
-            }
-          },
-          "required": [
-            "city"
-          ],
-          "type": "object"
-        }
-      },
-      "type": "function"
-    }
-  ]
-}
@@ -1,62 +0,0 @@
-{
-  "max_tokens": 4096,
-  "messages": [
-    {
-      "content": "Run the deploy.",
-      "role": "user"
-    },
-    {
-      "content": "",
-      "role": "assistant",
-      "tool_calls": [
-        {
-          "function": {
-            "arguments": "{}",
-            "name": "deploy"
-          },
-          "id": "call_1",
-          "type": "function"
-        }
-      ]
-    },
-    {
-      "content": "deployed",
-      "role": "tool",
-      "tool_call_id": "call_1"
-    },
-    {
-      "content": "Output-guard: deploy output looked clean.",
-      "role": "system"
-    },
-    {
-      "content": "Great, what's next?",
-      "role": "user"
-    }
-  ],
-  "model": "gemini-2.5-pro",
-  "stream": true,
-  "stream_options": {
-    "include_usage": true
-  },
-  "temperature": 0.5,
-  "tools": [
-    {
-      "function": {
-        "description": "Look up the weather for a city.",
-        "name": "get_weather",
-        "parameters": {
-          "properties": {
-            "city": {
-              "type": "string"
-            }
-          },
-          "required": [
-            "city"
-          ],
-          "type": "object"
-        }
-      },
-      "type": "function"
-    }
-  ]
-}
@@ -1,23 +0,0 @@
-{
-  "max_tokens": 4096,
-  "messages": [
-    {
-      "content": "Hi there.",
-      "role": "user"
-    },
-    {
-      "content": "Hello! How can I help?",
-      "role": "assistant"
-    },
-    {
-      "content": "What's the weather in Paris?",
-      "role": "user"
-    }
-  ],
-  "model": "gemini-2.5-pro",
-  "stream": true,
-  "stream_options": {
-    "include_usage": true
-  },
-  "temperature": 0.5
-}
@@ -1,58 +0,0 @@
-{
-  "max_tokens": 4096,
-  "messages": [
-    {
-      "content": "Weather in Paris?",
-      "role": "user"
-    },
-    {
-      "content": "",
-      "role": "assistant",
-      "tool_calls": [
-        {
-          "function": {
-            "arguments": "{\"city\": \"Paris\"}",
-            "name": "get_weather"
-          },
-          "id": "call_1",
-          "type": "function"
-        }
-      ]
-    },
-    {
-      "content": "18C, clear.",
-      "role": "tool",
-      "tool_call_id": "call_1"
-    },
-    {
-      "content": "It's 18C and clear in Paris.",
-      "role": "assistant"
-    }
-  ],
-  "model": "gemini-2.5-pro",
-  "stream": true,
-  "stream_options": {
-    "include_usage": true
-  },
-  "temperature": 0.5,
-  "tools": [
-    {
-      "function": {
-        "description": "Look up the weather for a city.",
-        "name": "get_weather",
-        "parameters": {
-          "properties": {
-            "city": {
-              "type": "string"
-            }
-          },
-          "required": [
-            "city"
-          ],
-          "type": "object"
-        }
-      },
-      "type": "function"
-    }
-  ]
-}
@@ -1,54 +0,0 @@
-{
-  "max_tokens": 4096,
-  "messages": [
-    {
-      "content": "Weather in Paris?",
-      "role": "user"
-    },
-    {
-      "content": "",
-      "role": "assistant",
-      "tool_calls": [
-        {
-          "function": {
-            "arguments": "{\"city\": \"Paris\"}",
-            "name": "get_weather"
-          },
-          "id": "call_1",
-          "type": "function"
-        }
-      ]
-    },
-    {
-      "content": "Tool execution was cancelled.",
-      "role": "tool",
-      "tool_call_id": "call_1"
-    }
-  ],
-  "model": "gemini-2.5-pro",
-  "stream": true,
-  "stream_options": {
-    "include_usage": true
-  },
-  "temperature": 0.5,
-  "tools": [
-    {
-      "function": {
-        "description": "Look up the weather for a city.",
-        "name": "get_weather",
-        "parameters": {
-          "properties": {
-            "city": {
-              "type": "string"
-            }
-          },
-          "required": [
-            "city"
-          ],
-          "type": "object"
-        }
-      },
-      "type": "function"
-    }
-  ]
-}
--- a/Show More
+++ b/Show More