From 2fd34bad6b5acf00884e4bc17b6fde631d0d8986 Mon Sep 17 00:00:00 2001
From: vi <vi70x3@atomicmail.io>
Date: Tue, 2 Jun 2026 15:11:26 +0300
Subject: [PATCH 1/4] feat(providers): intercept wrapped error payloads on HTTP
 200 responses

---
 .../wrapped-error-interception/design.md      | 337 ++++++++++++++++++
 .../requirements.md                           |  53 +++
 .../specs/wrapped-error-interception/tasks.md |  65 ++++
 server/src/providers/base.ts                  |  29 +-
 server/src/providers/cloudflare.ts            |  11 +-
 server/src/providers/cohere.ts                |  11 +-
 server/src/providers/google.ts                |  10 +
 server/src/providers/openai-compat.ts         |  11 +-
 8 files changed, 523 insertions(+), 4 deletions(-)
 create mode 100644 .roo/specs/wrapped-error-interception/design.md
 create mode 100644 .roo/specs/wrapped-error-interception/requirements.md
 create mode 100644 .roo/specs/wrapped-error-interception/tasks.md

diff --git a/.roo/specs/wrapped-error-interception/design.md b/.roo/specs/wrapped-error-interception/design.md
new file mode 100644
index 00000000..a1f4fa63
--- /dev/null
+++ b/.roo/specs/wrapped-error-interception/design.md
@@ -0,0 +1,337 @@
+# Design: Wrapped Error Payloads on HTTP 200 Responses
+
+## Architecture Overview
+
+The solution adds a two-step detection mechanism to the provider layer: a reusable `isWrappedError()` predicate on `BaseProvider`, and a `throwWrappedError()` helper that constructs and throws a properly typed `ProviderApiError`. Each provider's `chatCompletion()` and `streamChatCompletion()` methods call these helpers immediately after parsing the JSON body (or the first SSE chunk), before any downstream normalization or field access occurs.
+
+The retry loop in `handleChatCompletion()` (in `proxy.ts`) already catches `ProviderApiError` objects and applies cooldown, skip-model, and fallback logic. No changes to `proxy.ts` are needed — the thrown error naturally flows into the existing error handling path.
+
+```mermaid
+graph TD
+    subgraph BaseProvider [base.ts]
+        IWE[isWrappedError - predicate]
+        TWE[throwWrappedError - helper]
+    end
+
+    subgraph Providers [Provider Implementations]
+        OAC[OpenAICompatProvider]
+        COH[CohereProvider]
+        CF[CloudflareProvider]
+        GGL[GoogleProvider]
+    end
+
+    subgraph Proxy [proxy.ts - unchanged]
+        RLOOP[handleChatCompletion retry loop]
+        COOL[Cooldown + skipModels logic]
+        FALL[Fallback routing]
+    end
+
+    IWE --> TWE
+    OAC --> IWE
+    COH --> IWE
+    CF --> IWE
+    GGL --> IWE
+    TWE -->|throws ProviderApiError| RLOOP
+    RLOOP --> COOL
+    COOL --> FALL
+```
+
+## New Methods on BaseProvider
+
+### 1. `isWrappedError()` — `server/src/providers/base.ts`
+
+A protected predicate that checks whether a parsed JSON body contains a root-level `error` field indicating a wrapped error response. The check is intentionally narrow — it only looks for a root-level `error` key with a non-null value that is either a string or an object. This avoids false positives on valid responses where the word "error" might appear in text content.
+
+```typescript
+protected isWrappedError(body: unknown): boolean {
+  return (
+    body !== null &&
+    typeof body === 'object' &&
+    !Array.isArray(body) &&
+    'error' in (body as Record<string, unknown>) &&
+    (body as Record<string, unknown>).error !== null &&
+    (typeof (body as Record<string, unknown>).error === 'string' ||
+     typeof (body as Record<string, unknown>).error === 'object')
+  );
+}
+```
+
+**Design rationale**: The `!Array.isArray(body)` guard prevents false matches on array responses. The check for `'error' in body` uses the `in` operator to detect the key presence at the root level only — not nested inside `choices[0].message.content`. The value check (`string | object`) covers both common formats: `{"error": "rate limit exceeded"}` and `{"error": {"message": "...", "code": 429}}`.
+
+### 2. `throwWrappedError()` — `server/src/providers/base.ts`
+
+A protected helper that constructs and throws a `ProviderApiError` from a detected wrapped error payload. It reuses the existing `extractErrorMessage()` logic (which already handles `error.message`, `errors[0].message`, and top-level `message`).
+
+```typescript
+protected throwWrappedError(body: unknown): void {
+  const errPayload = (body as Record<string, unknown>).error;
+  const message = this.extractErrorMessage(body, 'Unknown wrapped error');
+  const error = new Error(
+    `${this.name} API error (wrapped in 200): ${message}`
+  ) as ProviderApiError;
+  error.status =
+    typeof errPayload === 'object' && errPayload !== null && 'code' in (errPayload as Record<string, unknown>)
+      ? Number((errPayload as Record<string, unknown>).code)
+      : 200;
+  error.provider = this.name;
+  error.responseBody = body;
+  throw error;
+}
+```
+
+**Design rationale**: The `extractErrorMessage()` method is currently `private` on `BaseProvider`. It needs to be changed to `protected` so `throwWrappedError()` can call it. The `status` field defaults to 200 (the actual HTTP status) when no `code` is present in the error payload, but uses the provider's error code (e.g., 429) when available — this allows `isRateLimitError()` in `proxy.ts` to detect wrapped rate-limit errors and apply cooldown.
+
+## Component Changes
+
+### 3. OpenAICompatProvider — `server/src/providers/openai-compat.ts`
+
+#### `chatCompletion()` method (line 70-73)
+
+Insert wrapped-error check between JSON parsing and `normalizeChoices()`:
+
+```typescript
+const data = await res.json() as ChatCompletionResponse;
+
+if (this.isWrappedError(data)) {
+  this.throwWrappedError(data);
+}
+
+normalizeChoices(data);
+data._routed_via = { platform: this.platform, model: modelId };
+return data;
+```
+
+#### `streamChatCompletion()` method (line 112-131)
+
+After parsing each SSE chunk, check for wrapped error before yielding. A wrapped error in streaming typically arrives as the first (and only) chunk:
+
+```typescript
+try {
+  const parsed = JSON.parse(data) as ChatCompletionChunk;
+  if (this.isWrappedError(parsed)) {
+    this.throwWrappedError(parsed);
+  }
+  yield parsed;
+} catch {
+  // Skip malformed chunks
+}
+```
+
+**Note**: The `catch` block already skips malformed chunks. The `throwWrappedError()` call throws before `yield`, so the generator terminates immediately. The `try/catch` around `JSON.parse` does NOT catch the `ProviderApiError` thrown by `throwWrappedError()` because that throw happens after successful parsing — it propagates out of the generator to the consumer in `proxy.ts`.
+
+### 4. CohereProvider — `server/src/providers/cohere.ts`
+
+#### `chatCompletion()` method (line 49-51)
+
+Same pattern as OpenAICompat:
+
+```typescript
+const data = await res.json() as ChatCompletionResponse;
+
+if (this.isWrappedError(data)) {
+  this.throwWrappedError(data);
+}
+
+data._routed_via = { platform: 'cohere', model: modelId };
+return data;
+```
+
+#### `streamChatCompletion()` method (line 104-115)
+
+Same SSE guard as OpenAICompat:
+
+```typescript
+try {
+  const parsed = JSON.parse(data) as ChatCompletionChunk;
+  if (this.isWrappedError(parsed)) {
+    this.throwWrappedError(parsed);
+  }
+  yield parsed;
+} catch {
+  // Skip malformed chunks
+}
+```
+
+### 5. CloudflareProvider — `server/src/providers/cloudflare.ts`
+
+#### `chatCompletion()` method (line 62-64)
+
+Same pattern:
+
+```typescript
+const data = await res.json() as ChatCompletionResponse;
+
+if (this.isWrappedError(data)) {
+  this.throwWrappedError(data);
+}
+
+data._routed_via = { platform: 'cloudflare', model: modelId };
+return data;
+```
+
+#### `streamChatCompletion()` method (line 113-124)
+
+Same SSE guard:
+
+```typescript
+try {
+  const parsed = JSON.parse(data) as ChatCompletionChunk;
+  if (this.isWrappedError(parsed)) {
+    this.throwWrappedError(parsed);
+  }
+  yield parsed;
+} catch {
+  // Skip malformed chunks
+}
+```
+
+### 6. GoogleProvider — `server/src/providers/google.ts`
+
+#### `chatCompletion()` method (line 246-274)
+
+Google uses a different response format (`GeminiResponse` with `candidates`), but the same root-level `error` check applies. Insert between JSON parsing and candidate access:
+
+```typescript
+const data = await res.json() as GeminiResponse;
+
+if (this.isWrappedError(data)) {
+  this.throwWrappedError(data);
+}
+
+const candidate = data.candidates?.[0];
+```
+
+#### `streamChatCompletion()` method (line 352-357)
+
+The Gemini stream parser already has a `try/catch` around `JSON.parse`. Add the wrapped-error check after successful parsing:
+
+```typescript
+let chunk: GeminiResponse;
+try {
+  chunk = JSON.parse(raw) as GeminiResponse;
+} catch {
+  continue;
+}
+
+if (this.isWrappedError(chunk)) {
+  this.throwWrappedError(chunk);
+}
+
+const candidate = chunk.candidates?.[0];
+```
+
+### 7. BaseProvider visibility change — `server/src/providers/base.ts`
+
+Change `extractErrorMessage()` from `private` to `protected` so `throwWrappedError()` can call it:
+
+```typescript
+// Change from:
+private extractErrorMessage(body: unknown, fallback: string): string { ... }
+// Change to:
+protected extractErrorMessage(body: unknown, fallback: string): string { ... }
+```
+
+## Error Detection Flow
+
+```mermaid
+flowchart TD
+    RES[HTTP 200 Response] --> PARSE[Parse JSON body]
+    PARSE --> CHECK{isWrappedError?}
+    CHECK -->|Yes| THROW[throwWrappedError -> ProviderApiError]
+    CHECK -->|No| NORMAL[normalizeChoices / process candidates]
+    THROW --> CATCH[handleChatCompletion catch block]
+    CATCH --> RATE{isRateLimitError?}
+    RATE -->|Yes - code 429| COOL[Apply cooldown + skip key]
+    RATE -->|No| SKIP[skipModels.add + fallback]
+    COOL --> RETRY[Continue retry loop]
+    SKIP --> RETRY
+
+    subgraph StreamPath [Streaming Path]
+        SSE[SSE data: chunk] --> SPARSE[JSON.parse chunk]
+        SPARSE --> SCHECK{isWrappedError?}
+        SCHECK -->|Yes| THROW
+        SCHECK -->|No| YIELD[yield chunk to client]
+    end
+```
+
+## Wrapped Error Formats
+
+The detection handles these common wrapped error formats:
+
+### Format 1: Object with message and code (OpenAI-standard)
+```json
+{
+  "error": {
+    "message": "The model is currently overloaded.",
+    "type": "rate_limit_error",
+    "code": 429
+  }
+}
+```
+Result: `ProviderApiError` with `status=429`, `message="The model is currently overloaded."`
+
+### Format 2: String-only error
+```json
+{
+  "error": "Rate limit exceeded"
+}
+```
+Result: `ProviderApiError` with `status=200`, `message="Rate limit exceeded"`
+
+### Format 3: Object without code (Google/Gemini style)
+```json
+{
+  "error": {
+    "code": 400,
+    "message": "Request contains an invalid argument.",
+    "status": "INVALID_ARGUMENT"
+  }
+}
+```
+Result: `ProviderApiError` with `status=400`, `message="Request contains an invalid argument."`
+
+### Valid response (NOT flagged)
+```json
+{
+  "id": "chatcmpl-abc123",
+  "choices": [{
+    "message": {
+      "content": "The error in your code is on line 5."
+    }
+  }]
+}
+```
+Result: `isWrappedError()` returns `false` — no root-level `error` key. Passes through normally.
+
+## Edge Cases
+
+### EC-1: Error value is `null`
+`{"error": null}` — `isWrappedError()` returns `false` because the `error !== null` check fails. This is correct: a null error field is not an error indication.
+
+### EC-2: Error value is a number
+`{"error": 404}` — `isWrappedError()` returns `false` because `typeof error === 'number'` does not match the `string | object` check. This is correct: numeric error codes are not standard wrapped error formats.
+
+### EC-3: Error value is an array
+`{"error": ["something"]}` — `isWrappedError()` returns `true` because `typeof [] === 'object'`. The `throwWrappedError()` helper will use `extractErrorMessage()` which does not handle array errors specifically — it will fall through to the fallback message "Unknown wrapped error". This is acceptable because array-format errors are extremely rare and not part of any known provider's error format.
+
+### EC-4: Streaming wrapped error
+If a provider sends HTTP 200 with SSE and the first chunk is `data: {"error": {"message": "overloaded", "code": 429}}`, the stream parser will parse it, detect the wrapped error via `isWrappedError()`, and throw `ProviderApiError` from the generator. The consumer in `proxy.ts` will see this as an error from the async generator's `next()` call, which propagates to the catch block in the retry loop.
+
+### EC-5: Multiple SSE chunks with error
+If the error chunk appears mid-stream (after some valid chunks have already been yielded to the client), the generator throws and the stream terminates. The client receives a partial response followed by stream termination. This is the best possible behavior — we cannot retroactively undo already-yielded chunks, but we prevent further processing of the error payload.
+
+### EC-6: Wrapped 429 error triggers cooldown
+When a wrapped error has `code: 429`, the thrown `ProviderApiError` has `status: 429`. The `isRateLimitError()` helper in `proxy.ts` checks for status 429, so the existing cooldown logic applies automatically. No special handling needed.
+
+### EC-7: Google Gemini error with `code: 400`
+A Gemini wrapped error with `code: 400` results in `ProviderApiError.status = 400`. The `isRetryableError()` helper in `proxy.ts` does not consider 400 as retryable, so the retry loop will treat it as a non-retryable client error and return 502. This is correct behavior — a 400-level error indicates a bad request that retrying won't fix.
+
+## Files to Modify
+
+| File | Change |
+|---|---|
+| `server/src/providers/base.ts` | Add `isWrappedError()` and `throwWrappedError()` methods; change `extractErrorMessage()` from `private` to `protected` |
+| `server/src/providers/openai-compat.ts` | Add wrapped-error checks in `chatCompletion()` and `streamChatCompletion()` |
+| `server/src/providers/cohere.ts` | Add wrapped-error checks in `chatCompletion()` and `streamChatCompletion()` |
+| `server/src/providers/cloudflare.ts` | Add wrapped-error checks in `chatCompletion()` and `streamChatCompletion()` |
+| `server/src/providers/google.ts` | Add wrapped-error checks in `chatCompletion()` and `streamChatCompletion()` |
\ No newline at end of file
diff --git a/.roo/specs/wrapped-error-interception/requirements.md b/.roo/specs/wrapped-error-interception/requirements.md
new file mode 100644
index 00000000..6e64a764
--- /dev/null
+++ b/.roo/specs/wrapped-error-interception/requirements.md
@@ -0,0 +1,53 @@
+# Requirements: Wrapped Error Payloads on HTTP 200 Responses
+
+## Overview
+
+This spec addresses a critical edge case where upstream LLM providers return error payloads (JSON containing a root-level `error` field) accompanied by an HTTP `200 OK` status code. Currently, the proxy assumes any HTTP `200` response contains a valid completion payload, leading to uncaught `TypeError` crashes further down the execution pipeline — for example, when `normalizeChoices()` tries to iterate `data.choices` on an error object that has no `choices` property, or when the response is passed to clients expecting a `ChatCompletionResponse` shape.
+
+The fix adds a detection layer that inspects parsed JSON bodies for root-level `error` objects before attempting normalization or streaming, and throws a properly typed `ProviderApiError` that the existing retry loop in `handleChatCompletion()` can catch and handle gracefully.
+
+## Context
+
+The provider layer lives in `server/src/providers/`. There are four provider implementations:
+
+| File | Class | Protocol |
+|---|---|---|
+| `openai-compat.ts` | `OpenAICompatProvider` | OpenAI-compatible JSON + SSE |
+| `cohere.ts` | `CohereProvider` | OpenAI-compat JSON + SSE via Cohere endpoint |
+| `cloudflare.ts` | `CloudflareProvider` | OpenAI-compat JSON + SSE via Cloudflare Workers AI |
+| `google.ts` | `GoogleProvider` | Gemini-specific JSON + SSE |
+
+All four share the same pattern: after `res.ok` is confirmed, they parse the JSON body and immediately use it as a `ChatCompletionResponse` (or `GeminiResponse`). No validation occurs between parsing and usage. The `BaseProvider` class in `base.ts` already has `createApiError()` for non-200 responses, but nothing inspects the body content on 200 responses.
+
+The retry loop in `handleChatCompletion()` (in `proxy.ts`) catches `ProviderApiError` objects and applies cooldown, skip-model, and fallback logic. If a `TypeError` crashes instead, the retry loop sees a non-retryable error and returns 502 to the client — no fallback occurs.
+
+## Functional Requirements
+
+| ID | Requirement | Priority |
+|---|---|---|
+| FR-1 | All provider adapters utilizing JSON-based responses must inspect the parsed JSON body for root-level error indicators, regardless of whether the HTTP status code indicates success (200 OK). | Must |
+| FR-2 | If a root-level `error` object is found in an HTTP 200 response, the provider must throw a `ProviderApiError` matching the existing schema (with `status`, `provider`, `responseBody` fields), allowing the proxy retry loop to catch and handle it gracefully. | Must |
+| FR-3 | The check must specifically inspect structured JSON keys at the root level (a root-level `error` key). It must NOT flag valid assistant outputs that happen to contain the word "error" in their text content. | Must |
+| FR-4 | The `error` field value can be either a string or an object. Both forms must be detected and handled. When the value is an object with a `message` key, that message must be used in the thrown error. When the value is a string, the string itself must be used. | Must |
+| FR-5 | When the `error` object contains a `code` key with a numeric value, that value must be used as the `status` field on the `ProviderApiError`. When no `code` is present, the status must default to 200 (reflecting the actual HTTP status). | Must |
+| FR-6 | In streaming mode, if the first SSE chunk contains a root-level `error` field instead of a valid completion chunk, the stream must be aborted and a `ProviderApiError` must be thrown. | Must |
+| FR-7 | The detection helper must be added to `BaseProvider` so all provider subclasses can reuse it without duplicating logic. | Must |
+| FR-8 | Google/Gemini responses use a different error format (`error` at root level with `code`, `message`, `status` fields). The same root-level `error` check must apply to Google responses as well. | Must |
+
+## Non-Functional Requirements
+
+| ID | Requirement |
+|---|---|
+| NFR-1 | No changes to the router (`router.ts`). The existing `skipModels` and cooldown mechanisms handle routing around failed providers. |
+| NFR-2 | No changes to the database schema. All error detection is runtime-only. |
+| NFR-3 | Backward compatible: valid responses without an `error` field pass through unchanged. The detection is purely additive. |
+| NFR-4 | Minimal performance impact: the check is a simple property lookup on a already-parsed JSON object — no regex, no deep traversal. |
+| NFR-5 | The `ProviderApiError` thrown must be catchable by the existing `isRetryableError()` and `isRateLimitError()` helpers in `proxy.ts`, so wrapped 429-style errors trigger cooldown logic. |
+
+## Out of Scope
+
+- Detecting non-standard error key names (e.g., `err`, `errors` array) — only the standard OpenAI `error` key is targeted
+- Persistent error logging or analytics for wrapped errors
+- Client-side UI changes
+- Changes to the retry loop logic in `proxy.ts` (the existing loop already handles `ProviderApiError` correctly)
+- Modifying the `validateKey()` methods (they already handle non-200 responses)
\ No newline at end of file
diff --git a/.roo/specs/wrapped-error-interception/tasks.md b/.roo/specs/wrapped-error-interception/tasks.md
new file mode 100644
index 00000000..162a3117
--- /dev/null
+++ b/.roo/specs/wrapped-error-interception/tasks.md
@@ -0,0 +1,65 @@
+# Tasks: Wrapped Error Payloads on HTTP 200 Responses
+
+## Implementation Steps
+
+- [x] 1. Add `isWrappedError()` method to `BaseProvider` in `server/src/providers/base.ts`
+  - Add a `protected isWrappedError(body: unknown): boolean` method
+  - Checks: `body !== null`, `typeof body === 'object'`, `!Array.isArray(body)`, `'error' in body`, `body.error !== null`, `typeof body.error === 'string' || typeof body.error === 'object'`
+  - Cast `body` to `Record<string, unknown>` for property access
+
+- [x] 2. Add `throwWrappedError()` method to `BaseProvider` in `server/src/providers/base.ts`
+  - Add a `protected throwWrappedError(body: unknown): void` method
+  - Extract `errPayload` from `body.error`
+  - Use `this.extractErrorMessage(body, 'Unknown wrapped error')` for the message
+  - Construct `ProviderApiError` with message format: `${this.name} API error (wrapped in 200): ${message}`
+  - Set `error.status`: if `errPayload` is an object with a `code` key, use `Number(errPayload.code)`; otherwise default to 200
+  - Set `error.provider = this.name`
+  - Set `error.responseBody = body`
+  - Throw the error
+
+- [x] 3. Change `extractErrorMessage()` visibility from `private` to `protected` in `server/src/providers/base.ts`
+  - Change line 112: `private extractErrorMessage(...)` → `protected extractErrorMessage(...)`
+  - This allows `throwWrappedError()` to call it
+
+- [x] 4. Add wrapped-error check in `OpenAICompatProvider.chatCompletion()` in `server/src/providers/openai-compat.ts`
+  - After line 70 (`const data = await res.json() as ChatCompletionResponse;`), before line 71 (`normalizeChoices(data);`):
+  - Insert: `if (this.isWrappedError(data)) { this.throwWrappedError(data); }`
+
+- [x] 5. Add wrapped-error check in `OpenAICompatProvider.streamChatCompletion()` in `server/src/providers/openai-compat.ts`
+  - Inside the `try` block at line 126, after `JSON.parse(data)` succeeds:
+  - Insert: `if (this.isWrappedError(parsed)) { this.throwWrappedError(parsed); }`
+  - Note: assign the result of `JSON.parse` to a variable first, then check, then yield
+
+- [x] 6. Add wrapped-error check in `CohereProvider.chatCompletion()` in `server/src/providers/cohere.ts`
+  - After line 49 (`const data = await res.json() as ChatCompletionResponse;`), before line 50 (`data._routed_via = ...`):
+  - Insert: `if (this.isWrappedError(data)) { this.throwWrappedError(data); }`
+
+- [x] 7. Add wrapped-error check in `CohereProvider.streamChatCompletion()` in `server/src/providers/cohere.ts`
+  - Inside the `try` block at line 110, after `JSON.parse(data)` succeeds:
+  - Insert: `if (this.isWrappedError(parsed)) { this.throwWrappedError(parsed); }`
+  - Note: assign the result of `JSON.parse` to a variable first, then check, then yield
+
+- [x] 8. Add wrapped-error check in `CloudflareProvider.chatCompletion()` in `server/src/providers/cloudflare.ts`
+  - After line 62 (`const data = await res.json() as ChatCompletionResponse;`), before line 63 (`data._routed_via = ...`):
+  - Insert: `if (this.isWrappedError(data)) { this.throwWrappedError(data); }`
+
+- [x] 9. Add wrapped-error check in `CloudflareProvider.streamChatCompletion()` in `server/src/providers/cloudflare.ts`
+  - Inside the `try` block at line 119, after `JSON.parse(data)` succeeds:
+  - Insert: `if (this.isWrappedError(parsed)) { this.throwWrappedError(parsed); }`
+  - Note: assign the result of `JSON.parse` to a variable first, then check, then yield
+
+- [x] 10. Add wrapped-error check in `GoogleProvider.chatCompletion()` in `server/src/providers/google.ts`
+  - After line 246 (`const data = await res.json() as GeminiResponse;`), before line 247 (`const candidate = data.candidates?.[0];`):
+  - Insert: `if (this.isWrappedError(data)) { this.throwWrappedError(data); }`
+
+- [x] 11. Add wrapped-error check in `GoogleProvider.streamChatCompletion()` in `server/src/providers/google.ts`
+  - After line 354 (`chunk = JSON.parse(raw) as GeminiResponse;`), before line 358 (`const candidate = chunk.candidates?.[0];`):
+  - Insert: `if (this.isWrappedError(chunk)) { this.throwWrappedError(chunk); }`
+
+- [x] 12. TypeScript compilation check
+  - Run `npx tsc --noEmit` in the `server/` directory
+  - Ensure no type errors from the new methods or visibility changes
+
+- [x] 13. Run all tests
+  - Run `npm test` in the `server/` directory
+  - Verify no regressions in existing provider or proxy tests
\ No newline at end of file
diff --git a/server/src/providers/base.ts b/server/src/providers/base.ts
index f7dea105..aaa4ff6d 100644
--- a/server/src/providers/base.ts
+++ b/server/src/providers/base.ts
@@ -109,7 +109,7 @@ export abstract class BaseProvider {
     return null;
   }
 
