broven
diff --git a/‎.config/wt.toml‎
Lines changed: 102 additions & 0 deletions b/‎.config/wt.toml‎
Lines changed: 102 additions & 0 deletions
diff --git a/‎.github/workflows/release.yml‎
Lines changed: 18 additions & 0 deletions b/‎.github/workflows/release.yml‎
Lines changed: 18 additions & 0 deletions
diff --git a/‎.gitignore‎
Lines changed: 2 additions & 1 deletion b/‎.gitignore‎
Lines changed: 2 additions & 1 deletion
diff --git a/‎CLAUDE.md‎
Lines changed: 79 additions & 93 deletions b/‎CLAUDE.md‎
Lines changed: 79 additions & 93 deletions
@@ -0,0 +1,102 @@
+# Worktrunk Project Configuration
+# Copy to: <repo>/.config/wt.toml
+#
+# Project-specific hooks that run automatically during worktree operations.
+# Check this file into git to share hooks across all developers.
+
+# ============================================================================
+# Hook Formats
+# ============================================================================
+# All hooks support two formats:
+#
+# Single command:
+#   post-create = "npm install"
+#
+# Named table (multiple commands):
+#   [post-create]
+#   deps = "npm install"
+#   build = "npm run build"
+#
+# Named commands appear in output, making it easier to identify failures.
+
+# ============================================================================
+# Template Variables — see https://worktrunk.dev/hook/#template-variables
+# ============================================================================
+# Common variables:
+#   {{ repo }}               - Repository directory name (e.g., "myproject")
+#   {{ branch }}             - Branch name (e.g., "feature/auth")
+#   {{ worktree_path }}      - Absolute path to worktree
+#   {{ primary_worktree_path }} - Main worktree (or default branch worktree for bare repos)
+#   {{ default_branch }}     - Default branch name (e.g., "main")
+#   {{ target }}             - Target branch (merge hooks only)
+#
+# Filters:
+#   {{ branch | sanitize }}     - Replace / and \ with - (e.g., "feature-auth")
+#   {{ branch | sanitize_db }}  - Database-safe identifier with hash suffix (e.g., "feature_auth_x7k")
+#   {{ branch | hash_port }}    - Deterministic port 10000-19999
+
+# ============================================================================
+# Hooks
+# ============================================================================
+
+# Post-Create: Runs after worktree creation, BLOCKS until complete
+# Use for: installing dependencies, setting up databases, copying configs
+#
+# [post-create]
+# deps = "npm ci"
+# env = "cp .env.example .env"
+
+# Post-Start: Runs in BACKGROUND after worktree creation (parallel)
+# Use for: dev servers, file watchers, background builds
+# Output logged to .git/wt-logs/{branch}-project-post-start-{name}.log
+#
+# [post-start]
+# server = "npm run dev -- --port {{ branch | hash_port }}"
+# watch = "npm run watch"
+
+# Post-Switch: Runs in BACKGROUND after every switch (parallel)
+# Use for: terminal tab naming, tmux window titles, IDE notifications
+#
+# post-switch = "echo -ne '\\033]0;{{ branch }}\\007'"
+
+# Pre-Commit: Runs before committing during merge, BLOCKS (fail-fast)
+# Use for: formatters, linters, quick checks
+#
+# [pre-commit]
+# format = "npm run format:check"
+# lint = "npm run lint"
+
+# Pre-Merge: Runs before merging to target, BLOCKS (fail-fast)
+# Use for: tests, build verification
+#
+# [pre-merge]
+# test = "npm test"
+# build = "npm run build"
+
+# Post-Merge: Runs after successful merge, BLOCKS
+# Use for: deployment, notifications
+#
+# post-merge = "echo 'Merged {{ branch }} to {{ target }}'"
+
+# Pre-Remove: Runs before worktree removal, BLOCKS (fail-fast)
+# Use for: cleanup, stopping services
+#
+# pre-remove = "docker compose down"
+
+# ============================================================================
+# Dev Server URL (shown in `wt list`)
+# ============================================================================
+# [list]
+# url = "http://localhost:{{ branch | hash_port }}"
+
+# ============================================================================
+# CI Platform Override
+# ============================================================================
+# Override CI platform detection for GitHub Enterprise or self-hosted GitLab
+# with custom domains where URL detection fails.
+#
+# [ci]
+# platform = "github"  # or "gitlab"
+[post-start]
+copy = "wt step copy-ignored"
+server = "npm run dev -- --port {{ branch | hash_port }}"
@@ -0,0 +1,18 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
@@ -7,4 +7,5 @@ logs.db
 providers.yaml
 .claude/
 .env
