@goodandready/dsh-key-rotation 0.8.75 → 0.8.77

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.8.77 (2026-10-30)
+
+### Session Routing, Typed Error Taxonomy & Pre-First-Token Failover (Block 5 Release)
+- **Pre-First-Token Failover & Request Attempt Loop (Issue #527)**: Introduced transaction-safe pre-first-token retry loop in `lib/rotate.js` with canonical `isContentChunk` detector (distinguishes model-visible tokens from stream envelopes and metadata). Stream metadata (such as `block-start`, `response-metadata`) emitted prior to the first content chunk is securely buffered; upon upstream failures (HTTP 429, 502, 503, connection drops) before any content token yields, the buffered metadata is cleanly discarded and the request seamlessly transitions to the next available healthy key without chat UI disruption or duplicate blocks.
+- **Typed Error Taxonomy & Canonical classifyResponseError (Issue #547)**: Implemented `lib/errors.js` with structured envelope parsing for OpenAI, Anthropic, Google Gemini, Groq, and Ollama. Added robust RFC 1123 HTTP-Date and numeric seconds parser for `Retry-After` headers converting to exact millisecond cooldowns; mapped provider failures into typed `@deepseek-ai/dsh-llm` `LlmError` instances (`QUOTA`, `ACCOUNT_QUOTA`, `RATE_LIMIT`, `CONTEXT_WINDOW_EXCEEDED`, `INVALID_CREDENTIAL`, `SERVER`, `TIMEOUT`); updated `isSwitchableError` and `classifyFailure` to replace brittle text regex matching with structured JSON payload classification.
+- **Bounded SessionRouter with LRU & Proactive Unsticking (Issue #548)**: Created standalone domain service `SessionRouter` (`lib/session-router.js`) with capacity limit (`MAX_SESSIONS = 1000`) and automatic 24-hour TTL expiration (`SESSION_TTL_MS`). Integrated Least-Used Initial Assignment to distribute new incoming sessions across least-loaded keys; implemented `unstickKey(failedKey)` in `lib/pool-selection.js` and key penalization to proactively unbind all sessions pinned to failed or cooling keys, guaranteeing seamless transparent failover on consecutive prompts.
+
+## 0.8.76 (2026-10-30)
+
+### Security Hardening, DNS Pinning & Mutation Integrity (Block 4 Release)
+- **SSRF DNS Rebinding Prevention (Issue #557)**: Replaced single-shot DNS precheck with connect-time socket IP validation (`createSafeLookup`) via native HTTPS request handling (`fetchNativeJson`). Enforces loopback and private IP rejection at the exact moment the socket establishes connection across all attempts and redirects, completely neutralizing TOCTOU DNS rebinding with zero runtime dependencies.
+- **Write-Origin Guard & Desktop Spoofing Elimination (Issue #516)**: Added `hasNonLoopbackForwarding` to detect requests proxied through LAN reverse proxies (`x-forwarded-for`, `x-real-ip`). Refused mutating requests (POST/PUT/DELETE/PATCH) lacking Origin or attempting to spoof Desktop headers (`@deepseek-ai/dsh-desktop/` User-Agent, `dsh-auth-` cookies, or `dsh-app://app` Origin) over LAN; ensured `/auto-import` strictly validates bodies and fails closed.
+- **Config Import Optimistic Concurrency & Revision Integrity (Issue #553)**: End-to-end optimistic revision tracking in config import; dry-run preview returns settings revision, WebUI client (`50-card-main.js`) stores preview revision and transmits `expectedRevision` upon apply; backend validates revision match and converts `SETTINGS_CONFLICT` during `settings.replace` into HTTP 409 Conflict with clear preview invalidation guidance instead of generic 500 errors.
+
 ## 0.8.75 (2026-10-30)
 
 ### Dependencies, Cleanup & Audit Finalization (Block 3 Release)

package/lib/client.js

@@ -1316,6 +1316,7 @@ window.__ModuleLoader__.load({
       const [importPassphrase, setImportPassphrase] = React.useState('');
       const [importMode, setImportMode] = React.useState('merge');
       const [importPreview, setImportPreview] = React.useState(null);
+      const [importRevision, setImportRevision] = React.useState(null);
       const [importError, setImportError] = React.useState('');
       const [importRunning, setImportRunning] = React.useState(false);
 
@@ -1358,6 +1359,7 @@ window.__ModuleLoader__.load({
       const runImportPreview = async () => {
         setImportError('');
         setImportPreview(null);
+        setImportRevision(null);
         setImportRunning(true);
         try {
           let parsed;
@@ -1381,6 +1383,7 @@ window.__ModuleLoader__.load({
           const data = await res.json();
           if (!res.ok || !data.ok) throw new Error(data?.error?.message || 'Import preview failed');
           setImportPreview(data.preview);
+          setImportRevision(data.revision ?? null);
         } catch (err) {
           setImportError(String(err?.message ?? err));
         } finally {
@@ -1406,14 +1409,23 @@ window.__ModuleLoader__.load({
               encrypted: parsed.encrypted,
               passphrase: importPassphrase.trim() || undefined,
               mode: importMode,
+              expectedRevision: importRevision !== null ? importRevision : undefined,
               dryRun: false,
             }),
             signal: (typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function') ? AbortSignal.timeout(10000) : undefined,
           });
           const data = await res.json();
-          if (!res.ok || !data.ok) throw new Error(data?.error?.message || 'Import apply failed');
+          if (!res.ok || !data.ok) {
+            if (res.status === 409 || data?.error?.code === 'conflict') {
+              setImportPreview(null);
+              setImportRevision(null);
+              throw new Error(data?.error?.message || 'Configuration was modified concurrently. Please preview again before applying.');
+            }
+            throw new Error(data?.error?.message || 'Import apply failed');
+          }
           setImportModal(false);
           setImportPreview(null);
+          setImportRevision(null);
           setImportText('');
           void load();
         } catch (err) {

package/lib/error-taxonomy.js

@@ -1,13 +1,35 @@
-import { SOFT_FAILURE_CODES } from './pool.js';
-// lib/error-taxonomy.js — complete failure classification (#267).
+// lib/error-taxonomy.js — complete failure classification (#267, #547).
 // action: 'switch' | 'surface' | 'cooldown'
 
+import { SOFT_FAILURE_CODES } from './pool.js';
+import {
+  classifyResponseError,
+  parseErrorBody,
+  retryAfterMs,
+  CONTEXT_WINDOW_EXCEEDED_CODE,
+  QUOTA_EXCEEDED_CODE,
+  ACCOUNT_QUOTA_EXCEEDED_CODE,
+  EMPTY_RESPONSE_CODE,
+  INVALID_CREDENTIAL_CODE,
+} from './errors.js';
+
+export {
+  classifyResponseError,
+  parseErrorBody,
+  retryAfterMs,
+  CONTEXT_WINDOW_EXCEEDED_CODE,
+  QUOTA_EXCEEDED_CODE,
+  ACCOUNT_QUOTA_EXCEEDED_CODE,
+  EMPTY_RESPONSE_CODE,
+  INVALID_CREDENTIAL_CODE,
+};
+
 const SWITCH_STATUS = new Set([408, 425, 429, 500, 502, 503, 504]);
 const SURFACE_STATUS = new Set([400, 404, 422]);
 const AUTH_STATUS = new Set([401, 403]);
 
 const SWITCH_CODES = new Set([
-  'QUOTA', 'RATE_LIMIT', 'SERVER', 'TIMEOUT', 'TRANSPORT', 'EMPTY_RESPONSE',
+  'QUOTA', 'ACCOUNT_QUOTA', 'RATE_LIMIT', 'SERVER', 'TIMEOUT', 'TRANSPORT', 'EMPTY_RESPONSE',
   'UNKNOWN_MODEL', 'AUTH', 'RESOURCE_EXHAUSTED', 'UNAVAILABLE', 'INTERNAL',
   'DEADLINE_EXCEEDED', 'UNAUTHENTICATED', 'PERMISSION_DENIED', 'ABORTED',
 ]);
@@ -19,7 +41,7 @@ const SOCKET_SWITCH = new Set([
 /**
  * Classify a failure for rotation.
  * @param {any} failureOrPayload
- * @returns {{ action: 'switch'|'surface'|'cooldown', code: string, soft: boolean, reason: string }}
+ * @returns {{ action: 'switch'|'surface'|'cooldown', code: string, soft: boolean, reason: string, retryAfterMs?: number }}
  */
 export function classifyFailure(failureOrPayload) {
   if (!failureOrPayload) {
@@ -29,18 +51,46 @@ export function classifyFailure(failureOrPayload) {
   const status = Number(failure.status ?? failure.statusCode ?? failure.httpStatus ?? 0);
   const code = String(failure.code ?? failure.reason ?? failure.name ?? '').toUpperCase();
   const message = String(failure.message ?? failureOrPayload.message ?? '');
+  const headers = failure.headers ?? failureOrPayload.headers ?? failure.response?.headers;
+  const retryMs = retryAfterMs(headers);
+
+  // Check structured body/error through classifyResponseError if available
+  if (status || failure.body || (code && code !== 'ERROR')) {
+    const typed = classifyResponseError(status, failure.body ?? message, headers);
+    if (typed.code === CONTEXT_WINDOW_EXCEEDED_CODE) {
+      return { action: 'surface', code: CONTEXT_WINDOW_EXCEEDED_CODE, soft: false, reason: 'context_window' };
+    }
+  }
 
-  if (AUTH_STATUS.has(status) || code === 'AUTH' || code === 'UNAUTHENTICATED' || code === 'PERMISSION_DENIED') {
-    return { action: 'switch', code: status ? String(status) : (code || 'AUTH'), soft: false, reason: 'auth' };
+  if (AUTH_STATUS.has(status) || code === 'AUTH' || code === 'UNAUTHENTICATED' || code === 'PERMISSION_DENIED' || code === INVALID_CREDENTIAL_CODE) {
+    return {
+      action: 'switch',
+      code: status ? String(status) : (code || 'AUTH'),
+      soft: false,
+      reason: 'auth',
+      ...(retryMs !== undefined ? { retryAfterMs: retryMs } : {}),
+    };
   }
-  if (status === 429 || code === 'RATE_LIMIT' || code === 'RESOURCE_EXHAUSTED' || code === 'QUOTA') {
-    return { action: 'switch', code: status ? '429' : (code || 'RATE_LIMIT'), soft: false, reason: 'quota' };
+  if (status === 429 || code === 'RATE_LIMIT' || code === 'RESOURCE_EXHAUSTED' || code === 'QUOTA' || code === 'ACCOUNT_QUOTA' || code === QUOTA_EXCEEDED_CODE) {
+    return {
+      action: 'switch',
+      code: status ? '429' : (code || 'RATE_LIMIT'),
+      soft: false,
+      reason: 'quota',
+      ...(retryMs !== undefined ? { retryAfterMs: retryMs } : {}),
+    };
   }
   const numCode = Number(code);
   if (SWITCH_STATUS.has(status) || (numCode > 0 && SWITCH_STATUS.has(numCode)) || SOFT_FAILURE_CODES.has(code)) {
     const effCode = status ? String(status) : (numCode > 0 ? String(numCode) : code);
     const soft = SOFT_FAILURE_CODES.has(effCode);
-    return { action: 'switch', code: effCode, soft, reason: 'http' };
+    return {
+      action: 'switch',
+      code: effCode,
+      soft,
+      reason: 'http',
+      ...(retryMs !== undefined ? { retryAfterMs: retryMs } : {}),
+    };
   }
   if (SURFACE_STATUS.has(status)) {
     return { action: 'surface', code: String(status), soft: false, reason: 'client' };
@@ -63,4 +113,3 @@ export function classifyFailure(failureOrPayload) {
   return { action: 'surface', code: code || 'UNKNOWN', soft: false, reason: 'unclassified' };
 }
 
-/** True when classification says switch to next key. */

package/lib/errors.js

@@ -0,0 +1,302 @@
+// lib/errors.js — Canonical error classification and taxonomy for DeepSeek Harness (#547).
+// Unifies error shapes across OpenAI, Anthropic, Gemini, Ollama, Groq and OpenCode into standard LlmError.
+
+import {
+  HarnessError as DshHarnessError,
+  LlmError as DshLlmError,
+  CONTEXT_WINDOW_EXCEEDED_CODE,
+  QUOTA_EXCEEDED_CODE,
+  ACCOUNT_QUOTA_EXCEEDED_CODE,
+  EMPTY_RESPONSE_CODE,
+  INVALID_CREDENTIAL_CODE,
+  isContextWindowExceededError,
+  isQuotaExceededError,
+} from '@deepseek-ai/dsh-llm';
+
+export {
+  CONTEXT_WINDOW_EXCEEDED_CODE,
+  QUOTA_EXCEEDED_CODE,
+  ACCOUNT_QUOTA_EXCEEDED_CODE,
+  EMPTY_RESPONSE_CODE,
+  INVALID_CREDENTIAL_CODE,
+  isContextWindowExceededError,
+  isQuotaExceededError,
+};
+
+// Fallback HarnessError and LlmError if ever decoupled from runtime
+export class HarnessError extends (DshHarnessError || Error) {
+  constructor(message, code, options) {
+    super(message, code, options);
+    this.code = code;
+    this.name = this.constructor.name;
+  }
+}
+
+export class LlmError extends (DshLlmError || HarnessError) {
+  constructor(message, code, options) {
+    super(message, code, options);
+    this.status = options?.status;
+    this.providerRetryAfterMs = options?.providerRetryAfterMs;
+    this.code = code;
+    this.name = this.constructor.name;
+  }
+}
+
+/**
+ * Robust parser for structured error bodies (JSON, object, text).
+ * Handles OpenAI, Anthropic, Gemini, Groq, Ollama envelopes.
+ *
+ * @param {unknown} body
+ * @returns {{ message?: string, type?: string, code?: string, status?: number, raw?: unknown }}
+ */
+export function parseErrorBody(body) {
+  if (!body) return {};
+  if (typeof body === 'object') {
+    return extractErrorFields(body);
+  }
+  if (typeof body === 'string') {
+    const trimmed = body.trim();
+    if (!trimmed) return {};
+    if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+      try {
+        const parsed = JSON.parse(trimmed);
+        return extractErrorFields(parsed);
+      } catch {
+        // Not valid JSON, return as plain message
+      }
+    }
+    return { message: trimmed.slice(0, 1000) };
+  }
+  return { message: String(body).slice(0, 1000) };
+}
+
+function extractErrorFields(obj) {
+  if (!obj || typeof obj !== 'object') return {};
+  const outer = obj;
+  const nested = outer.error;
+
+  let message = outer.message;
+  let type = outer.type;
+  let code = outer.code;
+  let status = outer.status;
+
+  if (typeof nested === 'string') {
+    message = nested;
+  } else if (nested && typeof nested === 'object' && !Array.isArray(nested)) {
+    if (typeof nested.message === 'string') message = nested.message;
+    if (typeof nested.type === 'string') type = nested.type;
+    if (nested.code !== undefined && nested.code !== null) code = String(nested.code);
+    if (typeof nested.status === 'number' || typeof nested.status === 'string') {
+      const s = Number(nested.status);
+      if (Number.isFinite(s)) status = s;
+    }
+  }
+
+  // Handle gRPC style status object: { code: 8, message: "Resource exhausted", details: [...] }
+  if (outer.details && Array.isArray(outer.details) && outer.details.length > 0) {
+    const firstDetail = outer.details[0];
+    if (firstDetail && typeof firstDetail === 'object') {
+      if (!message && typeof firstDetail.message === 'string') message = firstDetail.message;
+      if (!type && typeof firstDetail.reason === 'string') type = firstDetail.reason;
+    }
+  }
+
+  return {
+    ...(message ? { message: String(message) } : {}),
+    ...(type ? { type: String(type) } : {}),
+    ...(code !== undefined && code !== null ? { code: String(code) } : {}),
+    ...(typeof status === 'number' ? { status } : {}),
+    raw: obj,
+  };
+}
+
+/**
+ * Parse Retry-After value from Headers, headers object, or string into milliseconds.
+ *
+ * @param {Headers | Record<string, string | string[]> | string | null | undefined} headers
+ * @param {number} [now=Date.now()]
+ * @returns {number | undefined}
+ */
+export function retryAfterMs(headers, now = Date.now()) {
+  if (!headers) return undefined;
+  let raw = '';
+  if (typeof headers === 'string') {
+    const m = headers.match(/retry-after\s*[:=]\s*(.+)/i);
+    raw = m ? m[1].trim().split(/[\n\r;]/)[0].trim() : headers.trim();
+  } else if (typeof headers.get === 'function') {
+    raw = headers.get('retry-after') || headers.get('x-ratelimit-reset-after') || '';
+  } else if (typeof headers === 'object') {
+    for (const [k, v] of Object.entries(headers)) {
+      if (k.toLowerCase() === 'retry-after' || k.toLowerCase() === 'x-ratelimit-reset-after') {
+        raw = Array.isArray(v) ? v[0] : String(v || '');
+        break;
+      }
+    }
+  }
+
+  raw = String(raw).trim();
+  if (!raw) return undefined;
+
+  // 1. Seconds format: integer or float
+  const seconds = Number(raw);
+  if (Number.isFinite(seconds) && seconds >= 0 && seconds <= 86400 * 7) {
+    return Math.trunc(seconds * 1000);
+  }
+
+  // 2. HTTP-Date format: RFC 1123 / RFC 850
+  const parsedTs = Date.parse(raw);
+  if (Number.isFinite(parsedTs)) {
+    const diff = parsedTs - now;
+    return diff > 0 && diff < 86400 * 7 * 1000 ? Math.trunc(diff) : 0;
+  }
+
+  return undefined;
+}
+
+/**
+ * Determine if text/detail indicates quota or balance exhaustion.
+ *
+ * @param {string} detail
+ * @returns {boolean}
+ */
+export function isQuotaDetail(detail) {
+  if (!detail) return false;
+  if (isQuotaExceededError(detail)) return true;
+  const d = detail.toLowerCase();
+  return (
+    d.includes('insufficient_quota') ||
+    d.includes('insufficient balance') ||
+    d.includes('insufficient credits') ||
+    d.includes('out of credits') ||
+    d.includes('out of budget') ||
+    d.includes('quota exceeded') ||
+    d.includes('usage limit exceeded') ||
+    d.includes('resource_exhausted') ||
+    d.includes('credit balance') ||
+    d.includes('monthly limit') ||
+    d.includes('weekly limit') ||
+    d.includes('payment required')
+  );
+}
+
+/**
+ * Canonical classifier translating status, body and headers into typed LlmError (#547).
+ *
+ * @param {number} status HTTP status code
+ * @param {unknown} body Response body (string, object, buffer)
+ * @param {Headers | Record<string, unknown> | null | undefined} headers Response headers
+ * @param {{ now?: number }} [options]
+ * @returns {LlmError}
+ */
+export function classifyResponseError(status, body, headers, options = {}) {
+  const now = options.now ?? Date.now();
+  const parsed = parseErrorBody(body);
+  const type = parsed.type ?? '';
+  const message = parsed.message ?? (status ? `HTTP ${status}` : 'Unknown upstream error');
+  const code = (parsed.code ?? '').toUpperCase();
+  const detail = `${type} ${code} ${message}`.trim();
+  const retryMs = retryAfterMs(headers, now);
+
+  const validStatus = Number.isInteger(status) && status >= 100 && status <= 599 ? status : undefined;
+  const errorOptions = {
+    ...(validStatus !== undefined ? { status: validStatus } : {}),
+    ...(retryMs !== undefined ? { providerRetryAfterMs: retryMs } : {}),
+    ...(parsed.raw ? { cause: parsed.raw } : {}),
+  };
+
+  // 1. Context window exceeded
+  if (code === CONTEXT_WINDOW_EXCEEDED_CODE || isContextWindowExceededError(detail)) {
+    return new LlmError(message, CONTEXT_WINDOW_EXCEEDED_CODE, errorOptions);
+  }
+
+  // 2. Authentication & Credentials (401, 403, invalid_api_key)
+  if (
+    status === 401 ||
+    status === 403 ||
+    code === 'INVALID_API_KEY' ||
+    code === 'UNAUTHENTICATED' ||
+    code === 'PERMISSION_DENIED' ||
+    type === 'authentication_error' ||
+    type === 'permission_denied'
+  ) {
+    const isMalformed = /malformed|invalid|bad|incorrect/i.test(detail);
+    return new LlmError(
+      message,
+      isMalformed ? INVALID_CREDENTIAL_CODE : 'AUTH',
+      errorOptions
+    );
+  }
+
+  // 3. Quota & Balance exhaustion (429 or 402 with quota phrasing)
+  if (
+    status === 402 ||
+    code === 'QUOTA' ||
+    code === 'RESOURCE_EXHAUSTED' ||
+    code === 'INSUFFICIENT_QUOTA' ||
+    isQuotaDetail(detail)
+  ) {
+    const isAccount = /account|billing|subscription|replenish/i.test(detail);
+    return new LlmError(
+      message,
+      isAccount ? ACCOUNT_QUOTA_EXCEEDED_CODE : QUOTA_EXCEEDED_CODE,
+      errorOptions
+    );
+  }
+
+  // 4. Rate Limiting (429 without quota exhaustion, concurrency limits)
+  if (
+    status === 429 ||
+    code === 'RATE_LIMIT' ||
+    code === 'RATE_LIMIT_EXCEEDED' ||
+    type === 'rate_limit_error' ||
+    /rate[\s_-]?limit|too many requests|concurrency[\s_-]+limit|rpm|tpm/i.test(detail)
+  ) {
+    return new LlmError(message, 'RATE_LIMIT', errorOptions);
+  }
+
+  // 5. Unknown Model (explicit model_not_found or invalid_model)
+  if (
+    code === 'MODEL_NOT_FOUND' ||
+    code === 'UNKNOWN_MODEL' ||
+    type === 'invalid_model' ||
+    /model[_\s]+not[_\s]+found|unknown[_\s]+model/i.test(detail)
+  ) {
+    return new LlmError(message, 'UNKNOWN_MODEL', errorOptions);
+  }
+
+  // 6. Timeouts (408, 504, DEADLINE_EXCEEDED)
+  if (
+    status === 408 ||
+    status === 504 ||
+    code === 'TIMEOUT' ||
+    code === 'DEADLINE_EXCEEDED' ||
+    /timeout|timed[\s_-]?out/i.test(detail)
+  ) {
+    return new LlmError(message, 'TIMEOUT', errorOptions);
+  }
+
+  // 7. Server Errors (500, 502, 503)
+  if (
+    (status >= 500 && status <= 503) ||
+    code === 'SERVER' ||
+    code === 'INTERNAL' ||
+    code === 'UNAVAILABLE' ||
+    type === 'server_error' ||
+    type === 'api_error'
+  ) {
+    return new LlmError(message, 'SERVER', errorOptions);
+  }
+
+  // 8. Empty response
+  if (code === EMPTY_RESPONSE_CODE || (!message && status === 200)) {
+    return new LlmError(message || 'Upstream returned empty completion', EMPTY_RESPONSE_CODE, errorOptions);
+  }
+
+  // 9. Default client error (400, 422) or generic provider error
+  if (status >= 400 && status < 500) {
+    return new LlmError(message, code || String(status), errorOptions);
+  }
+
+  return new LlmError(message, code || 'PROVIDER_ERROR', errorOptions);
+}
+

package/lib/index.js

@@ -57,6 +57,9 @@ export const name = '@goodandready/dsh-key-rotation';
 export const inject = ['llm', 'webServer', 'settings', 'credentials'];
 export { keyTail, KEY_TAIL_CHARS, KEY_TAIL_PLACEHOLDER, isLoopbackAddress, isTrustedBridgeRequest, isDesktopShellRequest, DEFAULT_SWITCH_CODES, isSwitchableError, formatExhaustionMessage, getRuntime };
 export { notifySwitch, notifyExhaustion, notifyEarlyWarning };
+export { classifyResponseError } from './errors.js';
+export { SessionRouter, defaultSessionRouter, unstickFailedKey } from './session-router.js';
+export { isContentChunk } from './rotate.js';
 
 const NS = 'dsh-key-rotation';
 

package/lib/ops-config-io.js

@@ -349,15 +349,24 @@ export function registerConfigIoRoutes(ctx, deps) {
     }
     const rawCurrent = plainConfig(currentConfig);
 
-    // Concurrency control: if client provided expectedRevision, reject if stale (#553)
-    if (typeof body.expectedRevision === 'number' && currentRevision !== null) {
-      if (body.expectedRevision !== currentRevision) {
+    // Concurrency control: validate expectedRevision format and match (#553)
+    if (body.expectedRevision !== undefined && body.expectedRevision !== null) {
+      if (!Number.isSafeInteger(body.expectedRevision) || body.expectedRevision < 0) {
+        json(res, 400, {
+          error: {
+            code: 'bad-request',
+            message: 'expectedRevision must be a non-negative integer',
+          },
+        });
+        return;
+      }
+      if (currentRevision !== null && body.expectedRevision !== currentRevision) {
         json(res, 409, {
           error: {
             code: 'conflict',
             message: `Configuration has been modified concurrently (expected revision ${body.expectedRevision}, current is ${currentRevision})`,
             currentRevision,
-          }
+          },
         });
         return;
       }
@@ -406,8 +415,26 @@ export function registerConfigIoRoutes(ctx, deps) {
     }
 
     try {
-      await settings.replace(NS, mergedConfig, currentRevision ?? undefined);
+      await settings.replace(NS, mergedConfig, body.expectedRevision ?? currentRevision ?? undefined);
     } catch (err) {
+      const isConflict = err?.code === 'SETTINGS_CONFLICT' ||
+        err?.status === 409 ||
+        err?.code === 'CONFLICT' ||
+        /conflict|revision|stale/i.test(err?.message || '');
+      if (isConflict) {
+        let latestRevision = null;
+        try {
+          latestRevision = settings.describe({ redactSecrets: false })?.find((c) => c.ns === NS)?.revision ?? null;
+        } catch (_) {}
+        json(res, 409, {
+          error: {
+            code: 'conflict',
+            message: `Configuration has been modified concurrently: ${err.message}`,
+            currentRevision: latestRevision ?? currentRevision,
+          },
+        });
+        return;
+      }
       json(res, 500, { error: { code: 'settings-write-failed', message: err.message } });
       return;
     }

package/lib/pool-selection.js

@@ -1,30 +1,91 @@
-// lib/pool-selection.js — pool selection, sticky sessions, attempt sorting and budget metrics (#512).
+// lib/pool-selection.js — pool selection, sticky sessions, attempt sorting and budget metrics (#512, #548).
 // Extracted from lib/pool.js to enforce < 600 line modularity standard.
 
-export const MAX_SESSION_STICKY_ENTRIES = 500;
+import {
+  SessionRouter,
+  defaultSessionRouter,
+  MAX_SESSIONS,
+  SESSION_TTL_MS,
+} from './session-router.js';
 
-export function setSessionSticky(pool, sessionId, candidate) {
-  if (!sessionId || !candidate || !pool?.state) return;
-  if (!(pool.state.sessionSticky instanceof Map)) {
-    pool.state.sessionSticky = new Map();
+export {
+  SessionRouter,
+  defaultSessionRouter,
+  MAX_SESSIONS,
+  SESSION_TTL_MS,
+};
+
+export const MAX_SESSION_STICKY_ENTRIES = MAX_SESSIONS;
+
+/**
+ * Get or initialize the SessionRouter on pool.state or fallback to default.
+ * @param {object} [pool]
+ * @returns {SessionRouter}
+ */
+export function getOrCreateSessionRouter(pool) {
+  if (!pool?.state) return defaultSessionRouter;
+  if (!pool.state.sessionRouter) {
+    pool.state.sessionRouter = new SessionRouter({
+      maxSessions: MAX_SESSIONS,
+      sessionTtlMs: SESSION_TTL_MS,
+    });
   }
-  if (pool.state.sessionSticky.has(sessionId)) {
-    pool.state.sessionSticky.delete(sessionId);
-  } else if (pool.state.sessionSticky.size >= MAX_SESSION_STICKY_ENTRIES) {
-    const oldest = pool.state.sessionSticky.keys().next().value;
-    if (oldest !== undefined) pool.state.sessionSticky.delete(oldest);
+  return pool.state.sessionRouter;
+}
+
+export function setSessionSticky(pool, sessionId, candidate) {
+  if (!sessionId || !candidate) return;
+  const router = getOrCreateSessionRouter(pool);
+  router.setSession(sessionId, candidate);
+  if (pool?.state) {
+    if (!(pool.state.sessionSticky instanceof Map)) {
+      pool.state.sessionSticky = new Map();
+    }
+    if (pool.state.sessionSticky.has(sessionId)) {
+      pool.state.sessionSticky.delete(sessionId);
+    } else if (pool.state.sessionSticky.size >= MAX_SESSION_STICKY_ENTRIES) {
+      const oldest = pool.state.sessionSticky.keys().next().value;
+      if (oldest !== undefined) pool.state.sessionSticky.delete(oldest);
+    }
+    pool.state.sessionSticky.set(sessionId, candidate);
   }
-  pool.state.sessionSticky.set(sessionId, candidate);
 }
 
 export function getSessionSticky(pool, sessionId) {
-  if (!sessionId || !pool?.state?.sessionSticky) return null;
-  return pool.state.sessionSticky.get(sessionId) ?? null;
+  if (!sessionId) return null;
+  const router = getOrCreateSessionRouter(pool);
+  const fromRouter = router.getSession(sessionId);
+  if (fromRouter) return fromRouter;
+  return pool?.state?.sessionSticky?.get?.(sessionId) ?? null;
 }
 
 export function clearSessionSticky(pool, sessionId) {
-  if (!sessionId || !pool?.state?.sessionSticky) return;
-  pool.state.sessionSticky.delete(sessionId);
+  if (!sessionId) return;
+  const router = getOrCreateSessionRouter(pool);
+  router.unstick(sessionId);
+  if (pool?.state?.sessionSticky) {
+    pool.state.sessionSticky.delete(sessionId);
+  }
+}
+
+/**
+ * Proactively unstick all sessions pinned to a cooling or failed key (#548).
+ * @param {object} pool
+ * @param {string} keyRef
+ * @returns {number}
+ */
+export function unstickFailedKey(pool, keyRef) {
+  if (!keyRef) return 0;
+  const router = getOrCreateSessionRouter(pool);
+  const count = router.unstickKey(keyRef);
+  if (pool?.state?.sessionSticky) {
+    for (const [sId, ref] of pool.state.sessionSticky.entries()) {
+      if (ref === keyRef) {
+        pool.state.sessionSticky.delete(sId);
+      }
+    }
+  }
+  return count;
 }
 
 /** Pick a key pool for a (provider, model) pair. */
@@ -48,10 +109,23 @@ export function sortAttemptList(refs, strategy = 'round-robin', deps = {}) {
   if (!Array.isArray(refs) || refs.length <= 1) return (refs ?? []).slice();
   const list = refs.slice();
   if (strategy === 'sticky') {
-    const last = deps.sessionSticky ||
+    const router = getOrCreateSessionRouter(deps.pool);
+    let chosenKey = null;
+
+    if (deps.sessionId) {
+      const resolved = router.resolveSessionKey(deps.sessionId, list);
+      if (resolved && resolved.keyRef) {
+        chosenKey = resolved.keyRef;
+        if (deps.pool) setSessionSticky(deps.pool, deps.sessionId, chosenKey);
+      }
+    }
+
+    const last = chosenKey ||
+      deps.sessionSticky ||
       (deps.sessionId && (deps.pool?.state?.sessionSticky?.get?.(deps.sessionId) || deps.sessionStickyMap?.get?.(deps.sessionId))) ||
       deps.lastUsed ||
       (deps.pool && deps.pool.state && deps.pool.state.lastUsed);
+
     if (last && list.includes(last)) {
       const idx = list.indexOf(last);
       if (idx > 0) {
@@ -147,3 +221,4 @@ export function budgetVerdict(spend, budget) {
   const ratio = spend / budget;
   return { spend, budget, ratio, warn: ratio >= 0.8, exceeded: ratio >= 1 };
 }
+