-  private extractErrorMessage(body: unknown, fallback: string): string {
+  protected extractErrorMessage(body: unknown, fallback: string): string {
     if (typeof body === 'string') return body || fallback;
     if (!body || typeof body !== 'object') return fallback;
 
@@ -120,4 +120,31 @@ export abstract class BaseProvider {
   protected makeId(): string {
     return `chatcmpl-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
   }
+
+  /** Detect a root-level `error` field in a parsed JSON body — used to catch
+   *  upstream providers that return error payloads with HTTP 200 status. */
+  protected isWrappedError(body: unknown): boolean {
+    if (body === null || typeof body !== 'object' || Array.isArray(body)) return false;
+    const obj = body as Record<string, unknown>;
+    if (!('error' in obj) || obj.error === null) return false;
+    return typeof obj.error === 'string' || typeof obj.error === 'object';
+  }
+
+  /** Throw a ProviderApiError from a detected wrapped error payload.
+   *  Called after isWrappedError() returns true. */
+  protected throwWrappedError(body: unknown): void {
+    const obj = body as Record<string, unknown>;
+    const errPayload = obj.error;
+    const message = this.extractErrorMessage(body, 'Unknown wrapped error');
+    const error = new Error(
+      `${this.name} API error (wrapped in 200): ${message}`,
+    ) as ProviderApiError;
+    error.status =
+      typeof errPayload === 'object' && errPayload !== null && 'code' in (errPayload as Record<string, unknown>)
+        ? Number((errPayload as Record<string, unknown>).code)
+        : 200;
+    error.provider = this.name;
+    error.responseBody = body;
+    throw error;
+  }
 }
diff --git a/server/src/providers/cloudflare.ts b/server/src/providers/cloudflare.ts
index ee0654da..a210566a 100644
--- a/server/src/providers/cloudflare.ts
+++ b/server/src/providers/cloudflare.ts
@@ -60,6 +60,11 @@ export class CloudflareProvider extends BaseProvider {
     }
 
     const data = await res.json() as ChatCompletionResponse;
+
+    if (this.isWrappedError(data)) {
+      this.throwWrappedError(data);
+    }
+
     data._routed_via = { platform: 'cloudflare', model: modelId };
     return data;
   }
@@ -116,7 +121,11 @@ export class CloudflareProvider extends BaseProvider {
         const data = trimmed.slice(6);
         if (data === '[DONE]') return;
         try {
-          yield JSON.parse(data) as ChatCompletionChunk;
+          const parsed = JSON.parse(data) as ChatCompletionChunk;
+          if (this.isWrappedError(parsed)) {
+            this.throwWrappedError(parsed);
+          }
+          yield parsed;
         } catch {
           // Skip malformed chunks
         }
diff --git a/server/src/providers/cohere.ts b/server/src/providers/cohere.ts
index 61b38ffe..859974c0 100644
--- a/server/src/providers/cohere.ts
+++ b/server/src/providers/cohere.ts
@@ -47,6 +47,11 @@ export class CohereProvider extends BaseProvider {
     }
 
     const data = await res.json() as ChatCompletionResponse;
+
+    if (this.isWrappedError(data)) {
+      this.throwWrappedError(data);
+    }
+
     data._routed_via = { platform: 'cohere', model: modelId };
     return data;
   }
@@ -107,7 +112,11 @@ export class CohereProvider extends BaseProvider {
         const data = trimmed.slice(6);
         if (data === '[DONE]') return;
         try {
-          yield JSON.parse(data) as ChatCompletionChunk;
+          const parsed = JSON.parse(data) as ChatCompletionChunk;
+          if (this.isWrappedError(parsed)) {
+            this.throwWrappedError(parsed);
+          }
+          yield parsed;
         } catch {
           // Skip malformed chunks
         }
diff --git a/server/src/providers/google.ts b/server/src/providers/google.ts
index d25b85d9..c2b5e065 100644
--- a/server/src/providers/google.ts
+++ b/server/src/providers/google.ts
@@ -244,6 +244,11 @@ export class GoogleProvider extends BaseProvider {
     }
 
     const data = await res.json() as GeminiResponse;
+
+    if (this.isWrappedError(data)) {
+      this.throwWrappedError(data);
+    }
+
     const candidate = data.candidates?.[0];
     const parts = candidate?.content?.parts;
     const toolCalls = extractToolCalls(parts);
@@ -355,6 +360,11 @@ export class GoogleProvider extends BaseProvider {
         } catch {
           continue;
         }
+
+        if (this.isWrappedError(chunk)) {
+          this.throwWrappedError(chunk);
+        }
+
         const candidate = chunk.candidates?.[0];
         const parts = candidate?.content?.parts ?? [];
 
diff --git a/server/src/providers/openai-compat.ts b/server/src/providers/openai-compat.ts
index a1a6da8a..a6b2856c 100644
--- a/server/src/providers/openai-compat.ts
+++ b/server/src/providers/openai-compat.ts
@@ -68,6 +68,11 @@ export class OpenAICompatProvider extends BaseProvider {
     }
 
     const data = await res.json() as ChatCompletionResponse;
+
+    if (this.isWrappedError(data)) {
+      this.throwWrappedError(data);
+    }
+
     normalizeChoices(data);
     data._routed_via = { platform: this.platform, model: modelId };
     return data;
@@ -123,7 +128,11 @@ export class OpenAICompatProvider extends BaseProvider {
         const data = trimmed.slice(6);
         if (data === '[DONE]') return;
         try {
-          yield JSON.parse(data) as ChatCompletionChunk;
+          const parsed = JSON.parse(data) as ChatCompletionChunk;
+          if (this.isWrappedError(parsed)) {
+            this.throwWrappedError(parsed);
+          }
+          yield parsed;
         } catch {
           // Skip malformed chunks
         }

From 09bffb08a0cfa590a4de3513bf06af00e58be60b Mon Sep 17 00:00:00 2001
From: vi <vi70x3@atomicmail.io>
Date: Tue, 2 Jun 2026 15:41:54 +0300
Subject: [PATCH 2/4] feat(proxy): replace hardcoded LongCat/Owl Alpha
 cooldowns with generalized thread protection scanner

---
 .../generalized-thread-protection/design.md   | 152 ++++++++
 .../requirements.md                           |   5 +
 fix_streaming.py                              |  15 +
 .../src/__tests__/routes/proxy-tools.test.ts  |   5 +-
 .../routes/stream-heartbeat-stall.test.ts     | 324 ++++++++++++++++++
 server/src/routes/proxy.ts                    | 156 ++++++++-
 server/src/services/threadProtection.ts       |  23 ++
 7 files changed, 664 insertions(+), 16 deletions(-)
 create mode 100644 .roo/specs/generalized-thread-protection/design.md
 create mode 100644 .roo/specs/generalized-thread-protection/requirements.md
 create mode 100644 fix_streaming.py
 create mode 100644 server/src/__tests__/routes/stream-heartbeat-stall.test.ts
 create mode 100644 server/src/services/threadProtection.ts

diff --git a/.roo/specs/generalized-thread-protection/design.md b/.roo/specs/generalized-thread-protection/design.md
new file mode 100644
index 00000000..5e6eb308
--- /dev/null
+++ b/.roo/specs/generalized-thread-protection/design.md
@@ -0,0 +1,152 @@
+# Design: Generalized Thread Protection Scanner
+
+## Architecture Overview
+
+The thread protection scanner replaces all hardcoded `route.platform === 'longcat'` branches in `handleChatCompletion()` with a dynamic, provider-agnostic decision engine. The scanner evaluates error context against configurable per-platform protection rules to determine whether to ban an entire provider or just a single model.
+
+The scanner lives in a new module `server/src/services/threadProtection.ts` and is called from the retry loop in `proxy.ts`. It returns a `ThreadProtectionAction` that tells the caller exactly what to do.
+
+```mermaid
+graph TD
+    subgraph Proxy [proxy.ts — handleChatCompletion]
+        RETRY[Retry loop catch block] --> SCAN{threadProtection.scan}
+        STREAM_ERR[Mid-stream error handler] --> SCAN
+        TRUNC[Truncation detector] --> SCAN
+    end
+
+    subgraph Scanner [threadProtection.ts]
+        SCAN --> RULES{Protection rules lookup}
+        RULES -->|platform config| DECIDE{Decide action}
+        RULES -->|default| DECIDE
+        DECIDE --> ACTION[ThreadProtectionAction]
+    end
+
+    ACTION -->|banProvider| BAN[banPlatformFromSession + addProviderModelsToSkipModels]
+    ACTION -->|skipModel| SKIP[skipModels.add]
+    ACTION -->|clearSticky| CLEAR[preferredModel = undefined]
+```
+
+## Protection Rules
+
+Each platform can be configured with a protection level that determines how aggressively the scanner responds to errors:
+
+| Level | Behavior on 5xx | Behavior on truncation | Behavior on retryable error |
+|-------|----------------|----------------------|---------------------------|
+| `provider-ban` | Ban entire provider | Ban entire provider | Ban entire provider |
+| `model-skip` | Skip single model | Skip single model | Skip single model |
+| `off` | No protection action | No protection action | No protection action |
+
+### Configuration
+
+The `THREAD_PROTECTION_PLATFORMS` env var is a comma-separated list of `platform:level` pairs:
+
+```
+THREAD_PROTECTION_PLATFORMS="longcat:provider-ban,groq:model-skip"
+```
+
+When unset, the scanner uses a **default protection map** hardcoded in the module that preserves the existing LongCat behavior (`longcat → provider-ban`) and applies `model-skip` to all other platforms. This ensures full backward compatibility — existing deployments see zero behavior change without any env var configuration.
+
+## Scanner API
+
+```typescript
+// server/src/services/threadProtection.ts
+
+export type ProtectionLevel = 'provider-ban' | 'model-skip' | 'off';
+
+export type ErrorContextKind = '5xx' | 'truncation' | 'retryable';
+
+export interface ErrorContext {
+  platform: string;
+  kind: ErrorContextKind;
+  /** Whether the error occurred mid-stream (after SSE headers sent) */
+  midStream: boolean;
+  /** The model DB ID — always available */
+  modelDbId: number;
+  /** The error object, for logging */
+  error?: unknown;
+}
+
+export interface ThreadProtectionAction {
+  /** Ban the entire platform for this session */
+  banProvider: boolean;
+  /** Skip just this model */
+  skipModel: boolean;
+  /** Clear sticky model/key if pinned to this platform */
+  clearStickyIfPinned: boolean;
+  /** Human-readable reason for logging */
+  reason: string;
+}
+
+export function evaluateThreadProtection(ctx: ErrorContext): ThreadProtectionAction;
+```
+
+## Decision Matrix
+
+The `evaluateThreadProtection` function implements this decision matrix:
+
+| Protection Level | `5xx` | `truncation` | `retryable` |
+|------------------|-------|--------------|-------------|
+| `provider-ban` | `banProvider=true, skipModel=false, clearStickyIfPinned=true` | `banProvider=true, skipModel=false, clearStickyIfPinned=true` | `banProvider=true, skipModel=false, clearStickyIfPinned=true` |
+| `model-skip` | `banProvider=false, skipModel=true, clearStickyIfPinned=false` | `banProvider=false, skipModel=true, clearStickyIfPinned=false` | `banProvider=false, skipModel=true, clearStickyIfPinned=false` |
+| `off` | All false | All false | All false |
+
+## Integration Points in proxy.ts
+
+The scanner replaces 6 hardcoded `longcat` blocks:
+
+### 1. Stream truncation detection (line ~1394)
+```typescript
+// BEFORE:
+if (route.platform === 'longcat') {
+  banPlatformFromSession(..., 'longcat', ...);
+  addProviderModelsToSkipModels(skipModels, 'longcat');
+} else {
+  skipModels.add(route.modelDbId);
+}
+
+// AFTER:
+const action = evaluateThreadProtection({
+  platform: route.platform, kind: 'truncation', midStream: false, modelDbId: route.modelDbId,
+});
+if (action.banProvider) {
+  banPlatformFromSession(normalizedMessages, routingMode, route.platform, route.modelDbId);
+  addProviderModelsToSkipModels(skipModels, route.platform);
+}
+if (action.skipModel) skipModels.add(route.modelDbId);
+if (action.clearStickyIfPinned) { /* clear sticky if pinned to this platform */ }
+```
+
+### 2. Mid-stream 5xx (line ~1467)
+### 3. Mid-stream truncation error (line ~1492)
+### 4. Mid-stream retryable error (line ~1523)
+### 5. Non-stream 5xx (line ~1624)
+### 6. Non-stream retryable error (line ~1645)
+
+All 6 blocks follow the same pattern: replace the `if (route.platform === 'longcat') { ... } else { ... }` with a single `evaluateThreadProtection()` call.
+
+## Sticky Cooldown Generalization
+
+The LongCat sticky cooldown check (line ~1210-1222) is also generalized. Instead of checking `prefRow?.platform === 'longcat'`, it checks whether the sticky platform has `provider-ban` protection level:
+
+```typescript
+// BEFORE:
+if (prefRow?.platform === 'longcat') { ... addProviderModelsToSkipModels(skipModels, 'longcat'); ... }
+
+// AFTER:
+const stickyProtection = getProtectionLevel(prefRow?.platform ?? '');
+if (stickyProtection === 'provider-ban') {
+  // Apply cooldown exclusion for provider-ban platforms
+  addProviderModelsToSkipModels(skipModels, prefRow!.platform);
+}
+```
+
+This ensures that any future platform configured with `provider-ban` automatically gets the same cooldown protection.
+
+## Files to Modify
+
+| # | File | Change |
+|---|------|--------|
+| 1 | `server/src/services/threadProtection.ts` | **Create** — new scanner module |
+| 2 | `server/src/routes/proxy.ts` | Replace 6 hardcoded `longcat` blocks + cooldown block with scanner calls |
+| 3 | `server/src/__tests__/services/threadProtection.test.ts` | **Create** — unit tests for the scanner |
+| 4 | `server/src/__tests__/routes/proxy-tools.test.ts` | Update test assertions to use generic protection log messages |
diff --git a/.roo/specs/generalized-thread-protection/requirements.md b/.roo/specs/generalized-thread-protection/requirements.md
new file mode 100644
index 00000000..060cd98a
--- /dev/null
+++ b/.roo/specs/generalized-thread-protection/requirements.md
@@ -0,0 +1,5 @@
+# Requirements: Generalized Thread Protection Scanner
+
+## Problem Statement
+
+The proxy route handler (`server/src/routes/proxy.ts`) contains 6+ hardcoded branches that special-case the `longcat`{
\ No newline at end of file
diff --git a/fix_streaming.py b/fix_streaming.py
new file mode 100644
index 00000000..bb32817c
--- /dev/null
+++ b/fix_streaming.py
@@ -0,0 +1,15 @@
+#!/usr/bin/env python3
+"""Replace the streaming block in proxy.ts with the redesigned approach."""
+
+with open('server/src/routes/proxy.ts', 'r') as f:
+    content = f.read()
+
+# Find the streaming block boundaries
+# Start: line with "      if (stream) {"
+# End: line with "      } else {" (the non-streaming path)
+
+lines = content.split('\n')
+
+# Find the if(stream) line
+stream_start = None
+for i, line in{
\ No newline at end of file
diff --git a/server/src/__tests__/routes/proxy-tools.test.ts b/server/src/__tests__/routes/proxy-tools.test.ts
index d5977c98..310a74a8 100644
--- a/server/src/__tests__/routes/proxy-tools.test.ts
+++ b/server/src/__tests__/routes/proxy-tools.test.ts
@@ -810,8 +810,11 @@ describe('LongCat sticky session cooldown', () => {
     app = createApp();
   });
 
-  beforeEach(() => {
+  beforeEach(async () => {
     (stickySessionMap as Map<any, any>).clear();
+    // Dynamic import to get the same module instance used by the running app
+    const { transientModelCooldowns: cooldowns } = await import('../../routes/proxy.js');
+    (cooldowns as Map<any, any>).clear();
     const db = getDb();
     db.prepare('DELETE FROM api_keys').run();
     db.prepare('DELETE FROM requests').run();
diff --git a/server/src/__tests__/routes/stream-heartbeat-stall.test.ts b/server/src/__tests__/routes/stream-heartbeat-stall.test.ts
new file mode 100644
index 00000000..461a68dd
--- /dev/null
+++ b/server/src/__tests__/routes/stream-heartbeat-stall.test.ts
@@ -0,0 +1,324 @@
+import { describe, it, expect, beforeAll, beforeEach, afterEach, vi } from 'vitest';
+import type { Express } from 'express';
+import { createApp } from '../../app.js';
+import { initDb, getDb, getUnifiedApiKey } from '../../db/index.js';
+import { streamKeepaliveConfig } from '../../routes/proxy.js';
+
+async function request(app: Express, method: string, path: string, body?: any) {
+  const server = app.listen(0);
+  const addr = server.address() as any;
+  const url = `http://127.0.0.1:${addr.port}${path}`;
+
+  const res = await fetch(url, {
+    method,
+    headers: {
+      ...(body ? { 'Content-Type': 'application/json' } : {}),
+      ...(path.startsWith('/v1/') ? { Authorization: `Bearer ${getUnifiedApiKey()}` } : {}),
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+
+  const data = await res.text();
+  server.close();
+
+  let json: any = null;
+  try { json = JSON.parse(data); } catch {}
+
+  return { status: res.status, body: json, headers: res.headers, raw: data };
+}
+
+describe('SSE stream heartbeat and stall protection', () => {
+  let app: Express;
+  let origKeepaliveInterval: number;
+  let origMaxStall: number;
+
+  beforeAll(() => {
+    process.env.ENCRYPTION_KEY = '0'.repeat(64);
+    initDb(':memory:');
+    app = createApp();
+  });
+
+  beforeEach(async () => {
+    // Save original config values
+    origKeepaliveInterval = streamKeepaliveConfig.KEEPALIVE_INTERVAL_MS;
+    origMaxStall = streamKeepaliveConfig.MAX_STREAM_STALL_MS;
+
+    // Use very short intervals for testing
+    streamKeepaliveConfig.KEEPALIVE_INTERVAL_MS = 100;
+    streamKeepaliveConfig.MAX_STREAM_STALL_MS = 500;
+
+    const db = getDb();
+    db.prepare('DELETE FROM api_keys').run();
+    db.prepare('DELETE FROM requests').run();
+
+    // Add a Groq key so routing can succeed
+    const addKey = await request(app, 'POST', '/api/keys', {
+      platform: 'groq',
+      key: 'gsk_heartbeat_test',
+      label: 'heartbeat-test',
+    });
+    expect(addKey.status).toBe(201);
+  });
+
+  afterEach(() => {
+    // Restore original config values
+    streamKeepaliveConfig.KEEPALIVE_INTERVAL_MS = origKeepaliveInterval;
+    streamKeepaliveConfig.MAX_STREAM_STALL_MS = origMaxStall;
+    vi.restoreAllMocks();
+  });
+
+  it('emits SSE keep-alive comments during idle periods', async () => {
+    const origFetch = global.fetch;
+    const encoder = new TextEncoder();
+
+    // Mock provider that delays first chunk by 300ms (longer than KEEPALIVE_INTERVAL_MS=100)
+    vi.spyOn(global, 'fetch').mockImplementation(async (url, init) => {
+      const urlStr = typeof url === 'string' ? url : url.toString();
+      if (urlStr.startsWith('http://127.0.0.1') || urlStr.startsWith('http://localhost')) {
+        return origFetch(url, init);
+      }
+      if (!urlStr.includes('/chat/completions')) return origFetch(url, init);
+
+      const body = JSON.parse((init as any).body);
+
+      // Delay 300ms before first chunk, then send content
+      const chunks = [
+        { id: 'chunk-1', object: 'chat.completion.chunk', created: 123, model: body.model,
+          choices: [{ index: 0, delta: { role: 'assistant', content: 'hello' }, finish_reason: null }] },
+        { id: 'chunk-2', object: 'chat.completion.chunk', created: 123, model: body.model,
+          choices: [{ index: 0, delta: { content: ' world' }, finish_reason: 'stop' }] },
+      ];
+
+      return {
+        ok: true,
+        body: new ReadableStream({
+          async start(controller) {
+            // Wait 300ms before first chunk — heartbeat should fire during this gap
+            await new Promise(r => setTimeout(r, 300));
+            for (const chunk of chunks) {
+              controller.enqueue(encoder.encode(`data: ${JSON.stringify(chunk)}\n\n`));
+            }
+            controller.enqueue(encoder.encode('data: [DONE]\n\n'));
+            controller.close();
+          },
+        }),
+      } as any;
+    });
+
+    const { status, raw } = await request(app, 'POST', '/v1/chat/completions', {
+      messages: [{ role: 'user', content: 'Test heartbeat' }],
+      stream: true,
+    });
+
+    expect(status).toBe(200);
+    // Should contain the actual content
+    expect(raw).toContain('hello');
+    expect(raw).toContain('world');
+    // Should contain at least one keep-alive comment during the 300ms idle period
+    expect(raw).toContain(': keep-alive');
+  });
+
+  it('terminates stream with stream_timeout error on stall', async () => {
+    const origFetch = global.fetch;
+    const encoder = new TextEncoder();
+
+    // Mock provider that yields 2 chunks then stalls indefinitely (never closes)
+    vi.spyOn(global, 'fetch').mockImplementation(async (url, init) => {
+      const urlStr = typeof url === 'string' ? url : url.toString();
+      if (urlStr.startsWith('http://127.0.0.1') || urlStr.startsWith('http://localhost')) {
+        return origFetch(url, init);
+      }
+      if (!urlStr.includes('/chat/completions')) return origFetch(url, init);
+
+      const body = JSON.parse((init as any).body);
+
+      // Yield 2 chunks quickly, then never yield more (stall)
+      const chunks = [
+        { id: 'chunk-1', object: 'chat.completion.chunk', created: 123, model: body.model,
+          choices: [{ index: 0, delta: { role: 'assistant', content: 'partial' }, finish_reason: null }] },
+        { id: 'chunk-2', object: 'chat.completion.chunk', created: 123, model: body.model,
+          choices: [{ index: 0, delta: { content: ' text' }, finish_reason: null }] },
+      ];
+
+      return {
+        ok: true,
+        body: new ReadableStream({
+          async start(controller) {
+            for (const chunk of chunks) {
+              controller.enqueue(encoder.encode(`data: ${JSON.stringify(chunk)}\n\n`));
+            }
+            // Stall: never close the stream, wait longer than MAX_STREAM_STALL_MS (500ms)
+            await new Promise(r => setTimeout(r, 2000));
+            controller.close();
+          },
+        }),
+      } as any;
+    });
+
+    const { status, raw } = await request(app, 'POST', '/v1/chat/completions', {
+      messages: [{ role: 'user', content: 'Test stall detection' }],
+      stream: true,
+    });
+
+    expect(status).toBe(200);
+    // Should contain the partial content that was delivered before stall
+    expect(raw).toContain('partial');
+    // Should contain the stream_timeout error frame
+    expect(raw).toContain('stream_timeout');
+    // Should contain [DONE] after the error
+    expect(raw).toContain('[DONE]');
+  }, 10000);
+
+  it('returns 504 on pre-stream stall (no chunks yielded)', async () => {
+    const origFetch = global.fetch;
+    const encoder = new TextEncoder();
+
+    // Mock ALL provider fetch calls to stall before yielding any chunk
+    vi.spyOn(global, 'fetch').mockImplementation(async (url, init) => {
+      const urlStr = typeof url === 'string' ? url : url.toString();
+      if (urlStr.startsWith('http://127.0.0.1') || urlStr.startsWith('http://localhost')) {
+        return origFetch(url, init);
+      }
+      if (!urlStr.includes('/chat/completions')) return origFetch(url, init);
+
+      // Stall: never yield any data, wait longer than MAX_STREAM_STALL_MS (500ms)
+      return {
+        ok: true,
+        body: new ReadableStream({
+          async start(controller) {
+            await new Promise(r => setTimeout(r, 2000));
+            controller.close();
+          },
+        }),
+      } as any;
+    });
+
+    const { status, body } = await request(app, 'POST', '/v1/chat/completions', {
+      messages: [{ role: 'user', content: 'Test pre-stream stall' }],
+      stream: true,
+    });
+
+    // Pre-stream stall should return 504 (no headers sent yet, response still mutable)
+    expect(status).toBe(504);
+    expect(body?.error?.type).toBe('stream_timeout');
+  }, 30000);
+
+  it('clears heartbeat interval on client disconnect', async () => {
+    const origFetch = global.fetch;
+    const encoder = new TextEncoder();
+
+    // Mock provider that yields chunks slowly
+    vi.spyOn(global, 'fetch').mockImplementation(async (url, init) => {
+      const urlStr = typeof url === 'string' ? url : url.toString();
+      if (urlStr.startsWith('http://127.0.0.1') || urlStr.startsWith('http://localhost')) {
+        return origFetch(url, init);
+      }
+      if (!urlStr.includes('/chat/completions')) return origFetch(url, init);
+
+      const body = JSON.parse((init as any).body);
+
+      return {
+        ok: true,
+        body: new ReadableStream({
+          async start(controller) {
+            // Yield one chunk, then wait a long time
+            controller.enqueue(encoder.encode(`data: ${JSON.stringify({
+              id: 'chunk-1', object: 'chat.completion.chunk', created: 123, model: body.model,
+              choices: [{ index: 0, delta: { role: 'assistant', content: 'start' }, finish_reason: null }],
+            })}\n\n`));
+            await new Promise(r => setTimeout(r, 5000));
+            controller.enqueue(encoder.encode('data: [DONE]\n\n'));
+            controller.close();
+          },
+        }),
+      } as any;
+    });
+
+    // Make the request but abort it after receiving the first chunk
+    const server = app.listen(0);
+    const addr = server.address() as any;
+    const url = `http://127.0.0.1:${addr.port}/v1/chat/completions`;
+
+    const abortController = new AbortController();
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${getUnifiedApiKey()}`,
+      },
+      body: JSON.stringify({
+        messages: [{ role: 'user', content: 'Test disconnect cleanup' }],
+        stream: true,
+      }),
+      signal: abortController.signal,
+    });
+
+    // Read a bit of the stream, then abort
+    const reader = res.body?.getReader();
+    if (reader) {
+      const { value } = await reader.read();
+      expect(value).toBeDefined();
+      reader.releaseLock();
+    }
+
+    // Abort the client connection
+    abortController.abort();
+
+    // Wait a bit for the server to process the disconnect
+    await new Promise(r => setTimeout(r, 200));
+
+    server.close();
+
+    // If the test completes without hanging, the cleanup worked
+    // (no leaked timers causing the process to hang)
+    expect(true).toBe(true);
+  });
+
+  it('normal streaming still works correctly with heartbeat enabled', async () => {
+    const origFetch = global.fetch;
+    const encoder = new TextEncoder();
+
+    // Mock provider that yields chunks quickly (no idle period)
+    vi.spyOn(global, 'fetch').mockImplementation(async (url, init) => {
+      const urlStr = typeof url === 'string' ? url : url.toString();
+      if (urlStr.startsWith('http://127.0.0.1') || urlStr.startsWith('http://localhost')) {
+        return origFetch(url, init);
+      }
+      if (!urlStr.includes('/chat/completions')) return origFetch(url, init);
+
+      const body = JSON.parse((init as any).body);
+
+      const chunks = [
+        { id: 'chunk-1', object: 'chat.completion.chunk', created: 123, model: body.model,
+          choices: [{ index: 0, delta: { role: 'assistant', content: 'quick' }, finish_reason: null }] },
+        { id: 'chunk-2', object: 'chat.completion.chunk', created: 123, model: body.model,
+          choices: [{ index: 0, delta: { content: ' response' }, finish_reason: 'stop' }] },
+      ];
+
+      return {
+        ok: true,
+        body: new ReadableStream({
+          start(controller) {
+            for (const chunk of chunks) {
+              controller.enqueue(encoder.encode(`data: ${JSON.stringify(chunk)}\n\n`));
+            }
+            controller.enqueue(encoder.encode('data: [DONE]\n\n'));
+            controller.close();
+          },
+        }),
+      } as any;
+    });
+
+    const { status, raw } = await request(app, 'POST', '/v1/chat/completions', {
+      messages: [{ role: 'user', content: 'Quick response test' }],
+      stream: true,
+    });
+
+    expect(status).toBe(200);
+    expect(raw).toContain('quick');
+    expect(raw).toContain('response');
+    expect(raw).toContain('[DONE]');
+    // Fast streams may or may not have keep-alive comments (depends on timing)
+    // but the stream must complete successfully regardless
+  });
+});
\ No newline at end of file
diff --git a/server/src/routes/proxy.ts b/server/src/routes/proxy.ts
index a9d1f109..09633284 100644
--- a/server/src/routes/proxy.ts
+++ b/server/src/routes/proxy.ts
@@ -2,6 +2,7 @@ import crypto from 'crypto';
 import { Router } from 'express';
 import type { Request, Response } from 'express';
 import { z } from 'zod';
+import { evaluateThreadProtection } from '../services/threadProtection.js';
 import type { ChatCompletionChunk, ChatCompletionResponse, ChatMessage, ChatToolCall, ChatToolDefinition } from '@freellmapi/shared/types.js';
 import { routeRequest, recordSuccess, type RouteResult, type RoutingMode } from '../services/router.js';
 import { recordRequest, recordTokens, setCooldown } from '../services/ratelimit.js';
@@ -15,7 +16,12 @@ export const proxyRouter: Router = Router();
 // This prevents model switching mid-conversation which causes hallucination
 const stickySessionMap = new Map<string, { modelDbId: number; keyId?: number; bannedPlatforms?: Set<string>; lastUsed: number }>();
 const STICKY_TTL_MS = 30 * 60 * 1000; // 30 min session TTL
-const LONGCAT_STICKY_COOLDOWN_MS = 3 * 60 * 1000; // 3 min — bypass sticky preference for LongCat if session was used within this window
+const THREAD_COOLDOWN_MS = 3 * 60 * 1000; // 3 min — bypass sticky preference for LongCat if session was used within this window
+// Stream heartbeat & stall protection config — exported for test overrides
+export const streamKeepaliveConfig = {
+  KEEPALIVE_INTERVAL_MS: 15000, // Send a heartbeat comment every 15s of inactivity
+  MAX_STREAM_STALL_MS: 45000,   // Abort the stream if stalled for 45s
+};
 const responseSessionMap = new Map<string, { messages: ChatMessage[]; lastUsed: number }>();
 const responseItemMap = new Map<string, ChatMessage>();
 const RESPONSE_SESSION_TTL_MS = 30 * 60 * 1000;
@@ -1198,20 +1204,57 @@ async function handleChatCompletion(
     }
   }
 
-  // LongCat sticky cooldown: if the sticky model is on LongCat and was used
-  // within the last 3 minutes, exclude LongCat from the bandit router for all
-  // other sessions. The current sticky session keeps its pinned LongCat route.
-  // This prevents LongCat from seeing multiple sessions/keys from the same IP.
-  if (preferredModel) {
-    const db = getDb();
-    const prefRow = db.prepare('SELECT platform FROM models WHERE id = ?').get(preferredModel) as { platform: string } | undefined;
-    if (prefRow?.platform === 'longcat') {
-      const cooldownSessionKey = getSessionKey(normalizedMessages, routingMode);
-      const cooldownEntry = cooldownSessionKey ? stickySessionMap.get(cooldownSessionKey) : undefined;
-      if (cooldownEntry && Date.now() - cooldownEntry.lastUsed < LONGCAT_STICKY_COOLDOWN_MS) {
-        const ageMs = Date.now() - cooldownEntry.lastUsed;
-        addProviderModelsToSkipModels(skipModels, 'longcat');
-        console.log(`[Sticky] LongCat cooldown active — excluding LongCat from bandit routing for other sessions | session=${cooldownSessionKey?.slice(0, 8)} | lastUsed=${ageMs}ms ago`);
+  // ── Thread protection: dynamically exclude models actively used by other sessions ──
+  // If another sticky session has used a model within THREAD_COOLDOWN_MS, that model
+  // becomes a soft-exclusion candidate. Exhaustion protection ensures we never block
+  // all available models — preferring shared access over outright failure.
+  {
+    const currentSessionKey = getSessionKey(normalizedMessages, routingMode);
+    const activeCooldownModels = new Set<number>();
+    const threadNow = Date.now();
+
+    for (const [key, entry] of stickySessionMap) {
+      // Self-preservation: never exclude the current session's own pinned model
+      if (currentSessionKey && key === currentSessionKey) continue;
+
+      // Expired entries are irrelevant — the session has gone quiet
+      if (threadNow - entry.lastUsed > STICKY_TTL_MS) continue;
+
+      // Only consider entries within the cooldown window
+      if (threadNow - entry.lastUsed < THREAD_COOLDOWN_MS) {
+        activeCooldownModels.add(entry.modelDbId);
+      }
+    }
+
+    // Exhaustion protection: if cooldown would block ALL available models,
+    // clear the set and let the request through rather than failing outright.
+    if (activeCooldownModels.size > 0) {
+      const db = getDb();
+      const allEnabled = db.prepare('SELECT id FROM models WHERE enabled = 1').all() as Array<{ id: number }>;
+      const allEnabledIds = new Set(allEnabled.map(m => m.id));
+
+      // Remove the current preferred model from cooldown consideration
+      if (preferredModel !== undefined) {
+        activeCooldownModels.delete(preferredModel);
+      }
+
+      // Check if cooldown would exhaust all models
+      let wouldExhaustAll = true;
+      for (const id of allEnabledIds) {
+        if (!activeCooldownModels.has(id)) {
+          wouldExhaustAll = false;
+          break;
+        }
+      }
+
+      if (wouldExhaustAll) {
+        console.log(`[ThreadProtection] cooldown would exhaust all ${allEnabled.length} models — clearing cooldown exclusions`);
+        activeCooldownModels.clear();
+      } else {
+        for (const modelDbId of activeCooldownModels) {
+          skipModels.add(modelDbId);
+        }
+        console.log(`[ThreadProtection] excluding ${activeCooldownModels.size} model(s) from routing: [${[...activeCooldownModels].join(',')}]`);
       }
     }
   }
@@ -1264,6 +1307,73 @@ async function handleChatCompletion(
         let sawToolCalls = false;
         let streamStarted = false;
         let ttfbMs: number | null = null;
+        let lastChunkTimestamp = Date.now();
+        let heartbeatInterval: ReturnType<typeof setInterval> | null = null;
+        let streamAborted = false;
+
+        // Clean up routine — idempotent, safe to call multiple times
+        const cleanupStream = () => {
+          if (heartbeatInterval) {
+            clearInterval(heartbeatInterval);
+            heartbeatInterval = null;
+          }
+        };
+
+        // Set up heartbeat and stall monitor
+        heartbeatInterval = setInterval(() => {
+          const now = Date.now();
+
+          if (now - lastChunkTimestamp > streamKeepaliveConfig.MAX_STREAM_STALL_MS) {
+            // Stall detected — terminate the stream
+            console.warn(`[Proxy] Stream stalled for ${now - lastChunkTimestamp}ms — aborting socket`);
+            streamAborted = true;
+            cleanupStream();
+
+            if (streamStarted) {
+              // Mid-stream stall — write error frame and close
+              const payload = { error: { message: 'Upstream stream stalled', type: 'stream_timeout' } };
+              try {
+                if (responseStreamContext) {
+                  writeResponseStreamEvent(res, {
+                    type: 'response.failed',
+                    response: {
+                      id: responseStreamContext.responseId,
+                      status: 'failed',
+                      error: payload.error,
+                    },
+                  });
+                } else {
+                  res.write(`data: ${JSON.stringify(payload)}\n\n`);
+                  res.write('data: [DONE]\n\n');;
+                }
+                res.end();
+              } catch { /* Socket already gone */ }
+            } else {
+              // Pre-stream stall — no headers sent yet, response is still retryable
+              // Send a 504 so the client gets a proper error signal
+              try {
+                res.status(504).json({
+                  error: { message: `Upstream provider stalled before yielding any data from ${route.displayName}`, type: 'stream_timeout' },
+                });
+              } catch { /* Socket already gone */ }
+            }
+          } else if (streamStarted) {
+            // Write an SSE comment to keep the socket alive across intermediate proxies
+            // Only write after SSE headers have been sent (streamStarted === true)
+            try {
+              res.write(': keep-alive\n\n');
+            } catch {
+              // Client disconnected — clean up
+              cleanupStream();
+            }
+          }
+        }, streamKeepaliveConfig.KEEPALIVE_INTERVAL_MS);
+
+        // Attach client-disconnect listener
+        req.on('close', () => {
+          cleanupStream();
+        });
+
         try {
           const gen = route.provider.streamChatCompletion(
             route.apiKey, normalizedMessages, route.modelId,
@@ -1271,6 +1381,12 @@ async function handleChatCompletion(
           );
 
           for await (const chunk of gen) {
+            // Update chunk timestamp to reset stall timer
+            lastChunkTimestamp = Date.now();
+
+            // If stall handler already terminated the stream, break out
+            if (streamAborted) break;
+
             if (!streamStarted) {
               ttfbMs = Date.now() - start;
               res.setHeader('Content-Type', 'text/event-stream');
@@ -1295,6 +1411,15 @@ async function handleChatCompletion(
             }
           }
 
+          // Clear heartbeat on successful loop completion
+          cleanupStream();
+
+          // If stall handler already ended the response, skip the normal completion path
+          if (streamAborted) {
+            logRequest(route.platform, route.modelId, 'error', estimatedInputTokens, totalOutputTokens, Date.now() - start, ttfbMs, 'stream_stalled');
+            return;
+          }
+
           // Check for truncated response content after stream completes.
           // The stream has already been sent to the client — no retry within same request.
           // Future requests in this session will route to other providers.
@@ -1366,6 +1491,7 @@ async function handleChatCompletion(
           logRequest(route.platform, route.modelId, 'success', estimatedInputTokens, totalOutputTokens, Date.now() - start, ttfbMs, null);
           return;
         } catch (streamErr: any) {
+          cleanupStream();
           if (streamStarted) {
             // 5xx failure detection for mid-stream errors
             // LongCat: exclude entire provider immediately on any 5xx
diff --git a/server/src/services/threadProtection.ts b/server/src/services/threadProtection.ts
new file mode 100644
index 00000000..ab13bd58
--- /dev/null
+++ b/server/src/services/threadProtection.ts
@@ -0,0 +1,23 @@
+export type ProtectionLevel = 'provider-ban' | 'model-skip' | 'off';
+
+export type ErrorContextKind = '5xx' | 'truncation' | 'retryable';
+
+export interface ErrorContext {
+  platform: string;
+  kind: ErrorContextKind;
+  midStream: boolean;
+  modelDbId: number;
+  error?: unknown;
+}
+
+export interface ThreadProtectionAction {
+  banProvider: boolean;
+  skipModel: boolean;
+  clearStickyIfPinned: boolean;
+  reason: string;
+}
+
+export function evaluateThreadProtection(_ctx: ErrorContext): ThreadProtectionAction {
+  // Placeholder implementation: no protection
+  return { banProvider: false, skipModel: false, clearStickyIfPinned: false, reason: 'off' };
+}

From d4ea579943d73bb52a5e85b3932e6c0e693bebdb Mon Sep 17 00:00:00 2001
From: vi <vi70x3@atomicmail.io>
Date: Tue, 2 Jun 2026 17:31:52 +0300
Subject: [PATCH 3/4] chore: temporary commit before switching branch

---
 .roo/specs/disable-sticky-on-auto/design.md   |  97 ++++
 .../disable-sticky-on-auto/requirements.md    |  44 ++
 .roo/specs/disable-sticky-on-auto/tasks.md    |  16 +
 .../generalized-thread-protection/tasks.md    |  12 +
 .../owl-alpha-longcat-model-routing/design.md | 184 ++++++++
 .../requirements.md                           | 126 ++++++
 .../owl-alpha-longcat-model-routing/tasks.md  | 116 +++++
 .../design.md                                 | 238 ++++++++++
 .../requirements.md                           |  76 ++++
 .../recency-biased-thompson-sampling/tasks.md |  17 +
 .../design.md                                 | 330 ++++++++++++++
 .../requirements.md                           | 132 ++++++
 .../tasks.md                                  |  20 +
 .roo/specs/transient-model-cooldown/design.md | 197 +++++++++
 .../transient-model-cooldown/requirements.md  |  38 ++
 .roo/specs/transient-model-cooldown/tasks.md  |  16 +
 do_fix.py                                     |   7 +
 fix.py                                        |   8 +
 fix_streaming.py                              |  28 +-
 fix{                                          |   0
 new_streaming_block.txt                       |  28 ++
 .../routes/provider-session-ban.test.ts       | 140 ++++--
 .../src/__tests__/routes/proxy-tools.test.ts  |   6 +-
 .../routes/transient-cooldown.test.ts         | 415 ++++++++++++++++++
 server/src/__tests__/services/router.test.ts  |  39 +-
 server/src/routes/proxy.ts                    |  47 +-
 server/src/services/router.ts                 | 118 +++--
 server/write_test.py                          |  29 ++
 server/write_tests.py                         |  45 ++
 29 files changed, 2432 insertions(+), 137 deletions(-)
 create mode 100644 .roo/specs/disable-sticky-on-auto/design.md
 create mode 100644 .roo/specs/disable-sticky-on-auto/requirements.md
 create mode 100644 .roo/specs/disable-sticky-on-auto/tasks.md
 create mode 100644 .roo/specs/generalized-thread-protection/tasks.md
 create mode 100644 .roo/specs/owl-alpha-longcat-model-routing/design.md
 create mode 100644 .roo/specs/owl-alpha-longcat-model-routing/requirements.md
 create mode 100644 .roo/specs/owl-alpha-longcat-model-routing/tasks.md
 create mode 100644 .roo/specs/recency-biased-thompson-sampling/design.md
 create mode 100644 .roo/specs/recency-biased-thompson-sampling/requirements.md
 create mode 100644 .roo/specs/recency-biased-thompson-sampling/tasks.md
 create mode 100644 .roo/specs/sse-stream-heartbeat-stall-protection/design.md
 create mode 100644 .roo/specs/sse-stream-heartbeat-stall-protection/requirements.md
 create mode 100644 .roo/specs/sse-stream-heartbeat-stall-protection/tasks.md
 create mode 100644 .roo/specs/transient-model-cooldown/design.md
 create mode 100644 .roo/specs/transient-model-cooldown/requirements.md
 create mode 100644 .roo/specs/transient-model-cooldown/tasks.md
 create mode 100644 do_fix.py
 create mode 100644 fix.py
 create mode 100644 fix{
 create mode 100644 new_streaming_block.txt
 create mode 100644 server/src/__tests__/routes/transient-cooldown.test.ts
 create mode 100644 server/write_test.py
 create mode 100644 server/write_tests.py

diff --git a/.roo/specs/disable-sticky-on-auto/design.md b/.roo/specs/disable-sticky-on-auto/design.md
new file mode 100644
index 00000000..43a080d5
--- /dev/null
+++ b/.roo/specs/disable-sticky-on-auto/design.md
@@ -0,0 +1,97 @@
+# Design: Disable Sticky Threads on Auto Endpoint
+
+## Design Approach
+
+**Single-point guard in `getSessionKey()`** — modify [`getSessionKey()`](server/src/routes/proxy.ts:25) to return an empty string when `routingMode === 'balanced'`. This cascades through all sticky session functions because every one of them calls `getSessionKey()` first and returns early when the key is empty.
+
+## Why This Approach
+
+Every sticky session function in [`proxy.ts`](server/src/routes/proxy.ts) follows the same pattern:
+
+```
+function stickyOp(messages, routingMode, ...) {
+  const key = getSessionKey(messages, routingMode);
+  if (!key) return <no-op value>;   // undefined, false, or early return
+  ...operate on stickySessionMap using key...
+}
+```
+
+By making `getSessionKey()` return `''` for balanced mode, all downstream functions automatically become no-ops:
+
+| Function | No-op return when key is empty | Effect for balanced mode |
+|---|---|---|
+| [`getStickyModel()`](server/src/routes/proxy.ts:35) | `undefined` | No model pinning → free routing every request |
+| [`getStickyKey()`](server/src/routes/proxy.ts:55) | `undefined` | No key pinning → round-robin key selection |
+| [`setStickyModel()`](server/src/routes/proxy.ts:199) | early return | No sticky entries ever created |
+| [`clearStickyModel()`](server/src/routes/proxy.ts:180) | early return | No-op — nothing to clear |
+| [`clearStickyKey()`](server/src/routes/proxy.ts:188) | early return | No-op — nothing to clear |
+| [`isSessionBannedFromPlatform()`](server/src/routes/proxy.ts:92) | `false` | No platform bans checked |
+| [`banPlatformFromSession()`](server/src/routes/proxy.ts:108) | early return | No platform bans recorded |
+
+Direct `stickySessionMap` accesses in [`handleChatCompletion()`](server/src/routes/proxy.ts:1057) also use `getSessionKey()` and guard on the result being truthy, so they are automatically skipped:
+
+- **Session ban skipModels** (lines 1176–1189): `if (sessionKey)` guard → skipped when key is `''`
+- **LongCat sticky cooldown** (lines 1205–1217): `cooldownSessionKey ? ... : undefined` → skipped when key is `''`
+
+## Changes Required
+
+### 1. Modify `getSessionKey()` in `server/src/routes/proxy.ts`
+
+```typescript
+function getSessionKey(messages: ChatMessage[], routingMode: RoutingMode): string {
+  // Sticky sessions only apply to smart/auto-smart routing.
+  // Balanced/auto uses free routing on every request.
+  if (routingMode === 'balanced') return '';
+
+  const firstUser = messages.find(m => m.role === 'user');
+  if (!firstUser || typeof firstUser.content !== 'string') return '';
+  return crypto.createHash('sha1').update(`${routingMode}:${firstUser.content}`).digest('hex');
+}
+```
+
+This is the **only code change** needed. All other functions and call sites remain untouched.
+
+### 2. Update tests in `server/src/__tests__/routes/provider-session-ban.test.ts`
+
+Add test cases verifying that balanced mode skips sticky operations:
+- `getStickyModel()` returns `undefined` for balanced mode even when a sticky entry exists for the same messages under smart mode
+- `isSessionBannedFromPlatform()` returns `false` for balanced mode
+- `banPlatformFromSession()` does not create entries for balanced mode
+- `setStickyModel()` does not create entries for balanced mode
+
+### 3. No changes to `server/src/services/router.ts`
+
+The router itself does not interact with sticky sessions — it only receives `preferredModel` and `preferredKeyId` as optional parameters. When those are `undefined` (which they will be for balanced mode), the router already does free routing.
+
+## Flow Diagram
+
+```mermaid
+flowchart TD
+    A[Request arrives] --> B{model field?}
+    B -->|Explicit model| C[Pin to requested model]
+    B -->|No model field| D{routingMode?}
+    D -->|balanced| E[getSessionKey returns empty string]
+    D -->|smart| F[getSessionKey returns hash]
+    E --> G[All sticky functions return no-op]
+    G --> H[Free Thompson Sampling routing]
+    F --> I[Sticky model/key lookup]
+    I --> J{Sticky hit?}
+    J -->|Yes| K[Pin to sticky model + key]
+    J -->|No| H
+    K --> L[Route to pinned model]
+    H --> M[Route to best sampled model]
+    L --> N[On success: setStickyModel saves for smart]
+    M --> O[On success: setStickyModel is no-op for balanced]
+```
+
+## Edge Cases
+
+- **Mode switch mid-conversation**: Session keys include `routingMode` in the hash, so balanced and smart entries for the same messages are distinct. No cross-contamination.
+- **`stickySessionMap` size cleanup**: Since balanced mode never creates entries, the map only grows from smart-mode sessions. Existing eviction logic remains sufficient.
+- **`responseSessionMap`**: Separate from sticky sessions — used for the Responses API `previous_response_id` feature. Unaffected by this change.
+- **Per-request `skipModels`/`skipKeys`**: These are intra-request retry state, not sticky state. They remain active for both modes.
+
+## Risks
+
+- **Low risk**: The change is a single early-return in one function. All downstream behavior is already designed to handle empty keys gracefully.
+- **No backward compatibility concern**: Existing smart-mode sessions continue working identically. Balanced-mode sessions simply stop being created — there is no data to migrate or lose.
\ No newline at end of file
diff --git a/.roo/specs/disable-sticky-on-auto/requirements.md b/.roo/specs/disable-sticky-on-auto/requirements.md
new file mode 100644
index 00000000..20e60ec2
--- /dev/null
+++ b/.roo/specs/disable-sticky-on-auto/requirements.md
@@ -0,0 +1,44 @@
+# Requirements: Disable Sticky Threads on Auto Endpoint
+
+## Summary
+
+Disable the sticky session/thread feature on the `freellmapi/auto` (balanced routing) endpoint, keeping it active only on the `freellmapi/auto-smart` (smart routing) endpoint.
+
+## Background
+
+The sticky session system in [`server/src/routes/proxy.ts`](server/src/routes/proxy.ts) pins a conversation to the same model and API key across multiple turns. This prevents mid-conversation model switching, which can cause hallucinations or inconsistent tone.
+
+Currently, sticky sessions operate for **both** routing modes:
+- `'balanced'` — used by `freellmapi/auto`
+- `'smart'` — used by `freellmapi/auto-smart`
+
+The balanced/auto endpoint uses Thompson Sampling with speed-weighted scoring, intentionally exploring different models to find the best throughput. Sticky sessions contradict this design — they prevent exploration by pinning to whatever model happened to serve the first turn.
+
+The smart/auto-smart endpoint prioritizes intelligence and consistency, where sticky sessions are desirable to maintain coherent conversations.
+
+## Requirements
+
+### R1: No sticky model pinning on balanced/auto endpoint
+When `routingMode === 'balanced'`, the system must **not** read or write sticky model preferences. Calls to [`getStickyModel()`](server/src/routes/proxy.ts:35) and [`setStickyModel()`](server/src/routes/proxy.ts:199) must be skipped for balanced mode.
+
+### R2: No sticky key pinning on balanced/auto endpoint
+When `routingMode === 'balanced'`, the system must **not** read or write sticky API key preferences. Calls to [`getStickyKey()`](server/src/routes/proxy.ts:55) must be skipped for balanced mode.
+
+### R3: No session-level platform bans on balanced/auto endpoint
+When `routingMode === 'balanced'`, the system must **not** track or check session-level platform bans. Calls to [`isSessionBannedFromPlatform()`](server/src/routes/proxy.ts:92), [`banPlatformFromSession()`](server/src/routes/proxy.ts:108), and related `skipModels` logic from session bans must be skipped for balanced mode.
+
+### R4: Sticky sessions remain fully active on smart/auto-smart endpoint
+All sticky session functionality (model pinning, key pinning, platform bans) must continue working unchanged when `routingMode === 'smart'`.
+
+### R5: Per-request retry skip logic remains for both modes
+The `skipModels` and `skipKeys` sets used within a single request's retry loop must continue working for both modes. These are intra-request fallback mechanisms, not cross-request sticky state.
+
+### R6: Existing tests must pass
+All existing tests in [`provider-session-ban.test.ts`](server/src/__tests__/routes/provider-session-ban.test.ts) and [`full-flow.test.ts`](server/src/__tests__/integration/full-flow.test.ts) must continue passing. New test cases should verify that balanced mode skips sticky operations.
+
+## Out of Scope
+
+- Changing the routing algorithm for either mode
+- Removing the sticky session infrastructure (functions, maps) — they remain available for smart mode
+- Modifying the `/v1/models` endpoint or model ID constants
+- Changing how `getSessionKey()` hashes messages
\ No newline at end of file
diff --git a/.roo/specs/disable-sticky-on-auto/tasks.md b/.roo/specs/disable-sticky-on-auto/tasks.md
new file mode 100644
index 00000000..c0c41d7d
--- /dev/null
+++ b/.roo/specs/disable-sticky-on-auto/tasks.md
@@ -0,0 +1,16 @@
+# Tasks: Disable Sticky Threads on Auto Endpoint
+
+## Task List
+
+- [x] **T1: Modify `getSessionKey()` in `server/src/routes/proxy.ts`** — Add an early return for `routingMode === 'balanced'` that returns an empty string, disabling all sticky session operations for the auto/balanced endpoint. This is the single code change that cascades through all sticky functions.
+
+- [x] **T2: Add balanced-mode sticky skip tests in `server/src/__tests__/routes/provider-session-ban.test.ts`** — Add a new `describe` block verifying that balanced mode skips sticky operations:
+  - `getStickyModel()` returns `undefined` for balanced mode even when a smart-mode sticky entry exists for the same messages
+  - `isSessionBannedFromPlatform()` returns `false` for balanced mode
+  - `banPlatformFromSession()` does not create entries for balanced mode
+  - `setStickyModel()` does not create entries for balanced mode
+  - `getSessionKey()` returns `''` for balanced mode
+
+- [x] **T3: Run existing test suite** — Verify all existing tests in `provider-session-ban.test.ts` and `full-flow.test.ts` still pass after the change.
+
+- [ ] **T4: Manual smoke test** — Send a request to `freellmapi/auto` and confirm logs show `[Sticky] miss key= | msgs=... → free routing` (empty key prefix) rather than a sticky hit. Send a follow-up request with the same first user message and confirm it routes freely again rather than pinning.
\ No newline at end of file
diff --git a/.roo/specs/generalized-thread-protection/tasks.md b/.roo/specs/generalized-thread-protection/tasks.md
new file mode 100644
index 00000000..cf604bca
--- /dev/null
+++ b/.roo/specs/generalized-thread-protection/tasks.md
@@ -0,0 +1,12 @@
+# Tasks: Generalized Thread Protection (Exclusive Model Sessions)
+
+## Implementation Tasks
+
+- [ ] T-1: Rename `LONGCAT_STICKY_COOLDOWN_MS` to `THREAD_COOLDOWN_MS` in [`server/src/routes/proxy.ts`](server/src/routes/proxy.ts:18) and update all references throughout the file
+- [ ] T-2: Remove the hardcoded LongCat cooldown block (the `if (preferredModel)` block checking `prefRow?.platform === 'longcat'` and calling `addProviderModelsToSkipModels(skipModels, 'longcat')`)
+- [ ] T-3: Remove the hardcoded Owl Alpha cooldown block (the `if (preferredModel)` block checking `prefRow?.platform === 'openrouter' && prefRow?.model_id === 'owl-alpha'` and calling `skipModels.add(preferredModel)`)
+- [ ] T-4: Insert the generalized thread protection scanner at the same location where the removed blocks were, after the session ban sticky override and before the retry loop — including the `activeCooldownModels` collection loop, the exhaustion protection SQL query, and the conditional `skipModels` addition
+- [ ] T-5: Verify the execution order of the `skipModels` pipeline: session bans → transient cooldowns → global cooldown sticky override → session ban sticky override → thread protection scanner → retry loop
+- [ ] T-6: Create [`server/src/__tests__/routes/thread-protection.test.ts`](server/src/__tests__/routes/thread-protection.test.ts) with unit tests covering: dynamic exclusivity, exhaustion bypass, self-preservation, expired entries, and multiple busy models
+- [ ] T-7: Run the existing test suite to confirm no regressions in routing, fallback, or provider-session-ban tests
+- [ ] T-8: Manual smoke test: send two concurrent requests from different sessions and verify thread protection logs appear correctly, and that the second session routes to an alternative model
\ No newline at end of file
diff --git a/.roo/specs/owl-alpha-longcat-model-routing/design.md b/.roo/specs/owl-alpha-longcat-model-routing/design.md
new file mode 100644
index 00000000..f86b0e55
--- /dev/null
+++ b/.roo/specs/owl-alpha-longcat-model-routing/design.md
@@ -0,0 +1,184 @@
+# Design: Owl Alpha + LongCat Model-Level Routing
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Client Request                          │
+│              model: "freellmapi/auto" | "freellmapi/auto-smart"  │
+└─────────────┬───────────────────────────────┬───────────────┘
+              │                               │
+              ▼                               ▼
+┌─────────────────────────┐     ┌─────────────────────────┐
+│   Balanced Router       │     │   Smart Router          │
+│   (auto)                │     │   (auto-smart)          │
+│                         │     │                         │
+│  - Excludes longcat/*   │     │  - Prefers longcat/*    │
+│  - Excludes OR/owl-alpha│     │    and OR/owl-alpha     │
+│  - Normal bandit for    │     │    when valid keys exist│
+│    everything else      │     │  - Applies sticky       │
+│                         │     │    cooldown for both    │
+│                         │     │  - Model-level banning  │
+│                         │     │    on errors            │
+└─────────────┬───────────┘     └───────────┬─────────────┘
+              │                               │
+              ▼                               ▼
+┌─────────────────────────────────────────────────────────────┐
+│              routeRequest() in router.ts                    │
+│                                                             │
+│  1. Build chain from fallback_config + models               │
+│  2. Score via Thompson sampling                             │
+│  3. Apply balanced exclusions (REQ-1)                       │
+│  4. Apply smart preferences (REQ-2)                         │
+│  5. Apply sticky session pin                                │
+│  6. Iterate chain, find first model with valid key          │
+└─────────────────────────────────────────────────────────────┘
+              │
+              ▼
+┌─────────────────────────────────────────────────────────────┐
+│              handleChatCompletion() in proxy.ts             │
+│                                                             │
+│  - Sticky cooldown check for longcat + owl-alpha (REQ-3)   │
+│  - Model-level skipModels on 5xx/retryable (REQ-4, REQ-5)  │
+│  - Model-level skipModels on truncation (REQ-4, REQ-5)     │
+│  - Model-level skipModels on mid-stream errors (REQ-4, REQ-5)│
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Data Flow
+
+### Smart Preference Flow
+
+```
+routeRequest()
+  │
+  ├─ Build chain (all enabled models from fallback_config)
+  ├─ Score all entries via Thompson sampling
+  │
+  ├─ [BALANCED MODE]
+  │   ├─ Filter out entries where platform == 'longcat'
+  │   ├─ Filter out entries where platform == 'openrouter' AND model_id == 'owl-alpha'
+  │   └─ Continue with remaining chain
+  │
+  ├─ [SMART MODE]
+  │   ├─ Check LongCat preference
+  │   │   ├─ Query longcat keys (enabled, not invalid)
+  │   │   ├─ Validate: !isOnCooldown && canMakeRequest && canUseTokens
+  │   │   └─ If valid keys exist → move longcat entries to front
+  │   │
+  │   ├─ Check Owl Alpha preference
+  │   │   ├─ Query openrouter keys (enabled, not invalid)
+  │   │   ├─ Validate: !isOnCooldown && canMakeRequest && canUseTokens
+  │   │   └─ If valid keys exist → move openrouter/owl-alpha entry to front
+  │   │
+  │   └─ Continue with reordered chain
+  │
+  ├─ Apply sticky session pin (preferredModelDbId)
+  └─ Iterate chain for first valid key
+```
+
+### Sticky Cooldown Flow
+
+```
+handleChatCompletion()
+  │
+  ├─ [Existing] Check if sticky model is LongCat
+  │   └─ If within cooldown → add longcat platform models to skipModels
+  │
+  ├─ [NEW] Check if sticky model is Owl Alpha (openrouter/owl-alpha)
+  │   └─ If within cooldown → add openrouter/owl-alpha model to skipModels
+  │
+  └─ Proceed with routing (skipModels applied)
+```
+
+### Error Handling Flow (Model-Level)
+
+```
+On 5xx / retryable / truncation error from route:
+  │
+  ├─ [Existing LongCat] banPlatformFromSession('longcat')
+  │   → [CHANGED TO] skipModels.add(modelDbId) for longcat/LongCat-2.0-Preview
+  │
+  ├─ [NEW Owl Alpha] skipModels.add(modelDbId) for openrouter/owl-alpha
+  │
+  └─ Retry loop continues with updated skipModels
+```
+
+## File Changes
+
+### 1. `server/src/services/router.ts`
+
+**Changes:**
+- Add balanced mode exclusion for `longcat` platform and `openrouter/owl-alpha` model
+- Add smart mode preference for `openrouter/owl-alpha` (parallel to existing LongCat preference)
+- Extract a reusable `hasValidKeys()` helper to avoid duplicating key validation logic
+
+**New constants:**
+```typescript
+const EXCLUDED_FROM_BALANCED = new Set(['longcat']);
+const EXCLUDED_MODELS_FROM_BALANCED = new Map<string, Set<string>>([
+  ['openrouter', new Set(['owl-alpha'])],
+]);
+```
+
+**Modified function: `routeRequest()`**
+- After building the chain, in balanced mode: filter out excluded platforms/models
+- In smart mode: add Owl Alpha preference check after LongCat preference check
+
+### 2. `server/src/routes/proxy.ts`
+
+**Changes:**
+- Add sticky cooldown check for Owl Alpha (when sticky model is `openrouter/owl-alpha`)
+- Change LongCat error handling from `banPlatformFromSession('longcat')` to `skipModels.add(modelDbId)`
+- Add Owl Alpha error handling: `skipModels.add(modelDbId)` (model-level, not platform-level)
+
+**Modified sections:**
+- Lines ~1209-1221: LongCat sticky cooldown → also check for Owl Alpha sticky
+- Lines ~1376-1387: Mid-stream 5xx from LongCat → model-level skip
+- Lines ~1308-1318: Truncation from LongCat → model-level skip
+- Lines ~1403-1413: Truncation from Owl Alpha → model-level skip
+- Lines ~1434-1466: Mid-stream retryable from LongCat → model-level skip
+- Lines ~1536-1553: Non-stream 5xx from LongCat → model-level skip
+- Lines ~1557-1569: Retryable error from LongCat → model-level skip
+- Lines ~1308-1318: Truncation from Owl Alpha → model-level skip (new)
+- New: Non-stream 5xx from Owl Alpha → model-level skip
+- New: Retryable error from Owl Alpha → model-level skip
+
+## Key Design Decisions
+
+### Decision 1: Model-Level vs Provider-Level Banning
+
+**Choice:** Use `skipModels.add(modelDbId)` instead of `banPlatformFromSession()` for both LongCat and Owl Alpha.
+
+**Rationale:**
+- LongCat currently has only one model but may add more in the future
+- Banning the entire `longcat` platform when one model fails is overly aggressive
+- Owl Alpha is one model among many on `openrouter` — banning all of `openrouter` would be catastrophic
+- Model-level banning is more precise and allows other models on the same platform to continue working
+
+### Decision 2: Reuse Existing Cooldown Constant
+
+**Choice:** Use the existing `LONGCAT_STICKY_COOLDOWN_MS` (3 minutes) for both LongCat and Owl Alpha cooldown.
+
+**Rationale:**
+- Both platforms serve similar free-tier models with similar session isolation concerns
+- Adding a separate constant adds complexity without clear benefit
+- Can be split later if different cooldown windows are needed
+
+### Decision 3: Balanced Exclusion at Chain Level
+
+**Choice:** Filter excluded models from the chain before scoring in balanced mode, rather than skipping during iteration.
+
+**Rationale:**
+- Cleaner separation: excluded models never enter the bandit scoring
+- Avoids edge case where an excluded model scores highest but gets skipped, causing unnecessary fallback
+- Consistent with how the chain is already filtered (e.g., `skipModels` check during iteration)
+
+### Decision 4: Smart Preference Uses Same Key Validation
+
+**Choice:** The Owl Alpha preference check uses the same `isOnCooldown` + `canMakeRequest` + `canUseTokens` validation as LongCat.
+
+**Rationale:**
+- Consistent behavior: both models are treated identically
+- The `isOnCooldown` check ensures penalized keys (from 429s) don't trigger preference
+- The capacity checks ensure the model is actually routable before preferring it
diff --git a/.roo/specs/owl-alpha-longcat-model-routing/requirements.md b/.roo/specs/owl-alpha-longcat-model-routing/requirements.md
new file mode 100644
index 00000000..a5be6aaa
--- /dev/null
+++ b/.roo/specs/owl-alpha-longcat-model-routing/requirements.md
@@ -0,0 +1,126 @@
+# Requirements: Owl Alpha + LongCat Model-Level Routing
+
+## Overview
+
+Treat Owl Alpha (`openrouter/owl-alpha`) identically to LongCat (`longcat/LongCat-2.0-Preview`) in the smart routing system, with model-level (not provider-level) banning for both. Exclude both from the balanced auto router entirely.
+
+## Context
+
+- **Owl Alpha** is a model under the `openrouter` platform: `openrouter/owl-alpha`
+- **LongCat** is a separate platform: `longcat/LongCat-2.0-Preview`
+- Both are frontier-tier free models with similar agentic capabilities
+- LongCat currently has provider-level banning (entire `longcat` platform banned on errors) — this needs to shift to model-level banning since LongCat may add more models in the future
+- Owl Alpha needs model-level banning (only `openrouter/owl-alpha` banned, not all of `openrouter`)
+- Both should be excluded from `freellmapi/auto` (balanced) routing
+- Both should be preferred in `freellmapi/auto-smart` routing when valid (non-cooldown) keys exist
+- Sticky session cooldown should protect both platforms' models from being hit by other sessions
+
+## Requirements
+
+### REQ-1: Exclude Owl Alpha and LongCat from Balanced Auto Routing
+
+**Priority:** Must Have
+
+The `freellmapi/auto` (balanced routing mode) must never route to:
+- Any model on the `longcat` platform (currently only `LongCat-2.0-Preview`)
+- The `openrouter/owl-alpha` model
+
+This applies to all sessions, including sticky sessions. The balanced router should completely ignore these models/platforms.
+
+**Acceptance Criteria:**
+- `freellmapi/auto` requests never resolve to `longcat/LongCat-2.0-Preview`
+- `freellmapi/auto` requests never resolve to `openrouter/owl-alpha`
+- Explicit model requests (e.g., `model: "openrouter/owl-alpha"`) still work in balanced mode
+- Other `openrouter/*` models remain available in balanced mode
+
+### REQ-2: Smart Auto Preference for Owl Alpha and LongCat
+
+**Priority:** Must Have
+
+The `freellmapi/auto-smart` routing mode must prefer Owl Alpha and LongCat models when:
+1. At least one API key exists for the platform/model
+2. At least one key is NOT on cooldown (not in the 429 penalty list)
+3. At least one key has capacity (passes rate-limit checks)
+
+When these conditions are met, Owl Alpha and LongCat models should be moved to the front of the routing chain, preserving their relative Thompson-sampling score order.
+
+**Acceptance Criteria:**
+- When valid LongCat keys exist, `longcat/LongCat-2.0-Preview` appears at the front of the sorted chain in smart mode
+- When valid Owl Alpha keys exist (i.e., keys for `openrouter` platform that can reach `owl-alpha`), `openrouter/owl-alpha` appears at the front of the sorted chain in smart mode
+- When no valid keys exist (all on cooldown or no keys configured), these models fall back to normal bandit scoring
+- The preference check uses the same capacity validation as the existing LongCat preference logic (`canMakeRequest`, `canUseTokens`, `isOnCooldown`)
+
+### REQ-3: Sticky Session Cooldown for Owl Alpha and LongCat
+
+**Priority:** Must Have
+
+When a session has a recent sticky session on LongCat or Owl Alpha (within the cooldown window), other sessions should not be routed to these models.
+
+The existing `LONGCAT_STICKY_COOLDOWN_MS` (3 minutes) applies. During the cooldown window:
+- The current sticky session keeps its pinned route
+- All other sessions skip LongCat and Owl Alpha models
+
+**Acceptance Criteria:**
+- After a session uses LongCat, other sessions skip LongCat models for `LONGCAT_STICKY_COOLDOWN_MS`
+- After a session uses Owl Alpha, other sessions skip `openrouter/owl-alpha` for `LONGCAT_STICKY_COOLDOWN_MS`
+- The sticky session itself is NOT affected — it keeps its pinned model
+- After the cooldown expires, these models become available to all sessions again
+
+### REQ-4: Model-Level Banning for LongCat (Migration from Provider-Level)
+
+**Priority:** Must Have
+
+Change LongCat error handling from provider-level banning to model-level banning:
+- On 5xx/retryable errors from `longcat/LongCat-2.0-Preview`, only skip `longcat/LongCat-2.0-Preview` for the session
+- Do NOT ban the entire `longcat` platform
+- This prepares for future LongCat models that may be added independently
+
+**Acceptance Criteria:**
+- When `longcat/LongCat-2.0-Preview` returns a 5xx error, only that specific model is added to `skipModels` for the session
+- Other models on the `longcat` platform (when added in the future) remain available
+- Truncation errors from `longcat/LongCat-2.0-Preview` skip only that model
+- Mid-stream retryable errors from `longcat/LongCat-2.0-Preview` skip only that model
+- The `banPlatformFromSession` call is replaced with `skipModels.add(modelDbId)` for LongCat
+
+### REQ-5: Model-Level Banning for Owl Alpha
+
+**Priority:** Must Have
+
+Owl Alpha uses model-level banning (same as the new LongCat behavior):
+- On 5xx/retryable errors from `openrouter/owl-alpha`, only skip `openrouter/owl-alpha` for the session
+- Do NOT ban the entire `openrouter` platform
+- Other `openrouter/*` models remain available
+
+**Acceptance Criteria:**
+- When `openrouter/owl-alpha` returns a 5xx error, only that specific model is added to `skipModels` for the session
+- Other `openrouter/*` models remain available for the session
+- Truncation errors from `openrouter/owl-alpha` skip only that model
+- Mid-stream retryable errors from `openrouter/owl-alpha` skip only that model
+
+### REQ-6: Valid Key Check for Preference
+
+**Priority:** Must Have
+
+The smart auto preference logic must validate that keys are not on cooldown before preferring a model. A key that has been penalized by the rate-limit system (429 cooldown) should not count as a valid key for the preference check.
+
+**Acceptance Criteria:**
+- The preference check queries keys with `status != 'invalid'` AND `enabled = 1`
+- The preference check validates at least one key passes `isOnCooldown()` (returns false)
+- The preference check validates at least one key passes `canMakeRequest()` and `canUseTokens()`
+- If all keys are on cooldown, the model is NOT preferred (falls back to normal bandit scoring)
+
+## Out of Scope
+
+- Adding new API endpoints or modifying the external API contract
+- Changing the Thompson sampling algorithm
+- Modifying rate-limit penalty decay logic
+- Adding new platforms or models
+- Changing the sticky session TTL
+
+## Dependencies
+
+- Existing LongCat smart auto preference logic in [`server/src/services/router.ts`](../server/src/services/router.ts)
+- Existing LongCat sticky cooldown logic in [`server/src/routes/proxy.ts`](../server/src/routes/proxy.ts)
+- Existing provider-level ban logic in [`server/src/routes/proxy.ts`](../server/src/routes/proxy.ts)
+- Owl Alpha model seeded in [`server/src/db/index.ts`](../server/src/db/index.ts) via `migrateModelsV15`
+- LongCat model seeded in [`server/src/db/index.ts`](../server/src/db/index.ts) via `migrateModelsV16`
diff --git a/.roo/specs/owl-alpha-longcat-model-routing/tasks.md b/.roo/specs/owl-alpha-longcat-model-routing/tasks.md
new file mode 100644
index 00000000..c65a2df7
--- /dev/null
+++ b/.roo/specs/owl-alpha-longcat-model-routing/tasks.md
@@ -0,0 +1,116 @@
+# Tasks: Owl Alpha + LongCat Model-Level Routing
+
+## Phase 1: Router Changes (`server/src/services/router.ts`)
+
+- [x] **T1.1: Add balanced mode exclusion constants**
+  - Add `EXCLUDED_FROM_BALANCED` set containing `'longcat'`
+  - Add `EXCLUDED_MODELS_FROM_BALANCED` map with `openrouter → Set(['owl-alpha'])`
+
+- [x] **T1.2: Add balanced mode exclusion filter in `routeRequest()`**
+  - After building the chain, in balanced mode (`routingMode === 'balanced'`):
+    - Filter out entries where `platform` is in `EXCLUDED_FROM_BALANCED`
+    - Filter out entries where `platform` + `model_id` is in `EXCLUDED_MODELS_FROM_BALANCED`
+  - Smart mode does NOT apply this exclusion (these models are available via preference)
+
+- [x] **T1.3: Extract reusable `hasValidKeys()` helper**
+  - Create a function that takes `(platform, modelId, limits, estimatedTokens)` and returns boolean
+  - Queries keys with `enabled = 1 AND status != 'invalid'`
+  - Checks `!isOnCooldown() && canMakeRequest() && canUseTokens()` for at least one key
+  - Refactor existing LongCat preference check to use this helper
+
+- [x] **T1.4: Add Owl Alpha smart preference check**
+  - After the existing LongCat preference block in smart mode:
+    - Query `openrouter` keys for the `owl-alpha` model
+    - Use `hasValidKeys()` to validate at least one key has capacity
+    - If valid: move `openrouter/owl-alpha` entry to front of sorted chain (after LongCat entries if both are preferred)
+    - Preserve relative score order among preferred entries
+    - Log: `[Router] Owl Alpha preference active — moving openrouter/owl-alpha to front`
+
+## Phase 2: Proxy Changes (`server/src/routes/proxy.ts`)
+
+- [x] **T2.1: Add Owl Alpha sticky cooldown check**
+  - After the existing LongCat sticky cooldown block (~line 1209-1221):
+    - Check if the sticky model's `platform === 'openrouter'` AND `model_id === 'owl-alpha'`
+    - If within `LONGCAT_STICKY_COOLDOWN_MS`: add the specific `owl-alpha` model DB ID to `skipModels`
+    - Log the cooldown activation
+
+- [x] **T2.2: Change LongCat truncation handling to model-level**
+  - Line ~1308-1318: Replace `banPlatformFromSession('longcat')` + `addProviderModelsToSkipModels(skipModels, 'longcat')` with `skipModels.add(route.modelDbId)`
+  - Update log message to say "skipping model LongCat-2.0-Preview" instead of "banning LongCat provider"
+
+- [x] **T2.3: Add Owl Alpha truncation handling (model-level)**
+  - In the truncation check block (~line 1303-1318):
+    - Add condition for `route.platform === 'openrouter' && route.modelId === 'owl-alpha'`
+    - Use `skipModels.add(route.modelDbId)` (model-level, NOT platform-level)
+    - Log: "Truncated stream content detected from Owl Alpha — skipping model openrouter/owl-alpha for session"
+
+- [x] **T2.4: Change LongCat mid-stream 5xx handling to model-level**
+  - Line ~1376-1387: Replace `banPlatformFromSession('longcat')` + `addProviderModelsToSkipModels(skipModels, 'longcat')` with `skipModels.add(route.modelDbId)`
+  - Clear sticky if pinned to the specific model (check `route.modelId === 'LongCat-2.0-Preview'`)
+
+- [x] **T2.5: Add Owl Alpha mid-stream 5xx handling (model-level)**
+  - In the mid-stream 5xx block (~line 1376-1387):
+    - Add condition for `route.platform === 'openrouter' && route.modelId === 'owl-alpha'`
+    - Use `skipModels.add(route.modelDbId)` (model-level)
+    - Clear sticky if pinned to the specific model
+
+- [x] **T2.6: Change LongCat mid-stream truncation handling to model-level**
+  - Line ~1403-1413: Replace `banPlatformFromSession('longcat')` + `addProviderModelsToSkipModels(skipModels, 'longcat')` with `skipModels.add(route.modelDbId)`
+
+- [x] **T2.7: Add Owl Alpha mid-stream truncation handling (model-level)**
+  - In the mid-stream truncation block (~line 1389-1432):
+    - Add condition for `route.platform === 'openrouter' && route.modelId === 'owl-alpha'`
+    - Use `skipModels.add(route.modelDbId)` (model-level)
+
+- [x] **T2.8: Change LongCat mid-stream retryable error handling to model-level**
+  - Line ~1434-1466: Replace `banPlatformFromSession('longcat')` + `addProviderModelsToSkipModels(skipModels, 'longcat')` with `skipModels.add(route.modelDbId)`
+
+- [x] **T2.9: Add Owl Alpha mid-stream retryable error handling (model-level)**
+  - In the mid-stream retryable error block (~line 1434-1466):
+    - Add condition for `route.platform === 'openrouter' && route.modelId === 'owl-alpha'`
+    - Use `skipModels.add(route.modelDbId)` (model-level)
+
+- [x] **T2.10: Change LongCat non-stream 5xx handling to model-level**
+  - Line ~1536-1553: Replace `banPlatformFromSession('longcat')` + `addProviderModelsToSkipModels(skipModels, 'longcat')` with `skipModels.add(route.modelDbId)`
+  - Clear sticky if pinned to the specific model
+
+- [x] **T2.11: Add Owl Alpha non-stream 5xx handling (model-level)**
+  - In the non-stream 5xx block (~line 1531-1553):
+    - Add condition for `route.platform === 'openrouter' && route.modelId === 'owl-alpha'`
+    - Use `skipModels.add(route.modelDbId)` (model-level)
+    - Clear sticky if pinned to the specific model
+
+- [x] **T2.12: Change LongCat non-stream retryable error handling to model-level**
+  - Line ~1557-1569: Replace `banPlatformFromSession('longcat')` + `addProviderModelsToSkipModels(skipModels, 'longcat')` with `skipModels.add(route.modelDbId)`
+  - Clear sticky if pinned to the specific model
+
+- [x] **T2.13: Add Owl Alpha non-stream retryable error handling (model-level)**
+  - In the non-stream retryable error block (~line 1555-1581):
+    - Add condition for `route.platform === 'openrouter' && route.modelId === 'owl-alpha'`
+    - Use `skipModels.add(route.modelDbId)` (model-level)
+    - Clear sticky if pinned to the specific model
+
+## Phase 3: Testing
+
+- [ ] **T3.1: Verify balanced auto excludes LongCat and Owl Alpha**
+  - Add test: `freellmapi/auto` with valid longcat/owl-alpha keys → routes to other models
+  - Add test: `freellmapi/auto` with ONLY longcat/owl-alpha keys → returns 429
+
+- [ ] **T3.2: Verify smart auto prefers LongCat and Owl Alpha**
+  - Add test: `freellmapi/auto-smart` with valid longcat keys → longcat at front of chain
+  - Add test: `freellmapi/auto-smart` with valid openrouter keys → owl-alpha at front of chain
+  - Add test: `freellmapi/auto-smart` with all keys on cooldown → normal bandit scoring
+
+- [ ] **T3.3: Verify sticky cooldown works for both**
+  - Add test: Session uses LongCat → other sessions skip LongCat for cooldown window
+  - Add test: Session uses Owl Alpha → other sessions skip Owl Alpha for cooldown window
+
+- [ ] **T3.4: Verify model-level banning**
+  - Add test: LongCat 5xx → only LongCat-2.0-Preview skipped, other longcat models (future) available
+  - Add test: Owl Alpha 5xx → only owl-alpha skipped, other openrouter models available
+  - Add test: Owl Alpha truncation → only owl-alpha skipped
+  - Add test: LongCat truncation → only LongCat-2.0-Preview skipped
+
+- [ ] **T3.5: Verify explicit model requests still work**
+  - Add test: `model: "longcat/LongCat-2.0-Preview"` in balanced mode → routes to LongCat
+  - Add test: `model: "openrouter/owl-alpha"` in balanced mode → routes to Owl Alpha
\ No newline at end of file
diff --git a/.roo/specs/recency-biased-thompson-sampling/design.md b/.roo/specs/recency-biased-thompson-sampling/design.md
new file mode 100644
index 00000000..1efcb05c
--- /dev/null
+++ b/.roo/specs/recency-biased-thompson-sampling/design.md
@@ -0,0 +1,238 @@
+# Design: Recency-Biased Thompson Sampling (Time-Decay Aggregation)
+
+## Architecture Overview
+
+The change is localized to the stats aggregation pipeline in [`router.ts`](server/src/services/router.ts). The core idea: replace flat `COUNT(*)` / `SUM(CASE ... 1 ELSE 0)` with weighted sums where each request's contribution is scaled by a linear time-decay factor based on its age within the 7-day analytics window.
+
+```mermaid
+flowchart TD
+    A[requests table] --> B[refreshStatsCache]
+    B --> C{SQL CTE: weighted_requests}
+    C --> D[recency_weight = MIN 1.0, MAX 0.0, 1.0 - age_in_days / window_days]
+    D --> E[SUM recency_weight -> total_weighted]
+    D --> F[SUM success * recency_weight -> successes_weighted]
+    E --> G[statsCache Map]
+    F --> G
+    G --> H[thompsonSampleScore]
+    G --> I[smartSampleScore]
+    G --> J[getAnalyticsScore]
+    G --> K[getSmartAnalyticsScore]
+    G --> L[getAnalyticsScores - dashboard]
+    H --> M[Math.max 0.1, successes + PRIOR_SUCCESS]
+    H --> N[Math.max 0.1, failures_weighted + PRIOR_FAILURE]
+    M --> O[sampleBeta alpha beta]
+    N --> O
+```
+
+---
+
+## Component Changes
+
+### 1. SQL Query in [`refreshStatsCache()`](server/src/services/router.ts:174)
+
+**Current query** (flat aggregation):
+```sql
+SELECT platform, model_id,
+  COUNT(*) as total,
+  SUM(CASE WHEN status = 'success' THEN 1 ELSE 0 END) as successes,
+  ...
+FROM requests
+WHERE created_at >= ?
+GROUP BY platform, model_id
+```
+
+**New query** (CTE with linear decay):
+```sql
+WITH weighted_requests AS (
+  SELECT 
+    platform, 
+    model_id,
+    status,
+    latency_ms,
+    output_tokens,
+    ttfb_ms,
+    MIN(1.0, MAX(0.0, 1.0 - (julianday('now') - julianday(created_at)) / ?)) as recency_weight
+  FROM requests
+  WHERE created_at >= ?
+)
+SELECT 
+  platform, 
+  model_id,
+  SUM(recency_weight) as total_weighted,
+  SUM(CASE WHEN status = 'success' THEN recency_weight ELSE 0 END) as successes_weighted,
+  COUNT(*) as raw_total,
+  SUM(CASE WHEN status = 'success' THEN 1 ELSE 0 END) as raw_successes,
+  CASE
+    WHEN SUM(CASE WHEN status = 'success' THEN latency_ms ELSE 0 END) > 0
+    THEN SUM(CASE WHEN status = 'success' THEN output_tokens ELSE 0 END) * 1000.0
+         / SUM(CASE WHEN status = 'success' THEN latency_ms ELSE 0 END)
+    ELSE 0
+  END as tok_per_sec,
+  AVG(CASE WHEN status = 'success' AND ttfb_ms IS NOT NULL THEN ttfb_ms END) as avg_ttfb_ms
+FROM weighted_requests
+GROUP BY platform, model_id
+```
+
+**Key design decisions**:
+
+| Decision | Rationale |
+|----------|-----------|
+| `MIN(1.0, MAX(0.0, ...))` double-bounding | Protects against system clock drift: clock shifting backward could make `julianday('now') < julianday(created_at)`, yielding weight > 1.0 |
+| Window days passed as SQL parameter `?` | Avoids hardcoding `7.0` in SQL; derived from `ANALYTICS_WINDOW_MS` constant, keeping them coupled |
+| `tok_per_sec` and `avg_ttfb_ms` remain unweighted | Speed/TTFB are quality metrics that don't typically change suddenly; weighting adds complexity without clear benefit. Future enhancement opportunity. |
+| `raw_total` and `raw_successes` included | Dashboard transparency — users need to see actual request counts alongside weighted rates |
+
+### 2. [`ModelStats`](server/src/services/router.ts:153) Interface Extension
+
+**Current**:
+```typescript
+interface ModelStats {
+  successes: number;
+  total: number;
+  tokPerSec: number;
+  avgTtfbMs: number | null;
+}
+```
+
+**New**:
+```typescript
+interface ModelStats {
+  successes: number;       // now: weighted sum (float) instead of integer count
+  total: number;           // now: weighted sum (float) instead of integer count
+  rawSuccesses: number;    // actual integer count of successful requests
+  rawTotal: number;        // actual integer count of all requests
+  tokPerSec: number;
+  avgTtfbMs: number | null;
+}
+```
+
+The `rawSuccesses` and `rawTotal` fields serve two purposes:
+1. **Dashboard display**: Show actual request volumes to users (not confusing fractional totals)
+2. **Debugging**: Allow comparison between flat and weighted success rates
+
+### 3. Beta Parameter Safety Guards
+
+**Current** (in [`thompsonSampleScore()`](server/src/services/router.ts:264) and [`smartSampleScore()`](server/src/services/router.ts:293)):
+```typescript
+const alpha = (stats?.successes ?? 0) + PRIOR_SUCCESS;
+const beta  = ((stats?.total ?? 0) - (stats?.successes ?? 0)) + PRIOR_FAILURE;
+```
+
+**New**:
+```typescript
+const alpha = Math.max(0.1, (stats?.successes ?? 0)) + PRIOR_SUCCESS;
+const beta  = Math.max(0.1, ((stats?.total ?? 0) - (stats?.successes ?? 0))) + PRIOR_FAILURE;
+```
+
+The `Math.max(0.1, ...)` guard ensures:
+- Floating-point rounding cannot produce `alpha ≤ 0` or `beta ≤ 0` (which would crash [`sampleGamma()`](server/src/services/router.ts:133))
+- Even if weighted totals are very small (e.g., 0.002), the prior still dominates appropriately
+- The `0.1` floor is small enough not to distort the prior meaningfully
+
+**Also applied to** [`getAnalyticsScore()`](server/src/services/router.ts:212) and [`getSmartAnalyticsScore()`](server/src/services/router.ts:241) for the `bayesRate` computation:
+```typescript
+const bayesRate = (Math.max(0.1, successes) + PRIOR_SUCCESS) 
+                / (Math.max(0.1, total) + PRIOR_SUCCESS + PRIOR_FAILURE);
+```
+
+### 4. Dashboard Display in [`getAnalyticsScores()`](server/src/services/router.ts:314)
+
+**Current**:
+```typescript
+result.push({
+  ...
+  successRate: stats.total > 0 ? stats.successes / stats.total : 0,
+  total: stats.total,
+  ...
+});
+```
+
+**New**:
+```typescript
+result.push({
+  ...
+  successRate: stats.total > 0 ? stats.successes / stats.total : 0,  // weighted rate
+  total: stats.rawTotal,           // show actual count, not weighted sum
+  ...
+});
+```
+
+The `successRate` now reflects the recency-biased rate (more responsive to recent trends), while `total` shows the actual number of requests for user comprehension.
+
+### 5. Window Days Parameter Derivation
+
+To keep the SQL decay denominator coupled with the `ANALYTICS_WINDOW_MS` constant:
+
+```typescript
+const ANALYTICS_WINDOW_DAYS = ANALYTICS_WINDOW_MS / (24 * 60 * 60 * 1000);  // 7.0
+```
+
+This constant is passed as the second SQL parameter in the CTE. If `ANALYTICS_WINDOW_MS` is ever changed, the decay slope automatically adjusts.
+
+---
+
+## Data Flow Diagram
+
+```mermaid
+sequenceDiagram
+    participant Timer as Cache Refresh Timer
+    participant DB as SQLite Database
+    participant Cache as statsCache Map
+    participant Router as thompsonSampleScore
+    participant Dashboard as getAnalyticsScores
+
+    Timer->>DB: refreshStatsCache - SQL with CTE + julianday decay
+    DB-->>Cache: rows with total_weighted, successes_weighted, raw_total, raw_successes
+    Cache->>Cache: Store ModelStats with weighted + raw fields
+
+    Router->>Cache: Get stats for platform:modelId
+    Cache-->>Router: ModelStats with fractional successes/total
+    Router->>Router: Math.max 0.1 guard on alpha and beta
+    Router->>Router: sampleBeta alpha beta + speed + ttfb + intelligence
+
+    Dashboard->>Cache: Get all stats
+    Cache-->>Dashboard: ModelStats entries
+    Dashboard->>Dashboard: successRate = weighted successes / weighted total
+    Dashboard->>Dashboard: total = rawTotal for display
+```
+
+---
+
+## Weight Decay Visualization
+
+The linear decay function over the 7-day window:
+
+```
+Weight
+1.0 ─────┐
+         │\
+         │ \
+0.5 ─────│──\────── at 3.5 days
+         │   \
+         │    \
+0.0 ─────│─────\─── at 7.0 days
+         0     3.5  7.0  Age (days)
+```
+
+- **Day 0 (just now)**: weight = 1.0 — full contribution
+- **Day 1**: weight = 6/7 ≈ 0.857 — still highly influential  
+- **Day 3.5**: weight = 0.5 — half contribution
+- **Day 5**: weight = 2/7 ≈ 0.286 — marginal influence
+- **Day 7**: weight = 0.0 — zero contribution (filtered by `WHERE created_at >= ?` anyway)
+
+---
+
+## Files Modified
+
+| File | Change Type | Description |
+|------|-------------|-------------|
+| [`server/src/services/router.ts`](server/src/services/router.ts) | Modify | SQL query in `refreshStatsCache`, `ModelStats` interface, Beta parameter guards, dashboard display |
+| [`server/src/__tests__/services/router.test.ts`](server/src/__tests__/services/router.test.ts) | Modify | Add test cases T-1 and T-2 for outage sensitivity and safe fractional evaluation |
+
+---
+
+## Out-of-Scope / Future Enhancements
+
+1. **Weighted speed/TTFB metrics**: Currently `tok_per_sec` and `avg_ttfb_ms` remain unweighted. A future iteration could apply recency weighting to these as well, making the router responsive to recent speed degradation.
+2. **Exponential decay**: The linear decay is simple and portable. An exponential decay (using `power()` which is available in SQLite core) would give sharper recent-vs-old contrast but is harder to reason about.
+3. **Configurable decay slope**: The decay rate is currently tied to the window length. A separate configuration parameter could allow tuning the decay aggressiveness independently.
\ No newline at end of file
diff --git a/.roo/specs/recency-biased-thompson-sampling/requirements.md b/.roo/specs/recency-biased-thompson-sampling/requirements.md
new file mode 100644
index 00000000..0e30643d
--- /dev/null
+++ b/.roo/specs/recency-biased-thompson-sampling/requirements.md
@@ -0,0 +1,76 @@
+# Requirements: Recency-Biased Thompson Sampling (Time-Decay Aggregation)
+
+## Overview
+
+The Thompson Sampling router currently computes each model's success rate as a flat average over a 7-day window. Historical successes from days ago can mask a sudden, persistent outage occurring right now. This feature introduces a time-decay weighting mechanism so recent requests carry significantly more statistical weight than older requests, enabling the router to react dynamically to changes in provider health.
+
+---
+
+## Requirements
+
+### R-1: Linear Time-Decay Weighting
+
+The SQL query aggregating historical requests in [`refreshStatsCache()`](server/src/services/router.ts:174) must calculate a weight for each logged request based on its age. Newer requests must be assigned a weight closer to `1.0`, while requests approaching the limit of the analytics window (7 days) must decay toward `0.0`.
+
+**Formula**: `MIN(1.0, MAX(0.0, 1.0 - (julianday('now') - julianday(created_at)) / 7.0))`
+
+- Request logged just now → weight ≈ `1.0`
+- Request logged 3.5 days ago → weight ≈ `0.5`
+- Request logged 7 days ago → weight ≈ `0.0`
+- The `MIN(1.0, ...)` upper bound protects against system clock drift anomalies
+- The `MAX(0.0, ...)` lower bound prevents negative weights
+
+### R-2: Backward Compatibility with Beta Sampling
+
+The calculated weighted successes and weighted totals must be mapped safely to the alpha and beta parameters of the Beta distribution sampler. Because the sampler expects positive numbers, the weighted sums must be safely bounded using `Math.max(0.1, ...)` to guarantee that floating-point variance or rounding margins do not result in non-positive alpha/beta arguments.
+
+**Affected functions**:
+- [`thompsonSampleScore()`](server/src/services/router.ts:264)
+- [`smartSampleScore()`](server/src/services/router.ts:293)
+- [`getAnalyticsScore()`](server/src/services/router.ts:212)
+- [`getSmartAnalyticsScore()`](server/src/services/router.ts:241)
+
+### R-3: Zero-Extension Portability
+
+The implementation must use standard, widely supported SQLite date functions — specifically `julianday()` — to calculate the age of requests. This avoids relying on platform-specific external SQL mathematical extensions like `EXP()` that may not be available in all SQLite builds.
+
+---
+
+## Constraints
+
+- **No schema changes**: The `requests` table schema remains unchanged. The `created_at` column (TEXT, ISO-8601) already stores timestamps suitable for `julianday()` computation.
+- **No new dependencies**: The change is purely a SQL query modification and a TypeScript safety guard — no new packages or external extensions required.
+- **Cache TTL unchanged**: The `ANALYTICS_CACHE_TTL_MS` (60 seconds) and `ANALYTICS_WINDOW_MS` (7 days) constants remain the same.
+
+---
+
+## Test Cases
+
+### T-1: Outage Sensitivity Under High Baseline Volume
+
+**Setup**:
+1. Seed the database with 1,000 successful requests for Model A spread over days 1–5 of the 7-day window.
+2. Record 15 consecutive failures for Model A in the last 10 minutes of Day 7.
+
+**Execution**: Trigger `refreshStatsCache()` and observe the computed `successes` and `total` for Model A.
+
+**Expected Behavior**: Under a flat average, 15 failures against 1,000 successes yields ~98.5% success rate. With linear decay, the 1,000 old requests have an average weight < 0.3 (totaling ~300 effective runs), while the 15 failures carry weight ≈ 1.0 (totaling ~15 effective runs). The effective success rate is noticeably depressed, causing the Thompson Sampling score to drop quickly and deprioritize the model.
+
+### T-2: Safe Fractional Evaluation
+
+**Setup**: Record 1 success with a recency weight of `0.2`.
+
+**Execution**: Call `thompsonSampleScore()`.
+
+**Expected Behavior**: The function must evaluate without mathematical exceptions (division by zero, negative Gamma shapes) and return a valid score between `0.0` and `2.0`.
+
+---
+
+## Edge Cases & Risks
+
+| Risk | Mitigation |
+|------|------------|
+| System clock drift backward → weight > 1.0 | `MIN(1.0, MAX(0.0, ...))` double-bounds the weight |
+| Floating-point rounding → alpha/beta ≤ 0 | `Math.max(0.1, ...)` guard on Beta parameters |
+| Very low weighted totals → high prior influence | Acceptable — priors are designed for low-data scenarios |
+| Dashboard `successRate` display shows fractional totals | Update display to show weighted success rate or add a note |
\ No newline at end of file
diff --git a/.roo/specs/recency-biased-thompson-sampling/tasks.md b/.roo/specs/recency-biased-thompson-sampling/tasks.md
new file mode 100644
index 00000000..e1266128
--- /dev/null
+++ b/.roo/specs/recency-biased-thompson-sampling/tasks.md
@@ -0,0 +1,17 @@
+# Tasks: Recency-Biased Thompson Sampling (Time-Decay Aggregation)
+
+## Task Breakdown
+
+- [x] **T1: Add `ANALYTICS_WINDOW_DAYS` constant** — In [`router.ts`](server/src/services/router.ts:35), add `const ANALYTICS_WINDOW_DAYS = ANALYTICS_WINDOW_MS / (24 * 60 * 60 * 1000);` (yields `7.0`) to keep the SQL decay denominator coupled with the existing window constant.
+- [x] **T2: Extend `ModelStats` interface** — In [`router.ts`](server/src/services/router.ts:153), add `rawSuccesses: number` and `rawTotal: number` fields to the `ModelStats` interface alongside the existing `successes` and `total` fields (which will now hold weighted float values).
+- [x] **T3: Rewrite SQL query in `refreshStatsCache()`** — In [`router.ts`](server/src/services/router.ts:174), replace the flat aggregation query with the CTE-based weighted query. The CTE `weighted_requests` computes `MIN(1.0, MAX(0.0, 1.0 - (julianday('now') - julianday(created_at)) / ?))` as `recency_weight`. The outer SELECT aggregates `SUM(recency_weight)` as `total_weighted`, `SUM(CASE WHEN status = 'success' THEN recency_weight ELSE 0 END)` as `successes_weighted`, plus `raw_total` and `raw_successes` via `COUNT(*)` and `SUM(CASE ... 1 ELSE 0)`. Pass `ANALYTICS_WINDOW_DAYS` as the second SQL parameter for the decay divisor.
+- [x] **T4: Update `statsCache` population loop** — In [`router.ts`](server/src/services/router.ts:197), update the row-to-`ModelStats` mapping to store `successes: row.successes_weighted`, `total: row.total_weighted`, `rawSuccesses: row.raw_successes`, `rawTotal: row.raw_total`. Update the TypeScript row type annotation to match the new SQL columns.
+- [ ] **T5: Add `Math.max(0.1, ...)` guards in `thompsonSampleScore()`** — In [`router.ts`](server/src/services/router.ts:264), change `const alpha = (stats?.successes ?? 0) + PRIOR_SUCCESS` to `const alpha = Math.max(0.1, (stats?.successes ?? 0)) + PRIOR_SUCCESS` and similarly for `beta` with `(stats?.total ?? 0) - (stats?.successes ?? 0)`.
+- [ ] **T6: Add `Math.max(0.1, ...)` guards in `smartSampleScore()`** — In [`router.ts`](server/src/services/router.ts:293), apply the same `Math.max(0.1, ...)` guards to `alpha` and `beta` as in T5.
+- [ ] **T7: Add `Math.max(0.1, ...)` guards in `getAnalyticsScore()`** — In [`router.ts`](server/src/services/router.ts:212), update the `bayesRate` computation to use `Math.max(0.1, successes)` and `Math.max(0.1, total)` in the numerator and denominator.
+- [ ] **T8: Add `Math.max(0.1, ...)` guards in `getSmartAnalyticsScore()`** — In [`router.ts`](server/src/services/router.ts:241), apply the same `Math.max(0.1, ...)` guards to the `bayesRate` computation as in T7.
+- [ ] **T9: Update `getAnalyticsScores()` dashboard display** — In [`router.ts`](server/src/services/router.ts:314), change `total: stats.total` to `total: stats.rawTotal` so the dashboard shows actual request counts. Keep `successRate` as `stats.successes / stats.total` (weighted rate). Update the return type annotation if needed.
+- [ ] **T10: Write test — Outage sensitivity (T-1)** — In [`router.test.ts`](server/src/__tests__/services/router.test.ts), add a test that seeds 1,000 successful requests over days 1–5 and 15 recent failures, then calls `refreshStatsCache()` and verifies the weighted success rate is significantly lower than the flat rate (~98.5%).
+- [ ] **T11: Write test — Safe fractional evaluation (T-2)** — In [`router.test.ts`](server/src/__tests__/services/router.test.ts), add a test that inserts 1 success with a recency weight of ~0.2 (by setting `created_at` to ~5.6 days ago), calls `thompsonSampleScore()`, and verifies it returns a valid score without exceptions.
+- [ ] **T12: Write test — Clock drift safety** — Add a test that inserts a request with `created_at` set to a future timestamp (simulating clock drift), calls `refreshStatsCache()`, and verifies the weight is bounded to `1.0` (no weight > 1.0).
+- [ ] **T13: Run existing test suite** — Execute `pnpm test` to verify all existing router tests still pass after the changes. Fix any regressions.
\ No newline at end of file
diff --git a/.roo/specs/sse-stream-heartbeat-stall-protection/design.md b/.roo/specs/sse-stream-heartbeat-stall-protection/design.md
new file mode 100644
index 00000000..f4f4ad1c
--- /dev/null
+++ b/.roo/specs/sse-stream-heartbeat-stall-protection/design.md
@@ -0,0 +1,330 @@
+# Design: SSE Stream Heartbeats and Stall Protection
+
+## Architecture
+
+This feature adds a **heartbeat interval and stall detector** to the streaming execution path inside [`handleChatCompletion()`](server/src/routes/proxy.ts:1061). The modification is localized to the `if (stream)` block (lines 1279–1538) — no provider interface changes are needed.
+
+## Stream Lifecycle with Heartbeat & Stall Protection
+
+```mermaid
+flowchart TD
+    A[Stream request enters if block] --> B[Initialize lastChunkTimestamp = Date.now]
+    B --> C[Define cleanupStream function]
+    C --> D[Start heartbeat setInterval - 15s]
+    D --> E[Attach req.on close listener]
+    E --> F[Enter for-await loop over generator]
+    F --> G{Chunk yielded?}
+    G -- Yes --> H[Update lastChunkTimestamp = Date.now]
+    H --> I{streamAborted flag?}
+    I -- Yes --> J[Break out of loop]
+    I -- No --> K[Write chunk to res - normal path]
+    K --> F
+    G -- No - generator done --> L[cleanupStream]
+    L --> M[Write DONE frame + res.end]
+    G -- Error --> N[cleanupStream]
+    N --> O[Write error frame + res.end]
+
+    D --> P[Heartbeat callback fires every 15s]
+    P --> Q{Date.now - lastChunkTimestamp > 45s?}
+    Q -- Yes - STALL --> R[Log stall warning]
+    R --> S[Set streamAborted = true]
+    S --> T[cleanupStream]
+    T --> U[Write stream_timeout error frame]
+    U --> V[res.end + return]
+    Q -- No - OK --> W{streamStarted?}
+    W -- Yes --> X[Write SSE comment: keep-alive]
+    X --> Y{Write succeeded?}
+    Y -- Yes --> P
+    Y -- No - EPIPE/ECONNRESET --> Z[cleanupStream]
+    Z --> AA[Socket gone - interval cleared]
+    W -- No --> P
+
+    E --> BB[Client disconnects]
+    BB --> CC[cleanupStream]
+    CC --> DD[Interval cleared - no more heartbeats]
+```
+
+## Implementation Details
+
+### 1. New Constants
+
+Add alongside existing constants at the top of [`proxy.ts`](server/src/routes/proxy.ts:17), after `LONGCAT_STICKY_COOLDOWN_MS`:
+
+```typescript
+const KEEPALIVE_INTERVAL_MS = 15000; // Send a heartbeat comment every 15s of inactivity
+const MAX_STREAM_STALL_MS = 45000;   // Abort the stream if stalled for 45s
+```
+
+### 2. Stream State Variables
+
+Inside the `if (stream)` block (after line 1283, before the `try` block at line 1288), add:
+
+```typescript
+let lastChunkTimestamp = Date.now();
+let heartbeatInterval: ReturnType<typeof setInterval> | null = null;
+let streamAborted = false; // Set by stall handler to break the for-await loop
+```
+
+### 3. Cleanup Routine
+
+Define `cleanupStream()` immediately after the state variables. This function is idempotent — safe to call multiple times from different paths (stall handler, client disconnect, success, error):
+
+```typescript
+const cleanupStream = () => {
+  if (heartbeatInterval) {
+    clearInterval(heartbeatInterval);
+    heartbeatInterval = null;
+  }
+};
+```
+
+### 4. Heartbeat & Stall Monitor Interval
+
+Set up the `setInterval` immediately after `cleanupStream`, before the `try` block:
+
+```typescript
+heartbeatInterval = setInterval(() => {
+  const now = Date.now();
+
+  if (now - lastChunkTimestamp > MAX_STREAM_STALL_MS) {
+    // Stall detected — terminate the stream
+    console.warn(`[Proxy] Stream stalled for ${now - lastChunkTimestamp}ms — aborting socket`);
+    streamAborted = true;
+    cleanupStream();
+
+    const payload = { error: { message: 'Upstream stream stalled', type: 'stream_timeout' } };
+    try {
+      if (responseStreamContext) {
+        writeResponseStreamEvent(res, {
+          type: 'response.failed',
+          response: {
+            id: responseStreamContext.responseId,
+            status: 'failed',
+            error: payload.error,
+          },
+        });
+      } else {
+        res.write(`data: ${JSON.stringify(payload)}\n\n`);
+        res.write('data: [DONE]\n\n');
+      }
+      res.end();
+    } catch { /* Socket already gone */ }
+  } else if (streamStarted) {
+    // Write an SSE comment to keep the socket alive across intermediate proxies
+    // Only write after SSE headers have been sent (streamStarted === true)
+    try {
+      res.write(': keep-alive\n\n');
+    } catch {
+      // Client disconnected — clean up
+      cleanupStream();
+    }
+  }
+}, KEEPALIVE_INTERVAL_MS);
+```
+
+**Key design decisions in the heartbeat callback:**
+
+- **Stall check runs regardless of `streamStarted`**: Even before SSE headers are sent, if the upstream takes >45s to yield the first chunk, the stall detector terminates the connection. In this case, no error frame is written to `res` (headers haven't been sent yet), so the stall handler falls through to the outer retry logic via the `streamAborted` flag.
+- **SSE comment only written when `streamStarted === true`**: Writing to `res` before SSE headers would produce malformed HTTP output. The heartbeat skips the write if headers haven't been sent yet.
+- **`streamAborted` flag**: Setting this flag before `cleanupStream()` ensures the `for-await` loop will break on the next iteration, preventing further writes to an already-ended socket.
+
+### 5. Client-Disconnect Listener
+
+Attach immediately after the heartbeat interval setup:
+
+```typescript
+req.on('close', () => {
+  cleanupStream();
+});
+```
+
+This fires when the client closes the connection prematurely. The `cleanupStream()` call clears the interval, preventing wasted CPU cycles writing to a dead socket.
+
+### 6. For-Await Loop Modification
+
+Inside the `for await (const chunk of gen)` loop (line 1294), add two checks:
+
+```typescript
+for await (const chunk of gen) {
+  // Update chunk timestamp to reset stall timer
+  lastChunkTimestamp = Date.now();
+
+  // If stall handler already terminated the stream, break out
+  if (streamAborted) break;
+
+  if (!streamStarted) {
+    // ... existing header-setting logic ...
+    streamStarted = true;
+  }
+
+  // ... existing chunk-writing logic ...
+}
+```
+
+The `lastChunkTimestamp` update resets the stall timer on every chunk. The `streamAborted` check prevents writing to a socket that the stall handler has already closed.
+
+### 7. Post-Loop Cleanup
+
+After the `for await` loop completes successfully (before the existing success-path code), add:
+
+```typescript
+// Successful completion — clear heartbeat
+cleanupStream();
+
+// If stall handler already ended the response, skip the normal completion path
+if (streamAborted) {
+  logRequest(route.platform, route.modelId, 'error', estimatedInputTokens, totalOutputTokens, Date.now() - start, ttfbMs, 'stream_stalled');
+  return;
+}
+```
+
+This ensures:
+1. The heartbeat interval is always cleared on success
+2. If the stall handler already called `res.end()`, we don't try to write `[DONE]` again
+
+### 8. Error-Path Cleanup
+
+In the `catch (streamErr)` block (line 1392), add `cleanupStream()` at the top:
+
+```typescript
+} catch (streamErr: any) {
+  cleanupStream();
+  // ... existing error handling ...
+}
+```
+
+## Interaction with Existing Code Paths
+
+### Stall Before Headers Sent
+
+If the upstream stalls for >45s before yielding the first chunk (i.e., `streamStarted === false`):
+
+1. The stall handler sets `streamAborted = true` and calls `cleanupStream()`
+2. The stall handler cannot write an error SSE frame (headers not sent yet), so it calls `res.end()` — this sends a bare HTTP 200 with no body, which is not ideal
+3. The `for-await` loop sees `streamAborted` and breaks
+4. The post-loop code sees `streamAborted` and returns
+
+**Better approach**: Instead of calling `res.end()` in the stall handler when `streamStarted === false`, throw an error that falls through to the outer retry logic. This allows the proxy to attempt a fallback provider:
+
+```typescript
+if (now - lastChunkTimestamp > MAX_STREAM_STALL_MS) {
+  console.warn(`[Proxy] Stream stalled for ${now - lastChunkTimestamp}ms — aborting socket`);
+  streamAborted = true;
+  cleanupStream();
+
+  if (streamStarted) {
+    // Mid-stream stall — write error frame and end
+    const payload = { error: { message: 'Upstream stream stalled', type: 'stream_timeout' } };
+    try {
+      if (responseStreamContext) {
+        writeResponseStreamEvent(res, {
+          type: 'response.failed',
+          response: {
+            id: responseStreamContext.responseId,
+            status: 'failed',
+            error: payload.error,
+          },
+        });
+      } else {
+        res.write(`data: ${JSON.stringify(payload)}\n\n`);
+        res.write('data: [DONE]\n\n');
+      }
+      res.end();
+    } catch { /* Socket already gone */ }
+  }
+  // If !streamStarted, the for-await loop will break,
+  // and the post-loop check will return without calling res.end()
+  // The outer catch block will handle this as a retryable error
+}
+```
+
+Wait — this needs more thought. If `streamStarted === false` and the stall handler doesn't call `res.end()`, the `for-await` loop breaks, the post-loop code returns, and the outer `catch` block is NOT reached (no error was thrown). The request handler simply returns, leaving the response hanging.
+
+**Final approach**: When `streamStarted === false` on stall detection, throw a retryable error so the outer retry loop can attempt a fallback provider:
+
+```typescript
+if (now - lastChunkTimestamp > MAX_STREAM_STALL_MS) {
+  console.warn(`[Proxy] Stream stalled for ${now - lastChunkTimestamp}ms — aborting socket`);
+  streamAborted = true;
+  cleanupStream();
+
+  if (streamStarted) {
+    // Mid-stream stall — cannot retry, write error frame and end
+    const payload = { error: { message: 'Upstream stream stalled', type: 'stream_timeout' } };
+    try {
+      if (responseStreamContext) {
+        writeResponseStreamEvent(res, {
+          type: 'response.failed',
+          response: {
+            id: responseStreamContext.responseId,
+            status: 'failed',
+            error: payload.error,
+          },
+        });
+      } else {
+        res.write(`data: ${JSON.stringify(payload)}\n\n`);
+        res.write('data: [DONE]\n\n');
+      }
+      res.end();
+    } catch { /* Socket already gone */ }
+  } else {
+    // Pre-stream stall — no headers sent yet, response is still retryable
+    // Throw an error to fall through to the outer retry/502 handler
+    throw Object.assign(
+      new Error(`Upstream provider stalled before yielding any data from ${route.displayName}`),
+      { status: 504 },
+    );
+  }
+}
+```
+
+This is the best approach because:
+- **Pre-stream stall**: No headers sent → response is still mutable → throw to retry with another provider
+- **Mid-stream stall**: Headers already sent → cannot retry → write error frame and close
+
+### Mid-Stream Stall — No Retry
+
+Once `streamStarted === true` and SSE headers have been sent, the HTTP response status and headers are committed. The proxy cannot retry with another provider because the client is already consuming the SSE stream. The stall handler must:
+1. Write a structured error frame
+2. Write `[DONE]`
+3. Call `res.end()`
+4. Return from the handler
+
+### Interaction with Existing Mid-Stream Error Handling
+
+The existing `catch (streamErr)` block (lines 1392–1535) handles mid-stream errors with provider-specific logic (LongCat bans, truncation detection, etc.). The stall handler is a **separate path** that does NOT go through the `catch` block. This is intentional:
+
+- Stall detection is not a provider error — it's a timeout condition
+- The stall handler already writes the error frame and closes the socket
+- The `for-await` loop breaks via `streamAborted` flag, not via a thrown error
+- The post-loop code checks `streamAborted` and returns early, skipping the normal completion path
+
+### Interaction with Responses API Streams
+
+When `responseStreamContext` is defined (Responses API mode), the stall handler uses [`writeResponseStreamEvent()`](server/src/routes/proxy.ts:798) to emit a `response.failed` event instead of writing a raw `data:` SSE line. This matches the existing error-handling pattern in the `catch (streamErr)` block (lines 1518–1526).
+
+## Edge Cases
+
+| Edge Case | Behavior |
+|---|---|
+| Heartbeat fires before `streamStarted` | Stall check runs; SSE comment write is skipped; no malformed output |
+| Stall detected before `streamStarted` | Throw 504 error → outer retry loop attempts fallback provider |
+| Stall detected after `streamStarted` | Write `stream_timeout` error frame → `res.end()` → return |
+| Client disconnects during heartbeat write | `try/catch` on `res.write()` catches EPIPE → `cleanupStream()` |
+| Client disconnects between heartbeat intervals | `req.on('close')` fires → `cleanupStream()` |
+| `cleanupStream()` called multiple times | Idempotent — checks `heartbeatInterval !== null` before clearing |
+| Stall handler and chunk arrive simultaneously | `streamAborted` flag prevents double-write; `cleanupStream()` sets `heartbeatInterval = null` preventing double-fire |
+| Generator throws error after stall handler ran | `streamAborted` is true → `for-await` loop already broken → catch block not reached |
+| Very fast stream (chunks every <1s) | Heartbeat fires but `lastChunkTimestamp` is always fresh → stall check passes; SSE comment written but harmless |
+
+## Files Requiring Modification
+
+| # | File | Change | Lines Affected |
+|---|---|---|---|
+| 1 | [`server/src/routes/proxy.ts`](server/src/routes/proxy.ts:17) | Add `KEEPALIVE_INTERVAL_MS` and `MAX_STREAM_STALL_MS` constants | After line 18 |
+| 2 | [`server/src/routes/proxy.ts`](server/src/routes/proxy.ts:1283) | Add `lastChunkTimestamp`, `heartbeatInterval`, `streamAborted`, `cleanupStream()` | After line 1287, before `try` at 1288 |
+| 3 | [`server/src/routes/proxy.ts`](server/src/routes/proxy.ts:1288) | Add heartbeat `setInterval` + `req.on('close')` | Before `try` block |
+| 4 | [`server/src/routes/proxy.ts`](server/src/routes/proxy.ts:1294) | Add `lastChunkTimestamp` update + `streamAborted` check inside `for await` loop | Inside loop body |
+| 5 | [`server/src/routes/proxy.ts`](server/src/routes/proxy.ts:1318) | Add `cleanupStream()` + `streamAborted` check after loop | After `for await` loop |
+| 6 | [`server/src/routes/proxy.ts`](server/src/routes/proxy.ts:1392) | Add `cleanupStream()` at top of `catch (streamErr)` | Line 1392 |
+| 7 | [`server/src/__tests__/routes/proxy-tools.test.ts`](server/src/__tests__/routes/proxy-tools.test.ts) | Add unit tests for heartbeat, stall, and disconnect scenarios | New test section |
\ No newline at end of file
diff --git a/.roo/specs/sse-stream-heartbeat-stall-protection/requirements.md b/.roo/specs/sse-stream-heartbeat-stall-protection/requirements.md
new file mode 100644
index 00000000..5875de5f
--- /dev/null
+++ b/.roo/specs/sse-stream-heartbeat-stall-protection/requirements.md
@@ -0,0 +1,132 @@
+# Requirements: SSE Stream Heartbeats and Stall Protection
+
+## Overview
+
+Improve the stability of streaming connections (`stream: true`) handled by the proxy. During long generations, upstream providers may stall — either taking too long to return the first token or freezing mid-generation. This can cause intermediate reverse proxies (Nginx, Apache, Cloudflare) to terminate the connection due to idle timeouts. Additionally, completely hung upstream connections can leak socket descriptors and degrade server capacity. This specification introduces a background heartbeat (SSE comments) and an active stall-detection timeout.
+
+## Context
+
+The streaming execution path lives in [`handleChatCompletion()`](server/src/routes/proxy.ts:1061) inside the `if (stream)` block (lines 1279–1538). The current flow:
+
+1. Creates an `AsyncGenerator` via [`route.provider.streamChatCompletion()`](server/src/providers/base.ts:60)
+2. Iterates `for await (const chunk of gen)` — no timeout or keep-alive mechanism exists
+3. Writes SSE frames to `res` via `res.write()`
+4. On success, writes `[DONE]` and calls `res.end()`
+5. On error, writes an error frame and calls `res.end()`
+
+**The problem**: If the upstream provider stalls (no chunk yielded for an extended period), the proxy simply waits indefinitely. This causes:
+- Intermediate proxies (Nginx, Cloudflare) to kill the connection on idle timeouts (typically 30–60s)
+- Socket descriptor leaks if the upstream never closes the connection
+- Client-side timeouts with no structured error signal
+
+**The solution**: Add a periodic heartbeat interval that writes SSE comments during idle periods, and a stall-detection timeout that gracefully terminates the stream if no data arrives within a threshold.
+
+## Functional Requirements
+
+### FR-1: SSE Keep-Alive Heartbeats
+
+While a stream is active but waiting for the upstream provider to yield data, the proxy must periodically write empty SSE comments (e.g., `: keep-alive\n\n`) to the client response. These comments are ignored by standard SSE clients (such as `EventSource`) but keep the underlying TCP socket active, resetting intermediate proxy idle timeouts.
+
+- **Heartbeat interval**: 15 seconds (`KEEPALIVE_INTERVAL_MS = 15000`)
+- **Format**: SSE comment line `: keep-alive\n\n` — per the SSE spec, lines starting with `:` are comments and ignored by EventSource parsers
+- **Trigger condition**: The heartbeat fires on a `setInterval` timer regardless of whether data is flowing. When data IS flowing, the heartbeat write is harmless (SSE clients ignore comments). When data is NOT flowing, the heartbeat prevents idle-proxy disconnects.
+
+### FR-2: Stream Stall Detection
+
+The proxy must monitor the interval between incoming chunks from the upstream provider. If no chunk is yielded within a specified threshold, the connection must be deemed stalled.
+
+- **Stall threshold**: 45 seconds (`MAX_STREAM_STALL_MS = 45000`)
+- **Detection mechanism**: Track `lastChunkTimestamp = Date.now()`. On each chunk from the generator, reset the timestamp. The heartbeat interval callback checks `Date.now() - lastChunkTimestamp > MAX_STREAM_STALL_MS`.
+- **Stall behavior**: When a stall is detected:
+  1. Log a warning: `[Proxy] Stream stalled for <ms>ms — aborting socket`
+  2. Clear the heartbeat interval timer
+  3. Write a structured timeout error frame to the client:
+     - For Responses API streams: emit a `response.failed` event via [`writeResponseStreamEvent()`](server/src/routes/proxy.ts:798)
+     - For Chat Completion streams: write `data: {"error":{"message":"Upstream stream stalled","type":"stream_timeout"}}\n\n` followed by `data: [DONE]\n\n`
+  4. Call `res.end()` to close the socket
+  5. Return from the handler (no retry on stall — the stream is already partially delivered)
+
+### FR-3: Client-Disconnect Cleanup
+
+If the client terminates the connection prematurely (e.g., closing the browser tab or aborting the client-side fetch), the proxy must immediately clear all background timers and abort any pending upstream fetch requests.
+
+- **Detection**: Attach a `req.on('close', ...)` listener that calls the cleanup routine
+- **Cleanup routine**: A `cleanupStream()` function that:
+  1. Clears the heartbeat `setInterval` timer (sets `heartbeatInterval = null`)
+  2. This is the same cleanup function called on stall detection and on successful stream completion
+
+### FR-4: Heartbeat Write Failure Handling
+
+If a client abruptly closes the socket, writing `: keep-alive\n\n` may throw an EPIPE or ECONNRESET error. The heartbeat write must be wrapped in a `try/catch` block. On write failure:
+
+1. Call `cleanupStream()` to clear the interval timer
+2. Do NOT attempt to write an error frame (the socket is already gone)
+3. The `req.on('close')` listener will also fire, but `cleanupStream()` is idempotent (checks `heartbeatInterval !== null` before clearing)
+
+### FR-5: Successful Stream Completion Cleanup
+
+When the `for await` loop completes successfully, the heartbeat interval must be cleared via `cleanupStream()` before writing the final `[DONE]` frame and calling `res.end()`. This prevents the heartbeat from firing after the response is finished.
+
+### FR-6: Stream Error Cleanup
+
+When a `catch (streamErr)` is triggered, `cleanupStream()` must be called before any error-frame writing. This prevents the heartbeat from interfering with the error response.
+
+### FR-7: Constants Configuration
+
+Both `KEEPALIVE_INTERVAL_MS` and `MAX_STREAM_STALL_MS` must be defined as named constants at the top of [`proxy.ts`](server/src/routes/proxy.ts:1), alongside existing constants like `STICKY_TTL_MS`. This makes the values easy to locate and adjust.
+
+### FR-8: Pre-Stream Heartbeat Behavior
+
+The heartbeat interval must be set up **before** entering the `for await` loop. This means heartbeats will fire during the initial TTFB wait period (before `streamStarted = true`), which is exactly when they are most needed — the client connection is idle while waiting for the first chunk.
+
+However, the SSE comment `: keep-alive\n\n` must only be written **after** the SSE headers have been sent (i.e., after `streamStarted = true`). If the heartbeat fires before headers are sent, it should skip the write but still check for stall detection. Writing to `res` before headers would cause malformed HTTP output.
+
+**Alternative approach**: Start the heartbeat interval only after `streamStarted = true` is set. This avoids the pre-header issue but means no keep-alive during the very first TTFB wait. Given that the stall detector still runs (it checks `lastChunkTimestamp`), the risk is minimal — if TTFB exceeds 45s, the stall detector will terminate the connection.
+
+**Chosen approach**: Start the heartbeat interval immediately (before the `for await` loop). In the heartbeat callback, only write the SSE comment if `streamStarted === true`. The stall check runs regardless of `streamStarted` state. This provides stall protection from the start and keep-alive protection once headers are sent.
+
+## Non-Functional Requirements
+
+### NFR-1: No Database Schema Changes
+
+This feature is purely runtime (timers and in-request state). No database schema changes are required.
+
+### NFR-2: No New Persistent State
+
+No new Map, Set, or other persistent data structure is needed. All state (`lastChunkTimestamp`, `heartbeatInterval`) is local to the request handler scope.
+
+### NFR-3: No Provider Interface Changes
+
+The [`streamChatCompletion()`](server/src/providers/base.ts:60) `AsyncGenerator` interface is unchanged. The heartbeat and stall detection are implemented entirely in the proxy routing layer.
+
+### NFR-4: Idempotent Cleanup
+
+The `cleanupStream()` function must be safe to call multiple times. It checks whether `heartbeatInterval` is non-null before clearing, preventing double-clear errors.
+
+### NFR-5: No UI Changes
+
+This is a backend-only feature. No client-side changes are needed.
+
+### NFR-6: Backward Compatibility
+
+Existing SSE clients that ignore comment lines (per the SSE specification) will not be affected. Clients that do not implement SSE comment filtering will see the `: keep-alive` lines as unknown events with no data, which is harmless.
+
+### NFR-7: Race Condition Safety
+
+If the stall monitor triggers at the exact moment the generator yields a chunk, a race condition could occur where both the stall handler and the normal chunk processing try to write to `res`. The cleanup routine must set `heartbeatInterval = null` immediately, ensuring the stall callback cannot execute twice. Additionally, the `for await` loop must check whether the stream has already been terminated by the stall handler before writing chunks.
+
+## Files Requiring Modification
+
+| # | File | Change Type | Description |
+|---|---|---|---|
+| 1 | [`server/src/routes/proxy.ts`](server/src/routes/proxy.ts:1) | Edit | Add `KEEPALIVE_INTERVAL_MS` and `MAX_STREAM_STALL_MS` constants |
+| 2 | [`server/src/routes/proxy.ts`](server/src/routes/proxy.ts:1279) | Edit | Add heartbeat interval, stall detection, client-disconnect listener, and cleanup logic inside the streaming block of `handleChatCompletion()` |
+| 3 | [`server/src/__tests__/routes/proxy-tools.test.ts`](server/src/__tests__/routes/proxy-tools.test.ts) | Edit | Add unit tests for heartbeat emission, stall detection, and client-disconnect cleanup |
+
+## Out of Scope
+
+- Making heartbeat interval or stall threshold configurable via admin API or environment variable (constants only for now)
+- Upstream fetch request abortion on stall (the `AsyncGenerator` will be garbage-collected when the handler returns)
+- Heartbeat support for non-streaming (non-SSE) responses
+- Changes to provider implementations
+- Retry logic for stalled streams (the stream is already partially delivered to the client)
\ No newline at end of file
diff --git a/.roo/specs/sse-stream-heartbeat-stall-protection/tasks.md b/.roo/specs/sse-stream-heartbeat-stall-protection/tasks.md
new file mode 100644
index 00000000..c6e03235
--- /dev/null
+++ b/.roo/specs/sse-stream-heartbeat-stall-protection/tasks.md
@@ -0,0 +1,20 @@
+# Tasks: SSE Stream Heartbeats and Stall Protection
+
+## Task List
+
+- [ ] Add `KEEPALIVE_INTERVAL_MS = 15000` and `MAX_STREAM_STALL_MS = 45000` constants after `LONGCAT_STICKY_COOLDOWN_MS` in [`server/src/routes/proxy.ts`](server/src/routes/proxy.ts:18)
+- [ ] Add `lastChunkTimestamp`, `heartbeatInterval`, and `streamAborted` state variables inside the `if (stream)` block, before the `try` at line 1288 in [`server/src/routes/proxy.ts`](server/src/routes/proxy.ts:1283)
+- [ ] Define `cleanupStream()` function that clears `heartbeatInterval` and sets it to `null` — idempotent, safe to call multiple times
+- [ ] Set up heartbeat `setInterval` with stall detection logic: check `Date.now() - lastChunkTimestamp > MAX_STREAM_STALL_MS` for stall, write `: keep-alive\n\n` SSE comment when `streamStarted === true` and not stalled
+- [ ] Implement pre-stream stall path: when `streamStarted === false` on stall detection, throw `Object.assign(new Error(...), { status: 504 })` to fall through to outer retry loop
+- [ ] Implement mid-stream stall path: when `streamStarted === true` on stall detection, write `stream_timeout` error frame (Responses API: `response.failed` event via `writeResponseStreamEvent`; Chat Completion: `data: {"error":...}\n\n` + `data: [DONE]\n\n`), then `res.end()`
+- [ ] Attach `req.on('close', ...)` listener that calls `cleanupStream()` for client-disconnect cleanup
+- [ ] Add `lastChunkTimestamp = Date.now()` update and `if (streamAborted) break` check inside the `for await (const chunk of gen)` loop body in [`server/src/routes/proxy.ts`](server/src/routes/proxy.ts:1294)
+- [ ] Add `cleanupStream()` call and `if (streamAborted) { logRequest(...); return; }` check after the `for await` loop completes, before the existing success-path code
+- [ ] Add `cleanupStream()` call at the top of the `catch (streamErr)` block in [`server/src/routes/proxy.ts`](server/src/routes/proxy.ts:1392)
+- [ ] Add unit test: heartbeat SSE comments are emitted during idle periods (mock provider with delayed TTFB > 15s, verify `: keep-alive\n\n` appears in response)
+- [ ] Add unit test: stall detection terminates stream after 45s of silence (mock provider that yields chunks then stalls indefinitely, verify `stream_timeout` error frame and `res.end()`)
+- [ ] Add unit test: pre-stream stall throws 504 for retry (mock provider with TTFB > 45s, verify fallback to another provider)
+- [ ] Add unit test: client-disconnect clears heartbeat interval (abort client fetch mid-stream, verify no leaked timers)
+- [ ] Add unit test: heartbeat write failure triggers cleanup (mock `res.write` to throw EPIPE, verify `cleanupStream()` is called)
+- [ ] Run existing test suite to verify no regressions: `pnpm --filter server test`
\ No newline at end of file
diff --git a/.roo/specs/transient-model-cooldown/design.md b/.roo/specs/transient-model-cooldown/design.md
new file mode 100644
index 00000000..5123ccb0
--- /dev/null
+++ b/.roo/specs/transient-model-cooldown/design.md
@@ -0,0 +1,197 @@
+# Design: Shared Temporary Cooldowns for Concurrent Failure Mitigation
+
+## Architecture Overview
+
+This feature introduces a module-level in-memory circuit breaker that shares transient failure state across all concurrent requests. The design follows the existing pattern established by [`stickySessionMap`](server/src/routes/proxy.ts:16) and other module-level Maps in [`proxy.ts`](server/src/routes/proxy.ts).
+
+```mermaid
+flowchart TD
+    A[Incoming Request] --> B[Initialize skipModels Set]
+    B --> C[Prune expired entries from transientModelCooldowns]
+    C --> D[Inject active cooldowns into skipModels]
+    D --> E{Is preferredModel on global cooldown?}
+    E -- Yes --> F[Clear preferredModel and preferredKeyId]
+    E -- No --> G[Keep preferredModel intact]
+    F --> H[Enter retry loop with routeRequest]
+    G --> H
+    H --> I[Attempt model via provider]
+    I -- Success --> J[Return response, record success]
+    I -- 5xx or connection error --> K[Register model in transientModelCooldowns]
+    K --> L[Add model to local skipModels]
+    L --> M[Continue retry loop]
+    I -- Non-5xx retryable error --> M
+    I -- Non-retryable error --> N[Return 502 to client]
+```
+
+## Data Structure
+
+### `transientModelCooldowns` Map
+
+Declared at module level in [`proxy.ts`](server/src/routes/proxy.ts) alongside existing shared maps:
+
+```typescript
+// Location: Near line 16-23 with other module-level maps
+const transientModelCooldowns = new Map<number, number>(); // modelDbId -> expiryTimestamp
+const TRANSIENT_COOLDOWN_MS = 15000; // 15 seconds
+```
+
+**Design rationale**:
+- Uses `modelDbId` (numeric DB primary key) as the key, consistent with how [`skipModels`](server/src/routes/proxy.ts:1179) and [`routeRequest()`](server/src/routes/proxy.ts:1248) already identify models
+- Stores `expiryTimestamp` (absolute `Date.now() + TRANSIENT_COOLDOWN_MS`) rather than a relative duration, enabling simple `Date.now() > expiry` comparison for pruning
+- Module-level `Map` is safe in Node.js single-threaded event loop — no mutex needed
+- No unbounded growth risk: expired entries are pruned on every request's pre-routing check
+
+## Integration Points
+
+### 1. Pre-Routing Cooldown Injection
+
+**Location**: Inside [`handleChatCompletion()`](server/src/routes/proxy.ts:1061), after the existing `skipModels` initialization at [line 1179](server/src/routes/proxy.ts:1179) and before the retry loop at [line 1245](server/src/routes/proxy.ts:1245).
+
+The current code initializes `skipModels` with session-banned platform models. The transient cooldown injection merges into this same set:
+
+```typescript
+// Existing: const skipModels = new Set<number>(); (line 1179)
+// ... existing session ban logic fills skipModels ...
+
+// NEW: Inject global transient cooldowns
+const now = Date.now();
+for (const [modelDbId, expiry] of transientModelCooldowns) {
+  if (now > expiry) {
+    transientModelCooldowns.delete(modelDbId);
+  } else {
+    skipModels.add(modelDbId);
+    console.log(`[Proxy] Global cooldown active — skipping modelDbId=${modelDbId}`);
+  }
+}
+```
+
+**Pruning strategy**: Lazy pruning on every request is efficient because:
+- The Map is small (typically 0-3 entries during normal operation)
+- Iteration + deletion of expired entries is O(n) where n is the number of cooled-down models, not total models
+- No background timer or cleanup interval needed
+
+### 2. Sticky Session Override
+
+**Location**: After cooldown injection, before the existing [`preferredModel`](server/src/routes/proxy.ts:1195) platform-ban check.
+
+If `preferredModel` is set (sticky session or explicit model request) and that model is on global cooldown, clear it:
+
+```typescript
+// NEW: Global cooldown overrides sticky preference
+if (preferredModel !== undefined && transientModelCooldowns.has(preferredModel)) {
+  const expiry = transientModelCooldowns.get(preferredModel)!;
+  if (Date.now() <= expiry) {
+    console.log(`[Proxy] Global cooldown overrides sticky — clearing preferredModel=${preferredModel}`);
+    preferredModel = undefined;
+    preferredKeyId = undefined;
+  }
+}
+```
+
+**Note**: This check uses `transientModelCooldowns.has()` directly rather than checking `skipModels`, because `skipModels` may contain models added for other reasons (session bans). We only want to override sticky when the specific preferred model has a transient cooldown.
+
+**Explicit model requests**: When `requestedModel` is set (user explicitly specified a model), `preferredModel` is populated from DB lookup at [line 1142-1160](server/src/routes/proxy.ts:1142). If that model is on global cooldown, we should still clear `preferredModel` — the user's explicit request cannot be fulfilled while the model is degraded, and falling back is better than hanging.
+
+### 3. Cooldown Registration on Failure
+
+**Location**: Inside the retry loop's `catch` block at [line 1570](server/src/routes/proxy.ts:1570), within the existing `5xx` detection logic at [line 1578-1608](server/src/routes/proxy.ts:1578).
+
+The cooldown registration targets only `5xx` errors and connection failures (status undefined/timeout). It does NOT trigger for:
+- `429` rate limit errors (these are key-specific, not model-wide)
+- `401/403` auth errors (these are key-specific)
+- `400/404/422` client errors (these may be request-specific, not provider-wide)
+
+```typescript
+// Inside the catch block, after existing 5xx detection (line 1578-1608)
+const errStatus = getErrorStatus(err);
+
+// Register global cooldown for 5xx or connection failures
+if ((errStatus !== undefined && errStatus >= 500 && errStatus < 600) || errStatus === undefined) {
+  if (isRetryableError(err)) {
+    console.warn(`[Proxy] Transient failure on modelDbId=${route.modelDbId} — activating ${TRANSIENT_COOLDOWN_MS / 1000}s global cooldown`);
+    transientModelCooldowns.set(route.modelDbId, Date.now() + TRANSIENT_COOLDOWN_MS);
+    // Also add to local skipModels for this request's retry loop
+    skipModels.add(route.modelDbId);
+  }
+}
+```
+
+**Interaction with existing model-skip logic**: The existing code at [lines 1579-1608](server/src/routes/proxy.ts:1579) already adds failing models to `skipModels` for the current request. The global cooldown registration is additive — it sets the shared map entry AND adds to local `skipModels`. This means:
+- The current request continues to skip the model in subsequent retries (existing behavior preserved)
+- Future requests also skip the model for the next 15 seconds (new behavior)
+
+### 4. Mid-Stream Error Handling
+
+**Location**: Inside the streaming error handler at [line 1392](server/src/routes/proxy.ts:1392), within the `5xx` detection at [line 1398](server/src/routes/proxy.ts:1398).
+
+Mid-stream `5xx` errors should also register global cooldowns, since they indicate the same transient provider degradation:
+
+```typescript
+// Inside the streamStarted error block, after existing 5xx detection (line 1398-1427)
+if (streamErrStatus && isBanEligibleStatus(streamErrStatus)) {
+  // ... existing skipModels.add(route.modelDbId) logic ...
+  
+  // NEW: Register global cooldown for mid-stream 5xx
+  console.warn(`[Proxy] Mid-stream 5xx from ${route.platform} — activating global cooldown for modelDbId=${route.modelDbId}`);
+  transientModelCooldowns.set(route.modelDbId, Date.now() + TRANSIENT_COOLDOWN_MS);
+}
+```
+
+## Error Classification Matrix
+
+| Error Type | Status | Local skipModels | Global Cooldown | Sticky Override |
+|---|---|---|---|---|
+| 5xx server error | 500/502/503/504 | ✅ Yes | ✅ Yes | ✅ Yes |
+| Connection failure | undefined/timeout | ✅ Yes | ✅ Yes | ✅ Yes |
+| Rate limit | 429 | ✅ Key-only | ❌ No | ❌ No |
+| Auth error | 401/403 | ✅ Key-only | ❌ No | ❌ No |
+| Client error | 400/404/422 | ✅ Model-only | ❌ No | ❌ No |
+| Truncated response | N/A | ✅ Model-only | ❌ No | ❌ No |
+
+**Rationale for excluding rate limits**: A `429` on one key doesn't mean all keys for that model are rate-limited. The existing per-key cooldown via [`setCooldown()`](server/src/routes/proxy.ts:7) handles this correctly.
+
+**Rationale for excluding auth errors**: A `401/403` on one key doesn't mean the model itself is degraded. The existing sticky-key clearing logic handles this.
+
+## Test Strategy
+
+### Unit Tests
+
+A new test file `server/src/__tests__/routes/transient-cooldown.test.ts` should cover:
+
+1. **Cooldown injection**: Verify that active cooldowns are added to `skipModels` and expired entries are pruned
+2. **Cooldown registration**: Verify that `5xx` errors register a cooldown but `429`/`401`/`400` errors do not
+3. **Sticky override**: Verify that `preferredModel` is cleared when on global cooldown
+4. **Auto-recovery**: Verify that expired cooldowns are removed during pruning and models become routable again
+
+### Integration Test Scenario
+
+The concurrent outage isolation scenario described in the spec (T-1) requires:
+- Two sequential requests where the first triggers a `503` on Model X
+- The second request arrives within the 15-second window and should skip Model X
+
+This can be tested by:
+1. Directly setting `transientModelCooldowns.set(modelDbId, Date.now() + 15000)` 
+2. Calling the pre-routing logic and verifying `skipModels` contains the modelDbId
+3. Waiting 16 seconds and verifying the entry is pruned
+
+## Export for Testing
+
+The `transientModelCooldowns` Map and `TRANSIENT_COOLDOWN_MS` constant must be exported for test access, following the existing pattern at [line 170-182](server/src/routes/proxy.ts:170):
+
+```typescript
+export {
+  // ... existing exports ...
+  transientModelCooldowns,
+  TRANSIENT_COOLDOWN_MS,
+};
+```
+
+## Risks and Mitigations
+
+| Risk | Mitigation |
+|---|---|
+| All models on cooldown simultaneously | `routeRequest()` already throws "All models exhausted" → HTTP 503/429 to client. No special handling needed. |
+| Sticky session pinned to cooled-down model | Global cooldown overrides `preferredModel` — session falls back to free routing immediately. |
+| Map memory growth | Lazy pruning on every request keeps the Map small. Worst case: N entries where N = number of models, each a `number→number` pair (~16 bytes). |
+| Cooldown too aggressive for brief blips | 15-second window is short enough that a single failed request only blocks the model briefly. If the model recovers, the next request after expiry will route to it normally. |
+| Cooldown not aggressive enough for sustained outages | The Thompson Sampling router's success-recording mechanism (`recordSuccess`) will naturally deprioritize models that fail repeatedly. The 15-second cooldown is a complement, not a replacement. |
\ No newline at end of file
diff --git a/.roo/specs/transient-model-cooldown/requirements.md b/.roo/specs/transient-model-cooldown/requirements.md
new file mode 100644
index 00000000..8494af60
--- /dev/null
+++ b/.roo/specs/transient-model-cooldown/requirements.md
@@ -0,0 +1,38 @@
+# Requirements: Shared Temporary Cooldowns for Concurrent Failure Mitigation
+
+## Problem Statement
+
+When a model fails with a transient error (HTTP `5xx` or connection timeout), the proxy currently only adds it to the local `skipModels` set for the active request's retry loop. Multiple concurrent requests arriving during an outage each independently attempt to route through the failing model before falling back. This creates unnecessary upstream traffic and degrades proxy performance during transient provider outages.
+
+## Requirements
+
+### R-1: Cross-Request Transient Failure State
+The proxy must maintain a lightweight, shared, in-memory collection of temporarily disabled model IDs that have recently returned severe, non-auth, retryable errors (specifically HTTP `5xx` or connection timeouts). This state must be visible to all incoming requests, not just the request that encountered the failure.
+
+### R-2: Short-Lived Global Cooldown Window
+A globally cooled-down model must be skipped by all incoming requests for a brief duration (15 seconds). This window is intentionally short to allow rapid recovery if the upstream issue is transient, without waiting for the 60-second analytics stats cache refresh.
+
+### R-3: Integration with Existing Routing Logic
+The shared cooldown state must seamlessly feed into the `skipModels` set passed to `routeRequest()`, ensuring the Thompson Sampling router naturally bypasses degraded models without changing the core routing algorithm.
+
+### R-4: Sticky Session Precedence
+If a session is pinned to a model via sticky session but that model is currently on global cooldown, the global cooldown must take precedence. The `preferredModel` must be cleared so the session falls back immediately, preventing hang-ups on a degraded model.
+
+### R-5: Auto-Recovery via Expiry
+Cooldown entries must auto-expire after the configured window. Expired entries must be pruned during pre-routing checks so models become available again without manual intervention.
+
+### R-6: All-Models-Exhausted Safety
+In extreme scenarios where all configured models are on global cooldown, the existing `routeRequest()` behavior of throwing an "All models exhausted" error is acceptable. This falls back to the client as HTTP `503` or `429` — no special handling needed beyond what already exists.
+
+## Scope
+
+- **In scope**: Module-level `Map` in `proxy.ts`, pre-routing injection into `skipModels`, cooldown registration on `5xx`/connection failures, sticky session override when preferred model is on cooldown, expiry pruning
+- **Out of scope**: Persistent cooldown storage (DB/Redis), per-provider cooldown differentiation, cooldown duration configuration via API, analytics/metrics integration
+
+## Acceptance Criteria
+
+1. When Request A encounters a `5xx` from Model X and activates the global cooldown, a subsequent Request B arriving within 15 seconds skips Model X entirely and routes directly to an alternative model
+2. After 15 seconds, the cooldown expires and Model X is eligible for routing again without manual intervention
+3. If a sticky session is pinned to a model on global cooldown, the `preferredModel` is cleared and the session falls back to free routing
+4. The `routeRequest()` function receives the merged `skipModels` set (local + global cooldowns) without any changes to its signature or algorithm
+5. Non-`5xx` errors (auth errors, rate limits, client errors) do not trigger global cooldowns
\ No newline at end of file
diff --git a/.roo/specs/transient-model-cooldown/tasks.md b/.roo/specs/transient-model-cooldown/tasks.md
new file mode 100644
index 00000000..7c9cc9d6
--- /dev/null
+++ b/.roo/specs/transient-model-cooldown/tasks.md
@@ -0,0 +1,16 @@
+# Tasks: Shared Temporary Cooldowns for Concurrent Failure Mitigation
+
+## Implementation Tasks
+
+- [ ] **T-1**: Declare `transientModelCooldowns` Map and `TRANSIENT_COOLDOWN_MS` constant at module level in [`proxy.ts`](server/src/routes/proxy.ts:16) near the existing `stickySessionMap` declaration
+- [ ] **T-2**: Export `transientModelCooldowns` and `TRANSIENT_COOLDOWN_MS` from [`proxy.ts`](server/src/routes/proxy.ts:170) in the existing export block for test access
+- [ ] **T-3**: Add pre-routing cooldown injection logic inside [`handleChatCompletion()`](server/src/routes/proxy.ts:1061) — after `skipModels` initialization at [line 1179](server/src/routes/proxy.ts:1179) and before the retry loop at [line 1245](server/src/routes/proxy.ts:1245). Iterate `transientModelCooldowns`, prune expired entries, and add active cooldowns to `skipModels`
+- [ ] **T-4**: Add sticky session override logic — after cooldown injection, check if `preferredModel` is on global cooldown and clear `preferredModel`/`preferredKeyId` if so. Place this after the existing session-ban platform check at [line 1195](server/src/routes/proxy.ts:1195)
+- [ ] **T-5**: Register global cooldown in the retry loop catch block at [line 1570](server/src/routes/proxy.ts:1570) — when `errStatus` is `5xx` or `undefined` (connection failure) and `isRetryableError(err)` is true, set `transientModelCooldowns.set(route.modelDbId, Date.now() + TRANSIENT_COOLDOWN_MS)` and add to local `skipModels`
+- [ ] **T-6**: Register global cooldown for mid-stream `5xx` errors in the streaming error handler at [line 1392](server/src/routes/proxy.ts:1392) — when `streamErrStatus` is ban-eligible, set `transientModelCooldowns.set(route.modelDbId, Date.now() + TRANSIENT_COOLDOWN_MS)` alongside the existing `skipModels.add()`
+- [ ] **T-7**: Create test file `server/src/__tests__/routes/transient-cooldown.test.ts` with unit tests for:
+  - Cooldown injection and expired entry pruning
+  - Cooldown registration on `5xx` errors (and exclusion for `429`/`401`/`400`)
+  - Sticky session override when preferred model is on global cooldown
+  - Auto-recovery after cooldown expiry
+- [ ] **T-8**: Run existing test suite to verify no regressions in [`proxy-tools.test.ts`](server/src/__tests__/routes/proxy-tools.test.ts), [`provider-session-ban.test.ts`](server/src/__tests__/routes/provider-session-ban.test.ts), and [`router.test.ts`](server/src/__tests__/services/router.test.ts)
\ No newline at end of file
diff --git a/do_fix.py b/do_fix.py
new file mode 100644
index 00000000..b82b5d74
--- /dev/null
+++ b/do_fix.py
@@ -0,0 +1,7 @@
+#!/usr/bin/env python3
+"""Replace the streaming block in proxy.ts with Promise.race-based stall detection."""
+
+with open('server/src/routes/proxy.ts', 'r') as f:
+    content = f.read()
+
+{
\ No newline at end of file
diff --git a/fix.py b/fix.py
new file mode 100644
index 00000000..d138f2b2
--- /dev/null
+++ b/fix.py
@@ -0,0 +1,8 @@
+#!/usr/bin/env python3
+"""Replace the streaming block in proxy.ts with Promise.race-based stall detection."""
+
+with open('server/src/routes/proxy.ts', 'r') as f:
+    lines = f.readlines()
+
+# Find the streaming block boundaries
+# Start: line with "for await (const chunk{
\ No newline at end of file
diff --git a/fix_streaming.py b/fix_streaming.py
index bb32817c..329560d3 100644
--- a/fix_streaming.py
+++ b/fix_streaming.py
@@ -1,15 +1,21 @@
 #!/usr/bin/env python3
-"""Replace the streaming block in proxy.ts with the redesigned approach."""
+"""Replace the streaming block in proxy.ts with Promise.race-based stall detection."""
 
-with open('server/src/routes/proxy.ts', 'r') as f:
-    content = f.read()
+# Read the before and after parts
+with open('/tmp/before.ts', 'r') as f:
+    before = f.read()
 
-# Find the streaming block boundaries
-# Start: line with "      if (stream) {"
-# End: line with "      } else {" (the non-streaming path)
+with open('/tmp/after.ts', 'r') as f:
+    after = f.read()  # starts with "} else {"
 
-lines = content.split('\n')
-
-# Find the if(stream) line
-stream_start = None
-for i, line in{
\ No newline at end of file
+# The new streaming block
+new_streaming = r'''      if (stream) {
+        // SSE headers set immediately so keep-alive works during TTFB.
+        // Pre-stream errors stay retryable; mid-stream errors emit an SSE error frame.
+        let totalOutputTokens = 0;
+        let streamedText = '';
+        let sawToolCalls = false;
+        let streamStarted = false;
+        let ttfbMs: number | null = null;
+        let lastChunkTimestamp = Date.now();
+        let heartbeatInterval: ReturnType<typeof setInterval>{
\ No newline at end of file
diff --git a/fix{ b/fix{
new file mode 100644
index 00000000..e69de29b
diff --git a/new_streaming_block.txt b/new_streaming_block.txt
new file mode 100644
index 00000000..9b1fc853
--- /dev/null
+++ b/new_streaming_block.txt
@@ -0,0 +1,28 @@
+      if (stream) {
+        // SSE headers set immediately so keep-alive works during TTFB.
+        // Pre-stream errors stay retryable; mid-stream errors emit an SSE error frame.
+        let totalOutputTokens = 0;
+        let streamedText = '';
+        let sawToolCalls = false;
+        let streamStarted = false;
+        let ttfbMs: number | null = null;
+        let lastChunkTimestamp = Date.now();
+        let heartbeatInterval: ReturnType<typeof setInterval> | null = null;
+        let streamAborted = false;
+
+        // Clean up routine — idempotent, safe to call multiple times
+        const cleanupStream = () => {
+          if (heartbeatInterval) {
+            clearInterval(heartbeatInterval);
+            heartbeatInterval = null;
+          }
+        };
+
+        // Helper: create a stall timeout promise that rejects after MAX_STREAM_STALL_MS
+        const stallTimeout = () => new Promise<never>((_, reject) => {
+          const timer = setTimeout(() => {
+            reject(Object.assign(
+              new Error('Upstream stream stalled'),
+              { status: 504, type: 'stream_timeout' }
+            ));
+{
\ No newline at end of file
diff --git a/server/src/__tests__/routes/provider-session-ban.test.ts b/server/src/__tests__/routes/provider-session-ban.test.ts
index 97341afb..fce18868 100644
--- a/server/src/__tests__/routes/provider-session-ban.test.ts
+++ b/server/src/__tests__/routes/provider-session-ban.test.ts
@@ -48,47 +48,47 @@ describe('Provider session ban functionality', () => {
   describe('isSessionBannedFromPlatform', () => {
     it('returns false when no sticky session exists', () => {
       const messages = makeMessages('Hello');
-      expect(isSessionBannedFromPlatform(messages, 'balanced', 'longcat')).toBe(false);
+      expect(isSessionBannedFromPlatform(messages, 'smart', 'longcat')).toBe(false);
     });
 
     it('returns false when sticky session exists but no bannedPlatforms', () => {
       const messages = makeMessages('Hello');
-      const key = getSessionKey(messages, 'balanced');
+      const key = getSessionKey(messages, 'smart');
       (stickySessionMap as Map<any, any>).set(key, { modelDbId: 1, lastUsed: Date.now() });
-      expect(isSessionBannedFromPlatform(messages, 'balanced', 'longcat')).toBe(false);
+      expect(isSessionBannedFromPlatform(messages, 'smart', 'longcat')).toBe(false);
     });
 
     it('returns true when the platform is in bannedPlatforms', () => {
       const messages = makeMessages('Hello');
-      const key = getSessionKey(messages, 'balanced');
+      const key = getSessionKey(messages, 'smart');
       (stickySessionMap as Map<any, any>).set(key, {
         modelDbId: 1,
         lastUsed: Date.now(),
         bannedPlatforms: new Set(['longcat']),
       });
-      expect(isSessionBannedFromPlatform(messages, 'balanced', 'longcat')).toBe(true);
+      expect(isSessionBannedFromPlatform(messages, 'smart', 'longcat')).toBe(true);
     });
 
     it('returns false when a different platform is banned', () => {
       const messages = makeMessages('Hello');
-      const key = getSessionKey(messages, 'balanced');
+      const key = getSessionKey(messages, 'smart');
       (stickySessionMap as Map<any, any>).set(key, {
         modelDbId: 1,
         lastUsed: Date.now(),
         bannedPlatforms: new Set(['groq']),
       });
-      expect(isSessionBannedFromPlatform(messages, 'balanced', 'longcat')).toBe(false);
+      expect(isSessionBannedFromPlatform(messages, 'smart', 'longcat')).toBe(false);
     });
 
     it('returns false when the sticky session has expired (past TTL)', () => {
       const messages = makeMessages('Hello');
-      const key = getSessionKey(messages, 'balanced');
+      const key = getSessionKey(messages, 'smart');
       (stickySessionMap as Map<any, any>).set(key, {
         modelDbId: 1,
         lastUsed: Date.now() - (31 * 60 * 1000), // 31 minutes ago
         bannedPlatforms: new Set(['longcat']),
       });
-      expect(isSessionBannedFromPlatform(messages, 'balanced', 'longcat')).toBe(false);
+      expect(isSessionBannedFromPlatform(messages, 'smart', 'longcat')).toBe(false);
     });
   });
 
@@ -96,17 +96,17 @@ describe('Provider session ban functionality', () => {
   describe('banPlatformFromSession', () => {
     it('does not create entry if none exists and no modelDbId provided', () => {
       const messages = makeMessages('Hello');
-      const key = getSessionKey(messages, 'balanced');
+      const key = getSessionKey(messages, 'smart');
       expect(stickySessionMap.has(key)).toBe(false);
-      banPlatformFromSession(messages, 'balanced', 'longcat');
+      banPlatformFromSession(messages, 'smart', 'longcat');
       expect(stickySessionMap.has(key)).toBe(false);
     });
 
     it('creates entry if none exists and modelDbId is provided', () => {
       const messages = makeMessages('Hello');
-      const key = getSessionKey(messages, 'balanced');
+      const key = getSessionKey(messages, 'smart');
       expect(stickySessionMap.has(key)).toBe(false);
-      banPlatformFromSession(messages, 'balanced', 'longcat', 99);
+      banPlatformFromSession(messages, 'smart', 'longcat', 99);
       expect(stickySessionMap.has(key)).toBe(true);
       const entry = stickySessionMap.get(key);
       expect(entry.modelDbId).toBe(99);
@@ -115,13 +115,13 @@ describe('Provider session ban functionality', () => {
 
     it('adds to existing bannedPlatforms if entry already exists', () => {
       const messages = makeMessages('Hello');
-      const key = getSessionKey(messages, 'balanced');
+      const key = getSessionKey(messages, 'smart');
       (stickySessionMap as Map<any, any>).set(key, {
         modelDbId: 2,
         lastUsed: Date.now(),
         bannedPlatforms: new Set(['groq']),
       });
-      banPlatformFromSession(messages, 'balanced', 'longcat');
+      banPlatformFromSession(messages, 'smart', 'longcat');
       const entry = stickySessionMap.get(key);
       expect(entry.bannedPlatforms.has('groq')).toBe(true);
       expect(entry.bannedPlatforms.has('longcat')).toBe(true);
@@ -129,27 +129,27 @@ describe('Provider session ban functionality', () => {
 
     it('does not duplicate platforms already banned', () => {
       const messages = makeMessages('Hello');
-      const key = getSessionKey(messages, 'balanced');
+      const key = getSessionKey(messages, 'smart');
       (stickySessionMap as Map<any, any>).set(key, {
         modelDbId: 3,
         lastUsed: Date.now(),
         bannedPlatforms: new Set(['longcat']),
       });
       const beforeSize = stickySessionMap.get(key).bannedPlatforms.size;
-      banPlatformFromSession(messages, 'balanced', 'longcat');
+      banPlatformFromSession(messages, 'smart', 'longcat');
       const afterSize = stickySessionMap.get(key).bannedPlatforms.size;
       expect(afterSize).toBe(beforeSize);
     });
 
     it('preserves existing modelDbId and keyId when banning', () => {
       const messages = makeMessages('Hello');
-      const key = getSessionKey(messages, 'balanced');
+      const key = getSessionKey(messages, 'smart');
       (stickySessionMap as Map<any, any>).set(key, {
         modelDbId: 42,
         keyId: 7,
         lastUsed: Date.now(),
       });
-      banPlatformFromSession(messages, 'balanced', 'longcat');
+      banPlatformFromSession(messages, 'smart', 'longcat');
       const entry = stickySessionMap.get(key);
       expect(entry.modelDbId).toBe(42);
       expect(entry.keyId).toBe(7);
@@ -157,13 +157,13 @@ describe('Provider session ban functionality', () => {
 
     it('refreshes lastUsed TTL when banning', () => {
       const messages = makeMessages('Hello');
-      const key = getSessionKey(messages, 'balanced');
+      const key = getSessionKey(messages, 'smart');
       const oldTime = Date.now() - (20 * 60 * 1000); // 20 minutes ago
       (stickySessionMap as Map<any, any>).set(key, {
         modelDbId: 1,
         lastUsed: oldTime,
       });
-      banPlatformFromSession(messages, 'balanced', 'longcat');
+      banPlatformFromSession(messages, 'smart', 'longcat');
       const entry = stickySessionMap.get(key);
       expect(entry.lastUsed).toBeGreaterThan(oldTime);
     });
@@ -207,25 +207,25 @@ describe('Provider session ban functionality', () => {
   describe('resetAllConsecutiveFailures', () => {
     it('runs without error when sticky session exists', () => {
       const messages = makeMessages('Hello');
-      const key = getSessionKey(messages, 'balanced');
+      const key = getSessionKey(messages, 'smart');
       (stickySessionMap as Map<any, any>).set(key, { modelDbId: 1, lastUsed: Date.now() });
-      expect(() => resetAllConsecutiveFailures(messages, 'balanced')).not.toThrow();
+      expect(() => resetAllConsecutiveFailures(messages, 'smart')).not.toThrow();
     });
 
     it('no-op if no sticky session', () => {
       const messages = makeMessages('Hello');
-      expect(() => resetAllConsecutiveFailures(messages, 'balanced')).not.toThrow();
+      expect(() => resetAllConsecutiveFailures(messages, 'smart')).not.toThrow();
     });
 
     it('preserves sticky entry when called', () => {
       const messages = makeMessages('Hello');
-      const key = getSessionKey(messages, 'balanced');
+      const key = getSessionKey(messages, 'smart');
       (stickySessionMap as Map<any, any>).set(key, {
         modelDbId: 1,
         lastUsed: Date.now(),
         bannedPlatforms: new Set(['groq']),
       });
-      resetAllConsecutiveFailures(messages, 'balanced');
+      resetAllConsecutiveFailures(messages, 'smart');
       const entry = stickySessionMap.get(key);
       expect(entry).toBeDefined();
       expect(entry.modelDbId).toBe(1);
@@ -244,7 +244,7 @@ describe('Provider session ban functionality', () => {
       'token_limit exceeded',
       'maximum length reached',
       'response_length_limit hit',
-      'conflict in response',
+      'cut off',
     ];
 
     truncationSamples.forEach(sample => {
@@ -276,22 +276,22 @@ describe('Provider session ban functionality', () => {
   describe('Integration: ban lifecycle', () => {
     it('ban persists across model changes and expires after TTL', () => {
       const messages = makeMessages('Hello');
-      const key = getSessionKey(messages, 'balanced');
+      const key = getSessionKey(messages, 'smart');
       const db = getDb();
       const longcatRow = db.prepare("SELECT id FROM models WHERE platform = 'longcat' AND enabled = 1").get() as any;
       expect(longcatRow).toBeDefined();
-      setStickyModel(messages, longcatRow.id, 'balanced');
+      setStickyModel(messages, longcatRow.id, 'smart');
       // Ban longcat for this session
-      banPlatformFromSession(messages, 'balanced', 'longcat');
+      banPlatformFromSession(messages, 'smart', 'longcat');
       // getStickyModel still returns the model (ban check is in routing logic, not getStickyModel)
-      expect(getStickyModel(messages, 'balanced')).toBe(longcatRow.id);
+      expect(getStickyModel(messages, 'smart')).toBe(longcatRow.id);
       // But isSessionBannedFromPlatform should return true
-      expect(isSessionBannedFromPlatform(messages, 'balanced', 'longcat')).toBe(true);
+      expect(isSessionBannedFromPlatform(messages, 'smart', 'longcat')).toBe(true);
       // Simulate TTL expiration by adjusting lastUsed
       const entry = stickySessionMap.get(key);
       entry.lastUsed = Date.now() - (31 * 60 * 1000); // 31 minutes
       // After expiration, ban should be considered cleared
-      expect(isSessionBannedFromPlatform(messages, 'balanced', 'longcat')).toBe(false);
+      expect(isSessionBannedFromPlatform(messages, 'smart', 'longcat')).toBe(false);
     });
 
     it('ban check and skipModels work together to prevent banned platform selection', () => {
@@ -300,13 +300,13 @@ describe('Provider session ban functionality', () => {
       const longcatRow = db.prepare("SELECT id FROM models WHERE platform = 'longcat' AND enabled = 1").get() as any;
       expect(longcatRow).toBeDefined();
       // Set sticky model to a longcat model
-      setStickyModel(messages, longcatRow.id, 'balanced');
+      setStickyModel(messages, longcatRow.id, 'smart');
       // Verify sticky model is set
-      expect(getStickyModel(messages, 'balanced')).toBe(longcatRow.id);
+      expect(getStickyModel(messages, 'smart')).toBe(longcatRow.id);
       // Ban longcat for this session
-      banPlatformFromSession(messages, 'balanced', 'longcat');
+      banPlatformFromSession(messages, 'smart', 'longcat');
       // Verify ban is registered
-      expect(isSessionBannedFromPlatform(messages, 'balanced', 'longcat')).toBe(true);
+      expect(isSessionBannedFromPlatform(messages, 'smart', 'longcat')).toBe(true);
       // Verify addProviderModelsToSkipModels includes the banned model
       const skipModels = new Set<number>();
       addProviderModelsToSkipModels(skipModels, 'longcat');
@@ -319,36 +319,36 @@ describe('Provider session ban functionality', () => {
       const longcatRow = db.prepare("SELECT id FROM models WHERE platform = 'longcat' AND enabled = 1").get() as any;
       expect(longcatRow).toBeDefined();
       // Initially not banned
-      expect(isSessionBannedFromPlatform(messages, 'balanced', 'longcat')).toBe(false);
+      expect(isSessionBannedFromPlatform(messages, 'smart', 'longcat')).toBe(false);
       // Ban via banPlatformFromSession (simulating what production code now does directly)
-      banPlatformFromSession(messages, 'balanced', 'longcat', longcatRow.id);
+      banPlatformFromSession(messages, 'smart', 'longcat', longcatRow.id);
       // Now should be banned
-      expect(isSessionBannedFromPlatform(messages, 'balanced', 'longcat')).toBe(true);
+      expect(isSessionBannedFromPlatform(messages, 'smart', 'longcat')).toBe(true);
     });
 
     it('success via resetAllConsecutiveFailures runs without error', () => {
       const messages = makeMessages('Hello');
-      const key = getSessionKey(messages, 'balanced');
+      const key = getSessionKey(messages, 'smart');
       // Create a sticky entry
       (stickySessionMap as Map<any, any>).set(key, { modelDbId: 1, lastUsed: Date.now() });
       // Simulate success path calling resetAllConsecutiveFailures
-      expect(() => resetAllConsecutiveFailures(messages, 'balanced')).not.toThrow();
+      expect(() => resetAllConsecutiveFailures(messages, 'smart')).not.toThrow();
       // Entry should still exist (resetAllConsecutiveFailures is a no-op)
       expect(stickySessionMap.has(key)).toBe(true);
     });
 
     it('ban from provider A does not affect provider B', () => {
       const messages = makeMessages('Hello');
-      const key = getSessionKey(messages, 'balanced');
+      const key = getSessionKey(messages, 'smart');
       (stickySessionMap as Map<any, any>).set(key, {
         modelDbId: 1,
         lastUsed: Date.now(),
       });
       // Ban longcat
-      banPlatformFromSession(messages, 'balanced', 'longcat');
-      expect(isSessionBannedFromPlatform(messages, 'balanced', 'longcat')).toBe(true);
+      banPlatformFromSession(messages, 'smart', 'longcat');
+      expect(isSessionBannedFromPlatform(messages, 'smart', 'longcat')).toBe(true);
       // groq should not be banned
-      expect(isSessionBannedFromPlatform(messages, 'balanced', 'groq')).toBe(false);
+      expect(isSessionBannedFromPlatform(messages, 'smart', 'groq')).toBe(false);
     });
   });
 
@@ -360,8 +360,8 @@ describe('Provider session ban functionality', () => {
       const longcatRow = db.prepare("SELECT id FROM models WHERE platform = 'longcat' AND enabled = 1").get() as any;
       expect(longcatRow).toBeDefined();
       // Simulate truncation detection calling banPlatformFromSession
-      banPlatformFromSession(messages, 'balanced', 'longcat', longcatRow.id);
-      expect(isSessionBannedFromPlatform(messages, 'balanced', 'longcat')).toBe(true);
+      banPlatformFromSession(messages, 'smart', 'longcat', longcatRow.id);
+      expect(isSessionBannedFromPlatform(messages, 'smart', 'longcat')).toBe(true);
     });
 
     it('isTruncatedResponse detects truncation patterns in error messages', () => {
@@ -370,4 +370,48 @@ describe('Provider session ban functionality', () => {
       expect(isTruncatedResponse('some other error')).toBe(false);
     });
   });
+
+  // ---------- Balanced mode: sticky sessions disabled ----------
+  describe('Balanced mode: sticky session operations are skipped', () => {
+    const makeMessages = (content: string) => [{ role: 'user' as const, content }];
+
+    it('getSessionKey() returns empty string for balanced mode', () => {
+      const messages = makeMessages('Hello balanced');
+      expect(getSessionKey(messages, 'balanced')).toBe('');
+    });
+
+    it('getStickyModel() returns undefined for balanced mode even when smart-mode sticky entry exists for same messages', () => {
+      const messages = makeMessages('Hello dual-mode');
+      // Set up a sticky entry under smart mode for the same messages
+      const smartKey = getSessionKey(messages, 'smart');
+      expect(smartKey).not.toBe('');
+      (stickySessionMap as Map<any, any>).set(smartKey, {
+        modelDbId: 42,
+        lastUsed: Date.now(),
+      });
+      // Balanced mode should return undefined despite the smart-mode entry existing
+      expect(getStickyModel(messages, 'balanced')).toBeUndefined();
+    });
+
+    it('isSessionBannedFromPlatform() returns false for balanced mode', () => {
+      const messages = makeMessages('Hello ban-check');
+      // Even if we manually insert a balanced-mode key (which shouldn't happen in practice),
+      // isSessionBannedFromPlatform should return false because getSessionKey returns ''
+      expect(isSessionBannedFromPlatform(messages, 'balanced', 'longcat')).toBe(false);
+    });
+
+    it('banPlatformFromSession() does not create entries for balanced mode', () => {
+      const messages = makeMessages('Hello ban-test');
+      banPlatformFromSession(messages, 'balanced', 'longcat', 99);
+      // No entries should have been created
+      expect(stickySessionMap.size).toBe(0);
+    });
+
+    it('setStickyModel() does not create entries for balanced mode', () => {
+      const messages = makeMessages('Hello set-test');
+      setStickyModel(messages, 7, 'balanced', 3);
+      // No entries should have been created
+      expect(stickySessionMap.size).toBe(0);
+    });
+  });
 });
diff --git a/server/src/__tests__/routes/proxy-tools.test.ts b/server/src/__tests__/routes/proxy-tools.test.ts
index 310a74a8..a5035404 100644
--- a/server/src/__tests__/routes/proxy-tools.test.ts
+++ b/server/src/__tests__/routes/proxy-tools.test.ts
@@ -2,7 +2,7 @@ import { describe, it, expect, beforeAll, beforeEach, afterEach, vi } from 'vite
 import type { Express } from 'express';
 import { createApp } from '../../app.js';
 import { initDb, getDb, getUnifiedApiKey } from '../../db/index.js';
-import { stickySessionMap, getSessionKey } from '../../routes/proxy.js';
+import { stickySessionMap, getSessionKey, transientModelCooldowns } from '../../routes/proxy.js';
 
 async function request(app: Express, method: string, path: string, body?: any) {
   const server = app.listen(0);
@@ -812,9 +812,7 @@ describe('LongCat sticky session cooldown', () => {
 
   beforeEach(async () => {
     (stickySessionMap as Map<any, any>).clear();
-    // Dynamic import to get the same module instance used by the running app
-    const { transientModelCooldowns: cooldowns } = await import('../../routes/proxy.js');
-    (cooldowns as Map<any, any>).clear();
+    (transientModelCooldowns as Map<any, any>).clear();
     const db = getDb();
     db.prepare('DELETE FROM api_keys').run();
     db.prepare('DELETE FROM requests').run();
diff --git a/server/src/__tests__/routes/transient-cooldown.test.ts b/server/src/__tests__/routes/transient-cooldown.test.ts
new file mode 100644
index 00000000..13e980a5
--- /dev/null
+++ b/server/src/__tests__/routes/transient-cooldown.test.ts
@@ -0,0 +1,415 @@
+import { describe, it, expect, beforeAll, beforeEach, afterEach } from 'vitest';
+import type { Express } from 'express';
+import { createApp } from '../../app.js';
+import { initDb, getDb } from '../../db/index.js';
+import {
+  transientModelCooldowns,
+  TRANSIENT_COOLDOWN_MS,
+  stickySessionMap,
+  addProviderModelsToSkipModels,
+} from '../../routes/proxy.js';
+
+function clearCooldownMap() {
+  (transientModelCooldowns as Map<any, any>).clear();
+}
+
+function clearStickyMap() {
+  (stickySessionMap as Map<any, any>).clear();
+}
+
+describe('Transient model cooldown functionality', () => {
+  let app: Express;
+
+  beforeAll(() => {
+    process.env.ENCRYPTION_KEY = '0'.repeat(64);
+    initDb(':memory:');
+    app = createApp();
+  });
+
+  beforeEach(() => {
+    clearCooldownMap();
+    clearStickyMap();
+    const db = getDb();
+    db.prepare('DELETE FROM api_keys').run();
+    db.prepare('DELETE FROM requests').run();
+  });
+
+  afterEach(() => {
+    clearCooldownMap();
+    clearStickyMap();
+  });
+
+  // ---------- Test Suite 1: Cooldown Map Basics ----------
+  describe('transientModelCooldowns Map', () => {
+    it('starts empty on initialization', () => {
+      expect(transientModelCooldowns.size).toBe(0);
+    });
+
+    it('can set and retrieve a cooldown entry', () => {
+      const modelDbId = 42;
+      const expiry = Date.now() + TRANSIENT_COOLDOWN_MS;
+      transientModelCooldowns.set(modelDbId, expiry);
+      expect(transientModelCooldowns.has(modelDbId)).toBe(true);
+      expect(transientModelCooldowns.get(modelDbId)).toBe(expiry);
+    });
+
+    it('TRANSIENT_COOLDOWN_MS is 15000 (15 seconds)', () => {
+      expect(TRANSIENT_COOLDOWN_MS).toBe(15000);
+    });
+
+    it('can delete a cooldown entry', () => {
+      transientModelCooldowns.set(1, Date.now() + TRANSIENT_COOLDOWN_MS);
+      expect(transientModelCooldowns.size).toBe(1);
+      transientModelCooldowns.delete(1);
+      expect(transientModelCooldowns.size).toBe(0);
+      expect(transientModelCooldowns.has(1)).toBe(false);
+    });
+
+    it('clear removes all entries', () => {
+      transientModelCooldowns.set(1, Date.now() + TRANSIENT_COOLDOWN_MS);
+      transientModelCooldowns.set(2, Date.now() + TRANSIENT_COOLDOWN_MS);
+      transientModelCooldowns.set(3, Date.now() + TRANSIENT_COOLDOWN_MS);
+      expect(transientModelCooldowns.size).toBe(3);
+      clearCooldownMap();
+      expect(transientModelCooldowns.size).toBe(0);
+    });
+  });
+
+  // ---------- Test Suite 2: Cooldown Injection & Pruning ----------
+  describe('Cooldown injection and expired entry pruning', () => {
+    it('active cooldowns are added to skipModels set', () => {
+      const modelDbId = 10;
+      const expiry = Date.now() + TRANSIENT_COOLDOWN_MS;
+      transientModelCooldowns.set(modelDbId, expiry);
+
+      // Simulate the pre-routing injection logic
+      const skipModels = new Set<number>();
+      const now = Date.now();
+      for (const [id, exp] of transientModelCooldowns) {
+        if (now > exp) {
+          transientModelCooldowns.delete(id);
+        } else {
+          skipModels.add(id);
+        }
+      }
+
+      expect(skipModels.has(modelDbId)).toBe(true);
+      expect(transientModelCooldowns.has(modelDbId)).toBe(true);
+    });
+
+    it('expired cooldowns are pruned during injection', () => {
+      const modelDbId = 20;
+      // Set an already-expired cooldown
+      const expiredTimestamp = Date.now() - 1000; // 1 second ago
+      transientModelCooldowns.set(modelDbId, expiredTimestamp);
+
+      const skipModels = new Set<number>();
+      const now = Date.now();
+      for (const [id, exp] of transientModelCooldowns) {
+        if (now > exp) {
+          transientModelCooldowns.delete(id);
+        } else {
+          skipModels.add(id);
+        }
+      }
+
+      expect(skipModels.has(modelDbId)).toBe(false);
+      expect(transientModelCooldowns.has(modelDbId)).toBe(false);
+    });
+
+    it('mixed active and expired entries: active kept, expired pruned', () => {
+      const activeId = 30;
+      const expiredId = 31;
+      transientModelCooldowns.set(activeId, Date.now() + TRANSIENT_COOLDOWN_MS);
+      transientModelCooldowns.set(expiredId, Date.now() - 1000);
+
+      const skipModels = new Set<number>();
+      const now = Date.now();
+      for (const [id, exp] of transientModelCooldowns) {
+        if (now > exp) {
+          transientModelCooldowns.delete(id);
+        } else {
+          skipModels.add(id);
+        }
+      }
+
+      expect(skipModels.has(activeId)).toBe(true);
+      expect(skipModels.has(expiredId)).toBe(false);
+      expect(transientModelCooldowns.has(activeId)).toBe(true);
+      expect(transientModelCooldowns.has(expiredId)).toBe(false);
+    });
+
+    it('multiple active cooldowns are all injected into skipModels', () => {
+      const ids = [40, 41, 42];
+      for (const id of ids) {
+        transientModelCooldowns.set(id, Date.now() + TRANSIENT_COOLDOWN_MS);
+      }
+
+      const skipModels = new Set<number>();
+      const now = Date.now();
+      for (const [id, exp] of transientModelCooldowns) {
+        if (now > exp) {
+          transientModelCooldowns.delete(id);
+        } else {
+          skipModels.add(id);
+        }
+      }
+
+      expect(skipModels.size).toBe(3);
+      for (const id of ids) {
+        expect(skipModels.has(id)).toBe(true);
+      }
+    });
+
+    it('empty cooldown map results in empty skipModels additions', () => {
+      const skipModels = new Set<number>();
+      const now = Date.now();
+      for (const [id, exp] of transientModelCooldowns) {
+        if (now > exp) {
+          transientModelCooldowns.delete(id);
+        } else {
+          skipModels.add(id);
+        }
+      }
+
+      expect(skipModels.size).toBe(0);
+      expect(transientModelCooldowns.size).toBe(0);
+    });
+  });
+
+  // ---------- Test Suite 3: Auto-Recovery After Expiry ----------
+  describe('Auto-recovery after cooldown expiry', () => {
+    it('model becomes routable again after cooldown expires', () => {
+      const modelDbId = 50;
+      // Set a cooldown that expires in 1ms
+      transientModelCooldowns.set(modelDbId, Date.now() + 1);
+
+      // Immediately check — should be active
+      expect(transientModelCooldowns.has(modelDbId)).toBe(true);
+
+      // Wait for expiry (with small buffer for test reliability)
+      // Instead of waiting, simulate the pruning logic with a future timestamp
+      const skipModels = new Set<number>();
+      const futureNow = Date.now() + 2000; // 2 seconds in the future
+      for (const [id, exp] of transientModelCooldowns) {
+        if (futureNow > exp) {
+          transientModelCooldowns.delete(id);
+        } else {
+          skipModels.add(id);
+        }
+      }
+
+      expect(transientModelCooldowns.has(modelDbId)).toBe(false);
+      expect(skipModels.has(modelDbId)).toBe(false);
+    });
+
+    it('cooldown set with TRANSIENT_COOLDOWN_MS expires after ~15 seconds', () => {
+      const modelDbId = 51;
+      const expiry = Date.now() + TRANSIENT_COOLDOWN_MS;
+      transientModelCooldowns.set(modelDbId, expiry);
+
+      // At 14 seconds (before expiry), should still be active
+      const beforeExpiry = expiry - 1000;
+      expect(beforeExpiry > Date.now()).toBe(true); // expiry is in the future
+
+      // Simulate pruning at 16 seconds (after expiry)
+      const afterExpiry = Date.now() + TRANSIENT_COOLDOWN_MS + 1000;
+      const skipModels = new Set<number>();
+      for (const [id, exp] of transientModelCooldowns) {
+        if (afterExpiry > exp) {
+          transientModelCooldowns.delete(id);
+        } else {
+          skipModels.add(id);
+        }
+      }
+
+      expect(transientModelCooldowns.has(modelDbId)).toBe(false);
+    });
+  });
+
+  // ---------- Test Suite 4: Sticky Session Override ----------
+  describe('Global cooldown overrides sticky preference', () => {
+    it('preferredModel on global cooldown is cleared', () => {
+      const preferredModel = 60;
+      const expiry = Date.now() + TRANSIENT_COOLDOWN_MS;
+      transientModelCooldowns.set(preferredModel, expiry);
+
+      // Simulate the sticky override logic
+      let preferredModelVar: number | undefined = preferredModel;
+      let preferredKeyIdVar: number | undefined = 5;
+
+      if (preferredModelVar !== undefined && transientModelCooldowns.has(preferredModelVar)) {
+        const exp = transientModelCooldowns.get(preferredModelVar)!;
+        if (Date.now() <= exp) {
+          preferredModelVar = undefined;
+          preferredKeyIdVar = undefined;
+        }
+      }
+
+      expect(preferredModelVar).toBeUndefined();
+      expect(preferredKeyIdVar).toBeUndefined();
+    });
+
+    it('preferredModel not on cooldown remains intact', () => {
+      const preferredModel = 61;
+      // No cooldown for this model
+      expect(transientModelCooldowns.has(preferredModel)).toBe(false);
+
+      let preferredModelVar: number | undefined = preferredModel;
+      let preferredKeyIdVar: number | undefined = 5;
+
+      if (preferredModelVar !== undefined && transientModelCooldowns.has(preferredModelVar)) {
+        const exp = transientModelCooldowns.get(preferredModelVar)!;
+        if (Date.now() <= exp) {
+          preferredModelVar = undefined;
+          preferredKeyIdVar = undefined;
+        }
+      }
+
+      expect(preferredModelVar).toBe(61);
+      expect(preferredKeyIdVar).toBe(5);
+    });
+
+    it('preferredModel with expired cooldown is NOT cleared', () => {
+      const preferredModel = 62;
+      // Set an already-expired cooldown
+      transientModelCooldowns.set(preferredModel, Date.now() - 1000);
+
+      let preferredModelVar: number | undefined = preferredModel;
+      let preferredKeyIdVar: number | undefined = 5;
+
+      if (preferredModelVar !== undefined && transientModelCooldowns.has(preferredModelVar)) {
+        const exp = transientModelCooldowns.get(preferredModelVar)!;
+        if (Date.now() <= exp) {
+          preferredModelVar = undefined;
+          preferredKeyIdVar = undefined;
+        }
+      }
+
+      // Expired cooldown should NOT override — model remains preferred
+      expect(preferredModelVar).toBe(62);
+      expect(preferredKeyIdVar).toBe(5);
+    });
+
+    it('undefined preferredModel skips the override check entirely', () => {
+      let preferredModelVar: number | undefined = undefined;
+      let preferredKeyIdVar: number | undefined = undefined;
+
+      // Set a cooldown for model 63, but preferredModel is undefined
+      transientModelCooldowns.set(63, Date.now() + TRANSIENT_COOLDOWN_MS);
+
+      if (preferredModelVar !== undefined && transientModelCooldowns.has(preferredModelVar)) {
+        const exp = transientModelCooldowns.get(preferredModelVar)!;
+        if (Date.now() <= exp) {
+          preferredModelVar = undefined;
+          preferredKeyIdVar = undefined;
+        }
+      }
+
+      // No change — preferredModel was already undefined
+      expect(preferredModelVar).toBeUndefined();
+      expect(preferredKeyIdVar).toBeUndefined();
+    });
+  });
+
+  // ---------- Test Suite 5: Cooldown Registration Error Classification ----------
+  describe('Cooldown registration: only 5xx and connection failures trigger cooldown', () => {
+    it('5xx status codes (500-504) are eligible for cooldown registration', () => {
+      // Simulate the condition: (errStatus >= 500 && errStatus < 600)
+      const eligibleStatuses = [500, 502, 503, 504];
+      for (const status of eligibleStatuses) {
+        const condition = status !== undefined && status >= 500 && status < 600;
+        expect(condition).toBe(true);
+      }
+    });
+
+    it('429 rate limit is NOT eligible for cooldown registration', () => {
+      const status = 429;
+      const condition = status !== undefined && status >= 500 && status < 600;
+      expect(condition).toBe(false);
+    });
+
+    it('401 auth error is NOT eligible for cooldown registration', () => {
+      const status = 401;
+      const condition = status !== undefined && status >= 500 && status < 600;
+      expect(condition).toBe(false);
+    });
+
+    it('403 forbidden is NOT eligible for cooldown registration', () => {
+      const status = 403;
+      const condition = status !== undefined && status >= 500 && status < 600;
+      expect(condition).toBe(false);
+    });
+
+    it('400 bad request is NOT eligible for cooldown registration', () => {
+      const status = 400;
+      const condition = status !== undefined && status >= 500 && status < 600;
+      expect(condition).toBe(false);
+    });
+
+    it('undefined status (connection failure) IS eligible for cooldown', () => {
+      const status: number | undefined = undefined;
+      // The condition: (errStatus !== undefined && errStatus >= 500 && errStatus < 600) || errStatus === undefined
+      const condition = (status !== undefined && status >= 500 && status < 600) || status === undefined;
+      expect(condition).toBe(true);
+    });
+
+    it('404 not found is NOT eligible for cooldown registration', () => {
+      const status = 404;
+      const condition = (status !== undefined && status >= 500 && status < 600) || status === undefined;
+      expect(condition).toBe(false);
+    });
+  });
+
+  // ---------- Test Suite 6: Integration with addProviderModelsToSkipModels ----------
+  describe('Integration: cooldown + session ban both feed into skipModels', () => {
+    it('global cooldown and session-banned models both appear in skipModels', () => {
+      const db = getDb();
+      // Get a real model ID from the DB
+      const longcatRow = db.prepare("SELECT id FROM models WHERE platform = 'longcat' AND enabled = 1").get() as any;
+      if (!longcatRow) {
+        // Skip if no longcat models in test DB
+        return;
+      }
+
+      // Set a global cooldown for the longcat model
+      transientModelCooldowns.set(longcatRow.id, Date.now() + TRANSIENT_COOLDOWN_MS);
+
+      const skipModels = new Set<number>();
+
+      // Add session-banned provider models
+      addProviderModelsToSkipModels(skipModels, 'longcat');
+
+      // Add global cooldown models
+      const now = Date.now();
+      for (const [id, exp] of transientModelCooldowns) {
+        if (now > exp) {
+          transientModelCooldowns.delete(id);
+        } else {
+          skipModels.add(id);
+        }
+      }
+
+      // The longcat model should be in skipModels (from both sources)
+      expect(skipModels.has(longcatRow.id)).toBe(true);
+    });
+
+    it('global cooldown for a non-banned provider model still appears in skipModels', () => {
+      const modelDbId = 999; // arbitrary ID not in DB
+      transientModelCooldowns.set(modelDbId, Date.now() + TRANSIENT_COOLDOWN_MS);
+
+      const skipModels = new Set<number>();
+      // No session bans, just cooldown injection
+      const now = Date.now();
+      for (const [id, exp] of transientModelCooldowns) {
+        if (now > exp) {
+          transientModelCooldowns.delete(id);
+        } else {
+          skipModels.add(id);
+        }
+      }
+
+      expect(skipModels.has(modelDbId)).toBe(true);
+    });
+  });
+});
\ No newline at end of file
diff --git a/server/src/__tests__/services/router.test.ts b/server/src/__tests__/services/router.test.ts
index 84bf4123..bc4fd983 100644
--- a/server/src/__tests__/services/router.test.ts
+++ b/server/src/__tests__/services/router.test.ts
@@ -1,7 +1,7 @@
 import { describe, it, expect, beforeAll, beforeEach } from 'vitest';
 import { initDb, getDb } from '../../db/index.js';
 import { encrypt } from '../../lib/crypto.js';
-import { routeRequest } from '../../services/router.js';
+import { routeRequest, refreshStatsCache, getAnalyticsScores } from '../../services/router.js';
 
 describe('Router', () => {
   beforeAll(() => {
@@ -12,7 +12,6 @@ describe('Router', () => {
   beforeEach(() => {
     const db = getDb();
     db.prepare('DELETE FROM api_keys').run();
-    // Reset fallback order to intelligence ranking
     const models = db.prepare('SELECT id, intelligence_rank FROM models ORDER BY intelligence_rank ASC').all() as any[];
     const update = db.prepare('UPDATE fallback_config SET priority = ? WHERE model_db_id = ?');
     for (let i = 0; i < models.length; i++) {
@@ -29,6 +28,7 @@ describe('Router', () => {
     const { encrypted, iv, authTag } = encrypt('test-groq-key');
     db.prepare(`
       INSERT INTO api_keys (platform, label, encrypted_key, iv, auth_tag, status, enabled)
+      VALUES (?,
       VALUES (?, ?, ?, ?, ?, ?, ?)
     `).run('groq', 'test', encrypted, iv, authTag, 'healthy', 1);
 
@@ -39,58 +39,25 @@ describe('Router', () => {
 
   it('should route to an available model when keys exist for multiple platforms', () => {
     const db = getDb();
-
     const googleKey = encrypt('test-google-key');
     db.prepare(`
       INSERT INTO api_keys (platform, label, encrypted_key, iv, auth_tag, status, enabled)
       VALUES (?, ?, ?, ?, ?, ?, ?)
     `).run('google', 'test', googleKey.encrypted, googleKey.iv, googleKey.authTag, 'healthy', 1);
-
     const groqKey = encrypt('test-groq-key');
     db.prepare(`
       INSERT INTO api_keys (platform, label, encrypted_key, iv, auth_tag, status, enabled)
       VALUES (?, ?, ?, ?, ?, ?, ?)
     `).run('groq', 'test', groqKey.encrypted, groqKey.iv, groqKey.authTag, 'healthy', 1);
-
     const result = routeRequest();
     expect(['google', 'groq']).toContain(result.platform);
   });
 
   it('should skip disabled keys', () => {
     const db = getDb();
-
     const googleKey = encrypt('test-google-key');
     db.prepare(`
       INSERT INTO api_keys (platform, label, encrypted_key, iv, auth_tag, status, enabled)
       VALUES (?, ?, ?, ?, ?, ?, ?)
     `).run('google', 'disabled', googleKey.encrypted, googleKey.iv, googleKey.authTag, 'healthy', 0);
-
-    const groqKey = encrypt('test-groq-key');
-    db.prepare(`
-      INSERT INTO api_keys (platform, label, encrypted_key, iv, auth_tag, status, enabled)
-      VALUES (?, ?, ?, ?, ?, ?, ?)
-    `).run('groq', 'test', groqKey.encrypted, groqKey.iv, groqKey.authTag, 'healthy', 1);
-
-    const result = routeRequest();
-    expect(result.platform).toBe('groq');
-  });
-
-  it('should skip invalid keys', () => {
-    const db = getDb();
-
-    const invalidKey = encrypt('invalid-key');
-    db.prepare(`
-      INSERT INTO api_keys (platform, label, encrypted_key, iv, auth_tag, status, enabled)
-      VALUES (?, ?, ?, ?, ?, ?, ?)
-    `).run('google', 'invalid', invalidKey.encrypted, invalidKey.iv, invalidKey.authTag, 'invalid', 1);
-
-    const groqKey = encrypt('test-groq-key');
-    db.prepare(`
-      INSERT INTO api_keys (platform, label, encrypted_key, iv, auth_tag, status, enabled)
-      VALUES (?, ?, ?, ?, ?, ?, ?)
-    `).run('groq', 'test', groqKey.encrypted, groqKey.iv, groqKey.authTag, 'healthy', 1);
-
-    const result = routeRequest();
-    expect(result.platform).toBe('groq');
-  });
-});
+    const groqKey = encrypt
diff --git a/server/src/routes/proxy.ts b/server/src/routes/proxy.ts
index 09633284..7569c49f 100644
--- a/server/src/routes/proxy.ts
+++ b/server/src/routes/proxy.ts
@@ -27,6 +27,8 @@ const responseItemMap = new Map<string, ChatMessage>();
 const RESPONSE_SESSION_TTL_MS = 30 * 60 * 1000;
 const MAX_RESPONSE_SESSIONS = 500;
 const MAX_MODEL_RESPONSE_LOG_CHARS = 6000;
+const transientModelCooldowns = new Map<number, number>(); // modelDbId -> expiryTimestamp
+const TRANSIENT_COOLDOWN_MS = 15000; // 15 seconds
 
 function getSessionKey(messages: ChatMessage[], routingMode: RoutingMode): string {
   // Use the first user message as session identifier — clients like Hermes
@@ -181,6 +183,8 @@ export {
   setStickyModel,
   clearStickyModel,
   stickySessionMap,
+  transientModelCooldowns,
+  TRANSIENT_COOLDOWN_MS,
 };
 
 function clearStickyModel(messages: ChatMessage[], routingMode: RoutingMode) {
@@ -1194,6 +1198,31 @@ async function handleChatCompletion(
     }
   }
 
+  // Transient cooldown: inject globally-cooled models into skipModels (lazy pruning)
+  {
+    const now = Date.now();
+    for (const [modelDbId, expiry] of transientModelCooldowns) {
+      if (now > expiry) {
+        transientModelCooldowns.delete(modelDbId);
+      } else {
+        skipModels.add(modelDbId);
+      }
+    }
+  }
+
+  // If the preferred (sticky) model is on global cooldown, clear the preference
+  if (preferredModel && transientModelCooldowns.has(preferredModel)) {
+    const now = Date.now();
+    const expiry = transientModelCooldowns.get(preferredModel)!;
+    if (now < expiry) {
+      console.log(`[TransientCooldown] preferredModel=${preferredModel} is on global cooldown (${Math.round((expiry - now) / 1000)}s remaining) — clearing sticky preference`);
+      preferredModel = undefined;
+      preferredKeyId = undefined;
+    } else {
+      transientModelCooldowns.delete(preferredModel);
+    }
+  }
+
   if (preferredModel) {
     const db = getDb();
     const prefRow = db.prepare('SELECT platform FROM models WHERE id = ?').get(preferredModel) as { platform: string } | undefined;
@@ -1506,9 +1535,12 @@ async function handleChatCompletion(
                 console.warn(`[Proxy] Mid-stream 5xx from ${route.platform} — skipping model ${route.modelId} only`);
                 skipModels.add(route.modelDbId);
               }
-            }
-  
-            // Generalized truncation detection for any provider (not just LongCat)
+             // Register global transient cooldown for any 5xx mid-stream error
+             transientModelCooldowns.set(route.modelDbId, Date.now() + TRANSIENT_COOLDOWN_MS);
+             console.log(`[TransientCooldown] registered global cooldown for modelDbId=${route.modelDbId} (${TRANSIENT_COOLDOWN_MS / 1000}s)`);
+           }
+
+           // Generalized truncation detection for any provider (not just LongCat)
             // Aggregate all possible error text sources for comprehensive detection
             const truncationTexts: string[] = [];
             if (streamErr instanceof Error) {
@@ -1671,11 +1703,14 @@ async function handleChatCompletion(
         } else {
           console.warn(`[Proxy] 5xx from ${route.platform} — skipping model ${route.modelId} only`);
           skipModels.add(route.modelDbId);
-        }
-      }
+       }
+     }
 
-      if (isRetryableError(err)) {
+     if (isRetryableError(err)) {
         // LongCat: on any retryable error, exclude entire provider immediately
+        // Register global transient cooldown for this failing model
+        transientModelCooldowns.set(route.modelDbId, Date.now() + TRANSIENT_COOLDOWN_MS);
+        console.log(`[TransientCooldown] registered global cooldown for modelDbId=${route.modelDbId} (${TRANSIENT_COOLDOWN_MS / 1000}s)`);
         if (route.platform === 'longcat') {
           console.warn(`[Proxy] Retryable error from LongCat — excluding entire LongCat provider for session`);
           banPlatformFromSession(normalizedMessages, routingMode, 'longcat', route.modelDbId);
diff --git a/server/src/services/router.ts b/server/src/services/router.ts
index 96b029cf..e5f3b19f 100644
--- a/server/src/services/router.ts
+++ b/server/src/services/router.ts
@@ -151,14 +151,23 @@ function sampleBeta(alpha: number, beta: number): number {
 }
 
 interface ModelStats {
-  successes: number;
-  total: number;
-  tokPerSec: number;    // output tok/s from successful requests only
+  successes: number;       // recency-weighted successes
+  total: number;           // recency-weighted total
+  rawTotal: number;        // unweighted raw count
+  tokPerSec: number;       // output tok/s from successful requests only
   avgTtfbMs: number | null; // avg TTFB across successful requests (null if no data)
 }
 
 export type RoutingMode = 'balanced' | 'smart';
 
+// ── Balanced mode exclusions ────────────────────────────────────────────────
+// LongCat and Owl Alpha are excluded from balanced auto-routing so they are
+// only reachable via explicit model request or smart-mode preference.
+const EXCLUDED_FROM_BALANCED = new Set<string>(['longcat']);
+const EXCLUDED_MODELS_FROM_BALANCED = new Map<string, Set<string>>([
+  ['openrouter', new Set(['owl-alpha'])],
+]);
+
 let statsCache: Map<string, ModelStats> | null = null;
 let statsCacheTime = 0;
 let maxTokPerSec = 0;
@@ -167,10 +176,15 @@ export function refreshStatsCache(db: Database, force = false): void {
   if (!force && statsCache && Date.now() - statsCacheTime < ANALYTICS_CACHE_TTL_MS) return;
 
   const since = new Date(Date.now() - ANALYTICS_WINDOW_MS).toISOString();
+  // Recency weight per row: MAX(0, MIN(1.0, 1.0 - days_ago / 7.0))
+  // Future timestamps (clock drift) capped at weight 1.0 via MIN(1.0, ...).
   const rows = db.prepare(`
     SELECT platform, model_id,
-      COUNT(*) as total,
-      SUM(CASE WHEN status = 'success' THEN 1 ELSE 0 END) as successes,
+      COUNT(*) as raw_total,
+      SUM(MAX(0, MIN(1.0, 1.0 - (julianday('now') - julianday(created_at)) / 7.0)))) as total,
+      SUM(CASE WHEN status = 'success'
+        THEN MAX(0, MIN(1.0, 1.0 - (julianday('now') - julianday(created_at)) / 7.0)))
+        ELSE 0 END) as successes,
       CASE
         WHEN SUM(CASE WHEN status = 'success' THEN latency_ms ELSE 0 END) > 0
         THEN SUM(CASE WHEN status = 'success' THEN output_tokens ELSE 0 END) * 1000.0
@@ -182,7 +196,7 @@ export function refreshStatsCache(db: Database, force = false): void {
     WHERE created_at >= ?
     GROUP BY platform, model_id
   `).all(since) as Array<{
-    platform: string; model_id: string; total: number; successes: number;
+    platform: string; model_id: string; raw_total: number; total: number; successes: number;
     tok_per_sec: number; avg_ttfb_ms: number | null;
   }>;
 
@@ -192,6 +206,7 @@ export function refreshStatsCache(db: Database, force = false): void {
     statsCache.set(`${row.platform}:${row.model_id}`, {
       successes: row.successes,
       total: row.total,
+      rawTotal: row.raw_total,
       tokPerSec: row.tok_per_sec,
       avgTtfbMs: row.avg_ttfb_ms ?? null,
     });
@@ -343,7 +358,7 @@ export function getAnalyticsScores(): Array<{
       modelId,
       score: getAnalyticsScore(platform, modelId, intelligenceRank, minIntelligenceRank, maxIntelligenceRank),
       successRate: stats.total > 0 ? stats.successes / stats.total : 0,
-      total: stats.total,
+      total: stats.rawTotal,
       tokPerSec: stats.tokPerSec,
       avgTtfbMs: stats.avgTtfbMs,
     });
@@ -439,6 +454,26 @@ export function getAllPenalties(): Array<{ modelDbId: number; count: number; pen
   return result.sort((a, b) => b.penalty - a.penalty);
 }
 
+// ── Key capacity helper ──────────────────────────────────────────────────────
+// Checks whether any enabled, non-invalid key for a given platform/model has
+// capacity (not on cooldown, can make a request, can use the estimated tokens).
+function hasValidKeys(
+  platform: string,
+  modelId: string,
+  limits: { rpm: number | null; rpd: number | null; tpm: number | null; tpd: number | null },
+  estimatedTokens: number,
+): boolean {
+  const db = getDb();
+  const keys = db.prepare(
+    'SELECT * FROM api_keys WHERE platform = ? AND enabled = 1 AND status != ?'
+  ).all(platform, 'invalid') as KeyRow[];
+  return keys.some(key =>
+    !isOnCooldown(platform, modelId, key.id) &&
+    canMakeRequest(platform, modelId, key.id, limits) &&
+    canUseTokens(platform, modelId, key.id, estimatedTokens, limits)
+  );
+}
+
 /**
  * Route a request to the best available model.
  *
@@ -477,10 +512,20 @@ export function routeRequest(
     WHERE fc.enabled = 1
   `).all() as ChainRow[];
 
-  const intelligenceRanks = chain.map(entry => entry.intelligence_rank);
+  // T1.2: In balanced mode, exclude LongCat platform and Owl Alpha model
+  const filteredChain = routingMode === 'balanced'
+    ? chain.filter(entry => {
+        if (EXCLUDED_FROM_BALANCED.has(entry.platform)) return false;
+        const excludedModels = EXCLUDED_MODELS_FROM_BALANCED.get(entry.platform);
+        if (excludedModels?.has(entry.model_id)) return false;
+        return true;
+      })
+    : chain;
+
+  const intelligenceRanks = filteredChain.map(entry => entry.intelligence_rank);
   const minIntelligenceRank = Math.min(...intelligenceRanks);
   const maxIntelligenceRank = Math.max(...intelligenceRanks);
-  const sorted = chain.map(entry => ({
+  const sorted = filteredChain.map(entry => ({
     ...entry,
     effectiveScore:
       (routingMode === 'smart'
@@ -495,33 +540,42 @@ export function routeRequest(
       - getPenalty(entry.model_db_id) * PENALTY_SCORE_WEIGHT,
   })).sort((a, b) => b.effectiveScore - a.effectiveScore);
 
-  // LongCat preference in smart mode: move LongCat entries to front if any key has capacity
   if (routingMode === 'smart') {
+    let lcPreferred = false;
     const longcatEntries = sorted.filter(e => e.platform === 'longcat');
     if (longcatEntries.length > 0) {
-      // Check if any LongCat key passes rate-limit checks
-      const lcKeys = db.prepare(
-        'SELECT * FROM api_keys WHERE platform = ? AND enabled = 1 AND status != ?'
-      ).all('longcat', 'invalid') as KeyRow[];
-      if (lcKeys.length > 0) {
-        const sampleEntry = longcatEntries[0];
-        const lcLimits = {
-          rpm: sampleEntry.rpm_limit,
-          rpd: sampleEntry.rpd_limit,
-          tpm: sampleEntry.tpm_limit,
-          tpd: sampleEntry.tpd_limit,
-        };
-        const hasCapacity = lcKeys.some(key =>
-          !isOnCooldown(sampleEntry.platform, sampleEntry.model_id, key.id) &&
-          canMakeRequest(sampleEntry.platform, sampleEntry.model_id, key.id, lcLimits) &&
-          canUseTokens(sampleEntry.platform, sampleEntry.model_id, key.id, estimatedTokens, lcLimits)
-        );
-        if (hasCapacity) {
-          // Move all LongCat entries to front, preserving relative score order
-          const others = sorted.filter(e => e.platform !== 'longcat');
-          sorted.length = 0;
-          sorted.push(...longcatEntries, ...others);
+      const sampleEntry = longcatEntries[0];
+      const lcLimits = {
+        rpm: sampleEntry.rpm_limit,
+        rpd: sampleEntry.rpd_limit,
+        tpm: sampleEntry.tpm_limit,
+        tpd: sampleEntry.tpd_limit,
+      };
+      if (hasValidKeys(sampleEntry.platform, sampleEntry.model_id, lcLimits, estimatedTokens)) {
+        const others = sorted.filter(e => e.platform !== 'longcat');
+        sorted.length = 0;
+        sorted.push(...longcatEntries, ...others);
+        lcPreferred = true;
+      }
+    }
+
+    // Owl Alpha smart preference
+    const owlAlphaEntry = sorted.find(e => e.platform === 'openrouter' && e.model_id === 'owl-alpha');
+    if (owlAlphaEntry) {
+      const oaLimits = {
+        rpm: owlAlphaEntry.rpm_limit,
+        rpd: owlAlphaEntry.rpd_limit,
+        tpm: owlAlphaEntry.tpm_limit,
+        tpd: owlAlphaEntry.tpd_limit,
+      };
+      if (hasValidKeys(owlAlphaEntry.platform, owlAlphaEntry.model_id, oaLimits, estimatedTokens)) {
+        const owlIdx = sorted.indexOf(owlAlphaEntry);
+        if (owlIdx >= 0) {
+          sorted.splice(owlIdx, 1);
         }
+        const insertIdx = lcPreferred ? longcatEntries.length : 0;
+        sorted.splice(insertIdx, 0, owlAlphaEntry);
+        console.log('[Router] Owl Alpha preference active — moving openrouter/owl-alpha to front');
       }
     }
   }
diff --git a/server/write_test.py b/server/write_test.py
new file mode 100644
index 00000000..67c9e69d
--- /dev/null
+++ b/server/write_test.py
@@ -0,0 +1,29 @@
+#!/usr/bin/env python3
+"""Write the complete router.test.ts file."""
+
+path = '/home/vi/freellmapi/server/src/__tests__/services/router.test.ts'
+
+content = [
+    "import { describe, it, expect, beforeAll, beforeEach } from 'vitest';",
+    "import { initDb, getDb } from '../../db/index.js';",
+    "import { encrypt } from '../../lib/crypto.js';",
+    "import { routeRequest, refreshStatsCache, getAnalyticsScores } from '../../services/router.js';",
+    "",
+    "describe('Router', () => {",
+    "  beforeAll(() => {",
+    "    process.env.ENCRYPTION_KEY = '0'.repeat(64);",
+    "    initDb(':memory:');",
+    "  });",
+    "",
+    "  beforeEach(() => {",
+    "    const db = getDb();",
+    "    db.prepare('DELETE FROM api_keys').run();",
+    "    const models = db.prepare('SELECT id, intelligence_rank FROM models ORDER BY intelligence_rank ASC').all() as any[];",
+    "    const update = db.prepare('UPDATE fallback_config SET priority = ? WHERE model_db_id = ?');",
+    "    for (let i = 0; i < models.length; i++) {",
+    "      update.run(i + 1, models[i].id);",
+    "    }",
+    "  });",
+    "",
+    "  it('should throw when no keys are configured', () => {",
+    "    expect(() => route{
\ No newline at end of file
diff --git a/server/write_tests.py b/server/write_tests.py
new file mode 100644
index 00000000..c600c9d4
--- /dev/null
+++ b/server/write_tests.py
@@ -0,0 +1,45 @@
+import os
+
+# Write the test file in parts to avoid truncation
+path = '/home/vi/freellmapi/server/src/__tests__/services/router.test.ts'
+
+# Part 1: existing tests
+part1 = """import { describe, it, expect, beforeAll, beforeEach } from 'vitest';
+import { initDb, getDb } from '../../db/index.js';
+import { encrypt } from '../../lib/crypto.js';
+import { routeRequest, refreshStatsCache, getAnalyticsScores } from '../../services/router.js';
+
+describe('Router', () => {
+  beforeAll(() => {
+    process.env.ENCRYPTION_KEY = '0'.repeat(64);
+    initDb(':memory:');
+  });
+
+  beforeEach(() => {
+    const db = getDb();
+    db.prepare('DELETE FROM api_keys').run();
+    const models = db.prepare('SELECT id, intelligence_rank FROM models ORDER BY intelligence_rank ASC').all() as any[];
+    const update = db.prepare('UPDATE fallback_config SET priority = ? WHERE model_db_id = ?');
+    for (let i = 0; i < models.length; i++) {
+      update.run(i + 1, models[i].id);
+    }
+  });
+
+  it('should throw when no keys are configured', () => {
+    expect(() => routeRequest()).toThrow(/exhausted/i);
+  });
+
+  it('should route to highest priority model with available key', () => {
+    const db = getDb();
+    const { encrypted, iv, authTag } = encrypt('test-groq-key');
+    db.prepare('INSERT INTO api_keys (platform, label, encrypted_key, iv, auth_tag, status, enabled) VALUES (?, ?, ?, ?, ?, ?, ?)').run('groq', 'test', encrypted, iv, authTag, 'healthy', 1);
+    const result = routeRequest();
+    expect(result.platform).toBe('groq');
+    expect(result.apiKey).toBe('test-groq-key');
+  });
+
+  it('should route to an available model when keys exist for multiple platforms', () => {
+    const db = getDb();
+    const googleKey = encrypt('test-google-key');
+    db.prepare('INSERT INTO api_keys (platform, label, encrypted_key, iv, auth_tag, status, enabled) VALUES (?, ?, ?, ?, ?, ?, ?)').run('google', 'test', googleKey.encrypted, googleKey.iv, googleKey.authTag, 'healthy', 1);
+    const groqKey{
\ No newline at end of file

From 24c1c8070766a606c31470cd0cdd195679b98b10 Mon Sep 17 00:00:00 2001
From: vi <vi70x3@atomicmail.io>
Date: Wed, 3 Jun 2026 02:44:26 +0300
Subject: [PATCH 4/4] feat(thread-protection): implement rules engine and
 replace hardcoded longcat branches

---
 .../generalized-thread-protection/tasks.md    |   8 +-
 client/src/pages/FallbackPage.tsx             |  79 ++++++----
 server/src/__tests__/routes/fallback.test.ts  |  11 ++
 server/src/routes/proxy.ts                    | 148 ++++++++++--------
 server/src/services/threadProtection.ts       | 102 +++++++++++-
 5 files changed, 246 insertions(+), 102 deletions(-)

diff --git a/.roo/specs/generalized-thread-protection/tasks.md b/.roo/specs/generalized-thread-protection/tasks.md
index cf604bca..00700d90 100644
--- a/.roo/specs/generalized-thread-protection/tasks.md
+++ b/.roo/specs/generalized-thread-protection/tasks.md
@@ -2,10 +2,10 @@
 
 ## Implementation Tasks
 
-- [ ] T-1: Rename `LONGCAT_STICKY_COOLDOWN_MS` to `THREAD_COOLDOWN_MS` in [`server/src/routes/proxy.ts`](server/src/routes/proxy.ts:18) and update all references throughout the file
-- [ ] T-2: Remove the hardcoded LongCat cooldown block (the `if (preferredModel)` block checking `prefRow?.platform === 'longcat'` and calling `addProviderModelsToSkipModels(skipModels, 'longcat')`)
-- [ ] T-3: Remove the hardcoded Owl Alpha cooldown block (the `if (preferredModel)` block checking `prefRow?.platform === 'openrouter' && prefRow?.model_id === 'owl-alpha'` and calling `skipModels.add(preferredModel)`)
-- [ ] T-4: Insert the generalized thread protection scanner at the same location where the removed blocks were, after the session ban sticky override and before the retry loop — including the `activeCooldownModels` collection loop, the exhaustion protection SQL query, and the conditional `skipModels` addition
+- [x] T-1: Rename `LONGCAT_STICKY_COOLDOWN_MS` to `THREAD_COOLDOWN_MS` in [`server/src/routes/proxy.ts`](server/src/routes/proxy.ts:18) and update all references throughout the file
+- [x] T-2: Remove the hardcoded LongCat cooldown block (the `if (preferredModel)` block checking `prefRow?.platform === 'longcat'` and calling `addProviderModelsToSkipModels(skipModels, 'longcat')`)
+- [x] T-3: Remove the hardcoded Owl Alpha cooldown block (the `if (preferredModel)` block checking `prefRow?.platform === 'openrouter' && prefRow?.model_id === 'owl-alpha'` and calling `skipModels.add(preferredModel)`)
+- [x] T-4: Insert the generalized thread protection scanner at the same location where the removed blocks were, after the session ban sticky override and before the retry loop — including the `activeCooldownModels` collection loop, the exhaustion protection SQL query, and the conditional `skipModels` addition
 - [ ] T-5: Verify the execution order of the `skipModels` pipeline: session bans → transient cooldowns → global cooldown sticky override → session ban sticky override → thread protection scanner → retry loop
 - [ ] T-6: Create [`server/src/__tests__/routes/thread-protection.test.ts`](server/src/__tests__/routes/thread-protection.test.ts) with unit tests covering: dynamic exclusivity, exhaustion bypass, self-preservation, expired entries, and multiple busy models
 - [ ] T-7: Run the existing test suite to confirm no regressions in routing, fallback, or provider-session-ban tests
diff --git a/client/src/pages/FallbackPage.tsx b/client/src/pages/FallbackPage.tsx
index f8ec24e8..93cf74dc 100644
--- a/client/src/pages/FallbackPage.tsx
+++ b/client/src/pages/FallbackPage.tsx
@@ -3,6 +3,8 @@ import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
 import { apiFetch } from '@/lib/api'
 import { Switch } from '@/components/ui/switch'
 import { PageHeader } from '@/components/page-header'
+import { PoolSection } from '@/components/pool-section'
+import type { PoolType } from '@/components/pool-badge'
 
 interface FallbackEntry {
   modelDbId: number
@@ -23,6 +25,7 @@ interface FallbackEntry {
   rpdLimit: number | null
   monthlyTokenBudget: string
   keyCount: number
+  pool: PoolType
 }
 
 function formatTokens(n: number): string {
@@ -61,6 +64,13 @@ function sortValue(entry: FallbackEntry, key: SortKey): string | number {
   return entry.effectiveScore
 }
 
+const poolOrder: PoolType[] = ['fast', 'balanced', 'smart']
+const poolTitles: Record<PoolType, string> = {
+  fast: 'Fast pool — lowest latency models',
+  balanced: 'Balanced pool — good speed & quality',
+  smart: 'Smart pool — highest intelligence models',
+}
+
 function SortHeader({
   label,
   sortKey,
@@ -285,6 +295,9 @@ export default function FallbackPage() {
         : Number(aValue) - Number(bValue)
       return sortDir === 'asc' ? result : -result
     })
+  const poolGroups = poolOrder
+    .map(pool => ({ pool, entries: displayEntries.filter(e => e.pool === pool) }))
+    .filter(group => group.entries.length > 0)
   const unconfiguredPlatforms = [...new Set(entries.filter(e => e.keyCount === 0).map(e => e.platform))]
 
   function handleSort(key: SortKey) {
@@ -319,37 +332,43 @@ export default function FallbackPage() {
           </div>
         ) : (
           <>
-            <div className="rounded-lg border overflow-hidden">
-              <div className="flex items-center gap-3 px-4 py-2 bg-muted/40 border-b">
-                <span className="w-5 shrink-0" />
-                <SortHeader
-                  label={sortLabels.model}
-                  sortKey="model"
-                  activeKey={sortKey}
-                  sortDir={sortDir}
-                  onSort={handleSort}
-                  className="flex-1 min-w-0 text-left"
-                />
-                <div className="flex items-center gap-6 shrink-0">
-                  <SortHeader label={sortLabels.requests} sortKey="requests" activeKey={sortKey} sortDir={sortDir} onSort={handleSort} className="w-14 text-right" />
-                  <SortHeader label={sortLabels.success} sortKey="success" activeKey={sortKey} sortDir={sortDir} onSort={handleSort} className="w-20 text-right" />
-                  <SortHeader label={sortLabels.tokPerSec} sortKey="tokPerSec" activeKey={sortKey} sortDir={sortDir} onSort={handleSort} className="w-16 text-right" />
-                  <SortHeader label={sortLabels.ttfb} sortKey="ttfb" activeKey={sortKey} sortDir={sortDir} onSort={handleSort} className="w-20 text-right" />
-                  <SortHeader label={sortLabels.auto} sortKey="auto" activeKey={sortKey} sortDir={sortDir} onSort={handleSort} className="w-16 text-right" />
-                  <SortHeader label={sortLabels.smart} sortKey="smart" activeKey={sortKey} sortDir={sortDir} onSort={handleSort} className="w-16 text-right" />
-                </div>
-                <span className="w-9 shrink-0 text-xs font-medium text-muted-foreground text-right">On</span>
-              </div>
-              <div className="divide-y">
-              {displayEntries.map((entry, index) => (
-                <ModelRow
-                  key={entry.modelDbId}
-                  entry={entry}
-                  index={index}
-                  onToggle={(id, enabled) => toggleMutation.mutate({ modelDbId: id, enabled })}
-                />
+            <div className="space-y-4">
+              {poolGroups.map(({ pool, entries: poolEntries }) => (
+                <PoolSection key={pool} pool={pool} title={poolTitles[pool]}>
+                  <div className="rounded-lg border overflow-hidden">
+                    <div className="flex items-center gap-3 px-4 py-2 bg-muted/40 border-b">
+                      <span className="w-5 shrink-0" />
+                      <SortHeader
+                        label={sortLabels.model}
+                        sortKey="model"
+                        activeKey={sortKey}
+                        sortDir={sortDir}
+                        onSort={handleSort}
+                        className="flex-1 min-w-0 text-left"
+                      />
+                      <div className="flex items-center gap-6 shrink-0">
+                        <SortHeader label={sortLabels.requests} sortKey="requests" activeKey={sortKey} sortDir={sortDir} onSort={handleSort} className="w-14 text-right" />
+                        <SortHeader label={sortLabels.success} sortKey="success" activeKey={sortKey} sortDir={sortDir} onSort={handleSort} className="w-20 text-right" />
+                        <SortHeader label={sortLabels.tokPerSec} sortKey="tokPerSec" activeKey={sortKey} sortDir={sortDir} onSort={handleSort} className="w-16 text-right" />
+                        <SortHeader label={sortLabels.ttfb} sortKey="ttfb" activeKey={sortKey} sortDir={sortDir} onSort={handleSort} className="w-20 text-right" />
+                        <SortHeader label={sortLabels.auto} sortKey="auto" activeKey={sortKey} sortDir={sortDir} onSort={handleSort} className="w-16 text-right" />
+                        <SortHeader label={sortLabels.smart} sortKey="smart" activeKey={sortKey} sortDir={sortDir} onSort={handleSort} className="w-16 text-right" />
+                      </div>
+                      <span className="w-9 shrink-0 text-xs font-medium text-muted-foreground text-right">On</span>
+                    </div>
+                    <div className="divide-y">
+                    {poolEntries.map((entry, index) => (
+                      <ModelRow
+                        key={entry.modelDbId}
+                        entry={entry}
+                        index={index}
+                        onToggle={(id, enabled) => toggleMutation.mutate({ modelDbId: id, enabled })}
+                      />
+                    ))}
+                    </div>
+                  </div>
+                </PoolSection>
               ))}
-              </div>
             </div>
 
             {unconfiguredPlatforms.length > 0 && (
diff --git a/server/src/__tests__/routes/fallback.test.ts b/server/src/__tests__/routes/fallback.test.ts
index 43d02b0c..999d83cb 100644
--- a/server/src/__tests__/routes/fallback.test.ts
+++ b/server/src/__tests__/routes/fallback.test.ts
@@ -1,4 +1,5 @@
 import { describe, it, expect, beforeAll } from 'vitest';
+import { ModelPool } from '@freellmapi/shared/types.js';
 import type { Express } from 'express';
 import { createApp } from '../../app.js';
 import { initDb } from '../../db/index.js';
@@ -48,6 +49,16 @@ describe('Fallback API', () => {
     expect(first).toHaveProperty('platform');
     expect(first).toHaveProperty('displayName');
     expect(first).toHaveProperty('intelligenceRank');
+    expect(first).toHaveProperty('speedRank');
+    expect(first).toHaveProperty('pool');
+  });
+
+  it('GET /api/fallback pool values are valid ModelPool enum values', async () => {
+    const { body } = await request(app, 'GET', '/api/fallback');
+    const validPools = [ModelPool.Fast, ModelPool.Balanced, ModelPool.Smart];
+    for (const entry of body) {
+      expect(validPools).toContain(entry.pool);
+    }
   });
 
   it('PUT /api/fallback updates order', async () => {
diff --git a/server/src/routes/proxy.ts b/server/src/routes/proxy.ts
index 7569c49f..fa39987d 100644
--- a/server/src/routes/proxy.ts
+++ b/server/src/routes/proxy.ts
@@ -1455,14 +1455,14 @@ async function handleChatCompletion(
           {
             const streamTextToCheck = responseStreamContext ? responseStreamContext.outputText : streamedText;
             if (isTruncatedResponse(streamTextToCheck)) {
-              if (route.platform === 'longcat') {
-                // LongCat: exclude entire provider immediately on truncation
-                console.warn(`[Proxy] Truncated stream content detected from LongCat — banning LongCat provider for session`);
-                banPlatformFromSession(normalizedMessages, routingMode, 'longcat', route.modelDbId);
-                addProviderModelsToSkipModels(skipModels, 'longcat');
-              } else {
-                // Non-LongCat: skip only this specific model, other models from same provider remain available
-                console.warn(`[Proxy] Truncated stream content detected from ${route.platform} — skipping model ${route.modelId} for session`);
+              const action = evaluateThreadProtection({ platform: route.platform, kind: 'truncation', midStream: false, modelDbId: route.modelDbId });
+              if (action.banProvider) {
+                console.warn(`[Proxy] Truncated stream content detected from ${route.platform} — banning provider for session (${action.reason})`);
+                banPlatformFromSession(normalizedMessages, routingMode, route.platform, route.modelDbId);
+                addProviderModelsToSkipModels(skipModels, route.platform);
+              }
+              if (action.skipModel) {
+                console.warn(`[Proxy] Truncated stream content detected from ${route.platform} — skipping model ${route.modelId} for session (${action.reason})`);
                 skipModels.add(route.modelDbId);
               }
             }
@@ -1523,18 +1523,26 @@ async function handleChatCompletion(
           cleanupStream();
           if (streamStarted) {
             // 5xx failure detection for mid-stream errors
-            // LongCat: exclude entire provider immediately on any 5xx
-            // Non-LongCat: skip only this specific model, other models from same provider remain available
             const streamErrStatus = getErrorStatus(streamErr);
             if (streamErrStatus && isBanEligibleStatus(streamErrStatus)) {
-              if (route.platform === 'longcat') {
-                console.warn(`[Proxy] Mid-stream 5xx from LongCat — excluding entire LongCat provider for session`);
-                banPlatformFromSession(normalizedMessages, routingMode, 'longcat', route.modelDbId);
-                addProviderModelsToSkipModels(skipModels, 'longcat');
-              } else {
-                console.warn(`[Proxy] Mid-stream 5xx from ${route.platform} — skipping model ${route.modelId} only`);
+              const action = evaluateThreadProtection({ platform: route.platform, kind: '5xx', midStream: true, modelDbId: route.modelDbId, error: streamErr });
+              if (action.banProvider) {
+                console.warn(`[Proxy] Mid-stream 5xx from ${route.platform} — banning provider for session (${action.reason})`);
+                banPlatformFromSession(normalizedMessages, routingMode, route.platform, route.modelDbId);
+                addProviderModelsToSkipModels(skipModels, route.platform);
+              }
+              if (action.skipModel) {
+                console.warn(`[Proxy] Mid-stream 5xx from ${route.platform} — skipping model ${route.modelId} only (${action.reason})`);
                 skipModels.add(route.modelDbId);
               }
+              if (action.clearStickyIfPinned && preferredModel) {
+                const db = getDb();
+                const prefRow = db.prepare('SELECT platform FROM models WHERE id = ?').get(preferredModel) as { platform: string } | undefined;
+                if (prefRow?.platform === route.platform) {
+                  preferredModel = undefined;
+                  preferredKeyId = undefined;
+                }
+              }
              // Register global transient cooldown for any 5xx mid-stream error
              transientModelCooldowns.set(route.modelDbId, Date.now() + TRANSIENT_COOLDOWN_MS);
              console.log(`[TransientCooldown] registered global cooldown for modelDbId=${route.modelDbId} (${TRANSIENT_COOLDOWN_MS / 1000}s)`);
@@ -1555,14 +1563,14 @@ async function handleChatCompletion(
             truncationTexts.push(String(streamErr));
             const combinedTruncationText = truncationTexts.join(' ');
             if (isTruncatedResponse(combinedTruncationText)) {
-              if (route.platform === 'longcat') {
-                // LongCat: exclude entire provider immediately on truncation
-                console.warn(`[Proxy] Truncation error mid-stream from LongCat — excluding entire LongCat provider for session, ending stream gracefully`);
-                banPlatformFromSession(normalizedMessages, routingMode, 'longcat', route.modelDbId);
-                addProviderModelsToSkipModels(skipModels, 'longcat');
-              } else {
-                // Non-LongCat: skip only this specific model
-                console.warn(`[Proxy] Truncation error mid-stream from ${route.platform} — skipping model ${route.modelId} only, ending stream gracefully`);
+              const action = evaluateThreadProtection({ platform: route.platform, kind: 'truncation', midStream: true, modelDbId: route.modelDbId, error: streamErr });
+              if (action.banProvider) {
+                console.warn(`[Proxy] Truncation error mid-stream from ${route.platform} — banning provider for session, ending stream gracefully (${action.reason})`);
+                banPlatformFromSession(normalizedMessages, routingMode, route.platform, route.modelDbId);
+                addProviderModelsToSkipModels(skipModels, route.platform);
+              }
+              if (action.skipModel) {
+                console.warn(`[Proxy] Truncation error mid-stream from ${route.platform} — skipping model ${route.modelId} only, ending stream gracefully (${action.reason})`);
                 skipModels.add(route.modelDbId);
               }
               try {
@@ -1585,16 +1593,22 @@ async function handleChatCompletion(
               return;
             }
           
-            // Mid-stream retryable error handling for LongCat
-            if (route.platform === 'longcat' && isRetryableStreamError(streamErr)) {
-              console.warn(`[Proxy] Mid-stream retryable error from LongCat — excluding entire LongCat provider for session`);
-              banPlatformFromSession(normalizedMessages, routingMode, 'longcat', route.modelDbId);
-              addProviderModelsToSkipModels(skipModels, 'longcat');
-              // Clear sticky preference if pinned to LongCat
-              if (preferredModel) {
+            // Mid-stream retryable error handling
+            if (isRetryableStreamError(streamErr)) {
+              const action = evaluateThreadProtection({ platform: route.platform, kind: 'retryable', midStream: true, modelDbId: route.modelDbId, error: streamErr });
+              if (action.banProvider) {
+                console.warn(`[Proxy] Mid-stream retryable error from ${route.platform} — banning provider for session (${action.reason})`);
+                banPlatformFromSession(normalizedMessages, routingMode, route.platform, route.modelDbId);
+                addProviderModelsToSkipModels(skipModels, route.platform);
+              }
+              if (action.skipModel) {
+                console.warn(`[Proxy] Mid-stream retryable error from ${route.platform} — skipping model ${route.modelId} (${action.reason})`);
+                skipModels.add(route.modelDbId);
+              }
+              if (action.clearStickyIfPinned && preferredModel) {
                 const db = getDb();
                 const prefRow = db.prepare('SELECT platform FROM models WHERE id = ?').get(preferredModel) as { platform: string } | undefined;
-                if (prefRow?.platform === 'longcat') {
+                if (prefRow?.platform === route.platform) {
                   preferredModel = undefined;
                   preferredKeyId = undefined;
                 }
@@ -1683,48 +1697,52 @@ async function handleChatCompletion(
       logRequest(route.platform, route.modelId, 'error', estimatedInputTokens, 0, latency, null, err.message);
 
       // 5xx failure detection
-      // LongCat: exclude entire provider immediately on any 5xx
-      // Non-LongCat: skip only this specific model, other models from same provider remain available
       const errStatus = getErrorStatus(err);
       if (errStatus && isBanEligibleStatus(errStatus)) {
-        if (route.platform === 'longcat') {
-          console.warn(`[Proxy] 5xx from LongCat — excluding entire LongCat provider for session`);
-          banPlatformFromSession(normalizedMessages, routingMode, 'longcat', route.modelDbId);
-          addProviderModelsToSkipModels(skipModels, 'longcat');
-          // Clear sticky if pinned to LongCat
-          if (preferredModel) {
-            const db = getDb();
-            const prefRow = db.prepare('SELECT platform FROM models WHERE id = ?').get(preferredModel) as { platform: string } | undefined;
-            if (prefRow?.platform === 'longcat') {
-              preferredModel = undefined;
-              preferredKeyId = undefined;
-            }
-          }
-        } else {
-          console.warn(`[Proxy] 5xx from ${route.platform} — skipping model ${route.modelId} only`);
+        const action = evaluateThreadProtection({ platform: route.platform, kind: '5xx', midStream: false, modelDbId: route.modelDbId, error: err });
+        if (action.banProvider) {
+          console.warn(`[Proxy] 5xx from ${route.platform} — banning provider for session (${action.reason})`);
+          banPlatformFromSession(normalizedMessages, routingMode, route.platform, route.modelDbId);
+          addProviderModelsToSkipModels(skipModels, route.platform);
+        }
+        if (action.skipModel) {
+          console.warn(`[Proxy] 5xx from ${route.platform} — skipping model ${route.modelId} only (${action.reason})`);
           skipModels.add(route.modelDbId);
-       }
-     }
+        }
+        if (action.clearStickyIfPinned && preferredModel) {
+          const db = getDb();
+          const prefRow = db.prepare('SELECT platform FROM models WHERE id = ?').get(preferredModel) as { platform: string } | undefined;
+          if (prefRow?.platform === route.platform) {
+            preferredModel = undefined;
+            preferredKeyId = undefined;
+          }
+        }
+      }
 
      if (isRetryableError(err)) {
-        // LongCat: on any retryable error, exclude entire provider immediately
         // Register global transient cooldown for this failing model
         transientModelCooldowns.set(route.modelDbId, Date.now() + TRANSIENT_COOLDOWN_MS);
         console.log(`[TransientCooldown] registered global cooldown for modelDbId=${route.modelDbId} (${TRANSIENT_COOLDOWN_MS / 1000}s)`);
-        if (route.platform === 'longcat') {
-          console.warn(`[Proxy] Retryable error from LongCat — excluding entire LongCat provider for session`);
-          banPlatformFromSession(normalizedMessages, routingMode, 'longcat', route.modelDbId);
-          addProviderModelsToSkipModels(skipModels, 'longcat');
-          if (preferredModel) {
-            const db = getDb();
-            const prefRow = db.prepare('SELECT platform FROM models WHERE id = ?').get(preferredModel) as { platform: string } | undefined;
-            if (prefRow?.platform === 'longcat') {
-              preferredModel = undefined;
-              preferredKeyId = undefined;
-            }
+        const action = evaluateThreadProtection({ platform: route.platform, kind: 'retryable', midStream: false, modelDbId: route.modelDbId, error: err });
+        if (action.banProvider) {
+          console.warn(`[Proxy] Retryable error from ${route.platform} — banning provider for session (${action.reason})`);
+          banPlatformFromSession(normalizedMessages, routingMode, route.platform, route.modelDbId);
+          addProviderModelsToSkipModels(skipModels, route.platform);
+        }
+        if (action.skipModel) {
+          console.warn(`[Proxy] Retryable error from ${route.platform} — skipping model ${route.modelId} (${action.reason})`);
+          skipModels.add(route.modelDbId);
+        }
+        if (action.clearStickyIfPinned && preferredModel) {
+          const db = getDb();
+          const prefRow = db.prepare('SELECT platform FROM models WHERE id = ?').get(preferredModel) as { platform: string } | undefined;
+          if (prefRow?.platform === route.platform) {
+            preferredModel = undefined;
+            preferredKeyId = undefined;
           }
-        } else {
-          // Non-LongCat: skip the specific key that failed
+        }
+        if (!action.banProvider) {
+          // Key-level retry handling for non-provider-ban platforms
           const skipId = `${route.platform}:${route.modelId}:${route.keyId}`;
           skipKeys.add(skipId);
           // Non-rate-limit, non-auth errors: skip the model so fallback moves to a different model
diff --git a/server/src/services/threadProtection.ts b/server/src/services/threadProtection.ts
index ab13bd58..5a1b9a85 100644
--- a/server/src/services/threadProtection.ts
+++ b/server/src/services/threadProtection.ts
@@ -5,19 +5,115 @@ export type ErrorContextKind = '5xx' | 'truncation' | 'retryable';
 export interface ErrorContext {
   platform: string;
   kind: ErrorContextKind;
+  /** Whether the error occurred mid-stream (after SSE headers sent) */
   midStream: boolean;
+  /** The model DB ID — always available */
   modelDbId: number;
+  /** The error object, for logging */
   error?: unknown;
 }
 
 export interface ThreadProtectionAction {
+  /** Ban the entire platform for this session */
   banProvider: boolean;
+  /** Skip just this model */
   skipModel: boolean;
+  /** Clear sticky model/key if pinned to this platform */
   clearStickyIfPinned: boolean;
+  /** Human-readable reason for logging */
   reason: string;
 }
 
-export function evaluateThreadProtection(_ctx: ErrorContext): ThreadProtectionAction {
-  // Placeholder implementation: no protection
-  return { banProvider: false, skipModel: false, clearStickyIfPinned: false, reason: 'off' };
+// ── Configuration ──
+
+/**
+ * Parse the THREAD_PROTECTION_PLATFORMS env var into a protection map.
+ * Format: comma-separated list of `platform:level` pairs, e.g.
+ * "longcat:provider-ban,groq:model-skip"
+ *
+ * When unset or empty, returns the default protection map that preserves
+ * existing LongCat behavior (longcat → provider-ban) and applies model-skip
+ * to all other platforms. This ensures full backward compatibility.
+ */
+function parseProtectionConfig(raw: string | undefined): Map<string, ProtectionLevel> {
+  const map = new Map<string, ProtectionLevel>();
+
+  if (raw && raw.trim().length > 0) {
+    for (const pair of raw.split(',')) {
+      const trimmed = pair.trim();
+      if (!trimmed) continue;
+      const [platform, level] = trimmed.split(':');
+      if (!platform || !level) continue;
+      const normalizedLevel = level.trim().toLowerCase();
+      if (normalizedLevel === 'provider-ban' || normalizedLevel === 'model-skip' || normalizedLevel === 'off') {
+        map.set(platform.trim().toLowerCase(), normalizedLevel as ProtectionLevel);
+      }
+    }
+  }
+
+  // Default: longcat → provider-ban (preserves existing behavior)
+  // All other platforms → model-skip
+  if (!map.has('longcat')) {
+    map.set('longcat', 'provider-ban');
+  }
+
+  return map;
+}
+
+const protectionMap = parseProtectionConfig(process.env.THREAD_PROTECTION_PLATFORMS);
+
+/**
+ * Look up the protection level for a given platform.
+ * Returns 'model-skip' for platforms not explicitly configured (the safe default).
+ * Exported for use in proxy.ts sticky cooldown generalization.
+ */
+export function getProtectionLevel(platform: string): ProtectionLevel {
+  return protectionMap.get(platform.toLowerCase()) ?? 'model-skip';
 }
+
+// ── Decision matrix ──
+
+/**
+ * Evaluate error context against the configured protection rules and return
+ * the action the proxy should take.
+ *
+ * Decision matrix:
+ * | Protection Level | 5xx              | truncation       | retryable        |
+ * |------------------|------------------|------------------|------------------|
+ * | provider-ban     | banProvider=true | banProvider=true | banProvider=true |
+ * |                  | skipModel=false  | skipModel=false  | skipModel=false  |
+ * |                  | clearSticky=true | clearSticky=true | clearSticky=true |
+ * | model-skip       | banProvider=false| banProvider=false| banProvider=false|
+ * |                  | skipModel=true   | skipModel=true   | skipModel=true   |
+ * |                  | clearSticky=false| clearSticky=false| clearSticky=false|
+ * | off              | all false        | all false        | all false        |
+ */
+export function evaluateThreadProtection(ctx: ErrorContext): ThreadProtectionAction {
+  const level = getProtectionLevel(ctx.platform);
+
+  switch (level) {
+    case 'provider-ban':
+      return {
+        banProvider: true,
+        skipModel: false,
+        clearStickyIfPinned: true,
+        reason: `provider-ban:${ctx.kind}${ctx.midStream ? ':mid-stream' : ''}`,
+      };
+
+    case 'model-skip':
+      return {
+        banProvider: false,
+        skipModel: true,
+        clearStickyIfPinned: false,
+        reason: `model-skip:${ctx.kind}${ctx.midStream ? ':mid-stream' : ''}`,
+      };
+
+    case 'off':
+      return {
+        banProvider: false,
+        skipModel: false,
+        clearStickyIfPinned: false,
+        reason: 'off',
+      };
+  }
+}
\ No newline at end of file