-.wrangler/
+.wrangler/
+.dev.vars
@@ -5,7 +5,8 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## Commands
 
 - **Dev**: `npm run dev` (runs Wrangler local dev server on port 8787)
-- **Deploy**: `npm run deploy` (deploys to Cloudflare Workers)
+- **Build Frontend**: `npm run build:frontend` (builds the React frontend and embeds it into the Worker)
+- **Deploy**: `npm run deploy` (builds frontend and deploys to Cloudflare Workers)
 - **Type Check**: `npx tsc --noEmit`
 - **Tail Logs**: `npm run tail` (streams production logs from Cloudflare)
 - **Set Secrets**: `npx wrangler secret put ADMIN_TOKEN` (set authentication token)
@@ -15,56 +16,82 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Architecture
 
-Cloudflare Workers-based fallback proxy for Claude Code. Intercepts Anthropic API requests and routes to alternative providers when the primary API returns 401, 403, 429, or 5xx errors. Provider configuration is stored in Cloudflare KV and managed via web-based admin panel.
+Cloudflare Workers-based fallback proxy for Claude Code. Intercepts Anthropic API requests and routes to alternative providers when the primary API returns 401, 403, 429, or 5xx errors.
+
+The Admin Panel is built as a **Single Page Application (SPA)** using React, Vite, and Tailwind CSS. It is bundled into a single HTML file and embedded directly into the Worker logic, allowing for a zero-dependency deployment (no separate asset storage required).
+
+Implements a **Sliding Window Circuit Breaker (Plan C)** to track provider health and prevent cascading failures.
+- **State Storage**: `provider-state:{name}` in KV (JSON format).
+- **Tiered Cooldowns**: 0s (<3 failures), 30s (<5 failures), 60s (<10 failures), 300s (10+ failures).
+- **Safety Valve**: If all providers are in cooldown, the one with the earliest expiry is tried to prevent total service outage.
 
 ### Core Components
 
 - **`src/index.ts`** — Main Worker entry point. Hono app with routes for `/` (health check), `/v1/messages` (proxy), and `/admin/*` (management).
-- **`src/admin.ts`** — Admin panel and API handlers. Provides HTML UI for managing providers, handles token authentication, and KV storage operations.
-- **`src/config.ts`** — KV-based configuration loading and saving. Reads provider configuration from Cloudflare KV.
-- **`src/types.ts`** — TypeScript interfaces for provider config, app config, and Worker bindings (KV, ADMIN_TOKEN, DEBUG).
-- **`src/utils/provider.ts`** — Implements provider request logic with model mapping, header filtering, and custom auth.
-- **`src/utils/headers.ts`** — Utilities for filtering and cleaning HTTP headers for safe forwarding.
+- **`src/admin.ts`** — Admin panel and API handlers. Serves the React SPA (`ADMIN_HTML`) and handles API requests.
+- **`src/config.ts`** — KV-based configuration loading and saving.
+- **`src/utils/circuit-breaker.ts`** — Sliding window circuit breaker implementation with tiered backoff.
+- **`src/types.ts`** — TypeScript interfaces for `ProviderConfig`, `AppConfig`, `ProviderState`, and bindings.
+- **`src/utils/provider.ts`** — Implements provider request logic with model mapping and header filtering.
+- **`src/utils/rectifier/`** — Request rectification module. Auto-fixes incompatible requests (e.g., invalid thinking signatures, budget issues) and retries.
+  - `thinking-signature.ts` — Detects and strips invalid `thinking`/`redacted_thinking` blocks and `signature` fields.
+  - `thinking-budget.ts` — Detects and adjusts `budget_tokens`/`max_tokens` values.
+- **`frontend/`** — React source code for the admin panel.
+- **`scripts/build-frontend.sh`** — Builds the frontend and embeds it into `src/admin-html.ts`.
 
 ### Fallback Logic
 
 1. Try primary Anthropic API (`https://api.anthropic.com/v1/messages`)
-2. On 401, 403, 429, or 5xx errors → iterate through configured fallback providers
-3. Return first successful response or last error
+2. On 400 errors: **Rectifier** auto-detects thinking signature / budget issues, strips problematic blocks, and retries with 120s timeout. If rectifier retry also fails/times out, continues to fallback providers.
+3. On 401, 403, 429, or 5xx errors:
+   - Check circuit breaker state for each provider.
+   - Skip providers currently in cooldown.
+   - Iterate through available providers in configured order.
+   - If all providers in cooldown, trigger **Safety Valve** (try least recently failed).
+4. Return first successful response or last error.
 
 ### KV Configuration
 
-Provider configs are stored as JSON array in Cloudflare KV namespace `CONFIG_KV` under key `providers`:
-
-```json
-[
-  {
-    "name": "openrouter",
-    "baseUrl": "https://openrouter.ai/api/v1/chat/completions",
-    "apiKey": "sk-...",
-    "authHeader": "Authorization",
-    "modelMapping": {
-      "claude-sonnet-4-5-20250929": "anthropic/claude-sonnet-4"
-    }
-  }
-]
-```
+1. **Provider Configs** (`providers` key):
+   ```json
+   [
+     {
+       "name": "openrouter",
+       "baseUrl": "https://openrouter.ai/api/v1/chat/completions",
+       "apiKey": "sk-...",
+       "authHeader": "Authorization",
+       "modelMapping": {
+         "claude-sonnet-4-5-20250929": "anthropic/claude-sonnet-4"
+       }
+     }
+   ]
+   ```
+
+2. **Provider State** (`provider-state:{name}` keys):
+   ```json
+   {
+     "consecutiveFailures": 0,
+     "lastFailure": null,
+     "lastSuccess": 1715432100000,
+     "cooldownUntil": null
+   }
+   ```
 
 ## Configuration
 
 ### Environment Variables
 
-- **`ADMIN_TOKEN`** (required) — Secret token for protecting admin panel. Set via Cloudflare Dashboard or `wrangler secret put`.
+- **`ADMIN_TOKEN`** (required) — Secret token for protecting admin panel.
 - **`DEBUG`** (optional, default: `false`) — Enable debug logging.
 
 ### KV Namespace
 
-- **`CONFIG_KV`** — Binding to Cloudflare KV namespace storing provider configurations.
+- **`CONFIG_KV`** — Binding to Cloudflare KV namespace storing provider configurations and circuit breaker state.
 
 ### wrangler.jsonc
 
 Main configuration file. Contains:
-- KV namespace binding (requires namespace id from `npx wrangler kv:namespace create CONFIG`)
+- KV namespace binding (requires namespace id)
 - Environment variables
 - Development port (8787)
 
@@ -74,15 +101,27 @@ Access at: `https://your-worker.workers.dev/admin?token=YOUR_ADMIN_TOKEN`
 
 Features:
 - **Visual Editor**: Add/edit/delete providers with form UI
-- **JSON Editor**: Direct JSON editing for advanced users
-- **Real-time Save**: Changes persist immediately to KV
-- **Token Authentication**: Secured with `ADMIN_TOKEN` environment variable
+- **JSON Editor**: Direct JSON editing
+- **Circuit Breaker Settings**: Configure max cooldown duration
+- **Token Authentication**: Secured with `ADMIN_TOKEN`
+
+## Observability
 
-### API Endpoints
+The proxy outputs **structured JSON logs** with Request ID tracking for full observability. See [docs/observability.md](./docs/observability.md) for details.
 
-- `GET /admin` — Admin panel UI (requires token)
-- `GET /admin/config` — Get current provider config as JSON (requires token)
-- `POST /admin/config` — Update provider config (requires token, expects JSON array)
+**Quick Start:**
+```bash
+# View real-time logs
+npm run tail
+
+# Logs are automatically collected in: Dashboard → Observability
+```
+
+Every log includes:
+- Unique `requestId` for tracing requests end-to-end
+- `event` type (e.g., `provider.success`, `provider.failure`)
+- Performance metrics (`latency`, `status`)
+- Provider and model information
 
 ## Deployment Workflow
 
@@ -108,15 +147,6 @@ Features:
    https://your-worker.workers.dev/admin?token=YOUR_TOKEN
    ```
 
-## Local Development
-
-```bash
-npm run dev
-# Visit http://localhost:8787/admin?token=123456 (default token in wrangler.jsonc)
-```
-
-When running locally with `npx wrangler kv:namespace create CONFIG --preview`, you can test KV operations with preview binding.
-
 ## Provider Configuration
 
 Each provider requires:
@@ -129,33 +159,20 @@ Optional fields:
 - **`headers`** — Additional custom headers
 - **`modelMapping`** — Map model names (e.g., `claude-3-opus-20240229` → `openai/gpt-4`)
 
-## Type System
-
-Main types in `src/types.ts`:
-- `ProviderConfig` — Single provider configuration
-- `AppConfig` — Runtime config with debug flag and provider list
-- `Bindings` — Worker environment bindings (DEBUG, ADMIN_TOKEN, CONFIG_KV)
-
 ## Testing
 
-The project has a comprehensive test suite with 142 tests and 99%+ coverage.
+The project has a comprehensive test suite with **367 tests**.
 
 ### Test Structure
 
 ```
 src/__tests__/
   fixtures/         # Test data and mock responses
-    providers.ts    # Provider configurations
-    requests.ts     # API request/response fixtures
-  mocks/            # Mock implementations
-    kv.ts          # Mock KV namespace
-    fetch.ts       # Mock fetch utilities
-  utils/           # Unit tests for utilities
-    headers.test.ts
-    provider.test.ts
-  config.test.ts   # Config module tests
-  admin.test.ts    # Admin panel tests
-  index.test.ts    # Integration tests
+  mocks/            # Mock KV and fetch implementations
+  utils/            # Unit tests (headers, provider, circuit-breaker, rectifier)
+  config.test.ts    # Config module tests
+  admin.test.ts     # Admin panel tests
+  index.test.ts     # Integration tests
 ```
 
 ### Running Tests
@@ -170,34 +187,3 @@ npm run test:watch
 # Run with coverage report
 npm run test:coverage
 ```
-
-### Test Coverage
-
-The test suite maintains high coverage across all modules:
-- **Statements**: 99.28%
-- **Branches**: 98.48%
-- **Functions**: 94.73%
-- **Lines**: 100%
-
-Coverage thresholds are enforced at 80% for all metrics.
-
-### Writing Tests
-
-Tests use Vitest with Cloudflare Workers pool for accurate Workers environment simulation:
-
-```typescript
-import { describe, it, expect } from 'vitest';
-import { createMockBindings } from './__tests__/mocks/kv';
-
-describe('my feature', () => {
-  it('should work correctly', async () => {
-    const env = createMockBindings();
-    // Test implementation
-  });
-});
-```
-
-Key testing utilities:
-- `createMockBindings()` — Creates mock Worker bindings (KV, env vars)
-- `createMockResponse()` — Creates mock Response objects
-- Test fixtures in `__tests__/fixtures/` — Reusable test data