chore(quality): rebaseline eslintWarnings 4090->4103 — v3.8.40 cycle drift

+13 inherited cycle drift (any warn-allowed in open-sse/ + tests/) measured via
quality:collect on the release tip including reconciliation; my regression test
fixes add 0 new warnings. Same precedent as prior cycle-close rebaselines.

.dockerignore

@@ -77,6 +77,8 @@ bun.lock
 # Agent config
 .agents
 .gemini
+.claude
+.source
 
 # Misc
 llm.txt

.env.example

@@ -56,10 +56,12 @@ STORAGE_ENCRYPTION_KEY_VERSION=v1
 DISABLE_SQLITE_AUTO_BACKUP=false
 
 # ── Redis (Rate Limiting) ──
-# Redis connection URL for the rate limiter backend.
+# Redis connection URL for the rate limiter backend. OPT-IN: leave this
+# commented out to use the built-in in-memory rate limiter. Setting it to a
+# non-running localhost (#4878) makes ioredis flood "[REDIS] Error:" logs.
 # Used by: src/shared/utils/rateLimiter.ts
-# Default: redis://localhost:6379 (or redis://redis:6379 in Docker)
-REDIS_URL=redis://localhost:6379
+# Example: redis://localhost:6379 (or redis://redis:6379 in Docker)
+# REDIS_URL=redis://localhost:6379
 
 # ═══════════════════════════════════════════════════════════════════════════════
 # 3. NETWORK & PORTS
@@ -109,13 +111,19 @@ PORT=20128
 # Used by: src/app/api/v1/relay/chat/completions/route.ts
 # RELAY_IP_PER_MINUTE=30
 
-# Bundler selection for `npm run dev`. Set to 1 to opt into Turbopack.
-# Default is 0 (webpack) because Turbopack 16.2.x panics on the OmniRoute
-# module graph with "internal error: entered unreachable code: there must be
-# a path to a root" (turbopack-core/module_graph/mod.rs:662). Same bug class
-# the production Docker build worked around in PR #4052. Webpack starts
-# slower but compiles cleanly. Re-enable once upstream Turbopack ships a fix.
-OMNIROUTE_USE_TURBOPACK=0
+# Bundler selection for `npm run dev`. Set to 0 to fall back to webpack.
+# Default is 1 (Turbopack). PR #4092 had forced webpack because earlier
+# Turbopack 16.2.x panicked on the OmniRoute module graph with "internal error:
+# entered unreachable code: there must be a path to a root"
+# (turbopack-core/module_graph/mod.rs:662). That panic no longer reproduces on
+# the pinned Next 16.2.9 — verified across a broad cold-compile sweep (36
+# dashboard routes + open-sse-heavy API routes incl. /api/v1/chat/completions,
+# /api/v1/models, /api/mcp) and repeated HMR rebuilds: zero panics. Turbopack
+# also keeps dev memory far lower on the edit→rebuild loop (HMR rebuild RSS stays
+# ~flat vs webpack's monotonic growth), which mitigates the dev-server OOM on
+# this 60+ route app. The production build still uses webpack (build pipeline is
+# unaffected by this dev-only flag).
+OMNIROUTE_USE_TURBOPACK=1
 
 # Skip the SQLite integrity health check on startup (faster boot on large DBs).
 # Used by: src/lib/db/core.ts, src/lib/db/healthCheck.ts. Set to 1 to skip.
@@ -231,10 +239,13 @@ ALLOW_API_KEY_REVEAL=false
 # Default: 10485760 (10 MB)
 # MAX_BODY_SIZE_BYTES=10485760
 
-# CORS configuration — controls which origins can call the API.
-# Used by: Next.js middleware — sets Access-Control-Allow-Origin header.
-# Default: * (all origins)  |  Restrict for production security.
-# CORS_ORIGIN=https://your-domain.com
+# CORS configuration — controls which cross-origin browser clients can call the API.
+# Used by: src/server/cors/origins.ts — sets Access-Control-Allow-Origin.
+# Same-origin dashboard requests behind a reverse proxy do not need CORS; set
+# NEXT_PUBLIC_BASE_URL instead. No wildcard is sent unless CORS_ALLOW_ALL=true.
+# CORS_ALLOWED_ORIGINS=https://your-frontend.example.com
+# CORS_ORIGIN=https://your-frontend.example.com  # legacy single-origin alias
+# CORS_ALLOW_ALL=false
 
 # Allow provider URLs pointing to private/local networks (localhost, 192.168.x.x, etc.).
 # REQUIRED for self-hosted providers: LM Studio, Ollama, vLLM, Llamafile, Triton, etc.
@@ -242,6 +253,12 @@ ALLOW_API_KEY_REVEAL=false
 # Default: false (blocked)  |  Set true to enable local providers.
 # OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS=true
 
+# Allow adding/validating providers on local/private addresses (127.0.0.1, localhost, LAN).
+# Used by: src/shared/network/outboundUrlGuard.ts — scopes to the provider validation path and
+# still blocks cloud-metadata (169.254.169.254, metadata.google.internal). Default: true
+# (OmniRoute is local-first). Set false to enforce strict public-only blocking.
+# OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS=false
+
 # Legacy alias toggling the SSRF guard. Used by: src/shared/network/outboundUrlGuard.ts
 # When unset, OmniRoute uses the per-feature defaults. Set to "false"/"0" to disable.
 # OUTBOUND_SSRF_GUARD_ENABLED=true
@@ -318,6 +335,7 @@ ALLOW_API_KEY_REVEAL=false
 # URLs used for internal sync jobs, OAuth callbacks, and cloud relay.
 
 # Internal base URL — used by server-side sync jobs to call /api/sync/cloud.
+# Keep this as a loopback/container URL even when the app is publicly proxied.
 # Used by: src/lib/cloudSync.ts, src/lib/initCloudSync.ts
 # Default: http://localhost:20128
 BASE_URL=http://localhost:20128
@@ -332,7 +350,8 @@ CLOUD_URL=
 # CLOUD_SYNC_TIMEOUT_MS=12000
 
 # Public-facing base URL — CRITICAL for reverse proxy / OAuth callback setups.
-# Used by: OAuth redirect_uri computation, Dashboard UI links, cloud/model sync.
+# Used by: OAuth redirect_uri computation, Dashboard UI links, generated public
+# URLs, and same-origin browser mutation checks.
 # Set to your public URL when behind nginx/Caddy (e.g., https://omniroute.example.com).
 #
 # Dashboard display behavior: when this variable is unset, the dashboard
@@ -346,6 +365,7 @@ CLOUD_URL=
 NEXT_PUBLIC_BASE_URL=http://localhost:20128
 
 # Browser-facing OmniRoute origin for generated assets in API responses.
+# Highest-priority public origin override; also used by public-origin validation.
 # Used by: chatgpt-web image generation cache URLs (/v1/chatgpt-web/image/<id>).
 # Set this when OpenWebUI or another relay reaches OmniRoute by an internal URL
 # but the user's browser must fetch images from a LAN, tunnel, or public origin.
@@ -369,6 +389,13 @@ NEXT_PUBLIC_CLOUD_URL=
 # Legacy alias — fallback for NEXT_PUBLIC_BASE_URL in sync schedulers.
 # NEXT_PUBLIC_APP_URL=http://localhost:20128
 
+# Advanced reverse-proxy trust mode for deriving public origin from Forwarded /
+# X-Forwarded-* headers when no explicit public base URL is set. Prefer setting
+# NEXT_PUBLIC_BASE_URL. Only enable if direct client access to OmniRoute is blocked
+# and your proxy strips/rebuilds incoming forwarded headers.
+# Values: true/loopback (trust loopback proxy peers), private/lan (also trust LAN peers).
+# OMNIROUTE_TRUST_PROXY=
+
 # Public callback URL for asynchronous image/audio jobs (kie.ai, etc.).
 # Used by: open-sse/utils/kieTask.ts — overrides callbackUrlFromBaseUrl().
 # Honor order: KIE_CALLBACK_URL → OMNIROUTE_KIE_CALLBACK_URL → OMNIROUTE_PUBLIC_URL.
@@ -376,14 +403,35 @@ NEXT_PUBLIC_CLOUD_URL=
 #OMNIROUTE_KIE_CALLBACK_URL=
 #OMNIROUTE_PUBLIC_URL=
 
+# Headroom token-saver proxy URL. The dashboard lifecycle (api/headroom/*) spawns
+# a local headroom-ai CLI on loopback by default; override only to point at an
+# external Docker sidecar proxy. Defaults to http://localhost:8787 when unset.
+# Used by: src/lib/headroom/detect.ts.
+#HEADROOM_URL=http://localhost:8787
+
 # Upstream quota endpoints used by the Usage page. Override only for
 # debugging or when routing through a corporate mirror. Used by:
 # open-sse/services/usage.ts.
 #OMNIROUTE_CROF_USAGE_URL=https://crof.ai/usage_api/
-#OMNIROUTE_GEMINI_CLI_USAGE_URL=https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist
 #OMNIROUTE_CODEWHISPERER_BASE_URL=https://codewhisperer.us-east-1.amazonaws.com
 #OMNIROUTE_OPENCODE_QUOTA_URL=https://opencode.ai/zen/go/v1/quota
 #OMNIROUTE_OPENCODE_GO_QUOTA_URL=https://api.z.ai/api/monitor/usage/quota/limit
+#OMNIROUTE_OPENCODE_GO_DASHBOARD_URL=https://opencode.ai/workspace
+#OMNIROUTE_OLLAMA_CLOUD_USAGE_URL=https://ollama.com/settings
+
+# OpenCode Go dashboard quota scraping. Prefer configuring these per connection
+# in Dashboard → Providers → OpenCode Go. Env vars are useful for headless
+# deployments or shared server defaults. The cookie is sensitive.
+#OPENCODE_GO_WORKSPACE_ID=wrk_...
+#OMNIROUTE_OPENCODE_GO_WORKSPACE_ID=wrk_...
+#OPENCODE_GO_AUTH_COOKIE=auth=...
+#OMNIROUTE_OPENCODE_GO_AUTH_COOKIE=auth=...
+
+# Ollama Cloud quota scraping. Prefer configuring this per connection in
+# Dashboard → Providers → Ollama Cloud. The cookie is sensitive.
+#OLLAMA_USAGE_COOKIE=__Secure-session=...
+#OLLAMA_CLOUD_USAGE_COOKIE=__Secure-session=...
+#OMNIROUTE_OLLAMA_USAGE_COOKIE=__Secure-session=...
 
 # ═══════════════════════════════════════════════════════════════════════════════
 # 8. OUTBOUND PROXY (Upstream Provider Calls)
@@ -408,6 +456,13 @@ NEXT_PUBLIC_ENABLE_SOCKS5_PROXY=true
 # Set to 1 only for legacy diagnostics. Values above 256 are capped.
 # OMNIROUTE_PROXY_DISPATCHER_CONNECTIONS=32
 
+# SOCKS5 handshake (connect) timeout in ms (default 10000, capped at 120000).
+# Raise it when a single residential gateway host is hit by high concurrency
+# (e.g. 100 simultaneous requests): the real SOCKS5 handshake can exceed 10s
+# under a saturated pool even though the proxy is reachable, which otherwise
+# surfaces as a false "[Proxy Fast-Fail] Proxy unreachable".
+# SOCKS_HANDSHAKE_TIMEOUT_MS=10000
+
 # Proxy fail-open mode (default: false = fail-closed).
 # When false, a request whose assigned proxy fails to resolve is REFUSED rather than
 # falling back to a direct connection — prevents real-IP leaks in egress-controlled
@@ -535,6 +590,16 @@ PROVIDER_LIMITS_SYNC_SPACING_MS=1500
 # heuristic in instrumentation-node.ts.  Default: unset (tests skip background).
 #OMNIROUTE_ENABLE_RUNTIME_BACKGROUND_TASKS=1
 
+# Proactive connection-cooldown recovery (#8): re-validates connections whose
+# transient `rate_limited_until` window has elapsed OUTSIDE the request hot path,
+# so the first request after a cooldown does not pay the probe latency. Lazy
+# recovery in getProviderCredentials still applies regardless. Used by:
+# src/lib/quota/connectionRecovery.ts.
+# Tick cadence (ms). Default 60000, floor 5000.
+# OMNIROUTE_CONNECTION_RECOVERY_INTERVAL_MS=60000
+# Disable the proactive recovery scheduler entirely (default: false).
+# OMNIROUTE_DISABLE_CONNECTION_RECOVERY=false
+
 # Background job interval for budget reset checks (ms).  Default: 600000 (10m).
 # Used by: src/lib/jobs/budgetResetJob.ts.  Floor: 10000.
 #OMNIROUTE_BUDGET_RESET_JOB_INTERVAL_MS=600000
@@ -582,6 +647,11 @@ PROVIDER_LIMITS_SYNC_SPACING_MS=1500
 # Used by: scripts/postinstall.mjs.
 #OMNIROUTE_SKIP_POSTINSTALL=0
 
+# Operator-supplied JSON credentials for the offline compression-eval CLI
+# (parsed with JSON.parse; leave unset for a dry run). Developer tooling only.
+# Used by: scripts/compression-eval/index.ts.  Default: {} (empty).
+#OMNIROUTE_EVAL_CREDENTIALS={}
+
 # Skip the DB healthcheck entirely on startup (useful for short-lived tasks / tests).
 # Used by: src/lib/db/core.ts, src/lib/db/healthCheck.ts.  Set to 1 to disable.  Default: 0.
 #OMNIROUTE_SKIP_DB_HEALTHCHECK=0
@@ -650,7 +720,7 @@ CODEX_OAUTH_CLIENT_ID=app_EMoamEEZ73f0CkXaXp7hrann
 # Used by: open-sse/executors/theoldllm.ts. Default: 30000 (30s).
 # THEOLDLLM_NAV_TIMEOUT_MS=30000
 
-# ── Gemini / Gemini CLI / Antigravity / Windsurf (all Google-based) ──
+# ── Gemini / Antigravity / Windsurf (all Google-based) ──
 # These providers ship public OAuth client_id/secret values (or Firebase Web
 # keys) embedded in their public CLIs/binaries. Defaults are baked into the
 # code via open-sse/utils/publicCreds.ts — leave the env vars unset to use
@@ -659,8 +729,6 @@ CODEX_OAUTH_CLIENT_ID=app_EMoamEEZ73f0CkXaXp7hrann
 #
 # GEMINI_OAUTH_CLIENT_ID=
 # GEMINI_OAUTH_CLIENT_SECRET=
-# GEMINI_CLI_OAUTH_CLIENT_ID=
-# GEMINI_CLI_OAUTH_CLIENT_SECRET=
 # ANTIGRAVITY_OAUTH_CLIENT_ID=
 # ANTIGRAVITY_OAUTH_CLIENT_SECRET=
 # WINDSURF_FIREBASE_API_KEY=
@@ -748,7 +816,7 @@ GITHUB_OAUTH_CLIENT_ID=Iv1.b507a08c87ecfe98
 # VISION_BRIDGE_API_KEY=
 
 # ─────────────────────────────────────────────────────────────────────────────
-# ⚠️  GOOGLE OAUTH (Antigravity, Gemini CLI) & OTHER PROVIDERS — REMOTE SERVERS
+# ⚠️  GOOGLE OAUTH (Antigravity) & OTHER PROVIDERS — REMOTE SERVERS
 # ─────────────────────────────────────────────────────────────────────────────
 # The default Client IDs above ONLY work when OmniRoute runs on localhost.
 # For remote/VPS hosting (including Docker containers on remote servers):
@@ -776,7 +844,7 @@ GITHUB_OAUTH_CLIENT_ID=Iv1.b507a08c87ecfe98
 # Used by: open-sse/executors/base.ts — buildHeaders() dynamic lookup.
 # Update these when providers release new CLI versions to avoid blocks.
 
-CLAUDE_USER_AGENT="claude-cli/2.1.158 (external, cli)"
+CLAUDE_USER_AGENT="claude-cli/2.1.195 (external, cli)"
 
 # Disable the deterministic tool-name cloak applied on both Anthropic-bound paths
 # (executors/base.ts native OAuth + executors/cliproxyapi.ts CLIProxyAPI) —
@@ -785,23 +853,34 @@ CLAUDE_USER_AGENT="claude-cli/2.1.158 (external, cli)"
 # stream with a misleading 400 out-of-extra-usage placeholder. Set to true to
 # forward the original names verbatim (debugging only).
 # CLAUDE_DISABLE_TOOL_NAME_CLOAK=false
-CODEX_USER_AGENT="codex-cli/0.132.0 (Windows 10.0.26200; x64)"
-GITHUB_USER_AGENT="GitHubCopilotChat/0.45.1"
+CODEX_USER_AGENT="codex-cli/0.142.0 (Windows 10.0.26200; x64)"
+GITHUB_USER_AGENT="GitHubCopilotChat/0.54.0"
 ANTIGRAVITY_USER_AGENT="antigravity/2.0.1 linux/arm64 google-api-nodejs-client/10.3.0"
 KIRO_USER_AGENT="AWS-SDK-JS/3.0.0 kiro-ide/1.0.0"
+# KIRO_VERIFY_FULL_CRC=false           # opt-in: full per-frame message CRC validation on the Kiro event stream (debug corrupted streams; prelude CRC + TLS already protect framing)
 # Optional override for the Kiro social device-code OAuth clientId. Kiro's
 # device endpoint accepts any non-empty string and behaves like a User-Agent
 # rather than a secret. Only override if AWS ever starts enforcing this field.
 # Used by: src/lib/oauth/constants/oauth.ts (KIRO_CONFIG.socialClientId).
 # KIRO_OAUTH_CLIENT_ID=kiro-cli
+# Enable full per-frame message CRC validation for Kiro streams. Off by default
+# because it is O(frame bytes) on the main thread; use only for debugging
+# suspected corrupted-stream issues.
+# Used by: open-sse/executors/kiro.ts
+# KIRO_VERIFY_FULL_CRC=false
 QODER_USER_AGENT="Qoder-Cli"
-QWEN_USER_AGENT="QwenCode/0.15.11 (linux; x64)"
+QWEN_USER_AGENT="QwenCode/0.19.3 (linux; x64)"
 CURSOR_USER_AGENT="Cursor/3.4"
-GEMINI_CLI_USER_AGENT="google-api-nodejs-client/10.3.0"
 
 # Override Codex client version sent in headers independently of the
 # CODEX_USER_AGENT string. Used by: open-sse/config/codexClient.ts.
-# CODEX_CLIENT_VERSION=0.132.0
+# CODEX_CLIENT_VERSION=0.142.0
+
+# Kill-switch to strip non-standard `codex.*` SSE events (e.g. codex.rate_limits)
+# from the Codex Responses stream. These frames break the OpenAI SDK's
+# responses.stream() with a 502 "Controller is already closed". Off by default;
+# set to true/1/yes to enable. Used by: open-sse/executors/codex.ts.
+# OMNIROUTE_CODEX_DROP_NONSTANDARD_EVENTS=true
 
 # ═══════════════════════════════════════════════════════════════════════════════
 # 13. CLI FINGERPRINT COMPATIBILITY (Anti-Detection)
@@ -928,6 +1007,15 @@ GEMINI_CLI_USER_AGENT="google-api-nodejs-client/10.3.0"
 # OMNIROUTE_CIRCUIT_BREAKER_LOCAL_THRESHOLD=2
 # OMNIROUTE_CIRCUIT_BREAKER_LOCAL_RESET_MS=15000
 
+# ── Context-cache pin health gate ──
+# Used by: open-sse/services/combo.ts. When a context-cache pin points at a
+# provider that is durably unhealthy, the pin is dropped to allow failover.
+# PIN_DROP_BACKOFF_LEVEL gates how deep a connection's backoff must be before the
+# pin is considered durably unhealthy; PIN_DROP_GRACE_MS is the anti-flap window
+# that tolerates brief transient cooldowns before dropping the pin.
+# PIN_DROP_BACKOFF_LEVEL=2
+# PIN_DROP_GRACE_MS=20000
+
 # ── Stream idle detection ──
 # STREAM_IDLE_TIMEOUT_MS=600000      # Max silence between SSE chunks (default: 600000)
 #                                     # Extended-thinking models rarely pause >90s.
@@ -1000,6 +1088,11 @@ APP_LOG_TO_FILE=true
 # Default: 100000
 # CALL_LOGS_TABLE_MAX_ROWS=100000
 
+# Maximum age for orphaned active request log entries before the in-memory
+# pending-request reaper removes them. Accepts milliseconds.
+# Default: 3600000 (1 hour)
+# MAX_PENDING_REQUEST_AGE_MS=3600000
+
 # Whether call log pipeline capture stores stream chunks when enabled in settings.
 # Only applies when call_log_pipeline_enabled=true.
 # Default: true
@@ -1173,6 +1266,34 @@ APP_LOG_TO_FILE=true
 # Used by: open-sse/executors/cloudflare-ai.ts
 # CLOUDFLARE_ACCOUNT_ID=
 
+# ── Deno Deploy proxy relay (#4643 / 9router#1437) ──
+# Override the Deno Deploy REST API base used by the proxy-pool relay deployer.
+# Default: https://api.deno.com/v2 (omit unless mocking).
+# Used by: src/app/api/settings/proxy/deno-deploy/route.ts
+# DENO_DEPLOY_API_BASE=https://api.deno.com/v2
+
+# Default Deno Deploy app name suggested in the "Deploy Relay" modal.
+# Used by: src/app/(dashboard)/dashboard/settings/components/proxy/DenoRelayModal.tsx
+# NEXT_PUBLIC_DENO_RELAY_DEFAULT_PROJECT=omniroute-deno-relay
+
+# Set to "false" to hide the Deno Deploy relay option from the Proxy Pool tab.
+# Used by: src/app/(dashboard)/dashboard/settings/components/proxy/ProxyPoolTab.tsx
+# NEXT_PUBLIC_DENO_RELAY_ENABLED=true
+
+# ── Cloudflare Workers proxy relay (#4640 / 9router#1360) ──
+# Override the Cloudflare REST API base used by the proxy-pool relay deployer.
+# Default: https://api.cloudflare.com/client/v4 (omit unless mocking).
+# Used by: src/app/api/settings/proxy/cloudflare-deploy/route.ts
+# CLOUDFLARE_API_BASE=https://api.cloudflare.com/client/v4
+
+# Default worker project name suggested in the "Deploy Relay" modal.
+# Used by: src/app/(dashboard)/dashboard/settings/components/proxy/CloudflareRelayModal.tsx
+# NEXT_PUBLIC_CLOUDFLARE_RELAY_DEFAULT_PROJECT=omniroute-relay
+
+# Set to "false" to hide the Cloudflare Workers relay option from the Proxy Pool tab.
+# Used by: src/app/(dashboard)/dashboard/settings/components/proxy/ProxyPoolTab.tsx
+# NEXT_PUBLIC_CLOUDFLARE_RELAY_ENABLED=true
+
 # ── Cloudflare Tunnel (cloudflared) ──
 # Custom path to cloudflared binary for tunnel management.
 # Used by: src/lib/cloudflaredTunnel.ts
@@ -1237,6 +1358,11 @@ APP_LOG_TO_FILE=true
 # Health check result cache TTL (ms).  Default: 30000 (30s)
 # PROXY_HEALTH_CACHE_TTL_MS=30000
 
+# Unhealthy health check result cache TTL (ms). Default: 2000 (2s)
+# Keeps transient fast-fail timeouts from poisoning a proxy for the full
+# healthy-result cache window under high concurrency.
+# PROXY_HEALTH_UNHEALTHY_CACHE_TTL_MS=2000
+
 # Allow OAuth and provider validation flows to bypass a pinned proxy and connect
 # directly when proxy reachability pre-checks fail. Default: false.
 # Also configurable from Dashboard > Settings > Feature Flags.
@@ -1461,6 +1587,10 @@ APP_LOG_TO_FILE=true
 # dashboard's tunnel manager. Used by: src/lib/tailscaleTunnel.ts.
 # TAILSCALE_BIN=/usr/local/bin/tailscale
 # TAILSCALED_BIN=/usr/local/bin/tailscaled
+# Pre-shared Tailscale auth key for non-interactive / headless `tailscale up`
+# (passed via --auth-key=). When unset, login falls back to the interactive
+# browser auth URL. Used by: src/lib/tailscaleTunnel.ts.
+# TAILSCALE_AUTHKEY=
 
 # ── Ngrok tunnel ──
 # Used by: src/lib/ngrokTunnel.ts — authenticates outbound tunnels.
@@ -1606,7 +1736,17 @@ QUOTA_STORE_DRIVER=sqlite              # sqlite | redis
 # QUOTA_STORE_REDIS_URL=               # ex.: redis://localhost:6379 (apenas quando driver=redis)
 # QUOTA_SATURATION_THRESHOLD=0.5       # 0..1; >= threshold ativa modo strict (sem empréstimo)
 # QUOTA_SOFT_DEPRIORITIZE_FACTOR=0.7   # 0..1; multiplicador do score quando soft policy ativa
+# STATUS_SOFT_DEPRIORITIZE_FACTOR=0.5  # 0..1; multiplicador do score p/ provider esgotado (credits_exhausted/rate_limited) quando preflight cutoff OFF (#4540)
 # QUOTA_CONSUMPTION_RETENTION_DAYS=14  # GC de buckets quota_consumption.updated_at antigos
+# QUOTA_PREFLIGHT_CUTOFF_ENABLED=false # opt-in (default OFF): hard quota cutoff drops low-quota candidates before auto-routing scoring
+
+# ─── Auto-Combo tier filter (#4517) ───────────────────────────────────────
+# When an `auto/<category>:free` (or any `:<tier>`) request matches NO connected
+# candidates, OmniRoute returns an EMPTY pool by default — so `:free` really means
+# "free tier only" and a paid model is never picked just because no free provider is
+# connected. Set this to `true`/`1` to restore the legacy behavior of falling back to
+# the full (unfiltered) pool with a warning. Source: open-sse/services/autoCombo/virtualFactory.ts
+# OMNIROUTE_AUTO_FREE_FALLBACK_TO_FULL_POOL=false
 
 # ─── OpenCode config regeneration (scripts/ad-hoc/regen-opencode-config.ts) ───
 # Base URL of the OmniRoute instance to query for /v1/models when regenerating
@@ -1619,3 +1759,81 @@ QUOTA_STORE_DRIVER=sqlite              # sqlite | redis
 # OpenCode-style API key (sk-...) for the regenerated opencode.json. Used by:
 # scripts/ad-hoc/regen-opencode-config.ts. Falls back to OMNIROUTE_KEY.
 # OPENCODE_API_KEY=
+
+# ─── Bifrost Go sidecar (PR-4 in #3932) ──────────────────────────────────────
+# Master kill switch for the bifrost sidecar proxy. When set to 0, the
+# /api/v1/relay/chat/completions/bifrost route returns 503 with the
+# X-Bifrost-Killswitch header and the operator is bounced to the TS path.
+# Use this to disable the sidecar without redeploying (e.g. during a
+# tier-1 router incident or a key rotation). Default: 1 (sidecar active).
+# BIFROST_ENABLED=1
+# When BIFROST_BASE_URL is set, /api/v1/relay/chat/completions/bifrost routes
+# traffic to the Go gateway instead of the TS relay handler, removing TS from
+# the hot path. Auth/rate-limit/injection-guard stay in the route (security not
+# duplicated). Falls back to TS path via X-Bifrost-Fallback header on
+# timeout/failure. See bin/omniroute for the local-redis companion.
+# BIFROST_BASE_URL=
+# API key for the Bifrost gateway (sent as Authorization: Bearer ...). If
+# unset, the route expects the request to carry a valid OmniRoute API key;
+# this key is for gateway-side auth only.
+# BIFROST_API_KEY=
+# When true, the Bifrost sidecar route streams responses back via SSE through
+# the gateway rather than the TS streaming executor. Default: true (when
+# BIFROST_BASE_URL is set).
+# BIFROST_STREAMING_ENABLED=
+# Per-request timeout when proxying to the Bifrost gateway. Default: 30000 (30s).
+# BIFROST_TIMEOUT_MS=
+# Alias for BIFROST_API_KEY (used by scripts that read the env via
+# OMNIROUTE_*). Falls back to BIFROST_API_KEY when unset.
+# OMNIROUTE_BIFROST_KEY=
+
+# ─── 1-click local service launchers (PR-3 in #3932) ────────────────────────
+# Master switch for /api/local/* routes. When unset or "0", all /api/local/*
+# routes return 503 in production. Default: 0. Must be "1" in non-loopback
+# deploys to enable the Redis launcher and similar 1-click local service
+# starters. Belt-and-suspenders with the isLocalOnlyPath() route-guard
+# classification (LOCAL_ONLY_API_PREFIXES in src/server/authz/routeGuard.ts).
+# OMNIROUTE_LOCAL_ENDPOINTS_ENABLED=
+# Bearer token for /api/local/* callers that aren't on loopback (e.g. the
+# desktop app). When set, requests from non-loopback IPs must carry
+# Authorization: Bearer <token>. Required when
+# OMNIROUTE_LOCAL_ENDPOINTS_ENABLED=1 in non-loopback deployments. Default:
+# unset (loopback-only).
+# OMNIROUTE_LOCAL_ENDPOINTS_TOKEN=
+# Container name for the 1-click Redis launcher (`omniroute redis up`).
+# Default: omniroute-redis. Used by bin/cli/commands/redis.mjs and the
+# RedisLauncherPanel.
+# OMNIROUTE_REDIS_CONTAINER_NAME=
+# Host port for the 1-click Redis launcher. Default: 6379. Bump if the host
+# already binds 6379. The container's internal port stays 6379.
+# OMNIROUTE_REDIS_HOST_PORT=
+# Redis image used by the 1-click Redis launcher. Default: redis:7-alpine.
+# Override to redis:8-alpine or a private registry mirror as needed.
+# OMNIROUTE_REDIS_IMAGE=
+
+# ── Cluster Profile: Qdrant Vector Memory (opt-in via `docker compose --profile memory up`) ──
+# Qdrant is an OPTIONAL sidecar for deployments that need cosine-distance vector
+# search at >1M embeddings. The default vector store is sqlite-vec
+# (src/lib/memory/vectorStore.ts:108); flip this profile on only if you hit the
+# sqlite-vec ceiling or want persistent cross-replica vector state. See
+# docs/architecture/cluster-decisions.md § "Qdrant (memory profile)".
+# QDRANT_HOST=qdrant
+# QDRANT_PORT=6333
+# QDRANT_GRPC_PORT=6334
+# QDRANT_API_KEY=
+# QDRANT_COLLECTION=omniroute-memory
+# QDRANT_EMBEDDING_MODEL=text-embedding-3-small
+# QDRANT_VECTOR_SIZE=1536
+# QDRANT_HNSW_EF_CONSTRUCT=128
+
+# ── Cluster Profile: Bifrost Tier-1 Router (opt-in via `docker compose --profile bifrost up`) ──
+# Bifrost is an OPTIONAL Go-based Tier-1 router that handles the upstream-provider
+# multiplexing layer. Default: OmniRoute's open-sse/executors/bifrost.ts in-process
+# executor handles routing directly. Flip this profile on only if you want the
+# gateway as a separate sidecar (helps in 3+ replica deployments where you want
+# provider rotation centralised). See docs/architecture/cluster-decisions.md §
+# "Bifrost (bifrost profile)".
+# BIFROST_BASE_URL=http://bifrost:8080
+# BIFROST_API_KEY=
+# BIFROST_STREAMING_ENABLED=true
+# BIFROST_TIMEOUT_MS=30000

.github/actions/npm-ci-retry/action.yml

@@ -0,0 +1,29 @@
+name: npm ci with retry
+description: Run npm ci with retries for transient registry/network failures.
+runs:
+  using: composite
+  steps:
+    - shell: bash
+      run: |
+        set -euo pipefail
+
+        max_attempts=3
+        delay_seconds=20
+
+        for attempt in $(seq 1 "$max_attempts"); do
+          if [ "$attempt" -gt 1 ]; then
+            echo "npm ci attempt $attempt/$max_attempts after transient failure"
+          fi
+
+          if npm ci; then
+            exit 0
+          fi
+
+          exit_code=$?
+          if [ "$attempt" -eq "$max_attempts" ]; then
+            exit "$exit_code"
+          fi
+
+          sleep "$delay_seconds"
+          delay_seconds=$((delay_seconds * 2))
+        done

.github/workflows/ci.yml

@@ -21,6 +21,74 @@ env:
   CI_NODE_26_VERSION: "26"
 
 jobs:
+  changes:
+    name: Change Classification
+    runs-on: ubuntu-latest
+    outputs:
+      code: ${{ steps.classify.outputs.code }}
+      docs: ${{ steps.classify.outputs.docs }}
+      i18n: ${{ steps.classify.outputs.i18n }}
+      workflow: ${{ steps.classify.outputs.workflow }}
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      - id: classify
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          if [ "$EVENT_NAME" != "pull_request" ]; then
+            {
+              echo "code=true"
+              echo "docs=true"
+              echo "i18n=true"
+              echo "workflow=true"
+            } >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          code=false
+          docs=false
+          i18n=false
+          workflow=false
+
+          git diff --name-only "$BASE_SHA" "$HEAD_SHA" > changed-files.txt
+
+          while IFS= read -r file; do
+            case "$file" in
+              .github/workflows/*|.zizmor.yml)
+                workflow=true
+                code=true
+                ;;
+              docs/*|*.md)
+                docs=true
+                ;;
+              src/i18n/*|src/i18n/messages/*|scripts/i18n/*|config/i18n.json)
+                i18n=true
+                code=true
+                ;;
+              src/*|open-sse/*|bin/*|electron/*|tests/*|scripts/*|package.json|package-lock.json|tsconfig*.json|next.config.*|vitest*.config.*|playwright.config.*)
+                code=true
+                ;;
+              db/*|config/*)
+                code=true
+                ;;
+              *)
+                code=true
+                ;;
+            esac
+          done < changed-files.txt
+
+          {
+            echo "code=$code"
+            echo "docs=$docs"
+            echo "i18n=$i18n"
+            echo "workflow=$workflow"
+          } >> "$GITHUB_OUTPUT"
+
   lint:
     name: Lint
     runs-on: ubuntu-latest
@@ -38,7 +106,7 @@ jobs:
         with:
           node-version: ${{ env.CI_NODE_VERSION }}
           cache: npm
-      - run: npm ci
+      - uses: ./.github/actions/npm-ci-retry
       - run: npm run check:node-runtime
       - run: npm run audit:deps
       - run: npm run lint
@@ -72,7 +140,15 @@ jobs:
     name: Quality Ratchet
     runs-on: ubuntu-latest
     needs: test-coverage
-    if: ${{ always() && needs.test-coverage.result == 'success' }}
+    # Run even when test-coverage was SKIPPED/FAILED (e.g. a single flaky Coverage
+    # Shard breaks the shard→coverage→ratchet chain). The DETERMINISTIC ratchets
+    # (eslint / complexity / cognitive-complexity / duplication / codeql) do NOT need
+    # the coverage artifact and MUST still run so cycle drift is measured on the
+    # release PR — otherwise a flake silently skips the whole gate (incident: v3.8.36
+    # release PR #4854, where the drift cascade only surfaced post-merge in #5029).
+    # The coverage.* metrics degrade gracefully: the download is continue-on-error and
+    # the ratchet runs with --allow-missing, so absent coverage is skipped, not failed.
+    if: ${{ !cancelled() }}
     # security-events: read lets the CodeQL ratchet read open code-scanning alerts
     # via `gh api .../code-scanning/alerts`. contents: read keeps checkout working.
     permissions:
@@ -86,9 +162,14 @@ jobs:
         with:
           node-version: ${{ env.CI_NODE_VERSION }}
           cache: npm
-      - run: npm ci
+      - uses: ./.github/actions/npm-ci-retry
       # Coverage mergeada (coverage-summary.json) p/ o ratchet de cobertura.
+      # continue-on-error: o artifact pode não existir se a job test-coverage foi
+      # SKIPPED (shard flaky). Nesse caso collect-metrics pula coverage.* (ausente sem
+      # erro) e o ratchet roda com --allow-missing — as métricas determinísticas
+      # (eslint/complexity/cognitive) seguem BLOQUEANTES.
       - uses: actions/download-artifact@v8
+        continue-on-error: true
         with:
           name: coverage-report
           path: coverage/
@@ -96,8 +177,10 @@ jobs:
       # Catraca: falha se qualquer métrica regredir vs quality-baseline.json (commitado).
       # Hoje: contagem de warnings do ESLint. Fase 4 estende com cobertura (lida do
       # coverage mergeado). Tamanho de arquivo e duplicação têm gates dedicados.
+      # --allow-missing: pula métricas do baseline ausentes do collect (coverage.* quando
+      # o artifact não veio) em vez de falhar — mantém os gates determinísticos ativos.
       - name: Ratchet check
-        run: node scripts/quality/check-quality-ratchet.mjs --summary .artifacts/quality-ratchet.md
+        run: node scripts/quality/check-quality-ratchet.mjs --allow-missing --summary .artifacts/quality-ratchet.md
       # Fase 6A.5: require-tighten — BLOQUEANTE (promovido de advisory no fim do ciclo
       # v3.8.27). Falha quando uma métrica MELHOROU sem o baseline ter sido apertado no
       # mesmo PR (força capturar ganhos permanentes). As métricas coverage.* carregam
@@ -106,7 +189,7 @@ jobs:
       # mergeada == baseline (ver a nota _require_tighten_flip_blocking em
       # config/quality/quality-baseline.json).
       - name: Require-tighten (blocking)
-        run: node scripts/quality/check-quality-ratchet.mjs --require-tighten
+        run: node scripts/quality/check-quality-ratchet.mjs --allow-missing --require-tighten
       # Catraca de duplicação (jscpd@4 sobre src+open-sse). Roda neste job (paralelo)
       # para não pesar no caminho crítico do lint.
       - name: Duplication ratchet
@@ -159,7 +242,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       # fetch-depth: 0 — the OpenAPI breaking-change gate (oasdiff) reads the base
-      # spec via `git show <base_ref>:docs/reference/openapi.yaml`; a shallow clone
+      # spec via `git show <base_ref>:docs/openapi.yaml`; a shallow clone
       # would lack the base ref and the gate would self-skip (base-unresolved).
       - uses: actions/checkout@v7
         with:
@@ -169,7 +252,7 @@ jobs:
         with:
           node-version: ${{ env.CI_NODE_VERSION }}
           cache: npm
-      - run: npm ci
+      - uses: ./.github/actions/npm-ci-retry
       # Dead-code, cognitive-complexity, type-coverage foram promovidos ao job
       # quality-gate (bloqueante) na Fase 7 INT — não rodam aqui para evitar duplo custo.
       - name: Circular deps (dpdm; advisory)
@@ -250,7 +333,7 @@ jobs:
       - name: Workflow lint (actionlint+zizmor, ratchet, blocking)
         run: npm run check:workflows -- --ratchet
       # OpenAPI breaking-change detection (oasdiff). Diffs the PR's public API
-      # contract (docs/reference/openapi.yaml) against the base branch's spec.
+      # contract (docs/openapi.yaml) against the base branch's spec.
       # BLOCKING ratchet (Fase 9 Onda 0): reads metrics.openapiBreaking.value and
       # exits 1 ONLY on a measured regression (count > baseline). It SKIPs (exit 0)
       # when oasdiff is absent or the base spec can't be resolved — a missing
@@ -272,7 +355,7 @@ jobs:
         with:
           node-version: ${{ env.CI_NODE_VERSION }}
           cache: npm
-      - run: npm ci
+      - uses: ./.github/actions/npm-ci-retry
       - run: npm run check:docs-all
       # Previously-orphaned contract gates (existed as files, never wired anywhere).
       # All exit 0 today: cli-i18n is a hard gate, openapi-coverage is a ratchet
@@ -327,7 +410,7 @@ jobs:
         with:
           node-version: ${{ env.CI_NODE_VERSION }}
           cache: npm
-      - run: npm ci
+      - uses: ./.github/actions/npm-ci-retry
       - run: node scripts/i18n/check-ui-keys-coverage.mjs --threshold=65
 
   i18n-matrix:
@@ -413,6 +496,8 @@ jobs:
   build:
     name: Build
     runs-on: ubuntu-latest
+    needs: changes
+    if: ${{ github.event_name != 'pull_request' || needs.changes.outputs.code == 'true' }}
     steps:
       - uses: actions/checkout@v7
         with:
@@ -421,22 +506,30 @@ jobs:
         with:
           node-version: ${{ env.CI_NODE_VERSION }}
           cache: npm
-      - run: npm ci
+      - uses: ./.github/actions/npm-ci-retry
       - run: npm run check:node-runtime
+      - name: Cache Next.js build cache
+        uses: actions/cache@2c8a9bd7457de244a408f35966fab2fb45fda9c8
+        with:
+          path: .build/next/cache
+          key: nextjs-${{ runner.os }}-node-${{ env.CI_NODE_VERSION }}-${{ hashFiles('package-lock.json') }}-${{ hashFiles('src/**/*', 'open-sse/**/*', 'db/**/*', 'next.config.mjs', 'tsconfig*.json', 'postcss.config.*', 'tailwind.config.*') }}
+          restore-keys: |
+            nextjs-${{ runner.os }}-node-${{ env.CI_NODE_VERSION }}-${{ hashFiles('package-lock.json') }}-
       - run: npm run build
-      - name: Archive Next.js build for E2E shards
+      - name: Archive Next.js build for downstream jobs
         # Use tar so the archive preserves paths relative to CWD (.build/next/...).
         # upload-artifact path-stripping is ambiguous when exclude patterns are used;
         # an explicit tar avoids the double-nesting issue (.build/next/next/...).
+        # Keep standalone/node_modules intact: package/electron jobs consume the
+        # Next-traced standalone tree and must not replace it with root node_modules.
         run: |
           tar -czf /tmp/e2e-build.tar.gz \
-            --exclude='.build/next/standalone/node_modules' \
             --exclude='.build/next/cache' \
             .build/next
-      - name: Upload Next.js build for E2E shards
+      - name: Upload Next.js build for downstream jobs
         uses: actions/upload-artifact@v7
         with:
-          name: e2e-next-build
+          name: next-build
           path: /tmp/e2e-build.tar.gz
           retention-days: 1
 
@@ -454,10 +547,18 @@ jobs:
         with:
           node-version: ${{ env.CI_NODE_VERSION }}
           cache: npm
-      - run: npm ci
+      - uses: ./.github/actions/npm-ci-retry
       - run: npm run check:node-runtime
-      # build:cli runs a clean build into .build/next and assembles dist/
-      # For release builds prefer: npm run build:release (clean rebuild + HEAD sentinel)
+      - name: Download Next.js build artifact
+        uses: actions/download-artifact@v8
+        with:
+          name: next-build
+          path: /tmp/
+      - name: Extract Next.js build artifact
+        run: |
+          tar -xzf /tmp/e2e-build.tar.gz
+      # build:cli consumes the downloaded .build/next standalone artifact and assembles dist/;
+      # it only rebuilds if the downloaded standalone artifact is missing.
       - run: npm run build:cli
       - name: Assert dist/server.js exists
         run: test -f dist/server.js || (echo "dist/server.js missing — build:cli did not assemble correctly" && exit 1)
@@ -479,9 +580,16 @@ jobs:
         with:
           node-version: ${{ env.CI_NODE_VERSION }}
           cache: npm
-      - run: npm ci
+      - uses: ./.github/actions/npm-ci-retry
       - run: npm run check:node-runtime
-      - run: npm run build
+      - name: Download Next.js build artifact
+        uses: actions/download-artifact@v8
+        with:
+          name: next-build
+          path: /tmp/
+      - name: Extract Next.js build artifact
+        run: |
+          tar -xzf /tmp/e2e-build.tar.gz
       - name: Install Electron dependencies
         working-directory: electron
         run: npm install --no-audit --no-fund
@@ -514,9 +622,9 @@ jobs:
         with:
           node-version: ${{ env.CI_NODE_VERSION }}
           cache: npm
-      - run: npm ci
+      - uses: ./.github/actions/npm-ci-retry
       - run: npm run check:node-runtime
-      - run: node --max-old-space-size=4096 --import tsx --import ./tests/_setup/isolateDataDir.ts --test --test-force-exit --test-concurrency=4 --test-shard=${{ matrix.shard }}/8 tests/unit/*.test.ts "tests/unit/{api,auth,authz,build,cli,cli-helper,combo,compression,correctness,cors,dashboard,db,db-adapters,docs,gamification,guardrails,lib,mcp,runtime,security,services,settings,shared,ui}/**/*.test.ts"
+      - run: node --max-old-space-size=4096 --import tsx --import ./tests/_setup/isolateDataDir.ts --test --test-force-exit --test-concurrency=4 --test-shard=${{ matrix.shard }}/8 tests/unit/*.test.ts "tests/unit/{api,auth,authz,build,cli,cli-helper,combo,compression,correctness,cors,dashboard,db,db-adapters,docs,gamification,guardrails,lib,mcp,runtime,security,services,settings,shared,ui,usage}/**/*.test.ts"
 
   test-vitest:
     name: Vitest (MCP / autoCombo / UI components)
@@ -535,7 +643,7 @@ jobs:
         with:
           node-version: ${{ env.CI_NODE_VERSION }}
           cache: npm
-      - run: npm ci
+      - uses: ./.github/actions/npm-ci-retry
       # The second test runner (CLAUDE.md: "Both test runners must pass") — was never
       # wired into CI until the 2026-06-09 quality audit (Fase 6A.2).
       - run: npm run test:vitest
@@ -546,14 +654,14 @@ jobs:
         continue-on-error: true
 
   node-24-compat:
-    name: Node 24 Compatibility (${{ matrix.shard }}/2)
+    name: Node 24 Compatibility Tests (${{ matrix.shard }}/4)
     runs-on: ubuntu-latest
-    timeout-minutes: 25
+    timeout-minutes: 20
     needs: build
     strategy:
       fail-fast: false
       matrix:
-        shard: [1, 2]
+        shard: [1, 2, 3, 4]
     env:
       JWT_SECRET: ci-test-secret-with-sufficient-length-for-validation
       API_KEY_SECRET: ci-test-api-key-secret-long
@@ -566,20 +674,15 @@ jobs:
         with:
           node-version: ${{ env.CI_NODE_24_VERSION }}
           cache: npm
-      - run: npm ci
+      - uses: ./.github/actions/npm-ci-retry
       - run: npm run check:node-runtime
-      - run: npm run build
-      - run: node --import tsx --import ./tests/_setup/isolateDataDir.ts --test --test-force-exit --test-concurrency=4 --test-shard=${{ matrix.shard }}/2 tests/unit/*.test.ts "tests/unit/{api,auth,authz,build,cli,cli-helper,combo,compression,correctness,cors,dashboard,db,db-adapters,docs,gamification,guardrails,lib,mcp,runtime,security,services,settings,shared,ui}/**/*.test.ts"
+      - run: node --max-old-space-size=4096 --import tsx --import ./tests/_setup/isolateDataDir.ts --test --test-force-exit --test-concurrency=4 --test-shard=${{ matrix.shard }}/4 tests/unit/*.test.ts "tests/unit/{api,auth,authz,build,cli,cli-helper,combo,compression,correctness,cors,dashboard,db,db-adapters,docs,gamification,guardrails,lib,mcp,runtime,security,services,settings,shared,ui,usage}/**/*.test.ts"
 
-  node-26-compat:
-    name: Node 26 Compatibility (${{ matrix.shard }}/2)
+  node-26-compat-build:
+    name: Node 26 Compatibility Build
     runs-on: ubuntu-latest
     timeout-minutes: 25
     needs: build
-    strategy:
-      fail-fast: false
-      matrix:
-        shard: [1, 2]
     env:
       JWT_SECRET: ci-test-secret-with-sufficient-length-for-validation
       API_KEY_SECRET: ci-test-api-key-secret-long
@@ -592,10 +695,41 @@ jobs:
         with:
           node-version: ${{ env.CI_NODE_26_VERSION }}
           cache: npm
-      - run: npm ci
+      - uses: ./.github/actions/npm-ci-retry
       - run: npm run check:node-runtime
+      - name: Cache Next.js build cache
+        uses: actions/cache@2c8a9bd7457de244a408f35966fab2fb45fda9c8
+        with:
+          path: .build/next/cache
+          key: nextjs-${{ runner.os }}-node-${{ env.CI_NODE_26_VERSION }}-${{ hashFiles('package-lock.json') }}-${{ hashFiles('src/**/*', 'open-sse/**/*', 'db/**/*', 'next.config.mjs', 'tsconfig*.json', 'postcss.config.*', 'tailwind.config.*') }}
+          restore-keys: |
+            nextjs-${{ runner.os }}-node-${{ env.CI_NODE_26_VERSION }}-${{ hashFiles('package-lock.json') }}-
       - run: npm run build
-      - run: node --import tsx --import ./tests/_setup/isolateDataDir.ts --test --test-force-exit --test-concurrency=4 --test-shard=${{ matrix.shard }}/2 tests/unit/*.test.ts "tests/unit/{api,auth,authz,build,cli,cli-helper,combo,compression,correctness,cors,dashboard,db,db-adapters,docs,gamification,guardrails,lib,mcp,runtime,security,services,settings,shared,ui}/**/*.test.ts"
+
+  node-26-compat:
+    name: Node 26 Compatibility Tests (${{ matrix.shard }}/4)
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    needs: node-26-compat-build
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2, 3, 4]
+    env:
+      JWT_SECRET: ci-test-secret-with-sufficient-length-for-validation
+      API_KEY_SECRET: ci-test-api-key-secret-long
+      DISABLE_SQLITE_AUTO_BACKUP: "true"
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.CI_NODE_26_VERSION }}
+          cache: npm
+      - uses: ./.github/actions/npm-ci-retry
+      - run: npm run check:node-runtime
+      - run: node --max-old-space-size=4096 --import tsx --import ./tests/_setup/isolateDataDir.ts --test --test-force-exit --test-concurrency=4 --test-shard=${{ matrix.shard }}/4 tests/unit/*.test.ts "tests/unit/{api,auth,authz,build,cli,cli-helper,combo,compression,correctness,cors,dashboard,db,db-adapters,docs,gamification,guardrails,lib,mcp,runtime,security,services,settings,shared,ui,usage}/**/*.test.ts"
 
   test-coverage-shard:
     name: Coverage Shard (${{ matrix.shard }}/8)
@@ -618,7 +752,7 @@ jobs:
         with:
           node-version: ${{ env.CI_NODE_VERSION }}
           cache: npm
-      - run: npm ci
+      - uses: ./.github/actions/npm-ci-retry
       - run: npm run check:node-runtime
       - name: Run c8 over shard ${{ matrix.shard }}/8
         run: |
@@ -636,7 +770,7 @@ jobs:
             --exclude=tests/** \
             --exclude=**/*.test.* \
             node --max-old-space-size=4096 --import tsx --import ./tests/_setup/isolateDataDir.ts --test --test-force-exit --test-concurrency=4 \
-              --test-shard=${{ matrix.shard }}/8 tests/unit/*.test.ts "tests/unit/{api,auth,authz,build,cli,cli-helper,combo,compression,correctness,cors,dashboard,db,db-adapters,docs,gamification,guardrails,lib,mcp,runtime,security,services,settings,shared,ui}/**/*.test.ts"
+              --test-shard=${{ matrix.shard }}/8 tests/unit/*.test.ts "tests/unit/{api,auth,authz,build,cli,cli-helper,combo,compression,correctness,cors,dashboard,db,db-adapters,docs,gamification,guardrails,lib,mcp,runtime,security,services,settings,shared,ui,usage}/**/*.test.ts"
       - name: Upload raw shard coverage
         if: always()
         uses: actions/upload-artifact@v7
@@ -650,7 +784,7 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     needs: test-coverage-shard
-    if: ${{ always() && needs.test-coverage-shard.result == 'success' }}
+    if: ${{ !cancelled() && needs.test-coverage-shard.result == 'success' }}
     env:
       JWT_SECRET: ci-test-secret-with-sufficient-length-for-validation
       API_KEY_SECRET: ci-test-api-key-secret-long
@@ -662,7 +796,7 @@ jobs:
         with:
           node-version: ${{ env.CI_NODE_VERSION }}
           cache: npm
-      - run: npm ci
+      - uses: ./.github/actions/npm-ci-retry
       - name: Download all shard coverage
         uses: actions/download-artifact@v8
         with:
@@ -670,14 +804,18 @@ jobs:
           path: coverage-shards/
           merge-multiple: true
       - name: Merge + report + gate
-        # Merging 8 shards of raw v8 coverage is memory-heavy; the 6 GB heap can
-        # still OOM on large PR runs. Keep this job focused on the gate and
-        # JSON summary that downstream ratchets consume.
+        # Merging 8 shards of raw v8 coverage is memory-heavy. `--merge-async`
+        # keeps the V8 coverage merge incremental instead of loading every raw
+        # JSON blob into one in-memory merge, which avoids Node heap OOMs.
         env:
           NODE_OPTIONS: --max-old-space-size=8192
         run: |
           mkdir -p coverage
-          if [ ! -d coverage-shards ] || ! find coverage-shards -maxdepth 1 -type f -name '*.json' | grep -q .; then
+          first_coverage_file=""
+          if [ -d coverage-shards ]; then
+            first_coverage_file="$(find coverage-shards -maxdepth 1 -type f -name '*.json' -print -quit)"
+          fi
+          if [ -z "$first_coverage_file" ]; then
             echo "::error::No raw coverage shard data was downloaded."
             find . -maxdepth 3 -type f | sort
             exit 1
@@ -691,6 +829,7 @@ jobs:
           npx c8 report \
             --temp-directory coverage-shards \
             --reports-dir coverage \
+            --merge-async \
             --reporter=text-summary \
             --reporter=json-summary \
             --exclude=tests/** \
@@ -722,13 +861,14 @@ jobs:
           path: |
             coverage/coverage-summary.json
             coverage/coverage-report.md
+            coverage/lcov.info
           if-no-files-found: warn
 
   sonarqube:
     name: SonarQube
     runs-on: ubuntu-latest
     needs: test-coverage
-    if: ${{ always() && needs.test-coverage.result == 'success' }}
+    if: ${{ !cancelled() && needs.test-coverage.result == 'success' }}
     env:
       SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
       SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
@@ -759,8 +899,9 @@ jobs:
   coverage-pr-comment:
     name: PR Coverage Comment
     runs-on: ubuntu-latest
-    if: ${{ always() && github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork == false }}
+    if: ${{ !cancelled() && github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork == false && needs.changes.outputs.code == 'true' }}
     needs:
+      - changes
       - pr-test-policy
       - test-coverage
     permissions:
@@ -860,10 +1001,10 @@ jobs:
         with:
           node-version: ${{ env.CI_NODE_VERSION }}
           cache: npm
-      - run: npm ci
+      - uses: ./.github/actions/npm-ci-retry
       - run: npm run check:node-runtime
       - name: Cache Playwright browsers
-        uses: actions/cache@v5.0.5
+        uses: actions/cache@v6.0.0
         with:
           path: ~/.cache/ms-playwright
           key: playwright-chromium-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
@@ -872,12 +1013,11 @@ jobs:
       - name: Download Next.js build artifact
         uses: actions/download-artifact@v8
         with:
-          name: e2e-next-build
+          name: next-build
           path: /tmp/
-      - name: Extract Next.js build and restore standalone node_modules
+      - name: Extract Next.js build artifact
         run: |
           tar -xzf /tmp/e2e-build.tar.gz
-          cp -r node_modules .build/next/standalone/node_modules
       - run: npx playwright test tests/e2e/*.spec.ts --shard=${{ matrix.shard }}/9
 
   test-integration:
@@ -903,7 +1043,7 @@ jobs:
         with:
           node-version: ${{ env.CI_NODE_VERSION }}
           cache: npm
-      - run: npm ci
+      - uses: ./.github/actions/npm-ci-retry
       - run: npm run check:node-runtime
       - run: node --import tsx --import ./tests/_setup/isolateDataDir.ts --test --test-force-exit --test-concurrency=1 --test-shard=${{ matrix.shard }}/2 tests/integration/*.test.ts
 
@@ -923,26 +1063,27 @@ jobs:
         with:
           node-version: ${{ env.CI_NODE_VERSION }}
           cache: npm
-      - run: npm ci
+      - uses: ./.github/actions/npm-ci-retry
       - run: npm run check:node-runtime
       - run: npm run test:security
 
   ci-summary:
     name: CI Dashboard
     runs-on: ubuntu-latest
-    if: always()
+    if: ${{ !cancelled() }}
     needs:
+      - changes
       - lint
       - docs-sync-strict
       - i18n-ui-coverage
       - i18n
       - pr-test-policy
-
       - build
       - package-artifact
       - electron-package-smoke
       - test-unit
       - node-24-compat
+      - node-26-compat-build
       - node-26-compat
       - test-coverage
       - sonarqube
@@ -979,11 +1120,11 @@ jobs:
           echo "## 🧱 Core Checks" >> "$GITHUB_STEP_SUMMARY"
           echo "| Job | Status |" >> "$GITHUB_STEP_SUMMARY"
           echo "|-----|--------|" >> "$GITHUB_STEP_SUMMARY"
+          echo "| Change Classification | $(status '${{ needs.changes.result }}') |" >> "$GITHUB_STEP_SUMMARY"
           echo "| Lint | $(status '${{ needs.lint.result }}') |" >> "$GITHUB_STEP_SUMMARY"
           echo "| Docs Sync (Strict) | $(status '${{ needs.docs-sync-strict.result }}') |" >> "$GITHUB_STEP_SUMMARY"
           echo "| i18n UI Coverage | $(status '${{ needs.i18n-ui-coverage.result }}') |" >> "$GITHUB_STEP_SUMMARY"
           echo "| PR Test Policy | $(status '${{ needs.pr-test-policy.result }}') |" >> "$GITHUB_STEP_SUMMARY"
-
           echo "| SonarQube | $(status '${{ needs.sonarqube.result }}') |" >> "$GITHUB_STEP_SUMMARY"
 
           echo "" >> "$GITHUB_STEP_SUMMARY"
@@ -993,14 +1134,15 @@ jobs:
           echo "| Build Matrix | $(status '${{ needs.build.result }}') |" >> "$GITHUB_STEP_SUMMARY"
           echo "| Package Artifact | $(status '${{ needs.package-artifact.result }}') |" >> "$GITHUB_STEP_SUMMARY"
           echo "| Electron Package Smoke | $(status '${{ needs.electron-package-smoke.result }}') |" >> "$GITHUB_STEP_SUMMARY"
+          echo "| Node 26 Compatibility Build | $(status '${{ needs.node-26-compat-build.result }}') |" >> "$GITHUB_STEP_SUMMARY"
 
           echo "" >> "$GITHUB_STEP_SUMMARY"
           echo "## 🧪 Tests" >> "$GITHUB_STEP_SUMMARY"
           echo "| Suite | Status |" >> "$GITHUB_STEP_SUMMARY"
           echo "|-------|--------|" >> "$GITHUB_STEP_SUMMARY"
           echo "| Unit | $(status '${{ needs.test-unit.result }}') |" >> "$GITHUB_STEP_SUMMARY"
-          echo "| Node 24 Compatibility | $(status '${{ needs.node-24-compat.result }}') |" >> "$GITHUB_STEP_SUMMARY"
-          echo "| Node 26 Compatibility | $(status '${{ needs.node-26-compat.result }}') |" >> "$GITHUB_STEP_SUMMARY"
+          echo "| Node 24 Compatibility Tests | $(status '${{ needs.node-24-compat.result }}') |" >> "$GITHUB_STEP_SUMMARY"
+          echo "| Node 26 Compatibility Tests | $(status '${{ needs.node-26-compat.result }}') |" >> "$GITHUB_STEP_SUMMARY"
           echo "| Coverage | $(status '${{ needs.test-coverage.result }}') |" >> "$GITHUB_STEP_SUMMARY"
           echo "| PR Coverage Comment | $(status '${{ needs.coverage-pr-comment.result }}') |" >> "$GITHUB_STEP_SUMMARY"
           echo "| E2E | $(status '${{ needs.test-e2e.result }}') |" >> "$GITHUB_STEP_SUMMARY"

.github/workflows/dast-smoke.yml

@@ -42,7 +42,7 @@ jobs:
       - run: pip install schemathesis
       - name: Schemathesis smoke (high-risk endpoints, blocking)
         run: |
-          schemathesis run docs/reference/openapi.yaml --url http://localhost:20128 \
+          schemathesis run docs/openapi.yaml --url http://localhost:20128 \
             --include-path-regex '^/v1/(chat/completions|models)$|^/api/(auth|keys)' \
             --max-examples 8 --workers 4 --checks all --max-response-time 30 \
             --request-timeout 20 --suppress-health-check all --no-color

.github/workflows/docker-publish.yml

@@ -98,11 +98,13 @@ jobs:
             PROMOTE="${PROMOTE_INPUT:-false}"
           else
             git fetch --tags --quiet || true
-            HIGHEST=$(git tag -l 'v[0-9]*' | sed 's/^v//' | grep -vE -- '-(rc|alpha|beta|pre|next)' | sort -V | tail -1 || echo "")
-            if [ -n "$HIGHEST" ] && [ "$VERSION" = "$HIGHEST" ]; then
-              PROMOTE="true"
-            else
-              echo "Version $VERSION is not the highest semver tag (highest=${HIGHEST:-<none>}). Not promoting :latest."
+            # Decide via the extracted helper, which folds VERSION into the
+            # candidate set so the result is independent of git-tag sync timing
+            # on `release` events (#5301). Without that, the freshly-created tag
+            # is often not yet visible here and :latest stays a release behind.
+            PROMOTE=$(git tag -l 'v[0-9]*' | bash scripts/ci/should-promote-latest.sh "$VERSION")
+            if [ "$PROMOTE" != "true" ]; then
+              echo "Version $VERSION is not the highest stable semver. Not promoting :latest."
             fi
           fi
           echo "promote_latest=$PROMOTE" >> "$GITHUB_OUTPUT"
@@ -344,6 +346,15 @@ jobs:
 
       # Visibility scan: reports HIGH + CRITICAL into the SARIF (Security tab) but
       # never blocks (exit-code 0). The blocking gate below narrows to CRITICAL.
+      #
+      # ignore-unfixed mirrors the blocking gate: the Security tab must surface only
+      # ACTIONABLE vulnerabilities — ones with a published fix we can pull by rebuilding
+      # on a patched base or bumping the dep. Without it the advisory upload floods the
+      # tab with unfixable base-image OS CVEs (Debian trixie packages with no upstream
+      # patch yet, overwhelmingly local-only and not reachable from the proxy request
+      # surface), which is noise an operator cannot act on. trivyignores points at the
+      # repo-root .trivyignore so accepted-risk fixable CVEs have one auditable home.
+      # See docs/security/SUPPLY_CHAIN.md.
       - name: Trivy image scan (SARIF, advisory)
         if: needs.prepare.outputs.version != 'main'
         continue-on-error: true
@@ -353,6 +364,8 @@ jobs:
           format: sarif
           output: trivy-results.sarif
           severity: HIGH,CRITICAL
+          ignore-unfixed: true
+          trivyignores: .trivyignore
           exit-code: "0"
 
       # BLOCKING gate (v3.8.27 cycle-end): fail the release on a CRITICAL CVE in the

.github/workflows/electron-release.yml

@@ -94,7 +94,7 @@ jobs:
           cache: npm
 
       - name: Cache node_modules
-        uses: actions/cache@v5.0.5
+        uses: actions/cache@v6.0.0
         with:
           path: node_modules
           key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}

.github/workflows/nightly-mutation.yml

@@ -113,7 +113,7 @@ jobs:
           cache: npm
       - run: npm ci
       - name: Restore Stryker incremental cache
-        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        uses: actions/cache@2c8a9bd7457de244a408f35966fab2fb45fda9c8 # v6.0.0
         with:
           path: reports/mutation/stryker-incremental.json
           key: stryker-incremental-${{ matrix.batch.name }}-${{ github.run_id }}

.github/workflows/nightly-release-green.yml

@@ -0,0 +1,137 @@
+name: Nightly Release-Green
+
+# Solution D — continuous, NON-BLOCKING drift signal for the active release branch.
+#
+# WHY: the full gate (ci.yml) only runs on the release PR (PR → main), so reds
+# accrue silently on release/** and explode — in layers — at release time. This
+# nightly reproduces the release-equivalent validation on the active release branch
+# HEAD and, when there are HARD failures, opens/updates a single tracking issue.
+#
+# It is NOT a required status check and never touches a contributor PR — it only
+# reports. Ratchet drift (eslint warnings / cognitive-complexity / file-size) is
+# expected mid-cycle and is reported but never raises the alarm on its own; only
+# real defects (typecheck / lint errors / unit / vitest / db-rules / public-creds /
+# package-artifact) flip the issue open.
+
+on:
+  schedule:
+    - cron: "23 5 * * *" # 05:23 UTC daily — off-peak, distinct from other nightlies
+  workflow_dispatch:
+    inputs:
+      branch:
+        description: "Release branch to validate (default: highest release/vX.Y.Z)"
+        required: false
+        type: string
+
+permissions:
+  contents: read
+  issues: write
+
+concurrency:
+  group: nightly-release-green
+  cancel-in-progress: true
+
+jobs:
+  release-green:
+    name: Validate active release branch
+    runs-on: ubuntu-latest
+    env:
+      JWT_SECRET: ci-nightly-secret-with-sufficient-length-for-validation
+      API_KEY_SECRET: ci-nightly-api-key-secret-long
+      DISABLE_SQLITE_AUTO_BACKUP: "true"
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Resolve active release branch
+        id: branch
+        env:
+          INPUT_BRANCH: ${{ github.event.inputs.branch }}
+        run: |
+          set -euo pipefail
+          if [ -n "${INPUT_BRANCH:-}" ]; then
+            TARGET="$INPUT_BRANCH"
+          else
+            # highest release/vX.Y.Z by semver among remote branches
+            TARGET=$(git for-each-ref --format='%(refname:short)' 'refs/remotes/origin/release/v*' \
+              | sed 's#origin/##' \
+              | sort -t/ -k2 -V \
+              | tail -1)
+          fi
+          if [ -z "$TARGET" ]; then echo "No release/v* branch found"; exit 1; fi
+          # Strict format guard — reject anything that isn't release/vX.Y.Z (blocks
+          # ref/command injection via the workflow_dispatch input).
+          if ! printf '%s' "$TARGET" | grep -qE '^release/v[0-9]+\.[0-9]+\.[0-9]+$'; then
+            echo "Refusing non-canonical branch name: $TARGET"; exit 1
+          fi
+          echo "target=$TARGET" >> "$GITHUB_OUTPUT"
+          echo "Active release branch: $TARGET"
+
+      - name: Checkout the release branch
+        env:
+          TARGET: ${{ steps.branch.outputs.target }}
+        run: |
+          set -euo pipefail
+          git checkout "$TARGET"
+          git log -1 --oneline
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+          cache: npm
+
+      - uses: ./.github/actions/npm-ci-retry
+
+      - name: Release-green validation (full)
+        id: validate
+        run: |
+          set +e
+          node scripts/quality/validate-release-green.mjs --json --with-build \
+            1> release-green.json 2> release-green.log
+          echo "exit=$?" >> "$GITHUB_OUTPUT"
+          echo "------- report -------"
+          cat release-green.log
+
+      - name: Open / update tracking issue on HARD failure
+        if: steps.validate.outputs.exit != '0'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TARGET: ${{ steps.branch.outputs.target }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          set -euo pipefail
+          TITLE="🔴 Release branch not green: ${TARGET}"
+          {
+            echo "The nightly **release-green** validation found HARD failures on \`${TARGET}\`."
+            echo "These are real defects that would block the release PR — fix them in the"
+            echo "originating PR branch (via co-authorship), not by demanding it from contributors."
+            echo ""
+            echo "**Run:** ${RUN_URL}"
+            echo ""
+            echo '```'
+            sed -n '/──────── verdict ────────/,$p' release-green.log || tail -40 release-green.log
+            echo '```'
+            echo ""
+            echo "_Ratchet drift (eslint warnings / cognitive-complexity / file-size) listed above is expected mid-cycle and is rebaselined at release — it is NOT a contributor concern and did not, on its own, open this issue._"
+          } > issue-body.md
+
+          EXISTING=$(gh issue list --repo "$GITHUB_REPOSITORY" --state open \
+            --search "in:title $TITLE" --json number --jq '.[0].number' 2>/dev/null || echo "")
+          if [ -n "$EXISTING" ]; then
+            gh issue comment "$EXISTING" --repo "$GITHUB_REPOSITORY" --body-file issue-body.md
+            echo "Updated existing issue #$EXISTING"
+          else
+            gh issue create --repo "$GITHUB_REPOSITORY" --title "$TITLE" --body-file issue-body.md
+          fi
+
+      - name: Upload report artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-green-report
+          path: |
+            release-green.json
+            release-green.log
+          if-no-files-found: ignore

.github/workflows/nightly-resilience.yml

@@ -100,7 +100,7 @@ jobs:
           cache: npm
       - run: npm ci
       - name: Cache Playwright browsers
-        uses: actions/cache@v5.0.5
+        uses: actions/cache@v6.0.0
         with:
           path: ~/.cache/ms-playwright
           key: playwright-chromium-${{ runner.os }}-${{ hashFiles('package-lock.json') }}

.github/workflows/nightly-schemathesis.yml

@@ -45,7 +45,7 @@ jobs:
         # PROVE the contract is fuzzable and surface regressions, not to gate the build.
         continue-on-error: true
         run: |
-          schemathesis run docs/reference/openapi.yaml \
+          schemathesis run docs/openapi.yaml \
             --url http://localhost:20128 \
             --max-examples 20 \
             --workers 4 \

.github/workflows/quality.yml

@@ -40,6 +40,8 @@ jobs:
       - run: npm run check:fetch-targets
       - run: npm run check:openapi-routes
       - run: npm run check:docs-symbols
+      - name: Docs accuracy (fabricated-docs + i18n mirrors, strict)
+        run: npm run check:docs-all
       - run: npm run check:deps
       - run: npm run check:file-size
       - run: npm run check:error-helper
@@ -49,7 +51,20 @@ jobs:
       - run: npm run check:known-symbols
       - run: npm run check:route-guard-membership
       - run: npm run check:test-discovery
+      - run: npm run check:test-runner-api
       - run: npm run check:any-budget:t11
+      # Build-scope guard: fails if worktrees/cruft leak into the tsconfig include
+      # scope (would OOM `next build`). Instant. See incident 2026-06-25 / #5031.
+      - run: npm run check:build-scope
+      # Pack-policy (unexpected-files allowlist) WITHOUT a build — catches a stray file
+      # leaking into the npm tarball (v3.8.36: 6 ops bin/*.sh) per-PR instead of only on
+      # the release PR's heavy Package Artifact job.
+      - run: npm run check:pack-policy
+      # Complexity + cognitive-complexity ratchets on the fast-path (PR→release) so
+      # cycle drift is rebaselined PER-PR instead of cascading onto the release PR's
+      # Quality Ratchet (v3.8.36: +30 complexity / +15 cognitive surfaced only post-merge).
+      - run: npm run check:complexity
+      - run: npm run check:cognitive-complexity
       - name: Typecheck (core)
         run: npm run typecheck:core
       # TIA: build the impact map at runtime (gitignored, ~21MB) and run only the
@@ -82,3 +97,48 @@ jobs:
           echo "Running impacted tests:"; echo "$SEL"
           mapfile -t FILES <<< "$SEL"
           node --import tsx --import ./open-sse/utils/setupPolyfill.ts --import ./tests/_setup/isolateDataDir.ts --test --test-force-exit --test-concurrency=4 "${FILES[@]}"
+
+  fast-vitest:
+    name: Vitest (fast-path)
+    runs-on: ubuntu-latest
+    env:
+      JWT_SECRET: ci-lint-secret-with-sufficient-length-for-validation
+      API_KEY_SECRET: ci-lint-api-key-secret-long
+      DISABLE_SQLITE_AUTO_BACKUP: "true"
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.CI_NODE_VERSION }}
+          cache: npm
+      - run: npm ci
+      - run: npm run test:vitest
+
+  fast-unit:
+    name: Unit Tests fast-path (${{ matrix.shard }}/2)
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2]
+    env:
+      JWT_SECRET: ci-lint-secret-with-sufficient-length-for-validation
+      API_KEY_SECRET: ci-lint-api-key-secret-long
+      DISABLE_SQLITE_AUTO_BACKUP: "true"
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.CI_NODE_VERSION }}
+          cache: npm
+      - run: npm ci
+      - run: >
+          node --max-old-space-size=4096 --import tsx
+          --import ./tests/_setup/isolateDataDir.ts
+          --test --test-force-exit --test-concurrency=4 --test-shard=${{ matrix.shard }}/2
+          tests/unit/*.test.ts
+          "tests/unit/{api,auth,authz,build,cli,cli-helper,combo,compression,correctness,cors,dashboard,db,db-adapters,docs,gamification,guardrails,lib,mcp,runtime,security,services,settings,shared,ui}/**/*.test.ts"

.github/workflows/wiki-sync.yml

@@ -9,7 +9,7 @@ name: Wiki Sync
 # It does NOT overwrite existing wiki pages by default: several docs sources still carry
 # stale counts (e.g. ARCHITECTURE.md says "177 providers" while the wiki cover is 226),
 # so blind overwrite would regress the wiki. Full content parity (--update-existing) is
-# gated on regenerating those sources — see docs/ops/DOCUMENTATION_AUDIT_REPORT.md.
+# gated on regenerating those sources first.
 
 on:
   push:

.gitignore

@@ -161,6 +161,8 @@ typescript
 
 # Superpowers plans/specs (internal tooling, not project code)
 docs/superpowers/
+# Superpowers visual-companion brainstorm mockups (ephemeral)
+.superpowers/
 
 # TIA test-impact map — generated at runtime in CI (build-test-impact-map.mjs), never committed (~21MB)
 config/quality/test-impact-map.json

.mcp.json.example

@@ -1,17 +0,0 @@
-{
-  "$comment_purpose": "OPT-IN agent-lsp / LSP-in-the-loop (Quality Gates Fase 7 Task 15). Copy this file to `.mcp.json` to enable. It exposes a TypeScript language server to coding agents (Claude Code, etc.) so they get diagnostics / hover / go-to-definition / blast-radius BEFORE writing code — turning 'invented symbol' review-catches into impossible-at-edit-time. Pairs with `npm run typecheck:core` as a compile-before-claim check.",
-  "$comment_safety": "Shipped as `.example` (NOT `.mcp.json`) on purpose so it never auto-loads an unvetted server into everyone's session. Pick an MCP<->LSP bridge you trust and have verified locally, then drop in its package + args below. A broken MCP entry only logs a connection error; it does not break agent sessions. The underlying language server is `typescript-language-server` (npm, mature) — install via `npm i -g typescript-language-server typescript` or rely on npx.",
-  "mcpServers": {
-    "typescript-lsp": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "<your-mcp-lsp-bridge>",
-        "--lsp",
-        "typescript-language-server",
-        "--stdio"
-      ],
-      "$note": "Replace <your-mcp-lsp-bridge> with the concrete MCP<->LSP adapter you chose. It must speak MCP on stdio and proxy to `typescript-language-server --stdio`. Scope it to this repo's tsconfig (open-sse/tsconfig.json / tsconfig.json) for accurate diagnostics."
-    }
-  }
-}

.prettierignore

@@ -0,0 +1,2 @@
+# Long reference tables are manually aligned; formatting the whole file causes noisy diffs.
+docs/reference/ENVIRONMENT.md

.trivyignore

@@ -0,0 +1,22 @@
+# .trivyignore — accepted-risk suppressions for the container image scan
+#
+# Policy (see docs/security/SUPPLY_CHAIN.md):
+#   - The Trivy steps in .github/workflows/docker-publish.yml run with
+#     `ignore-unfixed: true`, so vulnerabilities WITHOUT a published fix are
+#     already excluded from both the blocking CRITICAL gate and the advisory
+#     Security-tab upload. You do NOT need an entry here for an unfixable
+#     base-image OS CVE — it will not be reported.
+#   - This file is the single auditable home for the rare case where a *fixable*
+#     CVE must be temporarily accepted (e.g. the upstream fix is not yet in the
+#     pinned base tag, or the affected package/binary is provably unreachable
+#     from the proxy request surface and rebuilding now is not justified).
+#
+# Format — one CVE id per line, each with a justification comment and, where
+# possible, an expiry, e.g.:
+#   # CVE-XXXX-YYYY — <why accepted>; revisit on next base-image bump (YYYY-MM-DD)
+#   CVE-XXXX-YYYY
+#
+# Keep this list SHORT and reviewed every release. Prefer fixing (rebuild on a
+# patched base / bump the dep) over suppressing. Stale entries are debt.
+#
+# (No accepted-risk suppressions at present — ignore-unfixed covers the noise.)

@omniroute/opencode-plugin/README.md

@@ -196,7 +196,7 @@ Every field is optional. Defaults mirror v0.1.0 behaviour so existing `opencode.
 | `combos`              | `boolean` | `true`  | Discover `/api/combos` and surface them as pseudo-models with LCD capabilities. Combos are keyed under the `combo/<slug>` namespace and labelled `Combo: <name>` in the model picker so they're distinguishable from raw provider/model pairs.                                                                                                                                                                                                                                                                                                                               |
 | `enrichment`          | `boolean` | `true`  | Pull display names from `/api/pricing/models` AND per-million-token pricing (`input`, `output`, `cached` → `cacheRead`, `cache_creation` → `cacheWrite`) from `/api/pricing`, then overlay both onto the live catalog (so the UI shows `Claude 4.7 Opus` with `cost.input: 5`, `cost.output: 25` instead of raw IDs and zeroed cost).                                                                                                                                                                                                                                        |
 | `compressionMetadata` | `boolean` | `false` | Pull `/api/context/combos` so combo names get tagged with their compression pipeline, e.g. `Combo: claude-primary [rtk🟡 → caveman🟠]`. Intensity tokens render as traffic-light emoji (🟢 lite/minimal · 🟡 standard · 🟠 aggressive/full · 🔴 ultra) so the picker advertises "how compressed" each combo is at a glance.                                                                                                                                                                                                                                                  |
-| `providerTag`         | `boolean` | `true`  | Prepend a short upstream-provider label to the enriched display name with `" - "` separator, so `cc/claude-opus-4-7 → Claude - Claude Opus 4.7` differs visibly from `kr/claude-opus-4-7 → Kiro - Claude Opus 4.7` in the OC TUI model picker. Label resolution: use `/api/pricing/models[<alias>].name` verbatim when ≤8 chars (e.g. `Claude`, `Kiro`, `Codex`, `Qwen`), otherwise fall back to `UPPER(alias)` (e.g. `GitHub Models` → `GHM`, `Gemini-cli` → `GEMINI-CLI`). Idempotent. Combos intentionally skipped (the `Combo: ` prefix already conveys multi-upstream). |
+| `providerTag`         | `boolean` | `true`  | Prepend a short upstream-provider label to the enriched display name with `" - "` separator, so `cc/claude-opus-4-7 → Claude - Claude Opus 4.7` differs visibly from `kr/claude-opus-4-7 → Kiro - Claude Opus 4.7` in the OC TUI model picker. Label resolution: use `/api/pricing/models[<alias>].name` verbatim when ≤8 chars (e.g. `Claude`, `Kiro`, `Codex`, `Qwen`), otherwise fall back to `UPPER(alias)` (e.g. `GitHub Models` → `GHM`, `Gemini` → `GEMINI`). Idempotent. Combos intentionally skipped (the `Combo: ` prefix already conveys multi-upstream). |
 | `usableOnly`          | `boolean` | `false` | Read `/api/providers` and filter the catalog to providers that have at least one connection with `isActive: true` AND `testStatus: 'active'`. Subtract-filter semantics: providers unknown to BOTH the pricing-models catalog AND the connection table pass through (so synthetic prefixes like `agentrouter/*` survive). On fetch failure the filter is disabled for the refresh — never hides the whole catalog.                                                                                                                                                           |
 | `diskCache`           | `boolean` | `true`  | Persist the last successful `/v1/models` + `/api/combos` + enrichment + connections + compression snapshot to `${OPENCODE_DATA_DIR ?? ~/.local/share/opencode}/plugins/omniroute-<providerId>.json`. On a subsequent cold start where `/v1/models` throws (network down / IP whitelist drop / 5xx) the static block hydrates from the snapshot so OC's model picker survives offline. Soft-fail on read/write — never blocks publishing.                                                                                                                                     |
 | `geminiSanitization`  | `boolean` | `true`  | Strip `$schema`/`$ref`/`additionalProperties` from tool params when the model id matches `gemini`                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |

@omniroute/opencode-plugin/src/index.ts

@@ -240,10 +240,18 @@ export function resolveOmniRoutePluginOptions(
   opts?: OmniRoutePluginOptions
 ): Required<Pick<OmniRoutePluginOptions, "providerId" | "displayName" | "modelCacheTtl">> &
   Pick<OmniRoutePluginOptions, "baseURL" | "features"> {
-  const providerId = opts?.providerId ?? OMNIROUTE_PROVIDER_KEY;
+  const rawProviderId = opts?.providerId ?? OMNIROUTE_PROVIDER_KEY;
+  // OC 1.17.8+ native-adapter gate rejects providerID not in
+  // {openai, anthropic, opencode*}. Silently prefix so existing
+  // configs (providerId: "omniroute") keep working.
+  const providerId = rawProviderId.startsWith("opencode-")
+    ? rawProviderId
+    : `opencode-${rawProviderId}`;
   const displayName =
     opts?.displayName ??
-    (providerId === OMNIROUTE_PROVIDER_KEY ? "OmniRoute" : `OmniRoute (${providerId})`);
+    (providerId === `opencode-${OMNIROUTE_PROVIDER_KEY}`
+      ? "OmniRoute"
+      : `OmniRoute (${providerId})`);
   const modelCacheTtl =
     typeof opts?.modelCacheTtl === "number" && opts.modelCacheTtl > 0
       ? opts.modelCacheTtl
@@ -708,7 +716,14 @@ export function mapRawModelToModelV2(
   const outMods = new Set(raw.output_modalities ?? ["text"]);
 
   return {
-    id: raw.id,
+    // OC's static-catalog reader parses the key on `/` to recover
+    // `(providerID, modelID)`. If the raw id is already provider-prefixed
+    // (e.g. `cc/claude-opus-4-7` from the `cc` Claude Code alias, or
+    // `nvidia/llama-3-70b` from a provider that ships prefixed ids), leave
+    // it as-is — double-prefixing breaks OC's lookup. Otherwise prefix with
+    // the resolved `providerId` so a bare key like `claude-opus-4` parses as
+    // `(omniroute, claude-opus-4)` and the credentials resolve correctly.
+    id: raw.id.includes("/") ? raw.id : `${ctx.providerId}/${raw.id}`,
     /**
      * Display name. Falls back to raw.id when no enrichment is available;
      * the caller (`createOmniRouteProviderHook`) overlays
@@ -1166,6 +1181,10 @@ export function mapAutoComboToStaticEntry(
     typeof autoCombo.max_output_tokens === "number" && autoCombo.max_output_tokens > 0
       ? autoCombo.max_output_tokens
       : AUTO_COMBO_FALLBACK_OUTPUT;
+  // No `providerID` field on static-catalog entries — OC ignores it on the static
+  // path, and stamping it on auto-combos but not on raw/combo entries was an
+  // internal inconsistency. The dynamic-hook path builds its ModelV2 from the
+  // individual fields below and never read this field either.
   return {
     name,
     attachment: false,
@@ -1206,7 +1225,7 @@ export interface OmniRouteEnrichmentEntry {
     cacheWrite?: number;
   };
   /**
-   * Provider alias prefix seen in `/v1/models` ids (e.g. `cc`, `gemini-cli`).
+   * Provider alias prefix seen in `/v1/models` ids (e.g. `cc`, `gemini`).
    * Populated by `defaultOmniRouteEnrichmentFetcher` from
    * `/api/pricing/models` keys. Drives the `usableOnly` alias↔canonical
    * resolution.
@@ -1214,7 +1233,7 @@ export interface OmniRouteEnrichmentEntry {
   providerAlias?: string;
   /**
    * Canonical provider id used by `/api/providers` connections (e.g.
-   * `claude`, `gemini-cli`, `kiro`). Populated from the per-provider
+   * `claude`, `gemini`, `kiro`). Populated from the per-provider
    * `entry.id` field inside `/api/pricing/models`.
    */
   providerCanonical?: string;
@@ -2027,7 +2046,7 @@ export function formatCompressionPipeline(pipeline: OmniRouteCompressionStep[]):
 export interface OmniRouteProviderConnection {
   /** Connection UUID. */
   id: string;
-  /** Canonical provider id, e.g. `claude`, `gemini-cli`, `kiro`. Matches `entry.id` in `/api/pricing/models`. */
+  /** Canonical provider id, e.g. `claude`, `gemini`, `kiro`. Matches `entry.id` in `/api/pricing/models`. */
   provider: string;
   /** Connection auth flavor, e.g. `apikey`, `oauth`, `cookie`. */
   authType?: string;
@@ -2106,7 +2125,7 @@ export const defaultOmniRouteProvidersFetcher: OmniRouteProvidersFetcher = async
  * walk only the namespaced keys to derive the alias↔canonical mapping).
  *
  * Returns:
- *   - `aliases`: set of alias prefixes safe to keep (e.g. `cc`, `gemini-cli`).
+ *   - `aliases`: set of alias prefixes safe to keep (e.g. `cc`, `gemini`).
  *   - `canonicals`: set of canonical provider ids (e.g. `claude`, `kiro`).
  *
  * Callers should treat membership in EITHER set as "usable" — raw model
@@ -2155,7 +2174,7 @@ export function usableProviderAliasSet(
   }
   // Always include every usable canonical as an alias too — handles the
   // common case where `/v1/models` ids use the canonical id directly
-  // (e.g. `gemini-cli/gemini-1.5-pro`).
+  // (e.g. `gemini/gemini-1.5-pro`).
   for (const canonical of usableCanonicals) aliases.add(canonical);
   return { aliases, canonicals: usableCanonicals, knownAliases };
 }
@@ -2248,26 +2267,38 @@ export function slugifyComboName(name: string): string {
 }
 
 /**
- * Build a combo's static-block key (`combo/<slug>`), guaranteeing uniqueness
- * across an entire static catalog. If `<slug>` is already present in `used`,
- * suffixes a short UUID-prefix disambiguator from `combo.id` so the second
- * combo doesn't silently overwrite the first. Mutates `used` in place by
- * recording the chosen key. Returns the final `combo/<...>` key.
+ * Build a combo's static-block key, provider-prefixed as `<providerId>/<slug>`
+ * (e.g. `omniroute/MASTER`, `omniroute/MASTER-LIGHT`), guaranteeing uniqueness
+ * across an entire static catalog. If `<providerId>/<slug>` is already present in
+ * `used`, suffixes a short UUID-prefix disambiguator from `combo.id` so the second
+ * combo doesn't silently overwrite the first. Mutates `used` in place by recording
+ * the chosen key. Returns the final `<providerId>/<slug>` key.
  *
- * Falls back to `combo/<id>` when the friendly name slugifies to the empty
+ * NOTE: the key MUST carry the OWNING provider prefix (`omniroute/…`), never a
+ * `combo/` namespace — OpenCode parses model IDs on `/` to extract the provider,
+ * so `combo/MASTER` would resolve provider=`combo` (no credentials) and fail with
+ * "Unable to determine provider", whereas `omniroute/MASTER` resolves provider=
+ * `omniroute` and the openai-compatible adapter strips the prefix and sends the
+ * bare slug upstream, which the server resolves via getComboByName. See PR #4184.
+ *
+ * Falls back to `<providerId>/<id>` when the friendly name slugifies to the empty
  * string (e.g. a combo named just punctuation).
  */
-export function buildComboKey(combo: OmniRouteRawCombo, used: Set<string>): string {
+export function buildComboKey(
+  combo: OmniRouteRawCombo,
+  used: Set<string>,
+  providerId: string
+): string {
   const friendlyName = combo.name && combo.name.trim().length > 0 ? combo.name.trim() : combo.id;
   let slug = slugifyComboName(friendlyName);
   if (slug.length === 0) slug = combo.id;
-  let key = `combo/${slug}`;
+  let key = `${providerId}/${slug}`;
   if (used.has(key)) {
     const tail = combo.id.split("-")[0] ?? combo.id;
-    key = `combo/${slug}-${tail}`;
+    key = `${providerId}/${slug}-${tail}`;
     // Defensive: in the (impossible) event the disambiguated key also
     // collides, append the full id.
-    if (used.has(key)) key = `combo/${slug}-${combo.id}`;
+    if (used.has(key)) key = `${providerId}/${slug}-${combo.id}`;
   }
   used.add(key);
   return key;
@@ -2651,7 +2682,12 @@ export function createOmniRouteProviderHook(
           );
           applyProviderTag(model, tagEntry);
         }
-        models[entry.id] = model;
+        // OC's static-catalog reader parses the key on `/` to recover
+        // (providerID, modelID). `mapRawModelToModelV2` already stamps the
+        // prefixed id on `model.id` (e.g. `omniroute/claude-primary`), so we
+        // must key by `model.id` — not by the raw `entry.id` which would be
+        // a bare slug and parse as `providerID=slug, modelID=""`.
+        models[model.id] = model;
       }
 
       // Default compression combo (used to decorate ALL combo names when
@@ -2801,18 +2837,6 @@ export function createOmniRouteProviderHook(
           // models with curated names).
           applyEnrichment(mapped, rawEnrichment.get(combo.id));
 
-          // `Combo: ` prefix surfaces the combo nature in OC's model picker.
-          // Idempotent guard covers the case where enrichment overwrote
-          // mapped.name with an already-prefixed string. Mirrors the
-          // static-hook Combo:-prefix decoration.
-          if (!mapped.name.startsWith("Combo: ")) {
-            mapped.name = `Combo: ${mapped.name}`;
-          }
-
-          // Optionally decorate combo name with its compression pipeline.
-          // Only fires when features.compressionMetadata: true, OmniRoute
-          // returned at least one default compression combo, AND the
-          // combo has resolvable members — claiming compression on an
           // unroutable combo would mislead the picker.
           if (hasMembers && defaultCompression && defaultCompression.pipeline.length > 0) {
             const tag = formatCompressionPipeline(defaultCompression.pipeline);
@@ -2821,18 +2845,37 @@ export function createOmniRouteProviderHook(
             }
           }
 
-          const comboKey = buildComboKey(combo, usedComboKeys);
+          const comboKey = buildComboKey(combo, usedComboKeys, resolved.providerId);
 
           // Collision policy: combos win. Warn ONCE per (cacheKey, comboKey)
           // when overwriting a same-key raw model so the operator can spot
-          // the unusual naming choice without log spam.
+          // the unusual naming choice without log spam. Suppress the warning
+          // when the collision is the intentional dedup pattern (combo.name
+          // exactly matches an existing raw model's id) — /v1/models
+          // pre-mirrors combos as raw entries and the operator's intent is
+          // always "combo wins" in that case.
           if (Object.prototype.hasOwnProperty.call(models, comboKey)) {
-            const dedupeKey = `${cacheKey}::${comboKey}`;
-            if (!collisionWarned.has(dedupeKey)) {
-              collisionWarned.add(dedupeKey);
-              console.warn(
-                `[omniroute-plugin] combo key "${comboKey}" collides with a model id; combo wins.`
-              );
+            const existing = models[comboKey];
+            // Intentional dedup: `/v1/models` pre-mirrors combos as raw
+            // entries, so the bare combo name appears as the model id in
+            // `rawModels`. After our prefixing the existing entry's id is
+            // `${providerId}/${raw.id}` — the combo name is a substring of
+            // that prefixed id (or, for already-prefixed raw models, the
+            // exact id). Use `endsWith` to avoid matching substrings of
+            // unrelated prefixed ids.
+            const isIntentionalDedup =
+              existing &&
+              combo.name &&
+              combo.name.trim().length > 0 &&
+              (existing.id === combo.name.trim() || existing.id.endsWith(`/${combo.name.trim()}`));
+            if (!isIntentionalDedup) {
+              const dedupeKey = `${cacheKey}::${comboKey}`;
+              if (!collisionWarned.has(dedupeKey)) {
+                collisionWarned.add(dedupeKey);
+                console.warn(
+                  `[omniroute-plugin] combo key "${comboKey}" collides with a model id; combo wins.`
+                );
+              }
             }
           }
           models[comboKey] = mapped;
@@ -3131,7 +3174,6 @@ export function sanitizeGeminiToolSchemas(payload: unknown): unknown {
  *     `gemini-2.5-flash`, etc.)
  *   - `models/gemini-…` (Google Generative AI canonical id form)
  *   - `google-vertex/gemini-…` (OpenCode + AI-SDK Vertex routing prefix)
- *   - `gemini-cli/…` (real OmniRoute alias surfaced on b35 prod `/v1/models`)
  *
  * Liberal by design: a false positive (cleaning a payload that didn't
  * need cleaning) costs only a structuredClone + one walk; a false negative
@@ -3346,8 +3388,18 @@ function normaliseModalities(raw: unknown): OmniRouteModalityKind[] {
 }
 
 export interface OmniRouteStaticModelEntry {
+  /** Owning provider id. SHOULD match the parent `provider.<id>` key so OC's
+   * static-catalog reader resolves credentials via `providerID` instead of
+   * parsing the model key on `/`. Optional: OC's schema validator may
+   * reject the entire provider block when this field is present but the
+   * model KEY already carries the provider prefix (e.g. `omniroute/MASTER`),
+   * since the prefix makes the field redundant and the field is not part of
+   * OC's expected schema. We omit it from entries and rely on the prefix
+   * on the KEY alone. See PR #4184. */
+  providerID?: string;
   /** Display label rendered in OC's model picker. Defaults to the model id. */
   name: string;
+
   /** ISO date the model was released. Surfaces in OC's model card when present. */
   release_date?: string;
   /** Model accepts image / file attachments. */
@@ -3545,6 +3597,12 @@ export function buildStaticProviderEntry(
         if (!displayName.startsWith(prefix)) displayName = `${prefix}${displayName}`;
       }
     }
+    // OC's static-catalog schema doesn't expect a `providerID` field on
+    // individual entries — the parent block ID is the provider. Adding
+    // unknown fields here can cause OC's schema validator to reject the
+    // entire provider block, hiding ALL models. The provider prefix on the
+    // model KEY (e.g. `omniroute/claude-opus-4`) is what OC uses to recover
+    // (providerID, modelID) when the user selects a model.
     const entry: OmniRouteStaticModelEntry = { name: displayName };
 
     const attachment = caps.attachment ?? caps.vision;
@@ -3608,7 +3666,12 @@ export function buildStaticProviderEntry(
       entry.release_date = raw.release_date;
     }
 
-    models[raw.id] = entry;
+    // OC's static-catalog reader parses each key on `/` and rejects the
+    // entire provider block if ANY key resolves to a parsed providerID that
+    // has no corresponding provider block. So bare keys (no `/`) MUST be
+    // prefixed with the resolved providerId. Already-prefixed keys
+    // (e.g. `cc/claude-opus-4-7`) are left as-is to avoid double-prefixing.
+    models[raw.id.includes("/") ? raw.id : `${opts.providerId}/${raw.id}`] = entry;
   }
 
   // Combo entries → stripped LCD shape. Each combo is keyed as
@@ -3717,12 +3780,11 @@ export function buildStaticProviderEntry(
       const hasMembers = memberEntries.length > 0;
       const friendlyName =
         combo.name && combo.name.trim().length > 0 ? combo.name.trim() : combo.id;
-      // `Combo: ` prefix surfaces the combo nature in OC's model picker — the
-      // catalog key (`combo/<slug>`) is already namespaced, but the picker
-      // shows `name`, so prefix the display string too.
-      const prefixedName = `Combo: ${friendlyName}`;
       const displayName =
-        hasMembers && compressionSuffix ? `${prefixedName}${compressionSuffix}` : prefixedName;
+        hasMembers && compressionSuffix ? `${friendlyName} ${compressionSuffix}` : friendlyName;
+      // See the raw-model entry comment above — `providerID` on entries is
+      // not part of OC's static-catalog schema; the parent block ID is the
+      // provider and the KEY prefix (`omniroute/<slug>`) is what OC parses.
       const entry: OmniRouteStaticModelEntry = { name: displayName };
 
       if (hasMembers) {
@@ -3790,12 +3852,12 @@ export function buildStaticProviderEntry(
         entry.tool_call = false;
       }
 
-      // Key under `combo/<slug>` (e.g. `combo/claude-primary`) so the
-      // namespace cleanly separates combos from raw provider/model pairs
-      // and so the key is copy/paste-friendly. Slug collisions across
+      // Key under bare slug (e.g. `claude-primary`) — no `combo/` prefix
+      // because OpenCode parses model IDs on `/` and would treat
+      // `combo/MASTER` as provider=`combo`. Slug collisions across
       // combos are disambiguated with a short UUID-prefix suffix; see
       // `buildComboKey` for the policy.
-      models[buildComboKey(combo, usedComboKeys)] = entry;
+      models[buildComboKey(combo, usedComboKeys, opts.providerId)] = entry;
 
       // Make this combo's resolved entry available to parent combos
       // that reference it via combo-ref. Use the friendly name since
@@ -4343,8 +4405,24 @@ export function createOmniRouteConfigHook(
       authJson = undefined;
     }
 
-    const entry = authJson?.[resolved.providerId] as AuthJsonApiEntry | undefined;
-    const apiKey = entry && entry.type === "api" && typeof entry.key === "string" ? entry.key : "";
+    // Try both prefixed (e.g. opencode-omniroute) and unprefixed (e.g. omniroute)
+    // keys so a user who ran `/connect omniroute` before the auto-prefix fix
+    // does not need to re-auth. Also handles dual-key for auth.json entries
+    // written by a newer OC dispatcher with the prefixed key.
+    const bareKey = resolved.providerId.startsWith("opencode-")
+      ? resolved.providerId.slice("opencode-".length)
+      : resolved.providerId;
+    const lookupKeys = [resolved.providerId];
+    if (bareKey !== resolved.providerId) lookupKeys.push(bareKey);
+    let entry;
+    for (const k of lookupKeys) {
+      const e = authJson?.[k];
+      if (e?.type === "api" && typeof e.key === "string" && e.key.length > 0) {
+        entry = e;
+        break;
+      }
+    }
+    const apiKey = entry?.type === "api" && typeof entry.key === "string" ? entry.key : "";
 
     if (!apiKey) {
       // (c) no apiKey — silent no-op (with debug breadcrumb). The operator

@omniroute/opencode-plugin/tests/auth.test.ts

@@ -13,12 +13,12 @@ import { createOmniRouteAuthHook } from "../src/index.js";
 
 test("createOmniRouteAuthHook: default providerId is 'omniroute'", () => {
   const hook = createOmniRouteAuthHook();
-  assert.equal(hook.provider, "omniroute");
+  assert.equal(hook.provider, "opencode-omniroute");
 });
 
 test("createOmniRouteAuthHook: custom providerId binds to hook.provider (multi-instance)", () => {
   const hook = createOmniRouteAuthHook({ providerId: "omniroute-preprod" });
-  assert.equal(hook.provider, "omniroute-preprod");
+  assert.equal(hook.provider, "opencode-omniroute-preprod");
 });
 
 test("createOmniRouteAuthHook: methods[0] is type 'api' with label including displayName", () => {
@@ -30,7 +30,7 @@ test("createOmniRouteAuthHook: methods[0] is type 'api' with label including dis
   assert.equal(m.label, "OmniRoute API Key");
 
   const custom = createOmniRouteAuthHook({ providerId: "omniroute-preprod" });
-  assert.equal(custom.methods[0].label, "OmniRoute (omniroute-preprod) API Key");
+  assert.equal(custom.methods[0].label, "OmniRoute (opencode-omniroute-preprod) API Key");
 });
 
 test("createOmniRouteAuthHook: prompts[0] uses key='apiKey' per @opencode-ai/plugin contract", () => {

@omniroute/opencode-plugin/tests/combos.test.ts

@@ -447,14 +447,14 @@ test("models() returns combo entries merged into the map", async () => {
 
   // 3 raw models + 1 combo = 4 entries
   assert.equal(Object.keys(out).length, 4);
-  assert.ok(out["claude-primary"]);
-  assert.ok(out["claude-secondary"]);
-  assert.ok(out["gemini-3-flash"]);
-  assert.ok(out["combo/claude-tier"]);
+  assert.ok(out["opencode-omniroute/claude-primary"]);
+  assert.ok(out["opencode-omniroute/claude-secondary"]);
+  assert.ok(out["opencode-omniroute/gemini-3-flash"]);
+  assert.ok(out["opencode-omniroute/claude-tier"]);
 
-  const combo = out["combo/claude-tier"];
-  assert.equal(combo.name, "Combo: Claude Tier");
-  assert.equal(combo.providerID, "omniroute");
+  const combo = out["opencode-omniroute/claude-tier"];
+  assert.equal(combo.name, "Claude Tier");
+  assert.equal(combo.providerID, "opencode-omniroute");
   // LCD over claude-primary (200k, reasoning) + claude-secondary (100k, no reasoning)
   assert.equal(combo.limit.context, 100_000);
   assert.equal(combo.capabilities.reasoning, false);
@@ -478,11 +478,11 @@ test("models(): combo with unknown member ids degrades to all-false LCD posture"
     { fetcher: modelsFetcher, combosFetcher }
   );
   const out = await hook.models!({} as never, { auth: apiAuth("sk-z") as never });
-  assert.ok(out["combo/phantom-combo"]);
+  assert.ok(out["opencode-omniroute/phantom-combo"]);
   // With zero resolvable members, LCD = all-false (defensive posture).
-  assert.equal(out["combo/phantom-combo"].capabilities.toolcall, false);
-  assert.equal(out["combo/phantom-combo"].capabilities.reasoning, false);
-  assert.equal(out["combo/phantom-combo"].limit.context, 0);
+  assert.equal(out["opencode-omniroute/phantom-combo"].capabilities.toolcall, false);
+  assert.equal(out["opencode-omniroute/phantom-combo"].capabilities.reasoning, false);
+  assert.equal(out["opencode-omniroute/phantom-combo"].limit.context, 0);
 });
 
 test("models(): hidden combos are excluded from the map", async () => {
@@ -505,11 +505,11 @@ test("models(): hidden combos are excluded from the map", async () => {
     { fetcher: modelsFetcher, combosFetcher }
   );
   const out = await hook.models!({} as never, { auth: apiAuth("sk-z") as never });
-  assert.ok(out["combo/visible"]);
-  assert.ok(!out["combo/hidden"], "hidden combo must be omitted");
+  assert.ok(out["opencode-omniroute/visible"]);
+  assert.ok(!out["opencode-omniroute/hidden"], "hidden combo must be omitted");
 });
 
-test("models(): combo name exactly matches raw model id → raw deleted, combo lives at combo/ key, no warn", async () => {
+test("models(): combo name exactly matches raw model id → raw deleted, raw deleted, no warn", async () => {
   // Combo.name === raw model id triggers the dedup deletion. This mirrors
   // the real OmniRoute payload where /v1/models pre-mirrors combos as
   // no-slash raw entries whose ids match /api/combos friendly names.
@@ -529,10 +529,9 @@ test("models(): combo name exactly matches raw model id → raw deleted, combo l
     return hook.models!({} as never, { auth: apiAuth("sk-z") as never });
   });
 
-  // Raw model deleted by combo-name dedup; combo surfaces under combo/<slug>.
-  assert.equal(out["claude-primary"], undefined, "raw deleted by combo-name dedup");
-  assert.ok(out["combo/claude-primary"], "combo surfaces under combo/ namespace");
-  assert.equal(out["combo/claude-primary"].name, "Combo: claude-primary");
+  // Raw model replaced by combo of the same key; combo now lives at the bare slug.
+  assert.ok(out["opencode-omniroute/claude-primary"], "combo surfaces under prefixed key");
+  assert.equal(out["opencode-omniroute/claude-primary"].name, "claude-primary");
 
   // No collision warning fires — dedup makes keys disjoint.
   const collisionWarns = warnings.filter((w) => {
@@ -543,7 +542,7 @@ test("models(): combo name exactly matches raw model id → raw deleted, combo l
 });
 
 test("models(): two combos with same slug → second gets disambiguator suffix", async () => {
-  // Both combos slug to `claude` — second must get `combo/claude-<id-prefix>`.
+  // Both combos slug to `claude` — second must get `claude-<id-prefix>`.
   const combos: OmniRouteRawCombo[] = [
     {
       id: "uuid-a",
@@ -566,8 +565,8 @@ test("models(): two combos with same slug → second gets disambiguator suffix",
 
   const out = await hook.models!({} as never, { auth: apiAuth("sk-z") as never });
   // First combo gets the bare slug; second gets disambiguated.
-  assert.ok(out["combo/claude"], "first combo at bare slug");
-  assert.ok(out["combo/claude-uuid"], "second combo disambiguated by id prefix");
+  assert.ok(out["opencode-omniroute/claude"], "first combo at prefixed slug");
+  assert.ok(out["opencode-omniroute/claude-uuid"], "second combo disambiguated by id prefix");
 });
 
 test("models(): combos fetch fails → falls back to models-only, warn emitted, no throw", async () => {
@@ -584,8 +583,8 @@ test("models(): combos fetch fails → falls back to models-only, warn emitted,
 
   // Catalog includes the models but NOT any combo entries.
   assert.equal(Object.keys(out).length, 2);
-  assert.ok(out["claude-primary"]);
-  assert.ok(out["claude-secondary"]);
+  assert.ok(out["opencode-omniroute/claude-primary"]);
+  assert.ok(out["opencode-omniroute/claude-secondary"]);
 
   // Soft-fail warning surfaced.
   const softFail = warnings.find((w) => {
@@ -610,7 +609,7 @@ test("models(): combos cached + reused within TTL (one combo fetch per TTL windo
   const second = await hook.models!({} as never, { auth: apiAuth("sk-z") as never });
   assert.equal(combosFetcher.callCount(), 1, "combos fetched only once within TTL");
   assert.equal(modelsFetcher.callCount(), 1, "models fetched only once within TTL");
-  assert.ok(second["combo/claude-tier"]);
+  assert.ok(second["opencode-omniroute/claude-tier"]);
 });
 
 test("models(): combos refetched after TTL expiry (same key as models)", async () => {
@@ -702,7 +701,7 @@ test("models(): nested combo-ref context is the min of nested + raw members", as
     { fetcher: modelsFetcher, combosFetcher }
   );
   const out = await hook.models!({} as never, { auth: apiAuth("sk-z") as never });
-  const masterLight = out["combo/master-light"];
+  const masterLight = out["opencode-omniroute/master-light"];
   assert.ok(masterLight, "MASTER-LIGHT entry must exist");
   assert.equal(
     masterLight.limit.context,

@omniroute/opencode-plugin/tests/config-shim.test.ts

@@ -203,7 +203,7 @@ function makeInput(initialProvider: Record<string, unknown> = {}): Config {
 
 test("config: with valid auth.json + apiKey + baseURL → mutates input.provider[id] with stripped models block", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test-1", baseURL: "https://or.example.com/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-test-1", baseURL: "https://or.example.com/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE, MODEL_GEMINI]);
   const combosFetcher = stubCombosFetcher([COMBO_CLAUDE_TIER]);
@@ -217,8 +217,8 @@ test("config: with valid auth.json + apiKey + baseURL → mutates input.provider
   await hook(input);
 
   const provider = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider;
-  const entry = provider.omniroute;
-  assert.ok(entry, "input.provider.omniroute set");
+  const entry = provider["opencode-omniroute"];
+  assert.ok(entry, "input.provider['opencode-omniroute'] set");
   assert.equal(entry.npm, "@ai-sdk/openai-compatible");
   assert.equal(entry.name, "OmniRoute");
   assert.equal(entry.options.baseURL, "https://or.example.com/v1");
@@ -227,7 +227,7 @@ test("config: with valid auth.json + apiKey + baseURL → mutates input.provider
   // Stripped per-model shape: name + cap flags + modalities + (optional)
   // cost. OC's SDK static schema accepts only `limit.{context,output}` —
   // `limit.input` is NOT in the SDK shape and gets dropped silently.
-  const claude = entry.models["claude-sonnet-4-6"];
+  const claude = entry.models["opencode-omniroute/claude-sonnet-4-6"];
   assert.ok(claude, "claude model surfaced");
   assert.equal(claude.name, "claude-sonnet-4-6");
   assert.equal(claude.attachment, true);
@@ -246,16 +246,75 @@ test("config: with valid auth.json + apiKey + baseURL → mutates input.provider
   assert.deepEqual(claude.modalities?.input, ["text", "image"]);
   assert.deepEqual(claude.modalities?.output, ["text"]);
 
-  // Combo surfaces under `combo/<friendly-name>` namespace + LCD'd
+  // Combo surfaces under bare key + LCD'd
   // (gemini's reasoning=false → combo reasoning=false).
-  const combo = entry.models["combo/claude-tier"];
-  assert.ok(combo, "combo surfaced under combo/ namespace");
-  assert.equal(combo.name, "Combo: Claude Tier");
+  const combo = entry.models["opencode-omniroute/claude-tier"];
+  assert.ok(combo, "combo surfaced under bare key");
+  assert.equal(combo.name, "Claude Tier");
   assert.equal(combo.reasoning, false, "LCD: any member reasoning=false → combo reasoning=false");
   assert.equal(combo.tool_call, true);
   assert.equal(combo.limit?.context, 200_000, "LCD: min(200_000, 1_000_000)");
 });
 
+// ────────────────────────────────────────────────────────────────────────────
+// 1b. Dual-key fallback (#5027) — auth.json stored under the BARE providerId
+//     (pre-auto-prefix login) must still resolve when the active providerId is
+//     prefixed (`opencode-omniroute`). Without the fallback the lookup misses
+//     the stored key and the user is forced to re-auth.
+// ────────────────────────────────────────────────────────────────────────────
+
+test("config: auth.json under bare key (pre-prefix login) resolves via dual-key fallback", async () => {
+  // Stored under bare `omniroute` (the key OC wrote before the auto-prefix fix),
+  // but the resolved providerId is now `opencode-omniroute`.
+  const readAuthJson = stubReadAuthJson({
+    omniroute: { type: "api", key: "sk-bare-1", baseURL: "https://or.example.com/v1" },
+  });
+  const fetcher = stubModelsFetcher([MODEL_CLAUDE]);
+  const combosFetcher = stubCombosFetcher([]);
+  const logger = captureWarn();
+
+  const hook = createOmniRouteConfigHook(
+    { providerId: "omniroute" }, // resolves to opencode-omniroute internally
+    { readAuthJson, fetcher, combosFetcher, logger }
+  );
+  const input = makeInput();
+  await hook(input);
+
+  const provider = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider;
+  const entry = provider["opencode-omniroute"];
+  assert.ok(entry, "provider entry published from bare-key apiKey");
+  assert.equal(entry.options.apiKey, "sk-bare-1", "apiKey resolved from the bare auth.json key");
+  assert.equal(entry.options.baseURL, "https://or.example.com/v1");
+});
+
+test("config: prefixed key wins over bare key when both present (dual-key precedence)", async () => {
+  const readAuthJson = stubReadAuthJson({
+    "opencode-omniroute": { type: "api", key: "sk-prefixed", baseURL: "https://pref.example/v1" },
+    omniroute: { type: "api", key: "sk-bare", baseURL: "https://bare.example/v1" },
+  });
+  const fetcher = stubModelsFetcher([MODEL_CLAUDE]);
+  const combosFetcher = stubCombosFetcher([]);
+  const logger = captureWarn();
+
+  const hook = createOmniRouteConfigHook(
+    { providerId: "omniroute" },
+    { readAuthJson, fetcher, combosFetcher, logger }
+  );
+  const input = makeInput();
+  await hook(input);
+
+  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
+  assert.ok(entry);
+  assert.equal(
+    entry.options.apiKey,
+    "sk-prefixed",
+    "prefixed key takes precedence (looked up first)"
+  );
+  assert.equal(entry.options.baseURL, "https://pref.example/v1");
+});
+
 // ────────────────────────────────────────────────────────────────────────────
 // 2. Missing auth.json → no-op, no throw, no mutation
 // ────────────────────────────────────────────────────────────────────────────
@@ -323,7 +382,7 @@ test("config: existing input.provider[id] → no overwrite (respect manual overr
     models: { "manual-model": { name: "manual-model" } },
   };
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE]);
   const combosFetcher = stubCombosFetcher([]);
@@ -333,11 +392,11 @@ test("config: existing input.provider[id] → no overwrite (respect manual overr
     { providerId: "omniroute" },
     { readAuthJson, fetcher, combosFetcher, logger }
   );
-  const input = makeInput({ omniroute: manual });
+  const input = makeInput({ "opencode-omniroute": manual });
   await hook(input);
 
   const provider = (input as { provider: Record<string, unknown> }).provider;
-  assert.equal(provider.omniroute, manual, "manual override preserved by reference");
+  assert.equal(provider["opencode-omniroute"], manual, "manual override preserved by reference");
   assert.equal(fetcher.callCount(), 0, "no fetch — short-circuited before I/O");
   assert.equal(readAuthJson.callCount(), 0, "no auth.json read either");
   assert.ok(
@@ -352,7 +411,7 @@ test("config: existing input.provider[id] → no overwrite (respect manual overr
 
 test("config: fetchers throw → warn + emit stub entry with models: {}", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
   });
   const fetcher = throwingModelsFetcher();
   const combosFetcher = throwingCombosFetcher();
@@ -368,8 +427,9 @@ test("config: fetchers throw → warn + emit stub entry with models: {}", async
   const input = makeInput();
   await hook(input);
 
-  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider
-    .omniroute;
+  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
   assert.ok(entry, "stub provider entry published even when fetchers fail");
   assert.equal(entry.npm, "@ai-sdk/openai-compatible");
   assert.deepEqual(entry.models, {}, "models stub is empty object");
@@ -392,7 +452,7 @@ test("config: fetchers throw → warn + emit stub entry with models: {}", async
 
 test("config: combos fetcher throws → emit models-only catalog (no combos in models block)", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE, MODEL_GEMINI]);
   const combosFetcher = throwingCombosFetcher();
@@ -405,12 +465,16 @@ test("config: combos fetcher throws → emit models-only catalog (no combos in m
   const input = makeInput();
   await hook(input);
 
-  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider
-    .omniroute;
+  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
   assert.ok(entry);
   const ids = Object.keys(entry.models).sort();
-  assert.deepEqual(ids, ["claude-sonnet-4-6", "gemini-3-flash"]);
-  assert.equal(entry.models["combo-claude-tier"], undefined, "no combo entry");
+  assert.deepEqual(ids, [
+    "opencode-omniroute/claude-sonnet-4-6",
+    "opencode-omniroute/gemini-3-flash",
+  ]);
+  assert.equal(entry.models["opencode-omniroute/claude-tier"], undefined, "no combo entry");
   assert.ok(
     logger.entries.some((e) => String(e[0]).includes("/api/combos fetch failed")),
     "combos-fetch breadcrumb emitted"
@@ -423,7 +487,7 @@ test("config: combos fetcher throws → emit models-only catalog (no combos in m
 
 test("config: baseURL from auth.json takes precedence when opts.baseURL absent", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test", baseURL: "https://creds.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-test", baseURL: "https://creds.example/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE]);
   const combosFetcher = stubCombosFetcher([]);
@@ -437,14 +501,15 @@ test("config: baseURL from auth.json takes precedence when opts.baseURL absent",
   await hook(input);
 
   assert.equal(fetcher.callsBy()[0][0], "https://creds.example/v1");
-  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider
-    .omniroute;
+  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
   assert.equal(entry.options.baseURL, "https://creds.example/v1");
 });
 
 test("config: opts.baseURL wins over auth.json's stored baseURL", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test", baseURL: "https://creds.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-test", baseURL: "https://creds.example/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE]);
   const combosFetcher = stubCombosFetcher([]);
@@ -458,14 +523,15 @@ test("config: opts.baseURL wins over auth.json's stored baseURL", async () => {
   await hook(input);
 
   assert.equal(fetcher.callsBy()[0][0], "https://opts.example/v1");
-  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider
-    .omniroute;
+  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
   assert.equal(entry.options.baseURL, "https://opts.example/v1");
 });
 
 test("config: no baseURL resolvable (no opts, no auth.json baseURL) → no-op", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test" }, // NO baseURL on the credential
+    "opencode-omniroute": { type: "api", key: "sk-test" }, // NO baseURL on the credential
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE]);
   const combosFetcher = stubCombosFetcher([]);
@@ -493,12 +559,12 @@ test("config: no baseURL resolvable (no opts, no auth.json baseURL) → no-op",
 
 test("config: multi-instance — two plugins with different providerIds publish to their own keys without collision", async () => {
   const readAuthJson = stubReadAuthJson({
-    "omniroute-prod": {
+    "opencode-omniroute-prod": {
       type: "api",
       key: "sk-prod",
       baseURL: "https://prod.example/v1",
     },
-    "omniroute-preprod": {
+    "opencode-omniroute-preprod": {
       type: "api",
       key: "sk-preprod",
       baseURL: "https://preprod.example/v1",
@@ -522,15 +588,18 @@ test("config: multi-instance — two plugins with different providerIds publish
   await hookB(input);
 
   const provider = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider;
-  assert.ok(provider["omniroute-prod"], "prod block present");
-  assert.ok(provider["omniroute-preprod"], "preprod block present");
-  assert.equal(provider["omniroute-prod"].options.apiKey, "sk-prod");
-  assert.equal(provider["omniroute-preprod"].options.apiKey, "sk-preprod");
-  assert.equal(provider["omniroute-prod"].options.baseURL, "https://prod.example/v1");
-  assert.equal(provider["omniroute-preprod"].options.baseURL, "https://preprod.example/v1");
+  assert.ok(provider["opencode-omniroute-prod"], "prod block present");
+  assert.ok(provider["opencode-omniroute-preprod"], "preprod block present");
+  assert.equal(provider["opencode-omniroute-prod"].options.apiKey, "sk-prod");
+  assert.equal(provider["opencode-omniroute-preprod"].options.apiKey, "sk-preprod");
+  assert.equal(provider["opencode-omniroute-prod"].options.baseURL, "https://prod.example/v1");
+  assert.equal(
+    provider["opencode-omniroute-preprod"].options.baseURL,
+    "https://preprod.example/v1"
+  );
   assert.notEqual(
-    provider["omniroute-prod"],
-    provider["omniroute-preprod"],
+    provider["opencode-omniroute-prod"],
+    provider["opencode-omniroute-preprod"],
     "blocks are distinct references"
   );
 });
@@ -542,7 +611,7 @@ test("config: multi-instance — two plugins with different providerIds publish
 
 test("config + provider share cache: second call uses cached fetch result (single fetch per TTL)", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-shared", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-shared", baseURL: "https://or.example/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE]);
   const combosFetcher = stubCombosFetcher([COMBO_CLAUDE_TIER]);
@@ -574,7 +643,7 @@ test("config + provider share cache: second call uses cached fetch result (singl
 
 test("provider → config order also dedupes (cache populated by provider, consumed by config)", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-reverse", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-reverse", baseURL: "https://or.example/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE]);
   const combosFetcher = stubCombosFetcher([]);
@@ -638,6 +707,7 @@ test("buildStaticProviderEntry: stripped per-model shape matches sibling @omniro
     "cost",
     "limit",
     "modalities",
+    "providerID",
   ]);
   for (const [id, entry] of Object.entries(block.models)) {
     for (const key of Object.keys(entry)) {
@@ -653,7 +723,7 @@ test("buildStaticProviderEntry: stripped per-model shape matches sibling @omniro
   }
 
   // Sanity: claude entry has all expected stripped fields.
-  const claude = block.models["claude-sonnet-4-6"];
+  const claude = block.models["opencode-omniroute/claude-sonnet-4-6"];
   assert.equal(typeof claude.name, "string");
   assert.equal(typeof claude.attachment, "boolean");
   assert.equal(typeof claude.reasoning, "boolean");
@@ -678,8 +748,8 @@ test("buildStaticProviderEntry: hidden combos are excluded", () => {
     "https://or.example/v1",
     "sk-test"
   );
-  assert.equal(block.models["combo-claude-tier"], undefined);
-  assert.ok(block.models["claude-sonnet-4-6"]);
+  assert.equal(block.models["opencode-omniroute/claude-tier"], undefined);
+  assert.ok(block.models["opencode-omniroute/claude-sonnet-4-6"]);
 });
 
 // ────────────────────────────────────────────────────────────────────────────
@@ -695,7 +765,7 @@ test("buildStaticProviderEntry: emits modalities.input from raw.input_modalities
     "https://or.example/v1",
     "sk-test"
   );
-  const claude = block.models["claude-sonnet-4-6"];
+  const claude = block.models["opencode-omniroute/claude-sonnet-4-6"];
   assert.deepEqual(claude.modalities?.input, ["text", "image"]);
   assert.deepEqual(claude.modalities?.output, ["text"]);
 });
@@ -709,7 +779,7 @@ test("buildStaticProviderEntry: never emits limit.input (OC SDK rejects it)", ()
     "https://or.example/v1",
     "sk-test"
   );
-  const claude = block.models["claude-sonnet-4-6"];
+  const claude = block.models["opencode-omniroute/claude-sonnet-4-6"];
   assert.equal((claude.limit as Record<string, unknown>).input, undefined);
   assert.equal(typeof claude.limit?.context, "number");
   assert.equal(typeof claude.limit?.output, "number");
@@ -737,7 +807,7 @@ test("buildStaticProviderEntry: emits cost when enrichment carries pricing", ()
     "sk-test",
     enrichment
   );
-  const claude = block.models["claude-sonnet-4-6"];
+  const claude = block.models["opencode-omniroute/claude-sonnet-4-6"];
   assert.equal(claude.cost?.input, 3);
   assert.equal(claude.cost?.output, 15);
   assert.equal(claude.cost?.cache_read, 0.3);
@@ -758,8 +828,8 @@ test("buildStaticProviderEntry: emits release_date when raw carries it; omits wh
     "https://or.example/v1",
     "sk-test"
   );
-  assert.equal(block.models["claude-with-date"].release_date, "2026-02-19");
-  assert.equal(block.models["gemini-3-flash"].release_date, undefined);
+  assert.equal(block.models["opencode-omniroute/claude-with-date"].release_date, "2026-02-19");
+  assert.equal(block.models["opencode-omniroute/gemini-3-flash"].release_date, undefined);
 });
 
 test("buildStaticProviderEntry: combo modalities = intersection of members (LCD)", () => {
@@ -788,7 +858,7 @@ test("buildStaticProviderEntry: combo modalities = intersection of members (LCD)
     "https://or.example/v1",
     "sk-test"
   );
-  const combo = block.models["combo/mixed-tier"];
+  const combo = block.models["opencode-omniroute/mixed-tier"];
   assert.ok(combo, "combo emitted under slug key");
   // claude has text+image, text-only has text → intersection drops image.
   assert.deepEqual(combo.modalities?.input, ["text"]);
@@ -812,7 +882,7 @@ test("OmniRoutePlugin factory exposes config hook alongside auth + provider", as
 
 test("config: auth.json entry of wrong type (oauth) → no-op", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "oauth", refresh: "r", access: "a", expires: 0 },
+    "opencode-omniroute": { type: "oauth", refresh: "r", access: "a", expires: 0 },
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE]);
   const combosFetcher = stubCombosFetcher([]);
@@ -849,7 +919,7 @@ test("config: readAuthJson throws → treat as missing file (silent fallback)",
 
 test("config: initialises input.provider when undefined", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk", baseURL: "https://or.example/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE]);
   const combosFetcher = stubCombosFetcher([]);
@@ -864,7 +934,7 @@ test("config: initialises input.provider when undefined", async () => {
   await hook(input);
   const provider = (input as { provider?: Record<string, unknown> }).provider;
   assert.ok(provider, "provider bag initialised");
-  assert.ok(provider!.omniroute);
+  assert.ok(provider!["opencode-omniroute"]);
 });
 
 // ────────────────────────────────────────────────────────────────────────────
@@ -874,7 +944,7 @@ test("config: initialises input.provider when undefined", async () => {
 
 test("config: enrichment fetched + name overlaid on raw-model entries", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE, MODEL_GEMINI]);
   const combosFetcher = stubCombosFetcher([COMBO_CLAUDE_TIER]);
@@ -893,19 +963,20 @@ test("config: enrichment fetched + name overlaid on raw-model entries", async ()
   const input = makeInput();
   await hook(input);
 
-  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider
-    .omniroute;
+  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
   assert.ok(entry);
-  assert.equal(entry.models["claude-sonnet-4-6"].name, "Claude Sonnet 4.6");
-  assert.equal(entry.models["gemini-3-flash"].name, "Gemini 3 Flash");
+  assert.equal(entry.models["opencode-omniroute/claude-sonnet-4-6"].name, "Claude Sonnet 4.6");
+  assert.equal(entry.models["opencode-omniroute/gemini-3-flash"].name, "Gemini 3 Flash");
   // Combo names still come from /api/combos — enrichment overlay does NOT touch combos.
-  assert.equal(entry.models["combo/claude-tier"].name, "Combo: Claude Tier");
+  assert.equal(entry.models["opencode-omniroute/claude-tier"].name, "Claude Tier");
   assert.equal(enrichmentFetcher.callCount(), 1);
 });
 
 test("config: features.enrichment=false skips enrichment fetch + keeps raw-id names", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE]);
   const combosFetcher = stubCombosFetcher([]);
@@ -923,16 +994,21 @@ test("config: features.enrichment=false skips enrichment fetch + keeps raw-id na
   const input = makeInput();
   await hook(input);
 
-  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider
-    .omniroute;
+  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
   assert.ok(entry);
   assert.equal(enrichmentFetcher.callCount(), 0, "enrichment fetch suppressed by feature flag");
-  assert.equal(entry.models["claude-sonnet-4-6"].name, "claude-sonnet-4-6", "raw id retained");
+  assert.equal(
+    entry.models["opencode-omniroute/claude-sonnet-4-6"].name,
+    "claude-sonnet-4-6",
+    "raw id retained"
+  );
 });
 
 test("config: enrichment fetcher throws → soft-fail (warn + raw-id static catalog)", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE]);
   const combosFetcher = stubCombosFetcher([]);
@@ -946,10 +1022,15 @@ test("config: enrichment fetcher throws → soft-fail (warn + raw-id static cata
   const input = makeInput();
   await hook(input);
 
-  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider
-    .omniroute;
+  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
   assert.ok(entry, "static block still published on enrichment failure");
-  assert.equal(entry.models["claude-sonnet-4-6"].name, "claude-sonnet-4-6", "raw id retained");
+  assert.equal(
+    entry.models["opencode-omniroute/claude-sonnet-4-6"].name,
+    "claude-sonnet-4-6",
+    "raw id retained"
+  );
   assert.equal(enrichmentFetcher.callCount(), 1);
   assert.ok(
     logger.entries.some((e) => String(e[0]).includes("/api/pricing/models fetch failed")),
@@ -990,7 +1071,7 @@ const MODEL_NV_LLAMA: OmniRouteRawModelEntry = {
 
 test("config: usableOnly=false → no filter (existing behavior)", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CC_OPUS, MODEL_NV_LLAMA]);
   const combosFetcher = stubCombosFetcher([]);
@@ -1012,8 +1093,9 @@ test("config: usableOnly=false → no filter (existing behavior)", async () => {
   const input = makeInput();
   await hook(input);
 
-  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider
-    .omniroute;
+  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
   assert.ok(entry.models["cc/claude-opus-4-7"], "claude kept");
   assert.ok(entry.models["nvidia/llama-3-70b"], "nvidia kept (filter off)");
   assert.equal(providersFetcher.callCount(), 0, "providers fetch not called when feature off");
@@ -1021,7 +1103,7 @@ test("config: usableOnly=false → no filter (existing behavior)", async () => {
 
 test("config: usableOnly=true → drops models for non-usable providers, keeps usable + unknown", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
   });
   const fetcher = stubModelsFetcher([
     MODEL_CC_OPUS,
@@ -1061,8 +1143,9 @@ test("config: usableOnly=true → drops models for non-usable providers, keeps u
   const input = makeInput();
   await hook(input);
 
-  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider
-    .omniroute;
+  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
   assert.ok(entry.models["cc/claude-opus-4-7"], "claude kept (active)");
   assert.equal(entry.models["nvidia/llama-3-70b"], undefined, "nvidia dropped (error status)");
   assert.ok(entry.models["agentrouter/synthetic-1"], "unknown prefix kept (subtract-filter)");
@@ -1071,7 +1154,7 @@ test("config: usableOnly=true → drops models for non-usable providers, keeps u
 
 test("config: usableOnly=true + providers fetch fails → soft-fail keeps everything", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CC_OPUS, MODEL_NV_LLAMA]);
   const combosFetcher = stubCombosFetcher([]);
@@ -1092,8 +1175,9 @@ test("config: usableOnly=true + providers fetch fails → soft-fail keeps everyt
   const input = makeInput();
   await hook(input);
 
-  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider
-    .omniroute;
+  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
   assert.ok(entry.models["cc/claude-opus-4-7"]);
   assert.ok(entry.models["nvidia/llama-3-70b"], "soft-fail keeps both");
   assert.ok(
@@ -1104,7 +1188,7 @@ test("config: usableOnly=true + providers fetch fails → soft-fail keeps everyt
 
 test("config: diskCache hydrates stale snapshot when /v1/models throws", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
   });
   const fetcher = throwingModelsFetcher();
   const combosFetcher = stubCombosFetcher([]);
@@ -1141,11 +1225,15 @@ test("config: diskCache hydrates stale snapshot when /v1/models throws", async (
   const input = makeInput();
   await hook(input);
 
-  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider
-    .omniroute;
-  assert.ok(entry.models["claude-sonnet-4-6"], "stale snapshot hydrated into static block");
+  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
+  assert.ok(
+    entry.models["opencode-omniroute/claude-sonnet-4-6"],
+    "stale snapshot hydrated into static block"
+  );
   assert.equal(
-    entry.models["claude-sonnet-4-6"].name,
+    entry.models["opencode-omniroute/claude-sonnet-4-6"].name,
     "Claude Sonnet 4.6 (cached)",
     "stale enrichment also reused"
   );
@@ -1158,7 +1246,7 @@ test("config: diskCache hydrates stale snapshot when /v1/models throws", async (
 
 test("config: cached rawEnrichment from earlier provider hook is reused (no refetch)", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-shared", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-shared", baseURL: "https://or.example/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE]);
   const combosFetcher = stubCombosFetcher([]);
@@ -1190,9 +1278,10 @@ test("config: cached rawEnrichment from earlier provider hook is reused (no refe
   await configHook(input);
   assert.equal(enrichmentFetcher.callCount(), 1, "config reused cached enrichment");
 
-  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider
-    .omniroute;
-  assert.equal(entry.models["claude-sonnet-4-6"].name, "Claude Sonnet 4.6");
+  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
+  assert.equal(entry.models["opencode-omniroute/claude-sonnet-4-6"].name, "Claude Sonnet 4.6");
 });
 
 // ─────────────────────────────────────────────────────────────────────
@@ -1203,7 +1292,7 @@ test("config: cached rawEnrichment from earlier provider hook is reused (no refe
 
 test("config: providerTag (default-on) prepends '<provider> - ' to enriched raw-model names", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE, MODEL_GEMINI]);
   const combosFetcher = stubCombosFetcher([COMBO_CLAUDE_TIER]);
@@ -1222,9 +1311,9 @@ test("config: providerTag (default-on) prepends '<provider> - ' to enriched raw-
         "gemini-3-flash",
         {
           name: "Gemini 3 Flash",
-          providerAlias: "gemini-cli",
-          providerCanonical: "gemini-cli",
-          providerDisplayName: "Gemini-cli",
+          providerAlias: "gemini",
+          providerCanonical: "gemini",
+          providerDisplayName: "Gemini",
         },
       ],
     ])
@@ -1238,18 +1327,22 @@ test("config: providerTag (default-on) prepends '<provider> - ' to enriched raw-
   const input = makeInput();
   await hook(input);
 
-  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider
-    .omniroute;
+  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
   assert.ok(entry);
-  assert.equal(entry.models["claude-sonnet-4-6"].name, "Claude - Claude Sonnet 4.6");
-  assert.equal(entry.models["gemini-3-flash"].name, "Gemini-cli - Gemini 3 Flash");
+  assert.equal(
+    entry.models["opencode-omniroute/claude-sonnet-4-6"].name,
+    "Claude - Claude Sonnet 4.6"
+  );
+  assert.equal(entry.models["opencode-omniroute/gemini-3-flash"].name, "Gemini - Gemini 3 Flash");
   // Combos stay untouched — `Combo: ` prefix already conveys multi-upstream.
-  assert.equal(entry.models["combo/claude-tier"].name, "Combo: Claude Tier");
+  assert.equal(entry.models["opencode-omniroute/claude-tier"].name, "Claude Tier");
 });
 
 test("config: providerTag=false suppresses the suffix", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE]);
   const combosFetcher = stubCombosFetcher([]);
@@ -1267,10 +1360,11 @@ test("config: providerTag=false suppresses the suffix", async () => {
   const input = makeInput();
   await hook(input);
 
-  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider
-    .omniroute;
+  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
   assert.equal(
-    entry.models["claude-sonnet-4-6"].name,
+    entry.models["opencode-omniroute/claude-sonnet-4-6"].name,
     "Claude Sonnet 4.6",
     "enriched name kept, provider tag suppressed"
   );
@@ -1278,7 +1372,7 @@ test("config: providerTag=false suppresses the suffix", async () => {
 
 test("config: providerTag falls back to UPPER(alias) when providerDisplayName missing", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE]);
   const combosFetcher = stubCombosFetcher([]);
@@ -1299,14 +1393,15 @@ test("config: providerTag falls back to UPPER(alias) when providerDisplayName mi
   const input = makeInput();
   await hook(input);
 
-  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider
-    .omniroute;
-  assert.equal(entry.models["claude-sonnet-4-6"].name, "CC - Claude Sonnet 4.6");
+  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
+  assert.equal(entry.models["opencode-omniroute/claude-sonnet-4-6"].name, "CC - Claude Sonnet 4.6");
 });
 
 test("config: providerTag skipped entirely when neither providerDisplayName nor providerAlias set", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE]);
   const combosFetcher = stubCombosFetcher([]);
@@ -1325,14 +1420,15 @@ test("config: providerTag skipped entirely when neither providerDisplayName nor
   const input = makeInput();
   await hook(input);
 
-  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider
-    .omniroute;
-  assert.equal(entry.models["claude-sonnet-4-6"].name, "Claude Sonnet 4.6");
+  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
+  assert.equal(entry.models["opencode-omniroute/claude-sonnet-4-6"].name, "Claude Sonnet 4.6");
 });
 
 test("config: providerTag is idempotent — second hook call doesn't double-suffix", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE]);
   const combosFetcher = stubCombosFetcher([]);
@@ -1351,16 +1447,24 @@ test("config: providerTag is idempotent — second hook call doesn't double-suff
 
   const inputA = makeInput();
   await hook(inputA);
-  const entryA = (inputA as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider
-    .omniroute;
-  assert.equal(entryA.models["claude-sonnet-4-6"].name, "Claude - Claude Sonnet 4.6");
+  const entryA = (inputA as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
+  assert.equal(
+    entryA.models["opencode-omniroute/claude-sonnet-4-6"].name,
+    "Claude - Claude Sonnet 4.6"
+  );
 
   // Second invocation (cache hit) — name must still be single-suffixed.
   const inputB = makeInput();
   await hook(inputB);
-  const entryB = (inputB as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider
-    .omniroute;
-  assert.equal(entryB.models["claude-sonnet-4-6"].name, "Claude - Claude Sonnet 4.6");
+  const entryB = (inputB as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
+  assert.equal(
+    entryB.models["opencode-omniroute/claude-sonnet-4-6"].name,
+    "Claude - Claude Sonnet 4.6"
+  );
 });
 
 // ────────────────────────────────────────────────────────────────────────────
@@ -1412,7 +1516,7 @@ test("buildStaticProviderEntry: nested combo-ref context is the bottleneck acros
   );
   // Pre-fix: Parent would advertise 200_000 (only raw-big counted).
   // Post-fix: Parent should advertise 8_000 (TinyCombo bottleneck).
-  const parent = block.models["combo/parent"];
+  const parent = block.models["opencode-omniroute/parent"];
   assert.ok(parent, "Parent combo must be in the static catalog");
   assert.equal(parent.limit?.context, 8_000);
 });

@omniroute/opencode-plugin/tests/features.test.ts

@@ -376,7 +376,7 @@ test("provider hook: enrichment fetcher called when features.enrichment !== fals
   );
   const out = await hook.models!({} as never, { auth: apiAuth("sk") as never });
   assert.equal(called, 1, "enrichment fetcher called once");
-  const m = out["claude-sonnet-4-6"];
+  const m = out["opencode-omniroute/claude-sonnet-4-6"];
   assert.equal(m.name, "Claude Sonnet 4.6", "enrichment name overlay applied");
   assert.equal(m.cost.input, 3, "enrichment pricing applied");
   assert.equal(m.cost.output, 15);
@@ -401,7 +401,11 @@ test("provider hook: enrichment fetcher NOT called when features.enrichment:fals
   );
   const out = await hook.models!({} as never, { auth: apiAuth("sk") as never });
   assert.equal(called, 0, "enrichment fetcher NOT called when gated off");
-  assert.equal(out["claude-sonnet-4-6"].name, "claude-sonnet-4-6", "raw id preserved");
+  assert.equal(
+    out["opencode-omniroute/claude-sonnet-4-6"].name,
+    "claude-sonnet-4-6",
+    "raw id preserved"
+  );
 });
 
 test("provider hook: compression metadata fetcher NOT called by default (opt-in)", async () => {
@@ -459,7 +463,7 @@ test("provider hook: compression metadata fetcher called when opted in", async (
   );
   const out = await hook.models!({} as never, { auth: apiAuth("sk") as never });
   assert.equal(called, 1, "compression metadata fetcher called");
-  const combo = out["combo/claude-primary"];
+  const combo = out["opencode-omniroute/claude-primary"];
   assert.ok(combo, "combo entry present");
   assert.match(
     combo.name,
@@ -473,7 +477,7 @@ test("provider hook: compression metadata fetcher called when opted in", async (
 // ─────────────────────────────────────────────────────────────────────────
 
 const stubAuthJson = (apiKey: string) => async () => ({
-  omniroute: { type: "api" as const, key: apiKey },
+  "opencode-omniroute": { type: "api" as const, key: apiKey },
 });
 
 test("config hook: MCP auto-emit OFF by default (no mcp entry)", async () => {
@@ -488,7 +492,7 @@ test("config hook: MCP auto-emit OFF by default (no mcp entry)", async () => {
   );
   const input: { provider?: Record<string, unknown>; mcp?: Record<string, unknown> } = {};
   await hook(input as never);
-  assert.ok(input.provider?.omniroute, "provider block written");
+  assert.ok(input.provider?.["opencode-omniroute"], "provider block written");
   assert.equal(input.mcp, undefined, "no mcp block written");
 });
 
@@ -508,7 +512,7 @@ test("config hook: features.mcpAutoEmit:true writes mcp entry with provider apiK
   );
   const input: { provider?: Record<string, unknown>; mcp?: Record<string, unknown> } = {};
   await hook(input as never);
-  const entry = input.mcp?.omniroute as
+  const entry = input.mcp?.["opencode-omniroute"] as
     | { type: string; url: string; enabled: boolean; headers: Record<string, string> }
     | undefined;
   assert.ok(entry, "mcp entry written");
@@ -538,7 +542,7 @@ test("config hook: features.mcpToken overrides provider apiKey in mcp Bearer", a
   );
   const input: { provider?: Record<string, unknown>; mcp?: Record<string, unknown> } = {};
   await hook(input as never);
-  const entry = input.mcp?.omniroute as { headers: Record<string, string> };
+  const entry = input.mcp?.["opencode-omniroute"] as { headers: Record<string, string> };
   assert.equal(
     entry.headers.Authorization,
     "Bearer sk-mcp-narrower",
@@ -561,11 +565,11 @@ test("config hook: existing operator mcp.<providerId> wins (no overwrite)", asyn
     }
   );
   const input: { provider?: Record<string, unknown>; mcp?: Record<string, unknown> } = {
-    mcp: { omniroute: { type: "custom-user-entry", url: "https://manual.example/mcp" } },
+    mcp: { "opencode-omniroute": { type: "custom-user-entry", url: "https://manual.example/mcp" } },
   };
   await hook(input as never);
   assert.deepEqual(
-    input.mcp?.omniroute,
+    input.mcp?.["opencode-omniroute"],
     { type: "custom-user-entry", url: "https://manual.example/mcp" },
     "operator override preserved"
   );
@@ -580,7 +584,7 @@ test("config hook: features.mcpAutoEmit:true with /v1 in baseURL → strips corr
     },
     {
       readAuthJson: async () => ({
-        "omniroute-preprod": { type: "api" as const, key: "sk-preprod" },
+        "opencode-omniroute-preprod": { type: "api" as const, key: "sk-preprod" },
       }),
       fetcher: async () => SAMPLE_RAW,
       combosFetcher: async () => [],
@@ -589,7 +593,7 @@ test("config hook: features.mcpAutoEmit:true with /v1 in baseURL → strips corr
   );
   const input: { provider?: Record<string, unknown>; mcp?: Record<string, unknown> } = {};
   await hook(input as never);
-  const entry = input.mcp?.["omniroute-preprod"] as { url: string };
+  const entry = input.mcp?.["opencode-omniroute-preprod"] as { url: string };
   assert.equal(
     entry.url,
     "https://or-preprod.example.com/api/mcp/stream",

@omniroute/opencode-plugin/tests/gemini-sanitize.test.ts

@@ -212,8 +212,8 @@ test("shouldSanitizeForGemini: google-vertex/gemini-1.5-flash → true", () => {
   assert.equal(shouldSanitizeForGemini({ model: "google-vertex/gemini-1.5-flash" }), true);
 });
 
-test("shouldSanitizeForGemini: gemini-cli/gemini-2.5-pro → true (real OmniRoute alias)", () => {
-  assert.equal(shouldSanitizeForGemini({ model: "gemini-cli/gemini-2.5-pro" }), true);
+test("shouldSanitizeForGemini: gemini/gemini-2.5-pro → true", () => {
+  assert.equal(shouldSanitizeForGemini({ model: "gemini/gemini-2.5-pro" }), true);
 });
 
 test("shouldSanitizeForGemini: claude-sonnet-4 → false", () => {

@omniroute/opencode-plugin/tests/multi-instance.test.ts

@@ -38,8 +38,8 @@ test("multi-instance: two plugin invocations bind to their own providerId", asyn
     baseURL: "https://b.example/v1",
   });
 
-  assert.equal(a.auth?.provider, "omniroute-prod");
-  assert.equal(b.auth?.provider, "omniroute-preprod");
+  assert.equal(a.auth?.provider, "opencode-omniroute-prod");
+  assert.equal(b.auth?.provider, "opencode-omniroute-preprod");
 });
 
 test("multi-instance: hook objects + nested arrays are independent references", async () => {
@@ -70,8 +70,8 @@ test("multi-instance: identical opts twice still yield independent objects", asy
   assert.notEqual(first.auth, second.auth);
   assert.notEqual(first.auth?.methods, second.auth?.methods);
   // Same provider id is fine — what matters is no shared mutable state.
-  assert.equal(first.auth?.provider, "twin");
-  assert.equal(second.auth?.provider, "twin");
+  assert.equal(first.auth?.provider, "opencode-twin");
+  assert.equal(second.auth?.provider, "opencode-twin");
 });
 
 test("multi-instance: mutating instance A's auth.methods does not affect instance B", async () => {
@@ -132,5 +132,5 @@ test("multi-instance: invalid opts on one instance does not poison the other", a
     providerId: "recovered",
     baseURL: "https://ok.example/v1",
   });
-  assert.equal(ok.auth?.provider, "recovered");
+  assert.equal(ok.auth?.provider, "opencode-recovered");
 });

@omniroute/opencode-plugin/tests/provider.test.ts

@@ -75,7 +75,7 @@ const apiAuth = (key: string, baseURL?: string): unknown =>
 
 test("createOmniRouteProviderHook: default providerId is 'omniroute'", () => {
   const hook = createOmniRouteProviderHook(undefined, { combosFetcher: async () => [] });
-  assert.equal(hook.id, "omniroute");
+  assert.equal(hook.id, "opencode-omniroute");
 });
 
 test("createOmniRouteProviderHook: custom providerId binds to hook.id (multi-instance)", () => {
@@ -87,8 +87,8 @@ test("createOmniRouteProviderHook: custom providerId binds to hook.id (multi-ins
     { providerId: "omniroute-local" },
     { combosFetcher: async () => [] }
   );
-  assert.equal(a.id, "omniroute-preprod");
-  assert.equal(b.id, "omniroute-local");
+  assert.equal(a.id, "opencode-omniroute-preprod");
+  assert.equal(b.id, "opencode-omniroute-local");
 });
 
 test("models: extracts apiKey from ctx.auth (type=api) and calls fetcher with it", async () => {
@@ -101,7 +101,7 @@ test("models: extracts apiKey from ctx.auth (type=api) and calls fetcher with it
   assert.equal(fetcher.callCount(), 1);
   assert.deepEqual(fetcher.callsBy()[0], ["https://or.example.com/v1", "sk-abc"]);
   assert.equal(Object.keys(out).length, 3);
-  assert.ok(out["claude-primary"]);
+  assert.ok(out["opencode-omniroute/claude-primary"]);
 });
 
 test("models: returns {} when ctx.auth is null/undefined/wrong-type/empty-key", async () => {
@@ -152,11 +152,13 @@ test("models: maps a sample /v1/models entry to ModelV2 (sanity)", async () => {
     { fetcher, combosFetcher: async () => [] }
   );
   const out = await hook.models!({} as never, { auth: apiAuth("sk-abc") as never });
-  const claude = out["claude-primary"];
+  const claude = out["opencode-omniroute/claude-primary"];
   assert.ok(claude, "claude-primary present");
-  assert.equal(claude.id, "claude-primary");
+  // `mapRawModelToModelV2` stamps the provider prefix on the id so OC's
+  // static-catalog reader resolves `(providerID, modelID)` from the key.
+  assert.equal(claude.id, "opencode-omniroute/claude-primary");
   assert.equal(claude.name, "claude-primary");
-  assert.equal(claude.providerID, "omniroute");
+  assert.equal(claude.providerID, "opencode-omniroute");
   assert.equal(claude.api.id, "openai-compatible");
   assert.equal(claude.api.url, "https://or.example.com/v1");
   assert.equal(claude.api.npm, "@ai-sdk/openai-compatible");

@omniroute/opencode-plugin/tests/scaffold.test.ts

@@ -26,7 +26,7 @@ test("scaffold: default export is v1 plugin shape { id, server: OmniRoutePlugin
 
 test("resolveOmniRoutePluginOptions: defaults", () => {
   const r = resolveOmniRoutePluginOptions();
-  assert.equal(r.providerId, "omniroute");
+  assert.equal(r.providerId, "opencode-omniroute");
   assert.equal(r.displayName, "OmniRoute");
   assert.equal(r.modelCacheTtl, 300_000);
   assert.equal(r.baseURL, undefined);
@@ -34,8 +34,8 @@ test("resolveOmniRoutePluginOptions: defaults", () => {
 
 test("resolveOmniRoutePluginOptions: custom providerId derives displayName", () => {
   const r = resolveOmniRoutePluginOptions({ providerId: "omniroute-preprod" });
-  assert.equal(r.providerId, "omniroute-preprod");
-  assert.equal(r.displayName, "OmniRoute (omniroute-preprod)");
+  assert.equal(r.providerId, "opencode-omniroute-preprod");
+  assert.equal(r.displayName, "OmniRoute (opencode-omniroute-preprod)");
 });
 
 test("resolveOmniRoutePluginOptions: explicit displayName wins", () => {

AGENTS.md

@@ -3,14 +3,14 @@
 ## Project
 
 Unified AI proxy/router — route any LLM through one endpoint. Multi-provider support
-with **227 provider entries** (OpenAI, Anthropic, Gemini, DeepSeek, Groq, xAI, Mistral, Fireworks,
+with **237 provider entries** (OpenAI, Anthropic, Gemini, DeepSeek, Groq, xAI, Mistral, Fireworks,
 Cohere, NVIDIA, Cerebras, Pollinations, Puter, Cloudflare AI, HuggingFace, DeepInfra,
 SambaNova, Meta Llama API, Moonshot AI, AI21 Labs, Databricks, Snowflake, and many more)
-with **MCP Server** (87 tools), **A2A v0.3 Protocol**, and **Electron desktop app**.
+with **MCP Server** (94 tools), **A2A v0.3 Protocol**, and **Electron desktop app**.
 
-> **Live counts (v3.8.24)**: providers 227 · MCP tools 87 · MCP scopes 30 · A2A skills 6 ·
-> open-sse services 115 · routing strategies 15 · auto-combo scoring factors 9 ·
-> DB modules 83 · DB migrations 97 · base tables 17 · search providers 11 ·
+> **Live counts (v3.8.40)**: providers 237 · MCP tools 94 · MCP scopes 30 · A2A skills 6 ·
+> open-sse services 298 · routing strategies 17 · auto-combo scoring factors 12 ·
+> DB modules 94 · DB migrations 106 · base tables 17 · search providers 11 ·
 > i18n locales 42. **Refresh with `npm run check:docs-all`.**
 
 ## Doc Accuracy Discipline (read before writing any doc)
@@ -267,7 +267,7 @@ Zod schemas, and unit tests aligned when editing.
 
 ### Provider Categories
 
-- **Free** (4): Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+- **Free** (3): Qoder AI, Qwen Code, Kiro AI
 - **OAuth** (14): Claude Code, Antigravity, Codex, GitHub Copilot, Cursor, Kimi Coding, Kilo Code, Cline, Qwen (⚠️ free tier discontinued 2026-04-15), Kiro, Qoder, Gemini, Windsurf (v3.8), GitLab Duo (v3.8)
 - **API Key** (120+): OpenAI, Anthropic, Gemini, DeepSeek, Groq, xAI, Mistral, Perplexity,
   Together, Fireworks, Cerebras, Cohere, NVIDIA, Nebius, SiliconFlow, Hyperbolic,
@@ -291,7 +291,7 @@ Providers are registered in `src/shared/constants/providers.ts` with Zod validat
 ### Executors (`open-sse/executors/`)
 
 Provider-specific request executors: `base.ts`, `default.ts`, `cursor.ts`, `codex.ts`,
-`antigravity.ts`, `github.ts`, `gemini-cli.ts`, `kiro.ts`, `qoder.ts`, `vertex.ts`,
+`antigravity.ts`, `github.ts`, `kiro.ts`, `qoder.ts`, `vertex.ts`,
 `cloudflare-ai.ts`, `opencode.ts`, `pollinations.ts`, `puter.ts`.
 
 #### Executor Internals
@@ -391,7 +391,7 @@ Policy engine modules: `policyEngine.ts`, `comboResolver.ts`, `costRules.ts`,
 
 ### MCP Server (`open-sse/mcp-server/`)
 
-**87 tools** total (`TOTAL_MCP_TOOL_COUNT`, `open-sse/mcp-server/server.ts`): a 33-entry base registry (`MCP_TOOLS` in `schemas/tools.ts`, bundling the core / cache / compression / 1proxy / advanced tools) **plus** standalone module sets — memory (3), skill (4), agentSkill (3), gamification (8), plugin (8), notion (6), obsidian (22). 3 transports (stdio / SSE / Streamable HTTP). Scoped auth (30 scopes — see `OMNIROUTE_MCP_SCOPES`), Zod schemas. See [`docs/frameworks/MCP-SERVER.md`](docs/frameworks/MCP-SERVER.md).
+**94 tools** total (`TOTAL_MCP_TOOL_COUNT`, `open-sse/mcp-server/server.ts`): a 34-entry base registry (`MCP_TOOLS` in `schemas/tools.ts`, bundling the core / cache / compression / 1proxy / advanced tools) **plus** standalone module sets — memory (3), skill (4), agentSkill (3), pool (6), gamification (8), plugin (8), notion (6), obsidian (22). 3 transports (stdio / SSE / Streamable HTTP). Scoped auth (30 scopes — see `OMNIROUTE_MCP_SCOPES`), Zod schemas. See [`docs/frameworks/MCP-SERVER.md`](docs/frameworks/MCP-SERVER.md).
 
 **Core tools** (20): get_health, list_combos, get_combo_metrics, switch_combo, check_quota,
 route_request, cost_report, list_models_catalog, web_search, simulate_route, set_budget_guard,
@@ -489,7 +489,7 @@ Request middleware including `promptInjectionGuard.ts`.
 
 ### Guardrails (`src/lib/guardrails/`)
 
-Hot-reloadable guardrails framework (3 built-in: pii-masker, prompt-injection, vision-bridge). Fail-open; per-request opt-out via header. See [`docs/security/GUARDRAILS.md`](docs/security/GUARDRAILS.md).
+Hot-reloadable guardrails framework (3 built-in: pii-masker, prompt-injection, vision-bridge). Fail-open. The `pii-masker` guardrail is registered and runs on every request, but its data-mutating logic is **opt-in** and OFF by default — it only redacts when `PII_REDACTION_ENABLED` (request) / `PII_RESPONSE_SANITIZATION` (response + streaming) are enabled (both `defaultValue: "false"`); with them off, payloads pass through untouched. A request can additionally opt OUT of any guardrail via header (`x-omniroute-disabled-guardrails`). Never make PII default-on (Hard Rule #20). See [`docs/security/GUARDRAILS.md`](docs/security/GUARDRAILS.md).
 
 ### Cloud Agents (`src/lib/cloudAgent/`)
 
@@ -534,32 +534,33 @@ Cloudflare Quick/Named, ngrok, Tailscale Funnel. See [`docs/ops/TUNNELS_GUIDE.md
 
 For any non-trivial change, read the matching deep-dive first:
 
-| Area                                       | Doc                                                                                                                                 |
-| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
-| Repo navigation                            | [`docs/architecture/REPOSITORY_MAP.md`](docs/architecture/REPOSITORY_MAP.md)                                                        |
-| Architecture                               | [`docs/architecture/ARCHITECTURE.md`](docs/architecture/ARCHITECTURE.md)                                                            |
-| Engineering reference                      | [`docs/architecture/CODEBASE_DOCUMENTATION.md`](docs/architecture/CODEBASE_DOCUMENTATION.md)                                        |
-| Auto-Combo (12-factor, 15 strategies)      | [`docs/routing/AUTO-COMBO.md`](docs/routing/AUTO-COMBO.md)                                                                          |
-| Resilience (3 layers)                      | [`docs/architecture/RESILIENCE_GUIDE.md`](docs/architecture/RESILIENCE_GUIDE.md)                                                    |
-| Skills                                     | [`docs/frameworks/SKILLS.md`](docs/frameworks/SKILLS.md)                                                                            |
-| Memory                                     | [`docs/frameworks/MEMORY.md`](docs/frameworks/MEMORY.md)                                                                            |
-| Cloud agents                               | [`docs/frameworks/CLOUD_AGENT.md`](docs/frameworks/CLOUD_AGENT.md)                                                                  |
-| Guardrails                                 | [`docs/security/GUARDRAILS.md`](docs/security/GUARDRAILS.md)                                                                        |
-| Evals                                      | [`docs/frameworks/EVALS.md`](docs/frameworks/EVALS.md)                                                                              |
-| Compliance                                 | [`docs/security/COMPLIANCE.md`](docs/security/COMPLIANCE.md)                                                                        |
-| Webhooks                                   | [`docs/frameworks/WEBHOOKS.md`](docs/frameworks/WEBHOOKS.md)                                                                        |
-| Authz                                      | [`docs/architecture/AUTHZ_GUIDE.md`](docs/architecture/AUTHZ_GUIDE.md)                                                              |
-| Stealth                                    | [`docs/security/STEALTH_GUIDE.md`](docs/security/STEALTH_GUIDE.md)                                                                  |
-| Reasoning replay                           | [`docs/routing/REASONING_REPLAY.md`](docs/routing/REASONING_REPLAY.md)                                                              |
-| Agent protocols (A2A / ACP / Cloud)        | [`docs/frameworks/AGENT_PROTOCOLS_GUIDE.md`](docs/frameworks/AGENT_PROTOCOLS_GUIDE.md)                                              |
-| MCP server                                 | [`docs/frameworks/MCP-SERVER.md`](docs/frameworks/MCP-SERVER.md)                                                                    |
-| A2A server                                 | [`docs/frameworks/A2A-SERVER.md`](docs/frameworks/A2A-SERVER.md)                                                                    |
-| API reference                              | [`docs/reference/API_REFERENCE.md`](docs/reference/API_REFERENCE.md) + [`docs/reference/openapi.yaml`](docs/reference/openapi.yaml) |
-| Provider catalog (auto-generated)          | [`docs/reference/PROVIDER_REFERENCE.md`](docs/reference/PROVIDER_REFERENCE.md)                                                      |
-| Tunnels                                    | [`docs/ops/TUNNELS_GUIDE.md`](docs/ops/TUNNELS_GUIDE.md)                                                                            |
-| Electron desktop                           | [`docs/guides/ELECTRON_GUIDE.md`](docs/guides/ELECTRON_GUIDE.md)                                                                    |
-| Release flow                               | [`docs/ops/RELEASE_CHECKLIST.md`](docs/ops/RELEASE_CHECKLIST.md)                                                                    |
-| Quality gates (35 gates, allowlist policy) | [`docs/architecture/QUALITY_GATES.md`](docs/architecture/QUALITY_GATES.md)                                                          |
+| Area                                       | Doc                                                                                                             |
+| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
+| Repo navigation                            | [`docs/architecture/REPOSITORY_MAP.md`](docs/architecture/REPOSITORY_MAP.md)                                    |
+| Architecture                               | [`docs/architecture/ARCHITECTURE.md`](docs/architecture/ARCHITECTURE.md)                                        |
+| Engineering reference                      | [`docs/architecture/CODEBASE_DOCUMENTATION.md`](docs/architecture/CODEBASE_DOCUMENTATION.md)                    |
+| Auto-Combo (12-factor, 17 strategies)      | [`docs/routing/AUTO-COMBO.md`](docs/routing/AUTO-COMBO.md)                                                      |
+| Resilience (3 layers)                      | [`docs/architecture/RESILIENCE_GUIDE.md`](docs/architecture/RESILIENCE_GUIDE.md)                                |
+| Skills                                     | [`docs/frameworks/SKILLS.md`](docs/frameworks/SKILLS.md)                                                        |
+| Memory                                     | [`docs/frameworks/MEMORY.md`](docs/frameworks/MEMORY.md)                                                        |
+| Cloud agents                               | [`docs/frameworks/CLOUD_AGENT.md`](docs/frameworks/CLOUD_AGENT.md)                                              |
+| Guardrails                                 | [`docs/security/GUARDRAILS.md`](docs/security/GUARDRAILS.md)                                                    |
+| Evals                                      | [`docs/frameworks/EVALS.md`](docs/frameworks/EVALS.md)                                                          |
+| Compliance                                 | [`docs/security/COMPLIANCE.md`](docs/security/COMPLIANCE.md)                                                    |
+| Webhooks                                   | [`docs/frameworks/WEBHOOKS.md`](docs/frameworks/WEBHOOKS.md)                                                    |
+| Authz                                      | [`docs/architecture/AUTHZ_GUIDE.md`](docs/architecture/AUTHZ_GUIDE.md)                                          |
+| Stealth                                    | [`docs/security/STEALTH_GUIDE.md`](docs/security/STEALTH_GUIDE.md)                                              |
+| Reasoning replay                           | [`docs/routing/REASONING_REPLAY.md`](docs/routing/REASONING_REPLAY.md)                                          |
+| Agent protocols (A2A / ACP / Cloud)        | [`docs/frameworks/AGENT_PROTOCOLS_GUIDE.md`](docs/frameworks/AGENT_PROTOCOLS_GUIDE.md)                          |
+| MCP server                                 | [`docs/frameworks/MCP-SERVER.md`](docs/frameworks/MCP-SERVER.md)                                                |
+| A2A server                                 | [`docs/frameworks/A2A-SERVER.md`](docs/frameworks/A2A-SERVER.md)                                                |
+| API reference                              | [`docs/reference/API_REFERENCE.md`](docs/reference/API_REFERENCE.md) + [`docs/openapi.yaml`](docs/openapi.yaml) |
+| Provider catalog (auto-generated)          | [`docs/reference/PROVIDER_REFERENCE.md`](docs/reference/PROVIDER_REFERENCE.md)                                  |
+| Tunnels                                    | [`docs/ops/TUNNELS_GUIDE.md`](docs/ops/TUNNELS_GUIDE.md)                                                        |
+| Electron desktop                           | [`docs/guides/ELECTRON_GUIDE.md`](docs/guides/ELECTRON_GUIDE.md)                                                |
+| Release flow                               | [`docs/ops/RELEASE_CHECKLIST.md`](docs/ops/RELEASE_CHECKLIST.md)                                                |
+| Quality gates (35 gates, allowlist policy) | [`docs/architecture/QUALITY_GATES.md`](docs/architecture/QUALITY_GATES.md)                                      |
+| Cluster opt-in profiles (memory, bifrost)  | [`docs/architecture/cluster-decisions.md`](docs/architecture/cluster-decisions.md)                              |
 
 ---
 

CHANGELOG.md

@@ -4,6 +4,846 @@
 
 ---
 
+## [3.8.40] — TBD
+
+_In development — bullets added per PR; finalized at release._
+
+### ✨ New Features
+
+- **feat(compression): relevance extractive engine** — a new opt-in compression engine that scores each sentence by term-overlap (Jaccard) with the user's last query minus a length/boilerplate penalty, greedily keeps the most relevant within a budget, and reconstructs the original order. Pure-string, deterministic, ReDoS-safe (char-code tokenization, no `RegExp` over user input), fail-open, default off. Ideal for trimming long pasted RAG context / tool output to what's relevant. Sentences carrying real signal (digits/URLs/errors/code/paths) are never dropped; `overlapThreshold`/`budgetPercent`/`boilerplateWeight` are configurable. Tier-2 item of the compression feature-extraction roadmap (#7). ([#5289](https://github.com/diegosouzapw/OmniRoute/pull/5289))
+- **feat(compression): hard-budget mode — compress to ≤ N tokens** — a deterministic post-pass (`targetTokens` / `targetRatio`, default unset → no-op) that trims a body to a token budget. It ranks sentences/lines by average `scoreToken` ascending and drops the lowest-saliency ones until the body fits (measured by the exact cl100k `countTextTokens`), preserving original order. Lines carrying real signal (digits, URLs, `Error:`-family, code fences, stack `at`-frames, multi-segment paths, `key=value`) are never dropped; the budget is distributed proportionally across messages so the total stays ≤ target; an unreachable target (all-preserved) surfaces a `validationWarnings` note instead of failing silently. Does NOT touch the `estimateCompressionTokens` budget-gate estimator. Tier-3 item of the compression feature-extraction roadmap (#17). ([#5288](https://github.com/diegosouzapw/OmniRoute/pull/5288), follow-up [#5291](https://github.com/diegosouzapw/OmniRoute/pull/5291))
+- **feat(compression): result memoization for deterministic engines (opt-in)** — caches `(input, config) → result` for provably pure, stateless modes (`lite`/`standard`/`rtk` and stacked pipelines of `{lite,caveman,rtk}`) to skip recompute on the hot path. Opt-in via `memoizeCompressionResults` (default off → zero behavior change). Conservative opt-in whitelist (stateful `ccr`/`session-dedup` — which write the cross-request CCR store — and model-backed `ultra`/`aggressive`/`llmlingua` are never cached), principal-scoped (skipped without a principal, so no cross-principal body leak), and clone-on-store + clone-on-read. Tier-3 item of the compression feature-extraction roadmap (#21). ([#5286](https://github.com/diegosouzapw/OmniRoute/pull/5286))
+- **feat(compression): inline transparency annotation** — surfaces `tokens=847→312; rules: filler×8, dedup×2` derived from existing compression stats. The `X-OmniRoute-Compression` response header is extended **append-only** (the `mode; source=X` prefix stays byte-identical, so existing header parsers don't break) and the compression studio cockpit shows a matching badge. Zero new computation — it aggregates the `rulesApplied`/`techniquesUsed` already on the stats. Tier-3 item of the compression feature-extraction roadmap (#18). ([#5284](https://github.com/diegosouzapw/OmniRoute/pull/5284))
+- **feat(compression): saliency heatmap in the compression studio** — the preview studio can now color each token by saliency: `ultra` per-token `scoreToken` (0–1, green→red gradient) or universal kept/removed from the existing diff. A dry-run visualization behind a toggle (no cost on a normal preview; backward-compatible when off). Completes the visualization half of roadmap item #13 (the A/B comparison shipped in [#5080](https://github.com/diegosouzapw/OmniRoute/pull/5080)). ([#5285](https://github.com/diegosouzapw/OmniRoute/pull/5285))
+- **feat(compression): composite-command splitter for RTK detection** — `cd /x && git status` now detects as `git-status` (previously the whole string was treated as one command and matched no filter). A quote-aware top-level tokenizer splits on `&&`/`||`/`;` (never inside quotes or `$(…)`/backtick subshells) and feeds the **last** segment to RTK command detection, so every RTK filter/renderer fires on commands wrapped in `cd … &&`/`||`/`;` chains. O(n), no RegExp over the command (ReDoS-safe). Tier-3 item of the compression feature-extraction roadmap (#16). ([#5283](https://github.com/diegosouzapw/OmniRoute/pull/5283))
+- **feat(mcp): `omniroute_tool_search` tool + one-line TS signatures** — new MCP tool that does lexical keyword search over every MCP tool's name/description and returns the top matches as compact one-line TypeScript signatures (~half the JSON-schema token cost), so agents discover tools on demand instead of carrying all ~88 schemas every turn. Search is ReDoS-safe (substring scoring, never `new RegExp` on the query) and deterministic; `tools/list` stays complete (no hidden tools). Adds the `read:tools` scope. Tier-1 item of the compression feature-extraction roadmap. ([#5269](https://github.com/diegosouzapw/OmniRoute/pull/5269))
+- **feat(compression): RTK semantic command-output renderers (opt-in)** — adds a second, opt-in compaction layer to the RTK engine that rewrites structured command output into a far more compact semantic form: `git diff` → file headers + `@@` hunks + changed lines only; an all-green `pytest`/`jest`/`vitest`/`eslint` run → its one-line summary; `terraform`/`tofu plan` → `Plan: +N ~M -K` plus the resource list; `kubectl`/`aws` JSON arrays → a minimal table. Each renderer is conservative (no-op when the shape doesn't match) and the integration is fail-open; the test-green renderer never collapses output that carries any failure signal. Gated by `RtkConfig.enableRenderers` (default off → zero behavioral change). Eighth item of the compression feature-extraction roadmap. ([#5268](https://github.com/diegosouzapw/OmniRoute/pull/5268))
+- **feat(compression): QuantumLock cache-prefix stabilization (opt-in, default off)** — recovers upstream prompt-cache hits that a volatile fragment in the system prompt would otherwise bust. When a caller injects a session UUID, unix timestamp, request-id, JWT, API-key shape, or long hex digest into the `role:system` message every turn, the longest common prefix across turns ends at that changing byte → the whole system prompt after it is re-billed and re-processed each turn. QuantumLock replaces each non-semantic volatile fragment with a **positional, value-independent** placeholder `⟦Q{i}⟧` and appends the real values in a delimited `⟦QUANTUMLOCK⟧` tail. The rewrite is **sent to the model** (lossless — not restored), so the system-prompt body becomes **byte-identical across turns** and the provider caches the long stable prefix while only the small tail differs. Opt-in, default off, applied only for caching providers (`isCachingProvider && config.quantumLock.enabled`); bounded ReDoS-safe patterns; idempotent; **no date/time patterns** (semantically meaningful — explicit non-goal). Studio gets a toggle + a "🔒 N volatile fragment(s) stabilized" dry-run badge. Seventh item of the compression feature-extraction roadmap (bench: [#5080](https://github.com/diegosouzapw/OmniRoute/pull/5080), gate: [#5127](https://github.com/diegosouzapw/OmniRoute/pull/5127), fuzzy: [#5143](https://github.com/diegosouzapw/OmniRoute/pull/5143), ionizer: [#5148](https://github.com/diegosouzapw/OmniRoute/pull/5148), TOON: [#5163](https://github.com/diegosouzapw/OmniRoute/pull/5163), CCR ranged: [#5187](https://github.com/diegosouzapw/OmniRoute/pull/5187), risk-gate: [#5243](https://github.com/diegosouzapw/OmniRoute/pull/5243)). ([#5260](https://github.com/diegosouzapw/OmniRoute/pull/5260))
+- **kilocode:** anonymous (no-auth) access to Kilo Code's free models, mirroring the `opencode`/`mimocode` pattern. With no Kilo account connected, requests now fall back to the gateway's anonymous tier (`Authorization: Bearer anonymous` on `api.kilo.ai/api/openrouter`) so the free models work without signup; a connected OAuth account is still used unchanged for the paid tier ([#5259](https://github.com/diegosouzapw/OmniRoute/pull/5259), #4019 — thanks @Theadd for the reference implementation)
+- **feat(logging): call-log correlation ID (end-to-end)** — every request now gets a unique correlation id, returned in the `X-Correlation-Id` response header, persisted in `call_logs` (migration **109**), filterable via `/api/usage/call-logs`, and surfaced in the dashboard request logger (per-chunk stream timestamps + active-requests-first sort). This is the safe, cohesive core subset of the larger #5275 — landed on its own so the low-risk value isn't blocked by the parts of that PR still under review. ([#5279](https://github.com/diegosouzapw/OmniRoute/pull/5279) — thanks @hartmark)
+- **feat(providers): Microsoft 365 Copilot individual provider** — adds the `copilot-m365-web` provider (the 237th), wiring the M365 BizChat framing/connection helpers into a selectable web-session provider backed by `m365.cloud.microsoft/chat` for individual Microsoft 365 plans. Builds on the M365 pure-framing groundwork from #4696. Regression guard: `tests/unit/copilot-m365-web-executor.test.ts`. ([#5302](https://github.com/diegosouzapw/OmniRoute/pull/5302) — thanks @skyzea1)
+
+### 🔧 Bug Fixes
+
+- **ci(docker):** re-point the Docker Hub / GHCR `:latest` (and `:latest-web`) tags to the just-published release. On a `release: released` event the freshly-created git tag is often not yet visible to `git fetch --tags` when `docker-publish` runs, so the `:latest`-promotion gate built its candidate set purely from `git tag -l` and resolved the highest semver to the **previous** version — leaving `latest` one release behind (3.8.39 published, `latest` still 3.8.38). The decision now lives in `scripts/ci/should-promote-latest.sh`, which folds the current `VERSION` into the candidate set before picking the highest stable semver, making promotion independent of tag-sync timing (a patch published after a higher minor still won't grab `latest`). Regression guard: `tests/unit/build/should-promote-latest-5301.test.ts` ([#5301](https://github.com/diegosouzapw/OmniRoute/issues/5301))
+- **command-code:** treat a non-positive `max_tokens`/`max_completion_tokens` (e.g. Zoo Code's `-1` "let the server choose") as "no limit" — omit the field instead of forcing it to `1`. `clampMaxTokens` previously did `Math.max(1, …)`, so a client `-1` was sent upstream as `max_tokens: 1`, truncating the response to a single token (the observed `completion_tokens: 1`, `content: null`, `reasoning_content: "The"` with `finish_reason: stop`). Now any value `≤ 0` is dropped so Command Code applies the model's native default; positive values are still floored and clamped to the 200k ceiling. Regression guard: `tests/unit/command-code-maxtokens-negative-5166.test.ts` ([#5166](https://github.com/diegosouzapw/OmniRoute/issues/5166) — thanks @Stazyu)
+- **fix(auth): compare-and-swap guard on the OAuth refresh persist** — under multi-agent load, the per-connection refresh mutex makes `[network refresh + DB write]` atomic for **one** connection, but it does not protect against a **third** writer (a sibling request, a concurrent HealthCheck, or a replica) landing a fresher `refresh_token` rotation on the same `connection_id` between the staleness read and the persist. Overwriting that fresher row reverts the sibling's rotation; the next caller then loads the now-consumed token, Auth0/Anthropic flag it as `refresh_token_reused`, and the whole token family gets revoked (the 1352× claude/`aa5dd5cf` invalidation storm). `getAccessToken` now re-reads the row's current `refresh_token` immediately before persisting (inside the mutex) and **skips the write** when it has rotated past the token the caller presented — the caller still receives the freshly-issued access token, only the DB overwrite is skipped. Opt-in via `runWithCasGuard` (no active guard ⇒ byte-identical behavior); skip/persist counters exposed via `getCasGuardStats()`. Regression guard: `tests/unit/token-refresh-cas-guard-4038.test.ts`. ([#4038](https://github.com/diegosouzapw/OmniRoute/issues/4038) — thanks @KooshaPari for the root-cause diagnosis)
+- **mcp:** break the `schemas/tools.ts ↔ schemas/toolSearch.ts` import cycle introduced when the `tool_search` defs (#5269) were extracted into their own module — `toolSearch.ts` imported `McpToolDefinition` from `tools.ts` while `tools.ts` imported `toolSearchTool` from `toolSearch.ts`, failing `check:cycles` on `release/v3.8.40`. The shared `AuditLevel` + `McpToolDefinition` types now live in a leaf `schemas/toolDefinition.ts` that both import; `tools.ts` re-exports them for backward compatibility.
+- **compression (analytics):** record attempted-but-no-op compression runs so Stacked is no longer invisible when it saves nothing. Previously a `compression_analytics` row was written only on a net-positive saving, so a Stacked (RTK→Caveman) pipeline that ran on already-compact context produced no row — indistinguishable from "never dispatched" (`byMode.stacked.count` stayed flat while Ultra climbed). Such runs are now recorded with `skip_reason` and surfaced as a per-mode `skipped` count plus `totalSkipped`/`bySkipReason` in the analytics summary and the Mode Breakdown; the existing net-saving totals/averages are unchanged (skip rows are excluded from them) (#4268 — thanks @abdulkadirozyurt, @androw)
+- **cli (tray):** fix `omniroute server --tray` showing no tray on macOS/Linux with no error printed. The wired Unix tray path loaded `systray2` through an inline loader that called `require("module")` inside an ESM `.mjs` file (`"type":"module"`) → `ReferenceError: require is not defined`, silently swallowed (regressed in v3.8.34); even if it had loaded, `systray2` isn't in `node_modules` (it's lazily installed into `~/.omniroute/runtime`). The loader now delegates to the runtime loader, the icon path (`icon.png`) is corrected, `isTemplateIcon` is `false` (the full-color icon rendered as a white square under macOS template mode), and tray start failures are surfaced to stderr instead of being swallowed (#4605 — thanks @ProgMEM-CC)
+- **agent-bridge (antigravity):** unwrap the cloudcode-pa `.request` envelope when converting Antigravity IDE requests. The real IDE sends `cloudcode-pa.googleapis.com/v1internal:generateContent` with the Gemini request nested under `.request` (`{ project, model, request: { contents, systemInstruction, generationConfig } }`), but the bridge read those fields at the top level — yielding an empty conversation, so prompts hung mid-execution. The legacy `/v1beta/models/<model>:generateContent` top-level shape still works (#4294 — thanks @shabeer)
+- **dashboard:** add a GitHub releases fallback to the "Update Available" lookup. After the v3.8.28 fix added an npm-registry HTTP fallback, the banner could still stay hidden on networks that reach GitHub (where the news feed already loads) but not `registry.npmjs.org`. `resolveLatestVersion()` now tries npm CLI → npm registry → GitHub releases (`/repos/diegosouzapw/OmniRoute/releases/latest`) before giving up, and logs a warning only when all three fail (#4100)
+- **command-code:** omit `max_tokens` when the client omits it so the upstream applies the model's native default, fixing `400 "expected <=200000"` on `/alpha/generate` for high-cap models; an explicit oversized client value is clamped to the 200k endpoint ceiling (#5221 — thanks @adivekar-utexas)
+- **combo:** wire session stickiness into the round-robin dispatch path. Multi-turn conversations from clients that send no session id (Codex CLI, Claude Code, most OpenAI-compatible tools) were rotated to a different connection on every turn by round-robin combos, busting the upstream prompt-cache → cold high-reasoning starts, intermittent `504`s and throughput collapse under concurrency. The weighted/priority paths already honored per-conversation stickiness; the round-robin handler returned before reaching it. Round-robin now starts the rotation at the conversation's sticky connection (failover to the other targets is preserved), and different conversations still spread across connections — only intra-conversation rotation is removed ([#5248](https://github.com/diegosouzapw/OmniRoute/pull/5248), #3825 — thanks @bypanghu, @jpsn123, @xz-dev)
+- **kiro:** replace the synthesized trailing `"Continue"` turn with a neutral filler (`"..."`) — when an OpenAI→Kiro request ends on an assistant/tool turn, the translator synthesizes the protocol-required trailing user turn, and the literal word `"Continue"` could be read by Kiro/CodeWhisperer as a real user instruction and trigger unintended agent action. A trailing tool-result turn is still promoted as-is (it already collapses to a real user turn); only the assistant-text-ending case is affected. Regression guards: `tests/unit/kiro-continue-filler-5231.test.ts`. ([#5231](https://github.com/diegosouzapw/OmniRoute/issues/5231))
+- **combo:** advance to the next combo target on a `400 "requested model is not supported"` instead of hard-failing. The 400 guard in the priority strategy treated `MODEL_CAPACITY` as a block-fallback reason, so a combo that hit a provider lacking a specific model returned a hard `400` even when other targets (different providers) supported it. Such 400s now fall through to the next target. ([#5249](https://github.com/diegosouzapw/OmniRoute/pull/5249) — thanks @Chewji9875)
+- **dashboard:** disabled no-auth providers no longer vanish from the All Providers page. Disabling a no-auth provider (the "No authentication required" toggle, which adds it to `blockedProviders`) silently removed its card because the page _dropped_ blocked no-auth entries from its render list — the only way back was buried under Settings → Security → Blocked Providers. The page now **partitions** no-auth entries: visible providers render as before, blocked ones appear in a "Disabled" sub-group with an **Enable** button that un-blocks them in place. Aggregates, counts and `/v1/models` still consume the visible-only list (blocked providers stay out of routing). Regression guard: `tests/unit/noauth-blocked-partition-5183.test.ts`. ([#5183](https://github.com/diegosouzapw/OmniRoute/issues/5183), follow-up from [#5166](https://github.com/diegosouzapw/OmniRoute/issues/5166) — thanks @WslzGmzs)
+- **dashboard:** add a parent `/dashboard/context` page so RSC prefetches of the compression-context hub no longer 404. The route only had sub-routes (`settings`, `combos`, `ultra`, …) and no parent page, so the App Router returned 404 for the bare segment. The parent now redirects to its canonical sub-route (`/dashboard/context/settings`), honoring a legacy `?tab=` query for deep links. Regression guard: `tests/unit/dashboard/context-parent-redirect-5298.test.ts` ([#5298](https://github.com/diegosouzapw/OmniRoute/issues/5298) — thanks @KooshaPari)
+- **i18n:** add the missing `sidebar.gamificationGroup` message across all 42 locales — the Gamification sidebar group referenced a `titleKey` that existed in no locale, logging `MISSING_MESSAGE: sidebar.gamificationGroup (en)` at runtime (the group still rendered via its `titleFallback`). The key is now present everywhere so the warning is gone and locale coverage is unaffected ([#5298](https://github.com/diegosouzapw/OmniRoute/issues/5298) — thanks @KooshaPari)
+- **api(stream):** `/v1/chat/completions` no longer returns SSE for a non-stream OpenAI-compatible request when `stream` is omitted and the client sends `Accept: application/json, text/event-stream` — the Vercel AI SDK / OpenAI SDK non-stream signature (`doGenerate()`/`generateText()`), which then failed with `Invalid JSON response` (`Unexpected token 'd', "data: {"id"...`). The route-level Accept override (#302) and `resolveStreamFlag` now treat an Accept header that explicitly lists `application/json` as a JSON opt-in even when it also lists `text/event-stream`; only a pure `Accept: text/event-stream` (no `application/json`) still opts an omitted-`stream` request into SSE, and an explicit body `stream` value always wins. The shared decision now lives in `acceptHeaderForcesStream`. Regression guard: `tests/unit/sse-nonstream-accept-5305.test.ts`. ([#5305](https://github.com/diegosouzapw/OmniRoute/issues/5305) — thanks @md-riaz)
+- **providers:** drop the retired GPT‑5.2 / GPT‑4.5 models from the direct **ChatGPT‑web** and **Codex** surfaces (OpenAI removed them there), so OmniRoute stops advertising/routing models that no longer exist. Scoped on purpose to those two providers — third‑party proxies that still expose the ids are untouched. ([#5280](https://github.com/diegosouzapw/OmniRoute/pull/5280) — thanks @backryun)
+- **codex:** drop the deprecated `local_shell` hosted tool type before forwarding to OpenAI's Responses API, resolving the omni-combo `400 "The local_shell tool is no longer supported."` spike. Inbound Responses `local_shell` is still accepted and mapped to a caller-side Chat `shell` function for compatibility. ([#5250](https://github.com/diegosouzapw/OmniRoute/pull/5250), [#5256](https://github.com/diegosouzapw/OmniRoute/pull/5256) — thanks @KooshaPari)
+- **antigravity:** retry excluded accounts via the fallback LRU. The combo same-model retry loop accumulates excluded Antigravity connection ids after account-level failures, but auth selection only treated a single `excludeConnectionId` as a fallback scenario — once exclusions accumulated through `excludedConnectionIds`, selection could fall back to normal sticky/priority behavior instead of LRU-selecting the next eligible account for the same model/family. Any non-empty accumulated exclude set is now treated as fallback mode. Builds on the family-scoped lockout work in #5180 (v3.8.39). ([#5222](https://github.com/diegosouzapw/OmniRoute/pull/5222) — thanks @Ardem2025)
+- **grok-cli:** strip unsupported sampling params (`presencePenalty`, `frequencyPenalty`, `logprobs`, `topLogprobs`) before sending to the Grok Build API, fixing `400 'Model does not support parameter presencePenalty'` when clients (MiMoCode, Cursor, etc.) send OpenAI-style params. ([#5273](https://github.com/diegosouzapw/OmniRoute/pull/5273) — thanks @fulorgnas)
+- **grok-cli:** accept the full `~/.grok/auth.json` object in the dashboard import-token endpoint. The `oauthImportTokenSchema` only accepted a bare string token while the UI sends the whole auth.json object → `400 Bad Request`; the schema now accepts the object and stores the original under `providerSpecificData.rawAuthJson` for diagnostics and token refresh. ([#5258](https://github.com/diegosouzapw/OmniRoute/pull/5258) — thanks @fulorgnas)
+- **qoder:** coalesce concurrent PAT→job-token exchanges per PAT so high-concurrency / multi-agent bursts no longer stampede `openapi.qoder.sh/api/v1/jobToken/exchange` before the first exchange populates the completed-token cache; the shared exchange is also decoupled from any single caller's `AbortSignal` so one aborted waiter can't cancel it for the others. ([#5254](https://github.com/diegosouzapw/OmniRoute/pull/5254), [#5265](https://github.com/diegosouzapw/OmniRoute/pull/5265) — thanks @KooshaPari)
+- **proxy:** scope the fallback reachability cache by normalized target **URL** instead of by hostname, so a failed probe for one endpoint on a shared API host no longer suppresses a later probe for a different endpoint on that same host for the full TTL (host fallback is preserved for malformed URLs). ([#5261](https://github.com/diegosouzapw/OmniRoute/pull/5261) — thanks @KooshaPari)
+- **proxy:** cache failed fast-fail health probes with a short negative TTL instead of the full positive health TTL, so a single transient timeout/load blip no longer marks a working residential SOCKS5 proxy unreachable for the whole window (#5109 regression coverage added). ([#5255](https://github.com/diegosouzapw/OmniRoute/pull/5255) — thanks @KooshaPari)
+- **mcp:** forward HTTP auth to internal tool fetches so MCP tools that call back into the local API surface carry the caller's authorization. ([#5218](https://github.com/diegosouzapw/OmniRoute/pull/5218) — thanks @KooshaPari)
+- **logging:** preserve the **outbound provider request** headers in the detailed call-log Provider Request payload (previously the upstream **response** headers were shown there). chatCore now keeps executor-returned request headers when wrapping streaming and non-streaming responses; response headers stay scoped to the `Response`. ([#5257](https://github.com/diegosouzapw/OmniRoute/pull/5257) — thanks @rdself)
+- **sse:** scope textual `<think>`/`<thinking>` tag extraction so generic OpenAI-compatible paths don't rewrite prompt-format content into `reasoning_content`; an explicit opt-in keeps tag-native families (DeepSeek-R1, QwQ) working while Antigravity/Agy stay excluded by provider/model prefix. ([#5224](https://github.com/diegosouzapw/OmniRoute/pull/5224) — thanks @rdself)
+- **mcp:** break the `schemas/tools.ts ↔ schemas/toolSearch.ts` import cycle introduced when the `tool_search` defs (#5269) were extracted into their own module — `toolSearch.ts` imported `McpToolDefinition` from `tools.ts` while `tools.ts` imported `toolSearchTool` from `toolSearch.ts`, failing `check:cycles` on `release/v3.8.40`. The shared `AuditLevel` + `McpToolDefinition` types now live in a leaf `schemas/toolDefinition.ts` that both import; `tools.ts` re-exports them for backward compatibility. ([#5282](https://github.com/diegosouzapw/OmniRoute/pull/5282))
+- **compression (analytics):** record attempted-but-no-op compression runs so Stacked is no longer invisible when it saves nothing. A `compression_analytics` row was previously written only on a net-positive saving, so a Stacked pipeline that ran on already-compact context produced no row — indistinguishable from "never dispatched". Such runs are now recorded with `skip_reason` and surfaced as a per-mode `skipped` count plus `totalSkipped`/`bySkipReason`; net-saving totals/averages are unchanged (skip rows excluded). ([#5277](https://github.com/diegosouzapw/OmniRoute/pull/5277), #4268 — thanks @abdulkadirozyurt, @androw)
+- **cli (tray):** fix `omniroute server --tray` showing no tray on macOS/Linux with no error printed. The Unix tray path loaded `systray2` through an inline loader that called `require("module")` inside an ESM `.mjs` file → `ReferenceError: require is not defined`, silently swallowed (regressed in v3.8.34); even if loaded, `systray2` is lazily installed into `~/.omniroute/runtime`, not `node_modules`. The loader now delegates to the runtime loader, the icon path is corrected, `isTemplateIcon` is `false` (the full-color icon rendered as a white square under macOS template mode), and tray start failures surface to stderr. ([#5276](https://github.com/diegosouzapw/OmniRoute/pull/5276), #4605 — thanks @ProgMEM-CC)
+- **agent-bridge (antigravity):** unwrap the cloudcode-pa `.request` envelope when converting Antigravity IDE requests. The real IDE sends `cloudcode-pa.googleapis.com/v1internal:generateContent` with the Gemini request nested under `.request`, but the bridge read those fields at the top level — yielding an empty conversation, so prompts hung mid-execution. The legacy `/v1beta/models/<model>:generateContent` top-level shape still works. ([#5267](https://github.com/diegosouzapw/OmniRoute/pull/5267), #4294 — thanks @shabeer)
+- **dashboard:** add a GitHub releases fallback to the "Update Available" lookup. After the v3.8.28 npm-registry fallback, the banner could still stay hidden on networks that reach GitHub but not `registry.npmjs.org`. `resolveLatestVersion()` now tries npm CLI → npm registry → GitHub releases before giving up. ([#5266](https://github.com/diegosouzapw/OmniRoute/pull/5266), #4100)
+- **command-code:** omit `max_tokens` when the client omits it so the upstream applies the model's native default, fixing `400 "expected <=200000"` on `/alpha/generate` for high-cap models; an explicit oversized client value is clamped to the 200k endpoint ceiling. ([#5221](https://github.com/diegosouzapw/OmniRoute/pull/5221) — thanks @adivekar-utexas)
+
+### 🔒 Security
+
+- **authz:** require auth for the `/v1beta/*` Gemini-compatible client API. `next.config.mjs` rewrote `/v1beta/:path*` → `/api/v1beta/:path*`, but `src/proxy.ts` didn't match `/v1beta` before the rewrite and `classifyRoute()` didn't classify `/api/v1beta/*` as client API — so unauthenticated `/v1beta/models/...:generateContent` traffic could reach the model-serving route without the central client-API auth policy. Both alias and rewritten forms are now classified `CLIENT_API`, enforcing Bearer auth when `REQUIRE_API_KEY` is enabled. ([#5274](https://github.com/diegosouzapw/OmniRoute/pull/5274) — thanks @rdself)
+- **sentinel:** security hardening pass across request handling. ([#5241](https://github.com/diegosouzapw/OmniRoute/pull/5241) — thanks @iamedwardngo)
+- **providers:** refresh impersonation User-Agents + TLS fingerprint profiles to current real-client versions; several had drifted or were inconsistent across files, a bot-detection/blocking risk. ([#5237](https://github.com/diegosouzapw/OmniRoute/pull/5237) — thanks @backryun)
+- **authz (public origin):** centralize browser-mutation origin validation into `src/server/origin/publicOrigin.ts` and wire it through the authz pipeline, replacing the per-route same-origin-only check that `403`'d dashboard mutations when served behind a reverse proxy on a different public origin. The module resolves the allowed public origin from configured base-URL env vars or trusted forwarded headers (only when `OMNIROUTE_TRUST_PROXY` is set **and** the peer is loopback/LAN via peer-stamp), validates `Sec-Fetch-Site` metadata, and sanitizes `Host`/`Forwarded` inputs (rejects control chars, userinfo, path/query in Host). Regression guards: `tests/unit/authz/public-origin.test.ts` + `tests/unit/authz/pipeline.test.ts`. ([#5278](https://github.com/diegosouzapw/OmniRoute/pull/5278) — thanks @Thinkscape / @abodera)
+
+### 📝 Maintenance
+
+- **docs:** reorganize `docs/`, run an accuracy audit, and drop Node 20 from the supported matrix (rebased onto the current release tip). ([#5262](https://github.com/diegosouzapw/OmniRoute/pull/5262))
+- **providers:** remove the discontinued Gemini CLI channel — Google shut it down on 2026-06-18; the supported migration path is Antigravity. ([#5246](https://github.com/diegosouzapw/OmniRoute/pull/5246) — thanks @rdself)
+- **dashboard:** add more provider icons from Lobehub. ([#5220](https://github.com/diegosouzapw/OmniRoute/pull/5220) — thanks @backryun)
+- **deps:** resolve `npm install` warnings, fix a runtime `Cannot find module` crash on `omniroute serve` (the runtime-env module was missing from the npm `files` allow-list), and clear the 4 moderate `npm audit` advisories. ([#5252](https://github.com/diegosouzapw/OmniRoute/pull/5252) — thanks @yunaamelia), ([#5230](https://github.com/diegosouzapw/OmniRoute/pull/5230), #5227)
+- **docker:** harden the base image against container-scan CVEs and skip comment lines in the #4076 builder heap-ordering check. ([#5229](https://github.com/diegosouzapw/OmniRoute/pull/5229), [#5233](https://github.com/diegosouzapw/OmniRoute/pull/5233))
+- **ci:** Trivy advisory scan now ignores unfixed CVEs to cut Security-tab noise. ([#5235](https://github.com/diegosouzapw/OmniRoute/pull/5235))
+- **test(combo):** reconcile the #4279 stop-guard test with the #5249 advance policy. ([#5300](https://github.com/diegosouzapw/OmniRoute/pull/5300))
+- **test(targets):** add 14 unit tests for the shared `combo/targetExhaustion.ts` handler (provider-exhausted / connection-error / transient rate-limited classification), registered in the vitest discovery list. ([#5296](https://github.com/diegosouzapw/OmniRoute/pull/5296) — thanks @KooshaPari)
+
+---
+
+## [3.8.39] — 2026-06-28
+
+### ✨ New Features
+
+- **feat(oauth): remote Antigravity login via local helper + paste-credentials** — Antigravity (and other Google "native/desktop" OAuth providers) use Google's `firstparty/nativeapp` consent, which only releases the auth code when the loopback redirect (`127.0.0.1:<port>`) is reachable from the approving browser. On a remote VPS install that loopback lives on the server, so the consent hangs forever and never emits a code — the "paste the callback URL" fallback has nothing to paste (a Google-side constraint, identical in upstream 9router). A new `omniroute login antigravity` CLI helper runs the OAuth on the user's **own** machine (where 127.0.0.1 works), exchanges the code, and prints a single-line `omniroute-cred-v1.…` credential blob; the dashboard's Antigravity Connect → Step 2 field now accepts that blob (alongside callback URLs) and persists the connection via a new `paste-credentials` action (server-side onboarding, provider-allowlisted, with the blob's embedded provider required to match the route). The SSH local-forward tunnel is documented as a zero-tooling alternative. See [`docs/guides/REMOTE-MODE.md`](docs/guides/REMOTE-MODE.md). ([#5203](https://github.com/diegosouzapw/OmniRoute/pull/5203))
+- **feat(agent-bridge): graceful cert-install fallback for containers / headless** — when the MITM root CA can't be installed into the system trust store automatically (Docker / headless / no sudo / read-only trust store), the Agent Bridge no longer hard-fails on start with a generic "Certificate install failed". It now starts in skip mode and the dashboard surfaces a platform-specific **manual-install guide** (plus a CA download link) so the operator can trust the certificate by hand. The trust-cert endpoints return a structured `{ skippable, manualGuide }` response (HTTP 200) for environment failures instead of a 500; an explicit user cancellation is still reported distinctly. ([#4546](https://github.com/diegosouzapw/OmniRoute/issues/4546) — thanks @phuchptty)
+- **feat(compression): CCR ranged/grep/stats retrieval (ReDoS-safe, backward-compat)** — extends the `omniroute_ccr_retrieve` MCP tool and `/api/compression/retrieve` endpoint with optional `range` (byte/line slice), `grep` (ReDoS-safe literal or bounded-pattern match against stored lines), and `stats` (byte/line/word counts) parameters so agents pull exactly the slice or summary they need instead of re-expanding the entire stored block. All parameters are optional — no parameters returns the full block byte-identical to the existing behavior; the CCR store written by ionizer/fuzzy/headroom is fully compatible. Sixth item of the compression roadmap. ([#5187](https://github.com/diegosouzapw/OmniRoute/pull/5187))
+- **feat(compression): TOON best-of-N candidate encoder + encoder A/B table** — adds `@toon-format/toon` as a candidate encoder in the headroom compression engine via a best-of-N scheme: both GCF and TOON run per prompt and the shorter result is kept, rather than hard-swapping encoders (GCF already encodes the headroom block and TOON is not a lossless universal win). An encoder A/B comparison table (GCF vs TOON vs JSON — bytes and cl100k tokens) is now surfaced in the compression studio. Fifth item of the compression feature-extraction roadmap (bench: [#5080](https://github.com/diegosouzapw/OmniRoute/pull/5080), gate: [#5127](https://github.com/diegosouzapw/OmniRoute/pull/5127), fuzzy/gate: [#5143](https://github.com/diegosouzapw/OmniRoute/pull/5143), ionizer: [#5148](https://github.com/diegosouzapw/OmniRoute/pull/5148)). ([#5163](https://github.com/diegosouzapw/OmniRoute/pull/5163))
+
+### 🔧 Bug Fixes
+
+- **fix(cli): global npm install no longer fails with "Cannot find module scripts/build/runtime-env.mjs"** — the v3.8.39 heap auto-calibration fix made `bin/cli/commands/serve.mjs` import `scripts/build/runtime-env.mjs`, but that file was never added to the `files` whitelist in `package.json`, so the published npm tarball shipped the importing CLI without the imported module — breaking **every** `npm install -g omniroute` at startup (regression, all platforms). The file is now whitelisted (`npm pack` confirms it ships) and added to the pack-artifact policy allow/required lists, and a new regression test scans all `bin/**` entrypoints for runtime imports resolving under `scripts/` and asserts each is covered by the package `files` whitelist, so any future unpackaged CLI import fails CI instead of users' installs. ([#5227](https://github.com/diegosouzapw/OmniRoute/issues/5227) — thanks @PriyomSaha, @m-Yaghoubi, @jonlwheat2-gif)
+- **fix(oauth): Antigravity refresh no longer nulls the stored refresh_token on an empty upstream response** — Google's OAuth token endpoint uses non-rotating refresh tokens: a refresh response normally OMITS `refresh_token` and occasionally returns it as an empty string. The Antigravity executor's `refreshCredentials` used `typeof tokens.refresh_token === "string" ? tokens.refresh_token : credentials.refreshToken`, and because `typeof "" === "string"` is true, an empty-string response overwrote the good token with `""` — nulling it on first refresh. The check now treats a non-string **or empty** value as absent and preserves the stored token, matching the canonical `refreshGoogleToken` (`tokens.refresh_token || refreshToken`) semantics. ([#3850](https://github.com/diegosouzapw/OmniRoute/issues/3850) — thanks @3xa228148)
+- **fix(api): LAN/Tailscale dashboard access — `ws:` CSP scheme, GET-exempt version route, surface combo field errors** — three failures when opening the dashboard from a non-loopback host: (1) CSP `connect-src` allowed the `ws:` scheme only for loopback origins, blocking the dashboard's `ws://<lan-host>:*` Live WebSocket from LAN/Tailscale clients; the bare `ws:` scheme is now permitted (symmetric with the bare `wss:` already allowed), kept declarative in `next.config.mjs` with no global middleware (the project has none by design); (2) `GET /api/system/version` was blocked by `LOCAL_ONLY_API_PREFIXES` for all methods despite only `POST` spawning child processes (git/npm/pm2) — a new `LOCAL_ONLY_API_GET_EXEMPTIONS` set exempts safe read methods for this path while keeping `POST`/`PUT`/`PATCH`/`DELETE` strictly loopback-only; (3) `COMBO_002` validation errors only surfaced the generic message — `firstField`/`firstMessage` are now extracted from the first Zod issue and included in the response body. ([#5083](https://github.com/diegosouzapw/OmniRoute/issues/5083) — thanks @KooshaPari for the diagnosis and original PR #5084)
+- **fix(sse): defer `</think>` close so it never leaks before `tool_calls` in Claude→OpenAI streaming** — when a Claude thinking block was followed by a tool_use block, the translator unconditionally emitted a `content: "</think>"` chunk at `content_block_stop`, injecting a spurious assistant text chunk immediately before the `tool_calls` delta and corrupting OpenAI-compatible clients (e.g. Kimi Coding). The close marker is now deferred: it is flushed at the first `text_delta` that follows the thinking block (preserving the #4633 / decolua/9router#454 behavior for Claude Code / Cursor) or at stream finish when no tool_calls were collected. Tool-use streams never get a `text_delta` after the thinking block, so `</think>` is never emitted into content before `tool_calls`. ([#5123](https://github.com/diegosouzapw/OmniRoute/issues/5123))
+- **fix(sse): normalize array user-message content in the Command Code executor to prevent upstream 400** — when a client sends a user turn whose `content` is an array of content parts (e.g. `[{type:"text",text:"…"}, …]`), the raw array was forwarded verbatim to the Command Code upstream, which requires `messages[N].content` for the `user` role to be a plain string — resulting in `expected string, received array` / HTTP 400 on DeepSeek V4-Pro and other Command Code models. The user branch of `convertMessages` now calls `normalizeContentText()` (already used by system, assistant, and tool branches) so multi-part user content is joined to a string before dispatch. Partially addresses ([#5166](https://github.com/diegosouzapw/OmniRoute/issues/5166)); the 0-output-token symptom on reasoning-only models is tracked separately.
+- **fix(mcp): return HTTP 404 (not 400) for an unknown/expired Streamable HTTP session id** — when an MCP session is terminated or idles out and the client reuses the stale `Mcp-Session-Id` header, the Streamable HTTP transport replied with HTTP 400. The MCP spec (2025-03-26 and 2025-11-25, Session Management) mandates HTTP 404 Not Found in that case, and spec-compliant clients only re-initialize a session on 404 — so the 400 was non-recoverable. The handler now returns 404 for a present-but-unknown session id, while a _missing_ session id on a non-initialize request correctly stays 400. ([#5169](https://github.com/diegosouzapw/OmniRoute/issues/5169) — thanks @czer323)
+- **fix(api): blocking "Auto (Zero-Config)" in Security settings now removes `auto/*` from `/v1/models`** — the built-in `auto/*` combo advertiser (#4164 / #4235) at the top of the models catalog ignored `settings.blockedProviders`, so checking **Auto (Zero-Config)** under Security → Blocked Providers had no effect and the model picker kept listing every `auto/*` entry. The injection loop now skips the entire `auto/*` block when the system provider `auto` (its id and alias are both `auto`) is blocked, consistent with how every other provider is filtered from the catalog. ([#5192](https://github.com/diegosouzapw/OmniRoute/issues/5192) — thanks @WslzGmzs)
+- **fix(cli): auto-calibrate the server V8 heap from physical RAM instead of a fixed 512MB default** — the server was spawned with a hard-coded `--max-old-space-size=512` (`omniroute serve`) or with no heap flag at all (Electron desktop, which then inherited the runtime's low ~512MB default), so RAM-rich machines still OOM-crashed under load (`FATAL ERROR: Ineffective mark-compacts near heap limit … ~500MB` at code=134) with many providers/accounts and large model catalogs (one report: 16GB RAM, 65 providers, ~100 accounts, ~2600 models). A new `calibrateHeapFallbackMb(os.totalmem())` helper derives the default heap as ~35% of physical RAM, clamped to `[512, 4096]`, and is wired into both `bin/cli/commands/serve.mjs` and `electron/main.js`. An explicit `OMNIROUTE_MEMORY_MB` (or a pre-set `--max-old-space-size`) still wins, so the #2939 override contract is unchanged. ([#5172](https://github.com/diegosouzapw/OmniRoute/issues/5172), [#5160](https://github.com/diegosouzapw/OmniRoute/issues/5160), [#5152](https://github.com/diegosouzapw/OmniRoute/issues/5152) — thanks @manchairwang, @Xyzjesus)
+
+- **fix(oauth): Antigravity login no longer hangs — fire-and-forget onboarding + bounded post-exchange** — the dashboard's Antigravity OAuth login spun indefinitely because `postExchange` awaited the `onboardUser` retry loop inline (up to 10 × 5 s per attempt, each fetch with no timeout), blocking the `/exchange` response forever. Matching the upstream 9router web flow: `onboardUser` now runs fire-and-forget in a background task; the `/exchange` endpoint is bounded by a 10 s hard timeout so it always returns; a progress endpoint lets the dashboard poll onboarding completion state. ([#5193](https://github.com/diegosouzapw/OmniRoute/pull/5193))
+- **fix(antigravity): retry Antigravity accounts by quota family before escalating the combo** — when one Antigravity account returns a quota or rate-limit `429` for a Gemini model (e.g. `gemini-3.5-flash-medium`), combo orchestration could prematurely advance to the next combo model instead of trying other eligible Antigravity accounts for the same quota family. Antigravity quota-family awareness is now added to the fallback path so a `429` on one account triggers a bounded same-model retry across other Antigravity accounts sharing that quota bucket before the combo degrades to a lower-tier model. ([#5180](https://github.com/diegosouzapw/OmniRoute/pull/5180) — thanks @Ardem2025)
+- **fix(translator): accept Claude Messages shape in the non-stream malformed-200 guard** — when a Claude client (e.g. Claude Code) is routed to a non-Claude provider, the translated non-streaming response body is in Claude Messages shape (`type: "message", content[]`) produced by `convertOpenAINonStreamingToClaude`. `detectMalformedNonStream` only recognized OpenAI `choices[].message` and Responses API `output[]`, so this shape fell through to `empty_choices` → 502. The guard now recognizes the Claude Messages shape: text, tool_use, and thinking blocks carrying a `signature` count as valid output, while a genuinely empty `content: []` is still flagged. ([#5156](https://github.com/diegosouzapw/OmniRoute/pull/5156) — thanks @NomenAK)
+- **fix(sse): resolve nameless deepseek-web `<tool>` blocks via parameter-schema match** — when `chat.deepseek.com` emits a `<tool>` block with no `<name>` child, no JSON body `name`/`type` key, and no tag suffix, every name-resolution path in `extractCall` returned `null` and the raw XML leaked to the client as plain text. A conservative schema-based fallback now compares the block's extracted parameter names against each declared tool's schema keys; if exactly one tool matches, its name is used. Zero or ambiguous (>1) matches still return `null` so no calls are misattributed. ([#5154](https://github.com/diegosouzapw/OmniRoute/issues/5154), [#5173](https://github.com/diegosouzapw/OmniRoute/pull/5173))
+- **fix(stream): normalize provider safety finish reasons to `content_filter`** — Gemini and Antigravity can return safety/prohibited terminal reasons (`SAFETY`, `RECITATION`, `BLOCKLIST`, `PROHIBITED_CONTENT`) that OpenAI-compatible downstream clients do not recognize. A shared finish-reason normalization helper now maps these to the standard `content_filter` value, applied in both the streaming and JSON collection paths for both providers. ([#5197](https://github.com/diegosouzapw/OmniRoute/pull/5197) — thanks @rdself)
+- **fix(responses): normalize non-array Responses API `input` before routing** — the OpenAI Responses API accepts `input` as a string, object, or list, but OmniRoute only handled list-shaped payloads; a string or object `input` was silently dropped on the Responses→Chat Completions path. The translator now normalizes `input` to a list before dispatch; the Codex-native Responses path also normalizes before forwarding (preventing upstream `400 Input must be a list`); and the prompt-injection and PII sanitizer extraction paths are guarded against object-valued `input` so security checks do not throw. ([#5204](https://github.com/diegosouzapw/OmniRoute/pull/5204) — thanks @wilsonicdev)
+- **fix(zenmux): normalize vendor-prefixed GLM system roles for Z.AI models** — ZenMux exposes Z.AI GLM via vendor-prefixed OpenAI-compatible IDs such as `z-ai/glm-5.2`. The existing GLM detection only matched bare `glm-*`/`glm` ids, so `zenmux/z-ai/glm-5.2` kept system messages in place; Z.AI rejects compressed histories ending with a system turn before `assistant(tool_calls) → tool` sequences. The fix extends GLM detection to cover `z-ai/glm-*` prefixes and routes them through the existing `normalizeSystemRole` path. ([#5158](https://github.com/diegosouzapw/OmniRoute/pull/5158) — thanks @Thinkscape)
+- **fix(xai): add OAuth connection test probe + normalize xAI reasoning effort aliases** — xAI rejects unsupported reasoning effort values (`max`, `xhigh`) with HTTP 400 after a provider update; the xAI translator now maps `max` and `xhigh` to `high` before forwarding. Additionally, xAI OAuth connections had no dashboard test configuration, so provider tests returned `"Provider test not supported"`; a dedicated OAuth test probe is now wired for xAI accounts with regression coverage for the effort normalization. ([#5157](https://github.com/diegosouzapw/OmniRoute/pull/5157) — thanks @nguyenxvotanminh3)
+- **fix(serve): honour `HOSTNAME` from `.env` instead of hardcoding `0.0.0.0`** — `bin/cli/commands/serve.mjs` spread `process.env` into the child-process environment but immediately overwrote `HOSTNAME` with a literal `"0.0.0.0"`, silently discarding any user-configured bind address even though `HOSTNAME` is documented in `.env.example` and `docs/reference/ENVIRONMENT.md`. `dist/server.js` already read `process.env.HOSTNAME` correctly; only the CLI wrapper was overriding it. The fix applies `process.env.HOSTNAME || "0.0.0.0"` so the env value takes effect. ([#5134](https://github.com/diegosouzapw/OmniRoute/issues/5134), [#5170](https://github.com/diegosouzapw/OmniRoute/pull/5170) — thanks @anki1kr / @Angelo90810)
+- **fix(cli): force `NODE_ENV` to match dev/start run mode in the custom Next server** — when `.env.example` ships `NODE_ENV=production`, starting `npm run dev` via `scripts/dev/run-next.mjs` forwarded that value to the programmatic `next()` entry, which — unlike the `next` CLI — does not normalize it to match the run mode. The resulting production flag caused PostCSS to skip Tailwind's CSS transform, surfacing as `Module parse failed: Unexpected character '@'` on `globals.css`. The custom server now explicitly forces `NODE_ENV=development` for the `dev` path and `NODE_ENV=production` for the `start` path regardless of `.env`. ([#5189](https://github.com/diegosouzapw/OmniRoute/pull/5189) — thanks @backryun)
+- **fix(cli): raise dev server Node heap limit to 8 GB to prevent OOM** — `npm run dev` crashed with `FATAL ERROR: Ineffective mark-compacts near heap limit — Allocation failed - JavaScript heap out of memory` while compiling heavy dashboard routes because `node scripts/dev/run-next.mjs` ran on V8's ~4 GB default with no `--max-old-space-size` flag. The `dev` npm script now passes `--max-old-space-size=8192` at invocation time (the only point where this flag can be set for that process). ([#5198](https://github.com/diegosouzapw/OmniRoute/pull/5198) — thanks @backryun)
+- **fix(cli): re-enable Turbopack as the default `npm run dev` bundler** — PR #4092 forced webpack because an earlier Turbopack 16.2.x panic (`internal error: entered unreachable code: there must be a path to a root` in `turbopack-core/module_graph`) blocked the OmniRoute module graph. That panic no longer reproduces on the pinned Next 16.2.9, so `OMNIROUTE_USE_TURBOPACK` is flipped from `0` to `1` in `.env.example`, aligning it with `docs/reference/ENVIRONMENT.md` which had already documented the default as `1`. ([#5206](https://github.com/diegosouzapw/OmniRoute/pull/5206) — thanks @backryun)
+- **fix(auth): allow synthetic no-auth fallback for mimocode** — mimocode connections without explicit credentials were blocked before reaching the executor. The auth layer now permits a synthetic no-auth fallback for the mimocode provider so credential-free access patterns work as intended. ([#5205](https://github.com/diegosouzapw/OmniRoute/pull/5205) — thanks @KooshaPari)
+- **fix(combo): reject empty Responses API `output: []` as a fail-over trigger** — a non-streaming Responses API body with `object: "response"` and `output: []` was accepted as a valid HTTP 200 by the combo response-quality validator, allowing a combo target to stop rather than fail over to the next leg. The non-stream validator now inspects Responses-API-shaped bodies before the generic `output` shortcut and rejects an empty `output: []` as `empty_choices`; structural non-empty output (e.g. `function_call`) remains valid. ([#5207](https://github.com/diegosouzapw/OmniRoute/pull/5207) — thanks @KooshaPari)
+- **fix(proxy): close cached dispatchers when clearing the proxy cache** — cached proxy and direct-retry dispatchers were not closed on cache clear, leaking open connection handles. The cache-clear path now calls `close()` on all evicted dispatchers; dispatcher cache and lifecycle helpers have been extracted from the oversized proxy-dispatcher module into a dedicated helper for reuse. ([#5202](https://github.com/diegosouzapw/OmniRoute/pull/5202) — thanks @KooshaPari)
+- **fix(proxy): coalesce concurrent fast-fail health probes per proxy URL** — under high concurrency each simultaneous request opened its own TCP health probe for the same proxy URL, creating a thundering-herd burst. Concurrent proxy fast-fail checks are now coalesced so only one TCP probe runs per proxy URL at a time; the completed-result health cache is preserved so subsequent same-URL checks return immediately. ([#5109](https://github.com/diegosouzapw/OmniRoute/issues/5109), [#5208](https://github.com/diegosouzapw/OmniRoute/pull/5208) — thanks @KooshaPari)
+- **fix(pwa): prefer cached navigation before showing the offline page** — the service worker was too eager to display `/offline` on transient navigation failures. It now caches successful navigation responses and consults the cached route or app shell before falling back to `/offline`; `/offline` remains the final fallback when no cached navigation or app shell exists. ([#5165](https://github.com/diegosouzapw/OmniRoute/issues/5165), [#5209](https://github.com/diegosouzapw/OmniRoute/pull/5209) — thanks @KooshaPari)
+- **fix(request-logger): never render a negative percentage in the compression badge** — when every prompt token was compressed (`totalIn = 0, compressed > 0`), the compression pill displayed `(-100%)` because the badge format hard-coded a leading `-` before the percentage value. The badge now omits the negative sign in this case, correctly representing the saving as a positive ratio. ([#5201](https://github.com/diegosouzapw/OmniRoute/pull/5201) — thanks @KooshaPari)
+- **fix(dashboard): use amber for home update-step warning icon** — the warning-state icon in the home update steps (`HomePageClient.tsx`) used `text-yellow-500` (Tailwind `#eab308`), which has poor contrast on light backgrounds (~1.9:1, below WCAG AA) and is inconsistent with the `amber` warning convention used by every sibling element in the same component. Switched to `text-amber-500` — a one-line `className` change with no behavior change. ([#5176](https://github.com/diegosouzapw/OmniRoute/pull/5176))
+
+### 📝 Maintenance
+
+- **test(docker): de-brittle the #4076 builder-stage heap-ordering test (false-failing on a comment)** — `dockerfile-build-heap-4076.test.ts` located the `npm run build` step via a raw `findIndex(/npm run build\b/)`, which matched a **comment line** in the builder stage (`# … npm run build fails with "Module not…"`, added with the v3.8.40 workspace-deps Docker fix) sitting before the `NODE_OPTIONS` heap line — making the test report the heap ceiling as set _after_ the build and fail, even though the real `RUN … npm run build` correctly follows the `ENV NODE_OPTIONS` line. Instruction matching now skips Dockerfile comment lines (`# …`), so the ordering guard checks real `ENV`/`RUN` instructions only. The Dockerfile itself was already correct; this was a base-red blocking every PR into `release/v3.8.40`. ([#4076](https://github.com/diegosouzapw/OmniRoute/issues/4076))
+- **test(combo): deterministic context-relay universal-handoff coverage** — covers the universal (provider-agnostic) session-handoff path in `context-relay` (`combo.ts:2099–2139`), which previously had only a definition-order assertion and a `TODO(phase-2)`. The test drives the real pipeline via session seams (`x-session-id` → `relayOptions.sessionId` → `maybeGenerateUniversalHandoff`) without live infrastructure. ([#5168](https://github.com/diegosouzapw/OmniRoute/pull/5168))
+- **test(combo): end-to-end quota-share DRR routing-decision coverage (matrix parity)** — adds the missing E2E test for the `quota-share` strategy, driving the real `handleChat` → chatCore → `selectQuotaShareTarget` → executor pipeline via in-process seams and asserting which connection is dispatched. The DRR selector already had 29 unit tests; this closes the E2E gap and brings quota-share to parity with the 17-strategy public matrix. ([#5179](https://github.com/diegosouzapw/OmniRoute/pull/5179))
+- **test(combo): deterministic context-relay codex quota-handoff coverage (closes last gap)** — covers the codex-specific handoff block of `context-relay` (`combo.ts:2143–2183`), which #5168 left documented-but-untested because it requires a `codex` connection. All seams (`fetchCodexQuota`, handoff generation, session relay) are mocked deterministically without live infra. ([#5195](https://github.com/diegosouzapw/OmniRoute/pull/5195))
+- **test(ci): wire antigravity-quota-family test under `test:vitest` (fix test-discovery orphan)** — `open-sse/services/__tests__/antigravity-quota-family.test.ts` (introduced by #5180) was not collected by any active runner, causing `check:test-discovery` to report a new orphan and gate every subsequent PR on the release branch. The file is now added to `vitest.mcp.config.ts` `include` and the corresponding orphan-allowlist entry is removed. ([#5196](https://github.com/diegosouzapw/OmniRoute/pull/5196))
+- **test(security): regression guard — PII redaction stays opt-in (default off) + Hard Rule #20** — adds a test asserting both `PII_REDACTION_ENABLED` and `PII_RESPONSE_SANITIZATION` feature-flag `defaultValue` fields are `"false"` and that data passes through all three application points (`piiMasker`, `piiSanitizer`, `streamingPiiTransform`) untouched when both flags are off, encoding Hard Rule #20 as a CI-enforced contract and fixing a misleading doc implication that PII masking was on by default. ([#5159](https://github.com/diegosouzapw/OmniRoute/pull/5159))
+- **docs(i18n): add Traditional Chinese (zh-TW) README + update zh-CN** — adds a new Traditional Chinese translation (`docs/i18n/zh-TW/README.md`) and updates the Simplified Chinese README to the current English baseline; the language index (`docs/i18n/README.md`) and root `README.md` badge row are updated accordingly. ([#5162](https://github.com/diegosouzapw/OmniRoute/pull/5162) — thanks @lunkerchen)
+- **docs(i18n): full sync of zh-TW and zh-CN README to canonical English v3.8.39** — brings both translations to full parity, adding the complete What's New section, compression real-token examples, and all sections updated in the v3.8.38/39 English README. ([#5171](https://github.com/diegosouzapw/OmniRoute/pull/5171) — thanks @lunkerchen)
+- **docs(combo): sync combo/routing-strategy docs to current state + document test coverage** — removes a stale ordinal from the Fusion bullet in `README.md`; adds a new **Testing & Coverage** section to `docs/routing/AUTO-COMBO.md` documenting the deterministic strategy matrix (`npm run test:combo:matrix`), quota-share DRR E2E coverage, and context-relay handoff tests delivered across the v3.8.39 cycle. ([#5185](https://github.com/diegosouzapw/OmniRoute/pull/5185))
+- **fix(docker):** copy the `open-sse` workspace manifest before `npm ci` so workspace-only deps install — the Dockerfile copied only the root `package*.json`, so `npm ci` skipped `safe-regex` and `@toon-format/toon` (declared in `open-sse/package.json`, not hoisted to root), breaking the multi-arch image build with `Module not found` during `npm run build`. (thanks @diegosouzapw)
+
+---
+
+## [3.8.38] — 2026-06-27
+
+### ✨ New Features
+
+- **feat(sidebar): colored menu icons** — sidebar menu icons now render with a per-item accent color: curated colors for known items (`SIDEBAR_ICON_ACCENTS`) plus a deterministic hash-based fallback (`getSidebarIconAccent`) so every item gets a stable, distinct color across sessions. ([#3812](https://github.com/diegosouzapw/OmniRoute/pull/3812) — thanks @rafacpti23)
+- **feat(providers): add Factory (factory.ai) as a subscription gateway provider** — `factory` (Factory Droids' hosted gateway) is now a first-class routing provider on the OpenAI-compatible `https://api.factory.ai/v1` endpoint with Bearer apikey auth; the key is supplied from the Dashboard connection (not env). ([#5065](https://github.com/diegosouzapw/OmniRoute/pull/5065) — thanks @KooshaPari)
+- **feat(providers): add Grok Build (xAI) provider with OAuth import-token flow** — `grok-cli` (alias `gc`) routes through Grok's CLI chat proxy; users paste their `~/.grok/auth.json` (or the JWT), with automatic `refresh_token` rotation. The public xAI client_id is embedded via `resolvePublicCred("grok_id")` (Hard Rule #11), never a literal. ([#5020](https://github.com/diegosouzapw/OmniRoute/pull/5020) — thanks @fulorgnas)
+- **feat(dashboard): click-to-edit model alias in the provider page** — click an alias to edit it inline (Enter/blur saves, Escape cancels), instead of only being able to delete and re-add it. ([#5119](https://github.com/diegosouzapw/OmniRoute/pull/5119) — thanks @waguriagentic)
+- **feat(providers): add ZenMux Free (session-cookie free-tier) provider** — `zenmux-free` (alias `zmf`) with a dedicated executor translating ZenMux's Anthropic-style SSE to OpenAI format; ships 12 free-tier models (DeepSeek V3.2, GLM 4.7 Flash Free, etc.). ([#5105](https://github.com/diegosouzapw/OmniRoute/pull/5105) — thanks @mrnasil)
+- **feat(providers): allow local/private provider URLs by default (`Allow Local Provider URLs` flag)** — adding/validating an OpenAI-compatible provider on a loopback/LAN address (e.g. `http://127.0.0.1:3264/api`) was rejected by the SSRF guard with "Blocked private or local provider URL", even though OmniRoute is local-first. A new `OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS` feature flag (default **ON**, toggle in Settings → Feature Flags) now scopes the provider-validation guard to allow local/private hosts while still blocking cloud-metadata endpoints (169.254.169.254, metadata.google.internal). Disable it to restore strict public-only blocking. Webhook/remote-image SSRF defaults are unchanged. ([#5066](https://github.com/diegosouzapw/OmniRoute/issues/5066), thanks @daniij)
+- **feat(blackbox):** refresh provider model catalog with latest models. (thanks @ptkelanatechsolutions)
+- **kiro**: inline `<thinking>` stream splitter — when `<thinking_mode>enabled</thinking_mode>` is present, `assistantResponseEvent` content is now split into separate `delta.content` / `delta.reasoning_content` SSE chunks (new `open-sse/executors/kiroThinking.ts` module wired into `KiroExecutor.transformEventStreamToSSE`).
+- **feat(cursor):** parse Cursor Composer DeepSeek-style inline tool calls — Composer `cu/composer-2.5*` models embed tool invocations in their visible text using `<｜tool▁calls▁begin｜>…<｜tool▁calls▁end｜>` markers instead of structured protobuf frames; a new streaming parser (`composerToolCalls.ts`) intercepts these in both streaming and non-streaming paths, suppresses the markers from the client-visible content, and emits proper OpenAI `tool_calls` deltas so downstream clients handle them natively. (thanks @noestelar)
+- **feat(proxy):** support auth-less `host:port` batch import and surface proxy-test failures. (thanks @dimaslanjaka)
+- **feat(video): Alibaba DashScope video provider (`wan2.7-t2v`)** — adds the `alibaba` video provider (DashScope async task → poll → MP4) wired through the standard apikey credential path, so text-to-video requests can route to Alibaba's `wan2.7-t2v` model. (thanks @josevictorferreira)
+- **feat(cc): per-connection "summarized thinking display" toggle for Claude-Code-compatible providers** — exposes a connection-level toggle that drives the existing Copilot summarized-thinking marker, so operators can opt a CC-compatible connection into summarized reasoning display from the UI (schema + request defaults + provider modals, with i18n). (thanks @rdself)
+- **feat(compression): compression playground in the studio (Play + Compare tabs)** — `/dashboard/compression/studio` gains a synthetic playground: paste text → per-engine **lanes** (each deterministic engine run alone via `/api/compression/preview`) plus a **combined waterfall** ordered by `stackPriority`, and a free **A/B Compare** grid with on-demand, **USD-capped** fidelity verdicts (`/api/compression/compare` + `compare/verify`). The preview route now uses the real cl100k tokenizer, returns `engineBreakdown`, and accepts an ordered `pipeline[]`; new `compare` / `compare/verify` / `retrieve` routes; the live WS feed moved to `/dashboard/compression/live`. Management-only. ([#5080](https://github.com/diegosouzapw/OmniRoute/pull/5080))
+- **feat(dashboard): expose Fusion `judgeModel` + `fusionTuning` in the combo editor** — the Fusion strategy editor now surfaces the judge model (synthesizes the panel answers; defaults to the first panel model) plus the quorum-grace tuning fields (`minPanel`, `stragglerGraceMs`, `panelHardTimeoutMs`) that `open-sse/services/fusion.ts` already reads. Schema-validated + bounded; empty tuning is never persisted. ([#5074](https://github.com/diegosouzapw/OmniRoute/pull/5074))
+- **feat(compression): opt-in per-step fidelity gate for the stacked pipeline** — each compression step can now be guarded by a pure fidelity checker (4 invariants, fail-open) so a lossy engine that would degrade the prompt past a threshold is rejected and its lane skipped instead of silently shipping. Configurable via `fidelityGate` (advanced thresholds intentionally API-omitted), with a per-lane rejection breakdown surfaced in the studio playground toggle. ([#5143](https://github.com/diegosouzapw/OmniRoute/pull/5143))
+- **feat(compression): fuzzy near-duplicate dedup (session-dedup 2nd pass)** — the session-dedup engine gains a second fuzzy pass that collapses near-duplicate (not just byte-identical) segments, with a playground toggle to compare on/off. ([#5143](https://github.com/diegosouzapw/OmniRoute/pull/5143))
+- **feat(quota): opt-in Codex/Claude auto-ping keepalive** — an opt-in background keepalive can periodically ping Codex/Claude connections to keep their session/quota state warm, reducing cold-start failures on the first real request. ([#5102](https://github.com/diegosouzapw/OmniRoute/pull/5102))
+- **feat(ops): SRE playbooks + ops helper scripts** — salvaged from a closed stale PR; adds operator runbooks and ops helper scripts. ([#5138](https://github.com/diegosouzapw/OmniRoute/pull/5138) — thanks @KooshaPari / @diegosouzapw)
+- **feat(mcp): web-session robustness — cookie dedup + browser-pool observability** — the MCP web-session path now de-duplicates cookies when (re)hydrating a session (avoiding conflicting duplicate `Cookie` headers) and exposes browser-pool observability (pool size / in-use / acquisition metrics) for the headless web providers. ([#5121](https://github.com/diegosouzapw/OmniRoute/pull/5121), builds on [#3368](https://github.com/diegosouzapw/OmniRoute/issues/3368))
+- **feat(compression): Ionizer engine — lossy JSON-array sampling reversible via CCR** — a new compression engine that down-samples large JSON arrays to a representative subset and records a Compact Change Representation (CCR) so the omitted rows can be reconstructed, trading exactness for a large token reduction on tabular/array-heavy payloads. ([#5148](https://github.com/diegosouzapw/OmniRoute/pull/5148))
+
+### 🔧 Bug Fixes
+
+- **fix(sse): resolve nameless deepseek-web `<tool>` blocks via parameter-schema match** — when `chat.deepseek.com` emits a `<tool>` block with no tag suffix, no `<name>` child, and no JSON body (only `<parameter name="…">` children), every existing name-resolution path returned `null` and the raw XML leaked to the client instead of being converted to a `tool_call`. `extractCall` now falls back to a conservative schema-based match: if the extracted parameter names are a subset of exactly one requested tool's declared schema keys, that tool name is used; zero or ambiguous (>1) schema matches still return `null` so no calls are misattributed. ([#5154](https://github.com/diegosouzapw/OmniRoute/issues/5154))
+- **fix(proxy): make the SOCKS5 handshake timeout operator-tunable (`SOCKS_HANDSHAKE_TIMEOUT_MS`)** — under high concurrency against a single residential gateway host, the SOCKS5 connect handshake could exceed the hardcoded 10s even though the proxy was reachable, surfacing as a false `[Proxy Fast-Fail] Proxy unreachable` (the pool size is already tunable via `OMNIROUTE_PROXY_DISPATCHER_CONNECTIONS`). The handshake timeout now reads `SOCKS_HANDSHAKE_TIMEOUT_MS` (default unchanged at `10000`, capped at `120000`) so a concurrency-heavy deployment can raise it without a code change. Mitigation for #5109 (the full concurrency-100 collapse still needs the reporter's live load-test confirmation). ([#5109](https://github.com/diegosouzapw/OmniRoute/issues/5109))
+- **fix(api): resolve `GET /v1/models/{id}` case-insensitively** — clients that normalise the model id (e.g. OpenCode requesting `minimax/minimax-m3` for the canonical catalog entry `minimax/MiniMax-M3`) missed the single-model lookup, which is case-sensitive, and fell back to advertising `context_length: 0`. `findModelById` now prefers an exact-case match and falls back to a case-insensitive match, so the real entry (and its context window) is returned regardless of casing. ([#5082](https://github.com/diegosouzapw/OmniRoute/issues/5082))
+- **fix(services): embed WS proxy honours `LIVE_WS_HOST`; reject empty `messages` early** — two headless/Docker deployment fixes (#5110). The embed WebSocket proxy (`:20131`) only read `EMBED_WS_PROXY_HOST`, so behind a reverse proxy/tunnel it stayed bound to `127.0.0.1` even with `LIVE_WS_HOST=0.0.0.0` set and the Live dashboard showed "WebSocket disconnected"; it now falls back to `LIVE_WS_HOST` (default still loopback). Separately, a request with an explicitly empty `messages: []` array was forwarded upstream and bounced back as a confusing raw `400/502`; `handleChat` now rejects it up front with a clear `messages: at least one message is required` (Responses-API `input` requests are unaffected). ([#5110](https://github.com/diegosouzapw/OmniRoute/issues/5110))
+- **fix(proxy): repair one-click Deno & Cloudflare relay deployments** — the `/api/settings/proxy/test` endpoint only recognized the `vercel` relay type, so testing a deployed Deno or Cloudflare relay returned `proxy.type must be http, https, or socks5` and never reached the relay; it now routes all relay types through `isRelayType()`. On installs with `STORAGE_ENCRYPTION_KEY` the relay-auth token is read via `extractRelayAuth` (encrypted `relayAuthEnc` form), fixing the silent `401` that left `publicIp` null. The Cloudflare Worker upload now sends the script part as `application/javascript` (the API rejects `application/javascript+module`; ES-module semantics come from `main_module`), and the proxy-registry schema accepts the `deno`/`cloudflare` types + `deno-relay`/`cloudflare-relay` sources so editing a deployed relay no longer 400s. ([#5128](https://github.com/diegosouzapw/OmniRoute/issues/5128))
+- **fix(kiro): retire `claude-sonnet-4.5` from the Kiro catalog + pin the exact Kiro 400 error** — `claude-sonnet-4.5` left the Kiro free-tier lineup (current active models: Opus 4.8/4.7/4.6, Sonnet 4.6, Haiku 4.5), so it is removed from the Kiro registry entry and the free-model catalog. A regression test now pins Kiro's verbatim `[400] Invalid model. Please select a different model to continue.` to the `isModelUnavailableError` model-unavailable classification. A 400 on every model (including current ones) points to a server-side Kiro tier/region gate, not an OmniRoute catalog bug. ([#5140](https://github.com/diegosouzapw/OmniRoute/pull/5140), closes [#4484](https://github.com/diegosouzapw/OmniRoute/issues/4484))
+- **fix(dashboard): preserve every rendered field when loading/saving Resilience settings** — `ResilienceTab` renders `comboCooldownWait` and `quotaShareConcurrencyLimit`, but both the initial-load and save paths rewrote component state without those fields, so after a successful `/api/resilience` response the cards received `undefined` and the page fell back to the generic "failed to load" state. A shared `toResilienceResponse()` mapper now keeps all rendered fields, and `PATCH /api/resilience` returns `quotaShareConcurrencyLimit` to match GET and the UI contract. ([#5139](https://github.com/diegosouzapw/OmniRoute/pull/5139) — thanks @rdself)
+- **fix(quota): hydrate the in-memory quota cache from snapshots + scope auto-combo candidates** — after a restart the quota cache was empty, so a known-exhausted connection looked healthy until re-queried; `isAccountQuotaExhausted` now lazily hydrates from persisted `quota_snapshots`. Auto-combo candidate expansion is also scoped to the connections each combo target actually allows, instead of pulling in every connection for the provider. ([#5015](https://github.com/diegosouzapw/OmniRoute/pull/5015) — thanks @JxnLexn)
+- **fix(resilience): harden quota cutoff, Gemini audio MIME, and model-lockout cooldown** — stored quota hard-cutoff values are no longer coerced to `enabled=true` from arbitrary strings; Gemini audio input parts have their MIME type validated/normalized before forwarding; and model lockout now honours the configured `maxCooldownMs` ceiling. ([#5093](https://github.com/diegosouzapw/OmniRoute/pull/5093) — thanks @KooshaPari)
+- **fix(streaming): harden long OpenAI-compatible SSE streams** — a late pipeline-wind-down error can no longer overwrite an already-recorded successful stream (`streamCompletionRecorded` guard), client disconnects finalize as `499 client_disconnected` instead of poisoning provider/account failure state, JSON bodies that are actually SSE (wrong `application/json` content-type) are sniffed and re-streamed, and reasoning fields (`reasoning`/`reasoning_content` + OpenRouter/Gemini encrypted `reasoning_details`) are preserved through the JSON-as-SSE fallback. ([#5124](https://github.com/diegosouzapw/OmniRoute/pull/5124) — thanks @rdself)
+- **fix(usage): dedupe request-usage logging and debounce stats events** — `saveRequestUsage` now guards against duplicate inserts (natural key: timestamp + provider + model + connection + api-key + token counts), back-fills a missing `endpoint`, and only emits `usageRecorded` when a row was actually inserted; stats `update`/`pending` event bursts are collapsed into a single debounced notification to reduce churn. ([#4940](https://github.com/diegosouzapw/OmniRoute/pull/4940) — thanks @nguyenxvotanminh3)
+- **fix(sse): convert the native Gemini request body to OpenAI format in the Antigravity MITM handler** — `contents` / `systemInstruction` / `generationConfig` / `thinkingConfig` are now translated to OpenAI chat-completions format before forwarding to `/v1/chat/completions`, so thinking-capable models (e.g. `ag/claude-opus-4-6-thinking`) no longer fail with provider-side 400 "invalid argument" errors. ([#4845](https://github.com/diegosouzapw/OmniRoute/pull/4845) — thanks @anuragg-saxenaa)
+- **fix(db): translate the two pt-BR SQLite driver-fallback log lines to English** — `[DB] Pré-inicializando sql.js WASM…` and `[DB] Drivers síncronos indisponíveis…` were the only non-English server log strings, mixing languages in the logs. Now `[DB] Pre-initializing sql.js WASM (synchronous drivers unavailable)…` / `[DB] Synchronous drivers unavailable — falling back to sql.js (WASM)`, guarded by a test that scans the driver path for accented log strings. ([#5103](https://github.com/diegosouzapw/OmniRoute/issues/5103))
+- **fix(diagnostics): non-streaming Claude responses no longer false-502 as `empty_choices`** — the v3.8.37 malformed-200 detector (#4942) only understood OpenAI `choices` and Responses-API `output` shapes, so a `/v1/messages` response that stays in Claude shape (`{type:"message", content:[…]}`) fell through to `empty_choices` → 502 (cascading to "All models failed" in a combo). Most visibly, an extended-thinking turn whose buffered body is a single **empty thinking block with a valid `signature`** (Claude Code's non-streaming Bash classifier) 502'd on every call. `detectMalformedNonStream` now understands the Claude shape: text/tool_use blocks and thinking blocks carrying a signature count as valid output, while a genuinely empty `content:[]` is still flagged. ([#5108](https://github.com/diegosouzapw/OmniRoute/issues/5108), thanks @insoln)
+- **fix(combo): empty-content 502 now fails over within the same request instead of exhausting the provider** — a leg that answers HTTP 200 with no usable completion is rewritten to `502 "Provider returned empty content"`, but the combo exhaustion classifier treated that synthetic 502 as a connection-level failure (`#1731v2`) and marked the whole provider/connection exhausted, skipping every remaining **same-provider** leg in that request. The connection is actually healthy (it just returned an empty body), so empty-content 502s are now classified as model-level transient failures: the request advances to the next leg and the rest of that provider's legs stay eligible. Genuine gateway 502s still trip connection exhaustion. ([#5085](https://github.com/diegosouzapw/OmniRoute/issues/5085), thanks @andrea-kingautomation)
+- **fix(dashboard): surface the detailed credential-validation error instead of a bare "invalid" badge** — the inline "Check" in the Add-Connection modal discarded the `error` message returned by `/api/providers/validate` and showed only an `invalid` badge. For web providers (claude-web / chatgpt-web) the real cause is often an environment error the backend already reports (e.g. `TLS impersonation client failed to start: EACCES … mkdir tls-client-node/bin`), so users were left guessing. The modal now renders the full reason next to the badge. ([#5088](https://github.com/diegosouzapw/OmniRoute/issues/5088), thanks @tkhs101)
+- **fix(executors): strip `client_metadata` from forwarded body for Cerebras and Mistral** — Cerebras returns 400 (`wrong_api_format`) and Mistral returns 422 (`extra_forbidden`) when the passthrough body carries `client_metadata` (an OpenAI Codex / Claude CLI field with no equivalent on these upstreams). The default executor now drops it for these two providers before sending downstream; other providers (notably `openai`/`codex`) keep it. (thanks @saurabh321gupta)
+- **fix(codebuddy):** only send reasoning params when the client requests reasoning. (thanks @anki1kr)
+- **fix(sse):** keep streaming for forceStream providers when a JSON client requests it. Providers marked `forceStream:true` reject `stream:false` upstream (HTTP 400); `resolveStreamFlag` now guards against this so stream-only providers keep streaming even when the client sends `Accept: application/json` or `stream:false`. (thanks @anki1kr)
+- **fix(sse):** prevent non-JSON SSE lines and duplicate `[DONE]` from breaking clients. (thanks @qianze0628)
+- **fix(sse):** dedupe case-variant Anthropic headers in the executor `buildHeaders` path — Node/undici's `fetch` merges `anthropic-version` and `Anthropic-Version` into a single `"v, v"` value that the Anthropic API rejects, so both case variants are now collapsed to one canonical lowercase header (same for `anthropic-beta`). (thanks @Delcado19)
+- **oauth(kiro):** support Kiro IDC (organization) token import — when the `~/.aws/sso/cache` token carries a `clientIdHash`, auto-import now reads the linked client registration file to obtain `clientId`/`clientSecret`, probes the Kiro IDE `profile.json` for `profileArn` (ARN region normalized to `us-east-1` for the runtime gateway), and refreshes via the regional AWS OIDC endpoint instead of the social path; the import schema and modal forward these credentials so manual imports also work for IDC tokens. (thanks @enjoyer-hub)
+- **fix(translator):** preserve client `cache_control` breakpoints when routing Claude-format requests (e.g. Claude Code) to Alibaba DashScope's OpenAI-compatible providers (`alibaba` / `alibaba-cn`). The Claude→OpenAI translation previously stripped the markers from the system and message text blocks, so DashScope's explicit caching never engaged and every request was a cache miss. Cache hints now survive when preservation is requested for caching-capable OpenAI-format providers. (thanks @sacrtap)
+- **fix(tts):** resolve Gemini TTS models from catalog and add `gemini-3.1-flash-tts-preview` as the new default Vertex TTS model. (thanks @nguyenha935)
+- **fix(sse): don't cool down a healthy connection on a self-inflicted upstream timeout (504)** — when OmniRoute's own deadline elapses (surfaced as `TimeoutError`/`BodyTimeoutError` → 504), the connection is no longer disabled/failed-over, so a slow-but-healthy provider isn't penalised for our timeout. Genuine upstream 5xx/429 still trigger cooldown; antigravity keeps its own policy. (thanks @costaeder)
+- **fix(translator):** forward image `tool_result` blocks as `image_url` instead of stringifying base64. (thanks @alican532)
+- **fix(sse): robust Anthropic `/v1/messages` streaming — real ping keepalive + client-disconnect guard** — slow first tokens on reasoning models could trip strict clients' idle-read watchdog; the route now keeps the stream warm with a real `event: ping` (Anthropic clients ignore SSE comments) from the very first frame, and a client disconnect (AbortError / controller-closed) no longer counts as a provider failure (no failover/cooldown). (thanks @costaeder)
+- **fix: preserve model hidden flags (`isHidden`) across model sync** — `replaceCustomModels` pruned the compat-override list to the new custom-model ids, silently wiping the `isHidden` flag of eye-hidden SYNCED models on every periodic sync / import (all hidden models turned back on). The redundant cleanup is removed (per-model removal already handles its own compat cleanup), so eye-hidden models stay hidden across re-sync. ([#5086](https://github.com/diegosouzapw/OmniRoute/pull/5086) — thanks @herjarsa)
+- **fix(models): derive model-discovery config from the registry `modelsUrl`** — providers absent from the hardcoded `PROVIDER_MODELS_CONFIG` but carrying a registry `modelsUrl` (e.g. MiniMax) now get an auto-derived Bearer `/v1/models` discovery config, so "discover models" works instead of returning nothing. (thanks @herjarsa)
+- **fix(compression): resolve worker + rule/filter assets via runtime anchors (standalone bundle)** — the LLMLingua worker and the RTK rule/filter loaders relied on `fileURLToPath(import.meta.url)`, which the standalone bundle freezes to the build-machine path, so the worker never spawned and rule/filter packs failed to resolve. They now anchor on `process.cwd()`/`argv[1]` (with `pathToFileURL` for the worker URL). (thanks @fulorgnas)
+- **fix(api): sanitize error responses on seven management routes (Rule #12 hardening)** — `cli-tools/backups`, `cli-tools/guide-settings/[toolId]`, `logs/export`, `models/catalog`, `providers/test-batch`, `settings/import-json` and `usage/proxy-logs` no longer return raw `error.message`; they wrap caught errors in `sanitizeErrorMessage(...)`, and the routes are removed from the `check-error-helper` allowlist. (thanks @JxnLexn)
+- **fix(sse): keep `output_text`-only Responses bodies from being dropped/false-502'd** — some upstreams return a shorthand Responses body whose answer is only in `output_text` with an empty `output[]`. `sanitizeResponsesApiResponse` discarded the text, so the response then tripped the malformed-200 guard. The sanitizer now synthesizes an `output[]` message item from a non-empty `output_text` (complements the Claude-native fix in #5108; both stem from #4942).
+- **fix(executors): preserve a lone caller-supplied `Anthropic-Version` header casing** — the case-variant dedupe (#4846) unconditionally rewrote `Anthropic-Version`/`Anthropic-Beta` to lowercase even when only one variant was present, clobbering the caller's header. Dedupe now runs only when both case variants coexist (the actual undici-merge collision it was meant to fix).
+- **fix(responses):** default `text.format` to `{ type: "text" }` for openai-compatible **responses** providers — some Responses-compatible upstreams (e.g. LM Studio) reject a `text` object missing `text.format` with a 400 `missing_required_parameter`; the default executor now fills the Responses-API default before forwarding (guarded to `openai-compatible-*responses*`, never overwriting an existing format). (thanks @StevanusPangau)
+- **fix(translator): stop stripping client-provided `reasoning_content` for reasoning-replay providers** — the #4849 agentic-context strip (which drops `reasoning_content` from tool-call assistant turns to avoid O(n²) token growth) ran unconditionally, so replay providers (DeepSeek V4, Kimi K2, Qwen-Thinking, etc.) lost the client's reasoning and the reasoning-replay cache then overwrote it with a stale cached value (and such upstreams 400 without the original reasoning). The strip now skips reasoning-replay targets while non-reasoning providers keep the O(n²) protection. ([#5122](https://github.com/diegosouzapw/OmniRoute/pull/5122))
+- **fix(providers): add MiniMax M3 & Nemotron 3 Ultra to the Cline catalog** — the two models were missing from Cline's provider catalog and could not be selected; both are now registered. ([#5136](https://github.com/diegosouzapw/OmniRoute/pull/5136), closes [#3321](https://github.com/diegosouzapw/OmniRoute/issues/3321))
+- **fix(dashboard): key model-visibility toggle on the canonical `providerId`** — the per-model visibility toggle keyed off a display id, so toggling a model on one provider alias could mis-target another; it now keys on the canonical `providerId`. ([#5091](https://github.com/diegosouzapw/OmniRoute/pull/5091) — thanks @Theadd)
+- **fix(diagnostics): recognize the Claude API format in `detectMalformedNonStream`** — salvaged null-guard so a Claude-shaped non-streaming body is no longer misclassified. ([#5141](https://github.com/diegosouzapw/OmniRoute/pull/5141) — thanks @herjarsa / @diegosouzapw)
+- **fix(logging): track the final connection IDs in failover logs** — failover log lines now record the connection that actually served (or last failed) the request, instead of only the first attempt. ([#5016](https://github.com/diegosouzapw/OmniRoute/pull/5016) — thanks @JxnLexn)
+- **fix(sse): ignore disconnect races during in-band stream error handling** — a client disconnect that races with in-band upstream error handling no longer surfaces as a spurious provider failure. ([#5007](https://github.com/diegosouzapw/OmniRoute/pull/5007) — thanks @JxnLexn)
+- **fix(dashboard): surface the server error on `handleToggleCombo` failure** — a failed combo toggle now shows the backend error instead of silently no-op'ing. ([#5138](https://github.com/diegosouzapw/OmniRoute/pull/5138) — thanks @KooshaPari / @diegosouzapw)
+- **fix(quota): track provider quota reset windows + enrich the Codex playground** — observed quota reset windows are tracked and surfaced, and the Codex playground gains the enriched quota metadata. ([#5141](https://github.com/diegosouzapw/OmniRoute/pull/5141) — thanks @Witroch4 / @diegosouzapw)
+- **fix(sidebar): drop the orphan `settings` accent color** — removed a dangling accent-color entry that broke `typecheck:core`. ([#5142](https://github.com/diegosouzapw/OmniRoute/pull/5142))
+- **fix(sse): preserve non-stream reasoning fields for compatible clients** — non-streaming responses now keep the upstream reasoning fields (`reasoning` / `reasoning_content` and OpenRouter/Gemini `reasoning_details`) instead of stripping them in `responseSanitizer`, so clients that render reasoning on buffered responses no longer lose it. ([#5155](https://github.com/diegosouzapw/OmniRoute/pull/5155) — thanks @rdself)
+- **fix(i18n): add missing English UI labels** — fills in untranslated English strings that were surfacing as raw keys in the dashboard. ([#5153](https://github.com/diegosouzapw/OmniRoute/pull/5153) — thanks @rdself)
+
+### 🔒 Security
+
+- **fix(security): exact-host Anthropic `baseUrl` check** — the Anthropic base-URL guard used a substring match that a crafted host could partially satisfy; it now requires an exact host match (resolves CodeQL `js/incomplete-url-substring-sanitization` alert #674). ([#5130](https://github.com/diegosouzapw/OmniRoute/pull/5130))
+
+### 📝 Maintenance
+
+- **refactor(store): remove dead legacy store modules** — salvaged cleanup of unused legacy store code. ([#5138](https://github.com/diegosouzapw/OmniRoute/pull/5138) — thanks @JxnLexn / @diegosouzapw)
+- **test(combo): deterministic routing-decision matrix for all 17 strategies** — a deterministic E2E matrix pins the routing decision of every combo strategy. ([#5146](https://github.com/diegosouzapw/OmniRoute/pull/5146))
+- **chore:** baseline reconciliations (complexity / file-size / cognitive), golden-snapshot + apikey-count alignment for new providers, orphan-test relocation, release base-red repairs, CHANGELOG i18n mirror sync, and an `actions/cache` 5→6 bump. ([#5145](https://github.com/diegosouzapw/OmniRoute/pull/5145), [#5144](https://github.com/diegosouzapw/OmniRoute/pull/5144), [#5125](https://github.com/diegosouzapw/OmniRoute/pull/5125), [#5126](https://github.com/diegosouzapw/OmniRoute/pull/5126), [#5120](https://github.com/diegosouzapw/OmniRoute/pull/5120), [#5117](https://github.com/diegosouzapw/OmniRoute/pull/5117), [#5112](https://github.com/diegosouzapw/OmniRoute/pull/5112))
+- **test:** gated live smoke for combo strategies (in-process + VPS HTTP) and refreshed release expectations to match current code. ([#5151](https://github.com/diegosouzapw/OmniRoute/pull/5151), [#5150](https://github.com/diegosouzapw/OmniRoute/pull/5150) — thanks @KooshaPari / @diegosouzapw)
+
+---
+
+## [3.8.37] — 2026-06-26
+
+### ✨ New Features
+
+- **feat(providers):** add DGrid AI gateway provider — OpenAI-compatible gateway at `api.dgrid.ai/v1` (alias `dgrid`, API-key auth, passthrough models). Free router tier (10 RPM / 100 RPD); a $5 lifetime top-up raises limits to 20 RPM / 1,000 RPD. ([#4931](https://github.com/diegosouzapw/OmniRoute/pull/4931) — thanks @dgridOP)
+
+- **feat(providers):** add Pioneer AI (Fastino Labs) provider — OpenAI-compatible chat completions at `api.pioneer.ai/v1`. Registered with alias `pn`, `X-API-Key` auth, and a catalog of 10 open-tier serverless models (Qwen3, Llama 3.1/3.2, Gemma 3, SmolLM3). Free $75 credits, no credit card required. Gated enterprise models (Claude/GPT/Gemini) require prior fine-tuning on the Pioneer platform and are intentionally excluded from the catalog. ([#4909](https://github.com/diegosouzapw/OmniRoute/pull/4909) — thanks @HikiNarou)
+
+- **feat(providers):** add xAI Grok inbound translators and a thinking patcher — Grok requests are now translated on the inbound path and reasoning is normalized so Grok modes behave consistently across clients. ([#4910](https://github.com/diegosouzapw/OmniRoute/pull/4910) — thanks @mugnimaestra)
+
+- **feat(oauth):** Codex bulk-import endpoint — `POST /api/oauth/codex/import` accepts multiple Codex OAuth credentials in one call for fast multi-account onboarding. ([#4914](https://github.com/diegosouzapw/OmniRoute/pull/4914) — thanks @beaaan)
+
+- **feat(embeddings):** add a `dimensions` override field to embedding combos so an embedding combo can pin the output vector size per target. ([#4913](https://github.com/diegosouzapw/OmniRoute/pull/4913) — thanks @wenzetan)
+
+- **feat(sse):** auto-promote successful combo model — a new opt-in `comboAutoPromoteEnabled` setting reorders a combo's persisted model list so that, when a combo model responds successfully, it is moved to position #1 for future requests. ([#4852](https://github.com/diegosouzapw/OmniRoute/pull/4852) — thanks @arssnndr)
+
+- **feat(sse):** add toggleable tool-source diagnostics — an opt-in switch surfaces where each tool definition originated when debugging tool-routing issues. ([#4856](https://github.com/diegosouzapw/OmniRoute/pull/4856) — thanks @DuyPrX)
+
+- **feat(headroom):** proxy lifecycle management + dashboard UI — start/stop/monitor a Headroom compression proxy from the dashboard, with Docker sidecar support. ([#4649](https://github.com/diegosouzapw/OmniRoute/pull/4649) — thanks @diegosouzapw / @carmelogunsroses)
+
+- **feat(sse):** `x-omniroute-strip-reasoning` request header to drop `reasoning_content` from upstream responses (opt-in, preserving reasoning-aware clients). ([#4678](https://github.com/diegosouzapw/OmniRoute/pull/4678) — thanks @anuragg-saxenaa / @diegosouzapw)
+
+- **feat(cli):** multi-model support for the Factory Droid CLI integration. ([#4682](https://github.com/diegosouzapw/OmniRoute/pull/4682) — thanks @anuragg-saxenaa / @diegosouzapw)
+
+- **feat(sse):** parse Gemini CLI 429 `retryDelay` from the structured `RetryInfo` payload so cooldowns honor the upstream-provided backoff. ([#4738](https://github.com/diegosouzapw/OmniRoute/pull/4738) — thanks @NoxzRCW)
+
+- **feat(sse):** add GPT-4 and GPT-4o mini to the GitHub Copilot provider catalog. ([#4798](https://github.com/diegosouzapw/OmniRoute/pull/4798), [#4797](https://github.com/diegosouzapw/OmniRoute/pull/4797) — thanks @decolua)
+
+- **feat(api):** add the `MiniMax-M3` pricing row (canonical + lowercase alias) so the new MiniMax default model gets accurate per-request cost accounting instead of falling back to a zero/default rate. ([#4814](https://github.com/diegosouzapw/OmniRoute/pull/4814) — thanks @octo-patch)
+
+### 🔧 Bug Fixes
+
+- **fix(sse):** dense, deterministic `response.output` ordering in `response.completed` — items are now sorted by their actual `output_index` (via a recorded-as-emitted accumulator + stable sort) instead of being rebuilt from unordered state dicts; `normalizeOutputIndex` replaces fragile `parseInt` calls for robust index coercion; superseded tool calls (replaced at the same index mid-stream) are excluded from the final output array. ([#4906](https://github.com/diegosouzapw/OmniRoute/pull/4906) — thanks @Marco9113)
+
+- **fix(sse):** normalize Codex custom/freeform tools (`apply_patch`, `type:"custom"` with no `parameters`) to a `{ input: string }` function schema instead of an empty schema — the empty schema made models invoke `apply_patch` with `{}`, breaking the Codex runtime which expects `{ input: string }`. Also maps `custom_tool_call` / `custom_tool_call_output` input items and streams `apply_patch` tool calls via `custom_tool_call_input.delta`/`.done` events. ([#4862](https://github.com/diegosouzapw/OmniRoute/pull/4862) — thanks @nstung463)
+
+- **fix(sse):** preserve the `required` array when translating Draft 2020-12 antigravity tool schemas (e.g. from OpenCode), stripping unsupported JSON Schema meta keywords while keeping mandatory arguments required so the model no longer calls tools without them. ([#4843](https://github.com/diegosouzapw/OmniRoute/pull/4843) — thanks @anuragg-saxenaa)
+
+- **fix(sse):** Kiro tool-schema sanitizer — strip unsupported JSON-Schema keywords (`anyOf`/`$ref`/`if`-`then`, etc.) and hash-truncate tool names >64 chars before dispatch, mapping the streamed tool-call name back for the client, so Kiro no longer rejects tool calls with `400 "Improperly formed request"`. ([#4847](https://github.com/diegosouzapw/OmniRoute/pull/4847) — thanks @smarthomeblack)
+
+- **fix(sse):** make the `anthropic-version` default-guard case-insensitive for `anthropic-compatible-*` providers, so a caller/operator-supplied `Anthropic-Version` (any casing) is no longer clobbered by a second lowercase `anthropic-version: 2023-06-01` header. ([#4823](https://github.com/diegosouzapw/OmniRoute/pull/4823) — thanks @zakirkun)
+
+- **fix(db):** validate HuggingFace API tokens via the `whoami-v2` endpoint as a pure auth probe so fine-grained Inference-Provider tokens (valid even when model/task endpoints reject them) are no longer falsely marked invalid; only 401/403 means an invalid key, other non-OK statuses surface as transient upstream errors. ([#4819](https://github.com/diegosouzapw/OmniRoute/pull/4819) — thanks @Delcado19)
+
+- **fix(sse):** reject the Anthropic-only `[1m]` context-1m suffix in `buildKiroPayload` before it reaches AWS Bedrock — Kiro is Bedrock-backed and cannot honor the beta, so a forwarded `kr/*[1m]` model id was malformed upstream; callers now get a clear error pointing them at a direct-Anthropic provider for 1M-context routing. ([#4816](https://github.com/diegosouzapw/OmniRoute/pull/4816) — thanks @Delcado19)
+
+- **fix(dashboard):** align the Engine Combos editor engines with the API schema — the named-combos pipeline dropdown offered four engines (`headroom`, `session-dedup`, `ccr`, `llmlingua`) that `PUT /api/context/combos/[id]` rejects, so selecting one made the save return 400 while the UI swallowed the error. The dropdown is now sourced from a single canonical engine map shared with `stackedPipelineStepSchema` (parity guarded by a unit test), and the editor surfaces save errors plus empty-name/empty-pipeline validation instead of failing quietly. ([#5062](https://github.com/diegosouzapw/OmniRoute/pull/5062) — closes #4955)
+
+- **fix(sse):** surface malformed HTTP-200 upstream responses instead of treating them as success, so combo fallback can trigger. ([#4942](https://github.com/diegosouzapw/OmniRoute/pull/4942) — thanks @haipham22)
+
+- **fix(antigravity):** retry transient upstream failures rather than failing the request outright. ([#4941](https://github.com/diegosouzapw/OmniRoute/pull/4941) — thanks @Jordannst)
+
+- **fix(sse):** exclude WS-bridge controller-closed errors from the provider circuit breaker so a client disconnect no longer trips the whole provider. ([#4870](https://github.com/diegosouzapw/OmniRoute/pull/4870) — closes #4602, thanks @huohua-dev)
+
+- **fix(sse):** resolve custom combos by id and case-insensitive name. ([#4869](https://github.com/diegosouzapw/OmniRoute/pull/4869) — closes #4446, thanks @herjarsa)
+
+- **fix(sse):** forward AI SDK image parts in the Responses translator. ([#4859](https://github.com/diegosouzapw/OmniRoute/pull/4859) — thanks @mugnimaestra)
+
+- **fix(sse):** emit valid concatenable Kiro `tool_calls.arguments` deltas. ([#4855](https://github.com/diegosouzapw/OmniRoute/pull/4855) — thanks @wahyuzero)
+
+- **fix(sse):** strip `temperature` for Claude models with extended thinking enabled (the upstream rejects it). ([#4853](https://github.com/diegosouzapw/OmniRoute/pull/4853) — thanks @noestelar)
+
+- **fix(sse):** unwrap the Qoder HTTP-200 SSE error envelope so combo fallback can trigger. ([#4850](https://github.com/diegosouzapw/OmniRoute/pull/4850) — thanks @vianlearns)
+
+- **fix(sse):** strip reasoning blobs from agentic context to prevent O(n²) token growth across multi-turn agent loops. ([#4849](https://github.com/diegosouzapw/OmniRoute/pull/4849) — thanks @GodrezJr2)
+
+- **fix(sse):** close the reasoning block before message content in the Responses stream so clients render reasoning and answer in the right order. ([#4848](https://github.com/diegosouzapw/OmniRoute/pull/4848) — thanks @kwanLeeFrmVi)
+
+- **fix(config):** sync the full SiliconFlow model list into the registry. ([#4844](https://github.com/diegosouzapw/OmniRoute/pull/4844) — thanks @letanphuc)
+
+- **fix(sse):** strip Composer `<｜final｜>` sentinel markers that leaked after Composer reasoning. ([#4842](https://github.com/diegosouzapw/OmniRoute/pull/4842) — thanks @noestelar)
+
+- **fix(build):** trace-include `sql.js`'s `sql-wasm.wasm` in the standalone bundle so SQLite-WASM works in the packaged build. ([#4839](https://github.com/diegosouzapw/OmniRoute/pull/4839) — thanks @Delcado19)
+
+- **fix(cli):** persist lazily-installed native runtime deps (`better-sqlite3`, `systray2`) to the shared runtime `package.json` with `--save-exact` instead of `--no-save`, so installing one no longer prunes the other as "extraneous" — fixing a "No SQLite driver available" failure after a `--tray` install. ([#4841](https://github.com/diegosouzapw/OmniRoute/pull/4841) — thanks @omartuhintvs)
+
+- **fix(sse):** resolve bare model names to a connection's `defaultModel` before upstream calls. ([#4825](https://github.com/diegosouzapw/OmniRoute/pull/4825) — thanks @anuragg-saxenaa)
+
+- **fix(api):** surface a Docker-localhost hint on provider-node validation connection errors. ([#4822](https://github.com/diegosouzapw/OmniRoute/pull/4822) — thanks @anuragg-saxenaa)
+
+- **fix(sse):** strip Gemini built-in tools when `functionDeclarations` are present in the Antigravity envelope (the two are mutually exclusive upstream). ([#4821](https://github.com/diegosouzapw/OmniRoute/pull/4821) — thanks @vanszs)
+
+- **fix(sse):** strip `X-Stainless-*` headers and normalize the SDK `User-Agent` for OpenAI-compatible endpoints. ([#4820](https://github.com/diegosouzapw/OmniRoute/pull/4820) — thanks @anuragg-saxenaa)
+
+- **fix(oauth):** allow a per-connection refresh lead-time override via `providerSpecificData.refreshLeadMs`. ([#4818](https://github.com/diegosouzapw/OmniRoute/pull/4818) — thanks @anuragg-saxenaa)
+
+- **fix(dashboard):** resolve passthrough model aliases by `providerId` in `ModelSelectModal`. ([#4815](https://github.com/diegosouzapw/OmniRoute/pull/4815) — thanks @anuragg-saxenaa)
+
+- **fix(sse):** strip `enumDescriptions` from Antigravity tool schemas. ([#4813](https://github.com/diegosouzapw/OmniRoute/pull/4813), [#4740](https://github.com/diegosouzapw/OmniRoute/pull/4740) — thanks @anuragg-saxenaa)
+
+- **fix(dashboard):** keep the desktop sidebar visible via an explicit CSS class. ([#4812](https://github.com/diegosouzapw/OmniRoute/pull/4812) — thanks @Delcado19)
+
+- **fix(sse):** filter nameless hosted tools when converting Responses API to Chat format. ([#4789](https://github.com/diegosouzapw/OmniRoute/pull/4789) — upstream, thanks Владимир Акимов)
+
+- **fix(sse):** stream-writer mock `abort()` now returns a Promise (test-stability fix). ([#4788](https://github.com/diegosouzapw/OmniRoute/pull/4788) — thanks @decolua)
+
+- **fix(sse):** use the WorkOS auth-token shape for Cline. ([#4787](https://github.com/diegosouzapw/OmniRoute/pull/4787) — thanks @apeltekci)
+
+- **fix(api):** fall back to the existing access token for any OAuth provider when a refresh fails. ([#4786](https://github.com/diegosouzapw/OmniRoute/pull/4786) — thanks @decolua)
+
+- **fix(sse):** read Antigravity usage from the `response.usageMetadata` envelope. ([#4785](https://github.com/diegosouzapw/OmniRoute/pull/4785) — thanks @decolua)
+
+- **fix(oauth):** verify Cursor installation on Linux before auto-import. ([#4770](https://github.com/diegosouzapw/OmniRoute/pull/4770) — upstream, thanks Ibrahim Ryan)
+
+- **fix(cli):** fall back to the default data dir when `DATA_DIR` is not writable. ([#4767](https://github.com/diegosouzapw/OmniRoute/pull/4767) — upstream, thanks Thiên Toán)
+
+- **fix(sse):** `json_schema` fallback for OpenAI-compatible providers that don't support structured outputs. ([#4766](https://github.com/diegosouzapw/OmniRoute/pull/4766) — thanks @mustafabozkaya)
+
+- **fix(cli):** verify launchd registration and skip self-SIGTERM in macOS autostart. ([#4765](https://github.com/diegosouzapw/OmniRoute/pull/4765) — thanks @ntdung6868)
+
+- **fix(sse):** finalize the `tool_calls` `finish_reason` on early stream end in the OpenAI Responses translator. ([#4764](https://github.com/diegosouzapw/OmniRoute/pull/4764) — thanks @decolua)
+
+- **fix(sse):** gate Kiro image attachments behind a Claude-capability check. ([#4763](https://github.com/diegosouzapw/OmniRoute/pull/4763) — thanks @decolua)
+
+- **fix(sse):** track Ollama streaming usage from raw NDJSON chunks. ([#4754](https://github.com/diegosouzapw/OmniRoute/pull/4754) — thanks @fresent)
+
+- **fix(sse):** include low-level cause details in `formatProviderError`. ([#4741](https://github.com/diegosouzapw/OmniRoute/pull/4741) — thanks @decolua)
+
+- **fix(executors):** `anthropic-compatible-*` gateways now get a `Bearer` token alongside `x-api-key`. ([#4729](https://github.com/diegosouzapw/OmniRoute/pull/4729) — thanks @hodtien)
+
+- **fix(translator):** strip the `x-anthropic-billing-header` in the claude-to-openai path. ([#4728](https://github.com/diegosouzapw/OmniRoute/pull/4728) — thanks @weimaozhen)
+
+- **fix(translator):** preserve `reasoning_effort` for non-Copilot Responses clients. ([#4688](https://github.com/diegosouzapw/OmniRoute/pull/4688) — thanks @ryanngit / @diegosouzapw)
+
+- **fix(codex):** treat an OAuth 401 as an unrecoverable refresh failure (stop retrying a dead token). ([#4686](https://github.com/diegosouzapw/OmniRoute/pull/4686) — thanks @sacwooky / @diegosouzapw)
+
+- **fix(translator):** coerce tool descriptions to strings in OpenAI normalization. ([#4675](https://github.com/diegosouzapw/OmniRoute/pull/4675) — thanks @East-rayyy / @diegosouzapw)
+
+- **fix(dashboard):** stop double-masking an already-masked API key in the list view (E2E 3/9 regression). ([#4671](https://github.com/diegosouzapw/OmniRoute/pull/4671) — thanks @diegosouzapw)
+
+- **fix(combo):** flatten Anthropic tool messages + tool history to prevent an upstream 503. ([#4648](https://github.com/diegosouzapw/OmniRoute/pull/4648) — thanks @warelik / @diegosouzapw)
+
+- **fix(providers):** require a Default Model in the compatible-provider API-key setup flow. ([#4641](https://github.com/diegosouzapw/OmniRoute/pull/4641) — thanks @arden1601)
+
+### 🔒 Security
+
+- **fix(auth):** only trust forwarding headers (`X-Forwarded-For` / `X-Real-IP`) from loopback TCP peers, so a non-loopback client can't spoof its origin to bypass local-only route guards. ([#4689](https://github.com/diegosouzapw/OmniRoute/pull/4689) — thanks @Jordannst / @diegosouzapw)
+
+- **fix(sse):** redact the API key from the AUTH debug log in the chat handler. ([#4858](https://github.com/diegosouzapw/OmniRoute/pull/4858) — thanks @sacwooky)
+
+- **fix(oauth):** classify `/api/oauth/cursor/auto-import` as a local-only route in the route guard, so the loopback-enforced process-spawning endpoint can't be reached through a tunneled/leaked JWT (Hard Rule #17). ([#5070](https://github.com/diegosouzapw/OmniRoute/pull/5070) — thanks @diegosouzapw)
+
+### 📝 Maintenance
+
+- **chore(ci):** harden the release flow — decouple the Quality Ratchet from coverage-shard flakes (`if: !cancelled()` + `--allow-missing`), add fast-path drift gates (`check:complexity`, `check:cognitive-complexity`, `check:pack-policy`, `check:build-scope`), and raise the default build heap to 8 GB. ([#5054](https://github.com/diegosouzapw/OmniRoute/pull/5054) — thanks @diegosouzapw)
+
+- **docs(routing):** sync the combo strategy docs for Fusion (17 strategies). ([#5067](https://github.com/diegosouzapw/OmniRoute/pull/5067) — thanks @diegosouzapw)
+
+- **test(sse):** golden-lock the `provider.ts` translate-path across all providers. ([#4734](https://github.com/diegosouzapw/OmniRoute/pull/4734) — thanks @diegosouzapw / @decolua)
+
+- **docs(env):** document `HEADROOM_URL` in `.env.example` + `ENVIRONMENT.md`. (thanks @diegosouzapw)
+
+- **chore(quality):** rebaseline the file-size ratchet across the rc17 PR-batch levas (leva2/leva3/leva4) to absorb cycle drift. (thanks @diegosouzapw)
+
+---
+
+## [3.8.36] — 2026-06-25
+
+### ✨ New Features
+
+**Quota-Share system**
+
+- **feat(quota):** introduce a dedicated `quota-share` combo strategy (Fase 3 #9) — Deficit Round Robin scheduling with per-model in-flight gating (P2C), automatic DB migration that promotes existing `qtSd/*` combos, and per-policy gating so invalid allocations cannot bleed `allow` to unintended connections. ([#4939](https://github.com/diegosouzapw/OmniRoute/pull/4939), [#4901](https://github.com/diegosouzapw/OmniRoute/pull/4901))
+- **feat(quota):** multi-window usage buckets, per-(key,model) caps, and session stickiness — connections now track consumption across 5 h, 7 d, and per-model windows; `quota_allocation_model_caps` enforces per-key/model limits; session stickiness preserves prompt-cache integrity across turns. ([#4928](https://github.com/diegosouzapw/OmniRoute/pull/4928), [#4927](https://github.com/diegosouzapw/OmniRoute/pull/4927), [#4929](https://github.com/diegosouzapw/OmniRoute/pull/4929))
+- **feat(quota):** headroom strategy + proactive saturation — new `headroom` combo strategy selects connections by available quota margin; universal proactive saturation via upstream token-usage response headers; real Claude quota saturation sourced from `/api/oauth/usage`. ([#4908](https://github.com/diegosouzapw/OmniRoute/pull/4908), [#4907](https://github.com/diegosouzapw/OmniRoute/pull/4907), [#4885](https://github.com/diegosouzapw/OmniRoute/pull/4885))
+- **feat(quota):** concurrency control + cooldown-wait (Fase 2.1) — `max_concurrent` is enforced at dispatch time; quota-share combos queue concurrent requests with a short cooldown-wait and re-dispatch on slot availability (Variant A); a cron heal proactively restores connections after their window resets. ([#4965](https://github.com/diegosouzapw/OmniRoute/pull/4965), [#4970](https://github.com/diegosouzapw/OmniRoute/pull/4970), [#4967](https://github.com/diegosouzapw/OmniRoute/pull/4967), [#4900](https://github.com/diegosouzapw/OmniRoute/pull/4900))
+
+**Combo routing**
+
+- **feat(combo):** task-aware routing strategy — routes requests to the best-fit connection based on task-type metadata, enabling per-task provider specialization within a combo. ([#4945](https://github.com/diegosouzapw/OmniRoute/pull/4945))
+- **feat(combo):** Fusion strategy (16th strategy) — fan out to a configurable panel of models in parallel, then synthesize results through a judge model. ([#4652](https://github.com/diegosouzapw/OmniRoute/pull/4652))
+- **feat(combos):** add an editable per-combo `description` field. The routing-combo form now has a Description input, persisted in the combo `data` blob via `/api/combos` (POST/PUT) and round-tripped through GET — no new DB column. ([#5005](https://github.com/diegosouzapw/OmniRoute/issues/5005))
+- **feat(routing):** honor `X-Route-Model` request header to override `body.model`, enabling per-request model switching without modifying the request body. ([#4863](https://github.com/diegosouzapw/OmniRoute/pull/4863) — thanks @costaeder)
+
+**Providers & models**
+
+- **feat(providers):** update volcengine-ark model list, adding DeepSeek-V4-Flash and DeepSeek-V4-Pro. ([#4905](https://github.com/diegosouzapw/OmniRoute/pull/4905) — thanks @kenlin8827)
+- **feat(provider):** add CodeBuddy CN (`copilot.tencent.com`) — full OAuth + executor + model catalog stack. ([#4664](https://github.com/diegosouzapw/OmniRoute/pull/4664))
+- **feat(opencode-go):** advertise `glm-5.2` and `kimi-k2.7-code` to align with official Go endpoints. ([#4711](https://github.com/diegosouzapw/OmniRoute/pull/4711))
+- **feat(sse):** add Google Flow video-generation provider. ([#4769](https://github.com/diegosouzapw/OmniRoute/pull/4769))
+- **feat(api/v1):** include alias-backed models in the `/v1/models` listing. ([#4630](https://github.com/diegosouzapw/OmniRoute/pull/4630))
+
+**Proxy pool**
+
+- **feat(proxy-pool):** Cloudflare Workers proxy deployer + pool integration — deploy Cloudflare Workers relays directly from the dashboard and register them in the proxy pool. ([#4640](https://github.com/diegosouzapw/OmniRoute/pull/4640))
+- **feat(proxy-pool):** Deno Deploy relays + group action buttons — deploy Deno Deploy relay workers and manage proxy groups with new bulk-action controls. ([#4643](https://github.com/diegosouzapw/OmniRoute/pull/4643))
+
+**Compression & infrastructure**
+
+- **feat(compression):** Kiro/CodeWhisperer tool-result compression engine — dedicated compressor for Kiro/CodeWhisperer tool outputs integrated into the streaming pipeline. ([#4635](https://github.com/diegosouzapw/OmniRoute/pull/4635))
+- **feat(endpoint):** per-endpoint custom system prompt injection. A toggle + text field in the Endpoint settings card lets users inject a custom system prompt into every model request, applied via the existing system-prompt engine. Stored in settings DB. ([#5022](https://github.com/diegosouzapw/OmniRoute/pull/5022) — thanks @whale9820)
+- **feat(live-ws):** allow non-loopback clients via `LIVE_WS_ALLOWED_HOSTS` env var, enabling multi-host setups to access the live WebSocket API. ([#4877](https://github.com/diegosouzapw/OmniRoute/pull/4877) — thanks @KooshaPari)
+- **feat(db):** track API endpoint dimension on `usage_history` for per-endpoint cost and usage analytics. ([#4676](https://github.com/diegosouzapw/OmniRoute/pull/4676))
+
+---
+
+### 🔧 Bug Fixes
+
+**Translator**
+
+- **fix(translator):** regroup parallel tool results to be adjacent to their originating assistant turn, fixing tool-message ordering for providers that require strict interleaving. ([#4882](https://github.com/diegosouzapw/OmniRoute/pull/4882))
+- **fix(translator):** preserve literal empty-string tool arguments in OpenAI-to-Claude streaming — they were previously dropped, causing tool calls to arrive with missing parameters. ([#4959](https://github.com/diegosouzapw/OmniRoute/pull/4959))
+- **fix(translator):** normalize tools to Anthropic-native shape for non-Anthropic providers, ensuring tool definitions pass validation regardless of the format at the call site. ([#4650](https://github.com/diegosouzapw/OmniRoute/pull/4650))
+- **fix(translator):** provider thinking compatibility — correct thinking-block serialization for DeepSeek and Gemini providers. ([#4946](https://github.com/diegosouzapw/OmniRoute/pull/4946))
+- **fix(translator):** emit `</think>` close marker for Anthropic thinking blocks, fixing truncated reasoning output in streamed responses. ([#4633](https://github.com/diegosouzapw/OmniRoute/pull/4633))
+- **fix(translator):** normalize `developer` role to `system` for OpenAI-format providers. ([#4625](https://github.com/diegosouzapw/OmniRoute/pull/4625))
+- **fix(translator):** strip top-level `client_metadata` on the OpenAI passthrough path (port from 9router#1157). ([#4624](https://github.com/diegosouzapw/OmniRoute/pull/4624))
+- **fix(translator):** replay `reasoning_content` on plain Xiaomi MiMo turns (port from 9router#1321). ([#4639](https://github.com/diegosouzapw/OmniRoute/pull/4639))
+
+**Copilot / GitHub executor**
+
+- **fix(copilot):** never route Gemini/Claude model variants to the `/responses` endpoint — these models require the chat-completions path only. ([#4627](https://github.com/diegosouzapw/OmniRoute/pull/4627))
+- **fix(github):** route Copilot Codex models to `/responses` (port from 9router#102). ([#4626](https://github.com/diegosouzapw/OmniRoute/pull/4626))
+- **fix(copilot,antigravity):** cap `maxOutputTokens` at 16384 to stop "Invalid Argument" 400 errors on high-token requests. ([#4636](https://github.com/diegosouzapw/OmniRoute/pull/4636))
+- **fix(codex):** drop non-standard `codex.*` streaming events that break `responses.stream` consumers. ([#4715](https://github.com/diegosouzapw/OmniRoute/pull/4715) — thanks @jeffer1312)
+
+**Claude / Anthropic**
+
+- **fix(claude):** omit `adaptive_thinking` and `output_config.effort` for Haiku model variants, which reject those parameters. ([#4661](https://github.com/diegosouzapw/OmniRoute/pull/4661))
+- **fix(claude):** skip `mcp__` tool-name cloaking and guard against missing `connectionId` to prevent crashes on Claude-native MCP tool calls. ([#4861](https://github.com/diegosouzapw/OmniRoute/pull/4861) — thanks @costaeder)
+- **fix(claude-oauth):** respect `429` backoff headers on the Claude OAuth usage endpoint to reduce polling spam during quota checks. ([#4655](https://github.com/diegosouzapw/OmniRoute/pull/4655))
+
+**Routing & SSE**
+
+- **fix(sse):** fail over on `400` responses that carry rate-limit text in the body, not just on canonical `429` status codes. ([#4986](https://github.com/diegosouzapw/OmniRoute/pull/4986))
+- **fix(sse):** honor per-account proxy and fingerprint-rotation settings in the opencode executor. ([#4989](https://github.com/diegosouzapw/OmniRoute/pull/4989))
+- **fix(sse):** soft-penalize exhausted providers in auto-combo scoring instead of hard-excluding them, improving fallback resilience. ([#4990](https://github.com/diegosouzapw/OmniRoute/pull/4990))
+- **fix(sse):** drop the CCP pin when the pinned provider is durably unhealthy, with anti-flap logic to prevent oscillation. ([#4864](https://github.com/diegosouzapw/OmniRoute/pull/4864) — thanks @costaeder)
+- **fix(combo):** fetch models dynamically from custom provider endpoints instead of relying on a static list. ([#4860](https://github.com/diegosouzapw/OmniRoute/pull/4860))
+- **fix(combo):** propagate the selected connection ID to fallback error responses so model lockout applies to the correct connection rather than the wrong fallback target. ([#4809](https://github.com/diegosouzapw/OmniRoute/pull/4809) — thanks @Chewji9875)
+- **fix(sse):** skip third-party tool-name cloaking for Anthropic-native server tools to prevent naming conflicts. ([#4808](https://github.com/diegosouzapw/OmniRoute/pull/4808) — thanks @NomenAK)
+
+**Quota**
+
+- **fix(quota):** quota-exclusive `qtSd/*` connections now appear in `/v1/models` listings; EPSILON-threshold check no longer falsely blocks under-budget allocations. ([#4830](https://github.com/diegosouzapw/OmniRoute/pull/4830))
+- **fix(quota):** migration 107 correctly activates the `quota-share` strategy on existing `qtSd/*` combos. ([#4962](https://github.com/diegosouzapw/OmniRoute/pull/4962))
+
+**API / responses**
+
+- **fix(api):** parse the `/v1/responses` request body once instead of 3–4 times on the hot path, reducing per-request overhead. ([#4958](https://github.com/diegosouzapw/OmniRoute/pull/4958))
+- **fix(api):** evict stale in-memory rate-limit windows to stop a slow heap leak on long-running instances. ([#4957](https://github.com/diegosouzapw/OmniRoute/pull/4957))
+- **fix(api):** require authentication on the compression `run-telemetry` endpoint; document `OMNIROUTE_EVAL_CREDENTIALS` env var. ([#4796](https://github.com/diegosouzapw/OmniRoute/pull/4796))
+- **fix(api):** stop `GET /api/system/env/repair` returning HTTP `500` on packaged installs (it broke the onboarding wizard). `createRequire(import.meta.url)` ran at module top-level; once webpack bundles the route into the standalone build, `import.meta.url` is frozen to the build-machine path and `createRequire` throws during evaluation, so the whole route failed to load. `createRequire` is now resolved lazily inside the guarded `better-sqlite3` block, root-dir resolution falls back to `process.cwd()`, and the route passes an explicit `rootDir`. ([#5028](https://github.com/diegosouzapw/OmniRoute/pull/5028))
+
+**Dashboard**
+
+- **fix(dashboard):** show custom provider given-name instead of internal id across dashboard pages — cache, combo health, compression analytics, cost overview, health/autopilot, provider stats, route explainability, provider utilization, runtime. Adds shared `resolveProviderName` resolver and `useProviderNodeMap` hook. (#4603)
+- **fix(dashboard):** on OAuth providers (e.g. GLM Coding), "Test all models" with auto-hide-failed now switches the model list to the "visible" filter after the run, so just-hidden failed models actually disappear on-screen — parity with the passthrough-provider path (#3610). Previously they were hidden in the DB but stayed visible under the "All" filter, so it looked like nothing was hidden. (#4887)
+- **fix(dashboard):** restore the home-page provider topology card that was hidden by a default state change in #4596. ([#4963](https://github.com/diegosouzapw/OmniRoute/pull/4963))
+- **fix(dashboard):** proxy-pool success gating, sync-timestamp persistence, and opt-in Redis backend. ([#4988](https://github.com/diegosouzapw/OmniRoute/pull/4988))
+- **fix(dashboard):** show custom vision models in the LLM selector dropdown. ([#4653](https://github.com/diegosouzapw/OmniRoute/pull/4653))
+
+**Providers**
+
+- **fix(pollinations):** stop forcing `jsonMode` on every request. Pollinations treats `jsonMode=true` as "the model MUST return JSON" and rejects (HTTP 400 "messages must contain the word 'json'") any normal chat request whose messages don't mention "json", so all non-JSON chat was broken. `jsonMode` is now only enabled when the caller actually requests JSON output (`response_format.type` of `json_object` or `json_schema`). (#3981)
+- **fix(antigravity):** default `safetySettings` to all-OFF for parity with the native Gemini paths. The Antigravity (Google Cloud Code) request builder set `safetySettings: undefined`, which `JSON.stringify` drops — so no safety settings reached Google and its server-side defaults false-flagged benign technical prompts as `prohibited_content` (HTTP 200 + blocked body, which combo failover treats as terminal). Now honors a caller-supplied value and otherwise defaults to `DEFAULT_SAFETY_SETTINGS`, matching the claude-to-gemini / openai-to-gemini paths. (#5003)
+- **fix(antigravity):** exclude the standard Gemini rate-limit message from quota-exhaustion keyword matching to prevent false-positive saturation flags. ([#4810](https://github.com/diegosouzapw/OmniRoute/pull/4810) — thanks @Chewji9875)
+- **fix(chatgpt-web):** map the advertised `gpt-5.5`, `gpt-5.5-pro`, `gpt-5.4-pro` and `gpt-5.2-pro` catalog ids to their dash-form ChatGPT backend slugs. They were missing from `MODEL_MAP`, so the executor sent the dot-form id verbatim, which the ChatGPT backend silently ignored and served the default Plus model instead of the requested one. Adds a drift guard asserting no advertised dot-form id reaches the backend verbatim. (#4665)
+- **fix(gemini):** preserve the `pattern` field in the Antigravity tool schema sanitizer to avoid stripping valid regex constraints from tool definitions. ([#4651](https://github.com/diegosouzapw/OmniRoute/pull/4651))
+- **fix(opencode):** preserve DeepSeek reasoning content in streamed responses. ([#4631](https://github.com/diegosouzapw/OmniRoute/pull/4631))
+- **fix(perplexity):** validate API keys via the `/v1/models` endpoint instead of issuing a full chat request. ([#4654](https://github.com/diegosouzapw/OmniRoute/pull/4654))
+- **fix(qoder):** exchange PAT for `jt-*` job token before initiating Cosy chat, fixing auth failures after the Qoder credential format change. ([#4884](https://github.com/diegosouzapw/OmniRoute/pull/4884))
+- **fix(executors):** strip parameters unsupported by the target provider/model to prevent `400 Invalid parameter` errors on strict endpoints. ([#4658](https://github.com/diegosouzapw/OmniRoute/pull/4658))
+- **fix(executors):** preserve literal `reasoning_effort: "max"` for Ollama Cloud instead of normalizing to `xhigh`. Ollama Cloud accepts `high|medium|low|max|none` and rejects `xhigh` (`invalid reasoning value: 'xhigh'`); OpenRouter DeepSeek `max→xhigh` normalization is unaffected. ([#4993](https://github.com/diegosouzapw/OmniRoute/pull/4993) — thanks @Thinkscape)
+- **fix(headroom):** translate openai-responses input through OpenAI for external compression. `adaptBodyForCompression` now serialises `function_call_output` items whose `output` field is a JSON object (not a string) so compression engines can process the content — previously those items were excluded from compression because `hasTextContent()` returned false for object values. ([#5023](https://github.com/diegosouzapw/OmniRoute/pull/5023) — thanks @anki1kr)
+- **fix(proxy):** fan out direct dispatcher streams to all registered proxy endpoints. ([#4803](https://github.com/diegosouzapw/OmniRoute/pull/4803) — thanks @makcimbx)
+
+**Compression**
+
+- **fix(compression):** eliminate ReDoS in the `math_inline` preservation regex — the previous pattern could catastrophically backtrack on untrusted input. ([#4838](https://github.com/diegosouzapw/OmniRoute/pull/4838))
+- **fix(compression):** stop RTK over-truncating file-read tool results — RTK now respects the full content length for file-read outputs. ([#4987](https://github.com/diegosouzapw/OmniRoute/pull/4987))
+
+**Build / CLI / infrastructure**
+
+- **fix(build):** drop `@omniroute/open-sse` from `optimizePackageImports` to fix the Next.js build OOM crash. ([#4968](https://github.com/diegosouzapw/OmniRoute/pull/4968))
+- **fix(cli):** SIGKILL the systray child PID before closing the IPC channel to prevent macOS NSStatusItem orphan processes. ([#4732](https://github.com/diegosouzapw/OmniRoute/pull/4732))
+- **fix(cli):** bump `better-sqlite3` runtime pin to 12.10.1 for Node 26 compatibility. ([#4685](https://github.com/diegosouzapw/OmniRoute/pull/4685))
+- **fix(cli):** harden the systray2 tray runtime (port from 9router#1080). ([#4628](https://github.com/diegosouzapw/OmniRoute/pull/4628))
+- **fix(cli-tools):** tolerate JSONC (comments and trailing commas) in tool settings files. ([#4659](https://github.com/diegosouzapw/OmniRoute/pull/4659))
+- **fix(install):** make the `transformers` dependency optional so CUDA-host installs that lack Python bindings succeed. ([#4807](https://github.com/diegosouzapw/OmniRoute/pull/4807) — thanks @megamen32)
+- **fix(db):** correct storage tuning settings to prevent WAL runaway on high-write workloads. ([#4834](https://github.com/diegosouzapw/OmniRoute/pull/4834) — thanks @rdself)
+- **fix(image):** prevent compatible nodes from shadowing provider aliases in the image routing table. ([#4656](https://github.com/diegosouzapw/OmniRoute/pull/4656))
+
+**Plugin**
+
+- **fix(plugin):** opencode `auth.json` dual-key fallback for the auto-prefix migration. The config hook now looks up both the prefixed (`opencode-omniroute`) and bare (`omniroute`) keys, so users who authenticated before the `opencode-` prefix landed no longer need to re-auth. ([#5027](https://github.com/diegosouzapw/OmniRoute/pull/5027) — thanks @herjarsa)
+
+---
+
+### 🔒 Security
+
+- **fix(security):** block SSRF allowlist bypass via `x-relay-path` header manipulation on Deno/Vercel relays. ([#4899](https://github.com/diegosouzapw/OmniRoute/pull/4899))
+- **fix(security):** pin image-fetch DNS resolution to prevent SSRF DNS-rebinding attacks (GHSA-cmhj-wh2f-9cgx). ([#4634](https://github.com/diegosouzapw/OmniRoute/pull/4634))
+- **fix(security):** do not trust the loopback socket as local-only when the server is behind a reverse proxy, closing a potential auth bypass path. ([#4632](https://github.com/diegosouzapw/OmniRoute/pull/4632))
+- **fix(security):** validate the Kiro region parameter to prevent SSRF via crafted region strings (GHSA-6mwv-4mrm-5p3m). ([#4629](https://github.com/diegosouzapw/OmniRoute/pull/4629))
+- **fix(copilot):** replace `execSync` shell interpolation with `execFile` in the `runOmniRouteCli` tool to prevent command injection. The user-supplied command is now split into an argv array and passed to `execFile` (no shell), so shell metacharacters are treated as literal text; error output is routed through `sanitizeErrorMessage()`. ([#5024](https://github.com/diegosouzapw/OmniRoute/pull/5024) — thanks @hamsa0x7)
+- **fix(db):** replace `Math.random` with `crypto.randomUUID` for database ID generation, removing a non-cryptographic source of collision/predictability in generated identifiers. ([#5026](https://github.com/diegosouzapw/OmniRoute/pull/5026) — thanks @hamsa0x7)
+
+---
+
+### 📝 Maintenance
+
+**God-file decomposition (continued, #3501)**
+
+- **refactor(chatCore):** extracted 12 focused helpers from `chatCore.ts` covering the streaming pipeline (`assembleStreamingPipeline`), cache-store logic (`storeStreamingSemanticCacheResponse`, `storeSemanticCacheResponse`), response headers (`assembleStreamingResponseHeaders`, `buildNonStreamingResponseHeaders`), JSON→SSE bridge (`maybeConvertJsonBodyToSse`), guardrail context (`buildPostCallGuardrailContext`), usage buffer (`applyClientUsageBuffer`), plugin hook (`runPluginOnRequestHook`), analytics (`writeCompressionAnalytics`, `emitOutputStyleTelemetry`), and compression predicates/settings (`resolveCompressionSettings`, et al.). ([#4811](https://github.com/diegosouzapw/OmniRoute/pull/4811)–[#4837](https://github.com/diegosouzapw/OmniRoute/pull/4837))
+- **refactor(sse/db/api):** continued decomposition of `services/usage.ts` (extracted quota-core, scalar/format helpers, Antigravity/GLM/MiniMax usage families), `db/core.ts` (schema-column reconciliation, snake↔camel column-mapping), `db/apiKeys.ts` (row-parsers, model-permission matching), and `validation.ts` (URL/headers/transport leaf layer, web-cookie/Meta-AI validators, enterprise-cloud + probe, audio/speech/apikey, search/embedding/rerank, and OpenAI/Anthropic format validators). ([#4921](https://github.com/diegosouzapw/OmniRoute/pull/4921)–[#4956](https://github.com/diegosouzapw/OmniRoute/pull/4956))
+- **refactor(pricing/providers):** decomposed `pricing.ts` into shared tiers + partitioned `DEFAULT_PRICING` modules, and split the `providers.ts` catalog into semantic data modules organized by provider family. ([#4917](https://github.com/diegosouzapw/OmniRoute/pull/4917), [#4918](https://github.com/diegosouzapw/OmniRoute/pull/4918))
+- **refactor(open-sse):** extract `safeParseJSON` utility and dedup `tryParseJSON` call sites; extract and dedup the fallback `tool_call` ID generation helper. ([#4735](https://github.com/diegosouzapw/OmniRoute/pull/4735), [#4736](https://github.com/diegosouzapw/OmniRoute/pull/4736))
+
+**Quality & CI**
+
+- **chore(quality):** release base-red reconciliation + ratchet rebaselines — file-size, env-doc, and catalog baseline updates across multiple gates. ([#4630](https://github.com/diegosouzapw/OmniRoute/pull/4630), [#4879](https://github.com/diegosouzapw/OmniRoute/pull/4879), [#4886](https://github.com/diegosouzapw/OmniRoute/pull/4886), [#4915](https://github.com/diegosouzapw/OmniRoute/pull/4915), [#4961](https://github.com/diegosouzapw/OmniRoute/pull/4961), [#4973](https://github.com/diegosouzapw/OmniRoute/pull/4973))
+- **ci(quality):** shift heavy validation gates to the PR→release merge fast-path to accelerate the release cycle. ([#4857](https://github.com/diegosouzapw/OmniRoute/pull/4857))
+- **fix(ci):** include `coverage/lcov.info` in the coverage-report artifact so SonarQube can consume it. ([#4670](https://github.com/diegosouzapw/OmniRoute/pull/4670))
+- **fix(test):** validate Anthropic-compatible connections via `POST /v1/messages` for accurate connectivity testing. ([#4657](https://github.com/diegosouzapw/OmniRoute/pull/4657))
+
+**Docs**
+
+- **docs(resilience):** document Quota-Share Concurrency Control — `max_concurrent` enforcement, serialization behavior, and cooldown-wait semantics. ([#4980](https://github.com/diegosouzapw/OmniRoute/pull/4980))
+- **docs(perf):** add per-endpoint p50/p95/p99 latency and cost budgets reference. ([#4867](https://github.com/diegosouzapw/OmniRoute/pull/4867) — thanks @KooshaPari)
+- **docs(ops):** add canonical incident response runbook. ([#4868](https://github.com/diegosouzapw/OmniRoute/pull/4868) — thanks @KooshaPari)
+- **docs(ops):** document the release-green family — `green-prs`, `check:release-green`, `babysit`, and nightly gate workflows. ([#4679](https://github.com/diegosouzapw/OmniRoute/pull/4679))
+- **docs(agentbridge):** document Electron `NODE_EXTRA_CA_CERTS`, real model IDs, and identity caveat for agent bridge integrations. ([#4718](https://github.com/diegosouzapw/OmniRoute/pull/4718))
+- **docs:** clarify Kiro provides ~50 credits/month per account, not unlimited. ([#4690](https://github.com/diegosouzapw/OmniRoute/pull/4690))
+
+**Misc**
+
+- **chore(claude,codex):** bump pinned CLI identities — Claude `2.1.158 → 2.1.187`, Codex `0.132.0 → 0.142.0`. ([#4883](https://github.com/diegosouzapw/OmniRoute/pull/4883))
+- **chore(dashboard):** rename Qoder display label from "Qoder AI" to "Qoder". ([#4733](https://github.com/diegosouzapw/OmniRoute/pull/4733))
+
+---
+
+## [3.8.35] — 2026-06-23
+
+### ✨ New Features
+
+- **Adaptive context compression (Phase 4)**: a four-layer compression upgrade landed across stacked PRs — an **Output Styles** registry (`terse-prose` / `less-code` / `terse-cjk`) ([#4694](https://github.com/diegosouzapw/OmniRoute/pull/4694) — thanks @diegosouzapw), an opt-in **SLM `ultra` tier** (two-tier LLMLingua with heuristic fallback) ([#4707](https://github.com/diegosouzapw/OmniRoute/pull/4707) — thanks @diegosouzapw), a **context-budget adaptive dial** (reserve-output ladder + floor) ([#4716](https://github.com/diegosouzapw/OmniRoute/pull/4716) — thanks @diegosouzapw), and an **offline evaluation harness** (PII-gated corpus, self-test judge, gold-grader, real-pipeline runner behind a `ModelClient` seam) ([#4720](https://github.com/diegosouzapw/OmniRoute/pull/4720) — thanks @diegosouzapw). All four layers share a single `CompressionRunTelemetry` contract.
+- **Redoc-rendered API docs**: a consolidated OpenAPI spec now lives at `docs/openapi.yaml` and is served as interactive Redoc documentation at `/api/docs`. ([#4781](https://github.com/diegosouzapw/OmniRoute/pull/4781) — thanks @KooshaPari / @diegosouzapw)
+
+### 🔧 Bug Fixes
+
+- **db-backups**: make the database-import size cap configurable via `OMNIROUTE_DB_IMPORT_MAX_MB` (default 100 MB, 4 GB ceiling) so backups larger than 100 MB can be restored; error message now points to the env var and to VACUUM ([#4757](https://github.com/diegosouzapw/OmniRoute/pull/4757) — closes #4719, thanks @diegosouzapw).
+- **Onboarding**: add the missing `onboarding.tiers` step-title translation so the setup wizard no longer crashes with `MISSING_MESSAGE: onboarding.tiers` ([#4755](https://github.com/diegosouzapw/OmniRoute/pull/4755) — closes #4698, thanks @diegosouzapw).
+- **deepseek-web**: fold `role:"tool"` results into the single-prompt transcript (`messagesToPrompt`) so tool outputs reach the model instead of being silently dropped when a follow-up turn omits the `tools[]` array ([#4756](https://github.com/diegosouzapw/OmniRoute/pull/4756) — closes #4712, thanks @diegosouzapw).
+- **Dashboard**: remove the dead, unconditional `useLiveRequests()` call from `HomePageClient.tsx` — it crashed the `/home` page in production builds with `ReferenceError: useLiveRequests is not defined` (#4759, #4745) and opened the live-dashboard WebSocket even when Provider Topology was hidden (#4596). The live feed remains owned by the settings-gated `HomeProviderTopologySection` ([#4761](https://github.com/diegosouzapw/OmniRoute/pull/4761) — thanks @diegosouzapw).
+- **Providers dashboard**: dedupe provider nodes by id when adding a compatible provider (`upsertProviderNodeById`) so the same provider can no longer appear twice and no-op adds don't invalidate the compatible-provider memo ([#4768](https://github.com/diegosouzapw/OmniRoute/pull/4768) — closes #4746, thanks @diegosouzapw).
+- **Storage VACUUM**: the scheduled VACUUM job now follows the Storage page settings (`scheduledVacuum` / `vacuumHour`) as the single source of truth; the legacy env-flag control path was removed ([#4726](https://github.com/diegosouzapw/OmniRoute/pull/4726) — thanks @rdself).
+- **Storage SQLite tuning**: `Cache Size` is now a positive KiB setting (for example, `16384`) that applies to SQLite as `PRAGMA cache_size = -16384`; Page Size and Cache Size changes are applied to the live database instead of being persisted only in the settings table.
+- **Tiers**: no-auth providers are now counted as free, and the free-tier filter returns an empty set instead of falling through to every provider ([#4753](https://github.com/diegosouzapw/OmniRoute/pull/4753) — thanks @megamen32 / @diegosouzapw).
+- **Combos**: auto-promote `zeroLatencyOptimizationsEnabled` so legacy configs (pre-3.8.33 `fallbackCompressionMode="lite"`) round-trip cleanly on the first GUI edit ([#4774](https://github.com/diegosouzapw/OmniRoute/pull/4774) — thanks @KooshaPari / @diegosouzapw).
+
+### 📝 Maintenance
+
+- **chatCore (#3501)**: continued the incremental decomposition of `executeProviderRequest` and the streaming/non-streaming hooks into pure leaf modules — top-level helpers + 6 pure leaves ([#4571](https://github.com/diegosouzapw/OmniRoute/pull/4571)), `resolveExecutorWithProxy` + `getExecutionCredentials` ([#4646](https://github.com/diegosouzapw/OmniRoute/pull/4646)), Claude message transforms ([#4708](https://github.com/diegosouzapw/OmniRoute/pull/4708)), `persistAttemptLogs` ([#4717](https://github.com/diegosouzapw/OmniRoute/pull/4717)), `stageTrace` + `compressionUsageReceipt` ([#4721](https://github.com/diegosouzapw/OmniRoute/pull/4721)), `prepareUpstreamBody` ([#4730](https://github.com/diegosouzapw/OmniRoute/pull/4730)), parse + non-streaming usage-stats ([#4762](https://github.com/diegosouzapw/OmniRoute/pull/4762)), `recordContextEditingTelemetryHook` ([#4779](https://github.com/diegosouzapw/OmniRoute/pull/4779)), `scheduleQuotaShareConsumption` ([#4780](https://github.com/diegosouzapw/OmniRoute/pull/4780)), `emitRequestGamificationEvent` ([#4776](https://github.com/diegosouzapw/OmniRoute/pull/4776)), `runPluginOnResponseHook` ([#4782](https://github.com/diegosouzapw/OmniRoute/pull/4782)), `scheduleStreamingQuotaShareConsumption` ([#4784](https://github.com/diegosouzapw/OmniRoute/pull/4784)), `recordCompressionCacheStats` ([#4792](https://github.com/diegosouzapw/OmniRoute/pull/4792)), `writeCavemanOutputAnalytics` ([#4794](https://github.com/diegosouzapw/OmniRoute/pull/4794)), `recordStreamingUsageStats` ([#4791](https://github.com/diegosouzapw/OmniRoute/pull/4791)), and `recordStreamingCost` ([#4790](https://github.com/diegosouzapw/OmniRoute/pull/4790)). (thanks @diegosouzapw)
+- **Quality**: expand `check:release-green` to reproduce the full release-PR gate set locally ([#4758](https://github.com/diegosouzapw/OmniRoute/pull/4758) — thanks @diegosouzapw).
+- **db**: re-export `compressionRunTelemetry` from `localDb` to satisfy the db-rules gate ([#4775](https://github.com/diegosouzapw/OmniRoute/pull/4775) — thanks @diegosouzapw).
+- **Security docs**: add a canonical STRIDE-based threat model ([#4783](https://github.com/diegosouzapw/OmniRoute/pull/4783) — thanks @KooshaPari).
+- **Tests**: add a smoke test for the home-client dashboard ([#4793](https://github.com/diegosouzapw/OmniRoute/pull/4793) — thanks @JxnLexn).
+- **Docs**: credit **ponytail** and **OmniCompress** in the README inspiring-projects list and restore the `check:env-doc-sync` release-green by exempting the harness-only `OMNIROUTE_EVAL_CREDENTIALS` var ([#4799](https://github.com/diegosouzapw/OmniRoute/pull/4799) — thanks @diegosouzapw); declare the Phase 4 compression layers in the README + GUIDE ([#4801](https://github.com/diegosouzapw/OmniRoute/pull/4801) — thanks @diegosouzapw).
+- **Quality**: trim `combo-config.test.ts` comments back under the file-size cap (follow-up to #4774) ([#4800](https://github.com/diegosouzapw/OmniRoute/pull/4800) — thanks @diegosouzapw).
+
+---
+
+## [3.8.34] — 2026-06-23
+
+### ✨ New Features
+
+- **feat(executors): Microsoft 365 Copilot pure framing + connection helpers** — adds the request/response framing and connection helpers to support `m365.cloud.microsoft/chat` for individual M365 plans. ([#4696](https://github.com/diegosouzapw/OmniRoute/pull/4696) — thanks @skyzea1 / @diegosouzapw)
+- **feat(compression): per-request `x-omniroute-compression` header (Phase 3)** — a request header now overrides the compression plan with the highest precedence (`request-header > routing > profile > auto-trigger > Default > off`), accepting `off` / `default` / `engine:<id>` / `<combo>`. The response echoes `X-OmniRoute-Compression: <mode>; source=<source>`. ([#4645](https://github.com/diegosouzapw/OmniRoute/pull/4645) — thanks @diegosouzapw)
+- **feat(audio): MiniMax T2A v2 TTS dispatch in `audioSpeech`** — adds MiniMax text-to-speech dispatch (port of upstream #1043). ([#4553](https://github.com/diegosouzapw/OmniRoute/pull/4553) — thanks @diegosouzapw)
+- **feat(opencode): OpenCode Go DeepSeek reasoning variants** — registers the Go DeepSeek reasoning model variants. ([#4647](https://github.com/diegosouzapw/OmniRoute/pull/4647) — thanks @DevEstacion)
+- **feat(quota): quota scraping for OpenCode Go and Ollama Cloud** — surfaces quota windows for the OpenCode Go and Ollama Cloud providers. ([#4642](https://github.com/diegosouzapw/OmniRoute/pull/4642) — thanks @JxnLexn)
+- **feat(settings): expose stream recovery feature flags** — surfaces the stream-recovery toggles in settings. ([#4586](https://github.com/diegosouzapw/OmniRoute/pull/4586) — thanks @rdself)
+- **feat(providers): optional model ID for custom API-key validation** — custom API-key connection tests can now specify the model ID used to validate the key. ([#4555](https://github.com/diegosouzapw/OmniRoute/pull/4555) — thanks @diegosouzapw)
+
+### 🐛 Fixed
+
+- **fix(tier): noAuth providers count as free; `auto/<cat>:free` returns an empty pool when no free candidate matches** — `freeProviders` is now the union of the legacy explicit list and every chat-tier `noAuth` provider derived from `NOAUTH_PROVIDERS` (so opencode / mimocode / duckduckgo-web are correctly classified free), the task-fitness lookup inherits a base model's `arena_elo` for its `-free` variant, and the `auto/<category>:<tier>` filter no longer silently falls back to the full pool — a `:free` request that matches no connected free model returns empty instead of billing a paid model (opt back into the legacy fallback with `OMNIROUTE_AUTO_FREE_FALLBACK_TO_FULL_POOL=true`). Corrupted/invalid `tier_config` rows now log a structured warning and fall back to defaults instead of throwing. ([#4753](https://github.com/diegosouzapw/OmniRoute/pull/4753), [#4517](https://github.com/diegosouzapw/OmniRoute/issues/4517) — thanks @megamen32)
+- **fix(db): scheduled VACUUM follows Storage settings** — the SQLite VACUUM scheduler now uses the existing Storage page `scheduledVacuum` / `vacuumHour` configuration as its single source of truth, refreshes immediately when those settings are saved, and no longer exposes a separate environment-variable control path.
+- **fix(db): scheduled cleanup actually runs + queries target the real tables (DB-bloat / OOM)** — `runAutoCleanup` was never scheduled, so retention cleanup never executed and tables (`compression_analytics`, `usage_history`, …) grew unbounded into multi-GB SQLite files driving high RSS. Worse, several cleanup queries referenced wrong table/column names (`call_logs.created_at`→`timestamp`, `compression_analytics.created_at`→`timestamp`, `mcp_audit_log`→`mcp_tool_audit`, `a2a_events`→`a2a_task_events`, `memory_entries`→`memories`), so even a manual run silently no-op'd or errored. Fixed the five queries to match the real schema, added `cleanupProxyLogs`, and wired a `startCleanupScheduler` (startup + every 6h, VACUUM after deletes) into `server-init` alongside the existing budget-reset and reasoning-cache jobs. ([#4691](https://github.com/diegosouzapw/OmniRoute/pull/4691), extracted from [#4428](https://github.com/diegosouzapw/OmniRoute/pull/4428) — thanks @oyi77 / @diegosouzapw)
+- **fix(routing): include all noAuth models in auto-combos + add reka-flash + best-free template** — noAuth provider models are no longer skipped when building auto-combos, `reka-flash` is registered, and a `best-free` combo template is added. ([#4621](https://github.com/diegosouzapw/OmniRoute/pull/4621) — thanks @oyi77)
+- **fix: noAuth provider validation + Kimi executor routing** — corrects noAuth provider membership checks and removes a mis-routed Kimi alias. (closes #4620) ([#4699](https://github.com/diegosouzapw/OmniRoute/pull/4699) — thanks @oyi77)
+- **fix(executors): Firecrawl `web_fetch` 500 with `include_metadata=true`** — fixes a crash when Firecrawl web_fetch is invoked with metadata extraction enabled. ([#4692](https://github.com/diegosouzapw/OmniRoute/pull/4692) — thanks @ponkcore)
+- **fix(proxy): apply `pipelining:0` + connections cap to the direct dispatcher** — same-provider concurrent requests no longer serialize behind a long/streaming request on the direct path. ([#4684](https://github.com/diegosouzapw/OmniRoute/pull/4684) — thanks @jeffer1312 / @diegosouzapw)
+- **fix(telemetry): back off live-WS event forwarding when the sidecar is unreachable** — stops repeatedly attempting to connect to `LIVE_WS_PORT` when live monitoring is not configured. ([#4687](https://github.com/diegosouzapw/OmniRoute/pull/4687) — thanks @FikFikk / @diegosouzapw)
+- **fix(api): serve `GET /v1/models/{model}` as JSON, not the HTML dashboard** — the per-model endpoint (IDs with slashes via a catch-all route) now returns JSON, unbreaking Claude Code. ([#4677](https://github.com/diegosouzapw/OmniRoute/pull/4677) — thanks @papajo / @diegosouzapw)
+- **fix(executors): robust deepseek-web tool-call parsing and agentic context retention** — hardens DeepSeek-web tool-call parsing and preserves agentic context across turns. ([#4644](https://github.com/diegosouzapw/OmniRoute/pull/4644) — thanks @BugsBag)
+- **fix(cli): authenticate `omniroute logs` and honor the active context** — the `logs` command now authenticates and respects the active context. ([#4638](https://github.com/diegosouzapw/OmniRoute/pull/4638) — thanks @Rahulsharma0810)
+- **fix(stream): estimate input tokens when upstream reports `prompt_tokens=0`** — input token usage is estimated when the upstream omits it. ([#4615](https://github.com/diegosouzapw/OmniRoute/pull/4615) — thanks @adivekar-utexas)
+- **fix(plugin): auto-prefix providerId with `opencode-` for OpenCode 1.17.8+ native gate** — adapts provider IDs to the OpenCode 1.17.8+ native provider gate. ([#4527](https://github.com/diegosouzapw/OmniRoute/pull/4527) — thanks @herjarsa)
+- **fix(catalog): shorten no-thinking gateway prefix to `no-think/`** — renames the no-thinking gateway prefix. ([#4525](https://github.com/diegosouzapw/OmniRoute/pull/4525) — thanks @Rahulsharma0810)
+- **fix(models): unknown max output limits no longer default to 8192** — models without synced/registry/static `maxOutputTokens` resolve the limit as unknown instead of a generic 8192 cap; clamping/injection only happens when a real cap is known. ([#4584](https://github.com/diegosouzapw/OmniRoute/pull/4584) — thanks @rdself)
+- **fix(resilience): respect upstream retry-hint toggle** — honors the configured toggle for upstream retry hints. ([#4585](https://github.com/diegosouzapw/OmniRoute/pull/4585) — thanks @rdself)
+- **fix(providers): show revealed connection API keys** — fixes revealing stored connection API keys in the UI. ([#4583](https://github.com/diegosouzapw/OmniRoute/pull/4583) — thanks @rdself)
+- **fix(logs): make active-request stale sweep configurable** — exposes the stale-request sweep interval as a setting. ([#4599](https://github.com/diegosouzapw/OmniRoute/pull/4599) — thanks @rdself)
+- **fix(resilience): retain provider cooldowns for the configured max window** — cooldowns persist for the configured maximum window. ([#4588](https://github.com/diegosouzapw/OmniRoute/pull/4588) — thanks @KooshaPari)
+- **fix(resilience): reject invalid provider cooldown bounds** — validates cooldown bound configuration. ([#4589](https://github.com/diegosouzapw/OmniRoute/pull/4589) — thanks @KooshaPari)
+- **fix(combo): preserve production combo metrics on shadow eviction** — shadow eviction no longer drops production combo metrics. ([#4590](https://github.com/diegosouzapw/OmniRoute/pull/4590) — thanks @KooshaPari)
+- **fix(combo): exclude exhausted connections from auto scoring** — exhausted connections are no longer scored as auto-combo candidates. ([#4592](https://github.com/diegosouzapw/OmniRoute/pull/4592) — thanks @KooshaPari)
+- **fix(relay): apply IP rate limit to the Bifrost sidecar** — extends IP rate limiting to the Bifrost relay sidecar. ([#4593](https://github.com/diegosouzapw/OmniRoute/pull/4593) — thanks @KooshaPari)
+- **fix(bifrost): finalize SSE relay usage after stream** — finalizes relay usage accounting once the SSE stream completes. ([#4612](https://github.com/diegosouzapw/OmniRoute/pull/4612) — thanks @KooshaPari)
+- **fix(quota): expose Bailian quota windows** — surfaces Bailian provider quota windows. ([#4610](https://github.com/diegosouzapw/OmniRoute/pull/4610) — thanks @KooshaPari)
+- **fix(dashboard): gate home topology live-WS networking behind widget visibility** — the home dashboard no longer starts topology polling / live sockets when topology is hidden. ([#4618](https://github.com/diegosouzapw/OmniRoute/pull/4618), [#4606](https://github.com/diegosouzapw/OmniRoute/pull/4606) — thanks @KooshaPari)
+- **fix(dashboard): isolate the quota widget refresh clock** — the quota widget refresh no longer drives unrelated re-renders. ([#4611](https://github.com/diegosouzapw/OmniRoute/pull/4611) — thanks @KooshaPari)
+- **fix(dashboard): memoize compatible provider groups** — avoids recomputing compatible provider groups on every render. ([#4613](https://github.com/diegosouzapw/OmniRoute/pull/4613) — thanks @KooshaPari)
+- **fix(cli): align `omniroute` data dir and env loading with the runtime** — the CLI's data-dir/env loading no longer drifts from the server runtime configuration. ([#4619](https://github.com/diegosouzapw/OmniRoute/pull/4619), [#4607](https://github.com/diegosouzapw/OmniRoute/pull/4607) — thanks @KooshaPari)
+- **fix(api/settings): prevent cached `/api/settings` responses** — disables caching on the settings endpoint (port from 9router#951). ([#4566](https://github.com/diegosouzapw/OmniRoute/pull/4566) — thanks @diegosouzapw)
+- **fix(executors): strip temperature for the GitHub Copilot gpt-5.4 family** — removes the unsupported `temperature` param for Copilot gpt-5.4 models (port from 9router#612). ([#4564](https://github.com/diegosouzapw/OmniRoute/pull/4564) — thanks @diegosouzapw)
+- **fix(dashboard): keep play_arrow spinning on provider "Test All" buttons** — fixes the spinner state on the provider test buttons (port from 9router#715). ([#4563](https://github.com/diegosouzapw/OmniRoute/pull/4563) — thanks @diegosouzapw)
+- **fix(dashboard): surface manual config CTA when Open Claw CLI auto-detect fails** — shows a manual-config call-to-action on the Open Claw CLI card when auto-detection fails. ([#4562](https://github.com/diegosouzapw/OmniRoute/pull/4562) — thanks @diegosouzapw)
+- **fix(oauth): update Qwen OAuth URLs from `chat.qwen.ai` to `qwen.ai`** — refreshes the Qwen OAuth endpoints (port of decolua/9router#683). ([#4561](https://github.com/diegosouzapw/OmniRoute/pull/4561) — thanks @diegosouzapw)
+
+### 📝 Maintenance
+
+- **refactor(imageGeneration): extract 8 provider families to co-located files** — splits the image-generation module into eight co-located per-provider files with no behavioral change. ([#4609](https://github.com/diegosouzapw/OmniRoute/pull/4609) — thanks @KooshaPari)
+- **deps: bump production + development groups; migrate js-yaml to v5 (ESM)** — dependency bumps plus a `js-yaml` v4→v5 migration to the ESM-only namespace import. ([#4697](https://github.com/diegosouzapw/OmniRoute/pull/4697) — thanks @diegosouzapw)
+- **chore(quality): release-green pre-flight validator + nightly signal** — new `npm run check:release-green` (`scripts/quality/validate-release-green.mjs`) reproduces the release-equivalent validation (full unit + vitest + ratchets + typecheck + lint, optional `--with-build` package-artifact) against the current working tree and classifies each red as **HARD** (real defect) vs **DRIFT** (ratchet, rebaselined at release) — purely diagnostic, never blocking contributors. A new `nightly-release-green` workflow runs it on the active release branch and opens/updates a tracking issue on hard failures. Closes the gap where the full gate (`ci.yml`) only ran on the release PR, so reds accrued silently on `release/**` and surfaced in layers at release time. ([#4622](https://github.com/diegosouzapw/OmniRoute/pull/4622) — thanks @diegosouzapw)
+- **chore(quality): reconcile file-size baseline for #4644 (`deepseek-web.ts` 1117→1125)** — rebaselines the file-size gate after the deepseek-web hardening. ([#4695](https://github.com/diegosouzapw/OmniRoute/pull/4695) — thanks @diegosouzapw)
+
+---
+
+## [3.8.33] — 2026-06-21
+
+### ✨ New Features
+
+- **feat(combo): nested combo-ref execution (`nestedComboMode: execute`)** — selection strategies can now treat a combo-reference step as a black box, executing the referenced combo as a single unit instead of flattening its targets. ([#4537](https://github.com/diegosouzapw/OmniRoute/pull/4537) — thanks @adivekar-utexas)
+- **feat(combo): sticky weighted selection limit with exhaustion-aware renormalization** — weighted strategies gain a configurable sticky-selection limit; once a target is exhausted, remaining weights renormalize so traffic is redistributed correctly. ([#4489](https://github.com/diegosouzapw/OmniRoute/pull/4489) — thanks @adivekar-utexas)
+- **feat(combos): provider-wildcard expansion in combo steps** — a combo step may now reference a whole provider via wildcard and have it expand to that provider's models at resolution time. ([#4545](https://github.com/diegosouzapw/OmniRoute/pull/4545) — thanks @Rahulsharma0810)
+- **feat(compression): Phase 2 — named profiles + active selector** — the compression settings panel becomes the single source of truth via a single active-profile selector (Default panel vs a named combo) wired into the runtime. ([#4521](https://github.com/diegosouzapw/OmniRoute/pull/4521) — thanks @diegosouzapw)
+- **feat(sse): route `web_search` requests to a configured model** — CCR-style webSearch scenario: requests carrying a `web_search*` tool can be routed to a dedicated `webSearchRouteModel`, configurable from the Routing tab. ([#4509](https://github.com/diegosouzapw/OmniRoute/pull/4509) — thanks @shafqatevo / @diegosouzapw)
+- **feat(mcp): `omniroute_web_fetch` tool for URL content extraction** — new MCP tool that fetches and extracts the content of a URL. ([#4510](https://github.com/diegosouzapw/OmniRoute/pull/4510) — thanks @ponkcore)
+- **feat(models): qualify duplicate model names with their provider prefix** — when two providers expose a same-named model, the catalog now disambiguates each with its provider prefix. ([#4516](https://github.com/diegosouzapw/OmniRoute/pull/4516) — thanks @Rahulsharma0810)
+- **feat(translator): accept OpenAI audio input parts in Gemini translation** — `input_audio` message parts are now translated through to Gemini. ([#4434](https://github.com/diegosouzapw/OmniRoute/pull/4434) — thanks @diegosouzapw)
+- **feat(webhooks): enrich Telegram request notifications** — Telegram webhook payloads carry richer request context. ([#4524](https://github.com/diegosouzapw/OmniRoute/pull/4524) — thanks @mppata-glitch)
+- **feat(bazaarlink): add `authHint` to the existing APIKEY_PROVIDERS entry** — surfaces the auth hint for the bazaarlink provider. ([#4522](https://github.com/diegosouzapw/OmniRoute/pull/4522) — thanks @adivekar-utexas)
+- **feat(usage): API-key USD quota percent + reset hints, weekly-window cutoff** — usage dashboard surfaces API-key USD quota percentage and reset hints, honoring the weekly window cutoff. ([#4398](https://github.com/diegosouzapw/OmniRoute/pull/4398) — thanks @Witroch4)
+- **feat(usage): surface Codex code-review weekly window + `additional_rate_limits` fallback** — exposes the Codex code-review weekly window and falls back to `additional_rate_limits` when present. ([#4494](https://github.com/diegosouzapw/OmniRoute/pull/4494) — thanks @diegosouzapw)
+- **feat(dashboard): per-provider dropdown filter on the quota dashboard** — filter the quota dashboard by provider. ([#4495](https://github.com/diegosouzapw/OmniRoute/pull/4495) — thanks @diegosouzapw)
+- **feat(dashboard): inline show/hide toggle for API keys on the API Manager page** ([#4505](https://github.com/diegosouzapw/OmniRoute/pull/4505) — thanks @diegosouzapw)
+- **feat(dashboard): toggle-style model deselection in the combo builder modal** ([#4498](https://github.com/diegosouzapw/OmniRoute/pull/4498) — thanks @diegosouzapw)
+- **feat(dashboard): Done button in the model picker for combo creation** ([#4496](https://github.com/diegosouzapw/OmniRoute/pull/4496) — thanks @diegosouzapw)
+- **feat(providers): expose `gpt-4o` on the built-in GitHub Copilot (`gh`) provider** ([#4487](https://github.com/diegosouzapw/OmniRoute/pull/4487) — thanks @diegosouzapw)
+- **feat(pricing): default pricing for the Qwen coder-model on the `qw` provider** ([#4488](https://github.com/diegosouzapw/OmniRoute/pull/4488) — thanks @diegosouzapw)
+
+### 🔧 Bug Fixes
+
+- **fix(telemetry): back off the live-WS event bridge so a missing sidecar stops spamming ProxyFetch errors** — in single-port deployments the live-dashboard sidecar (port 20129) is not running, but `forwardDashboardEventToLiveWs` POSTed to it on every compression event. Since the global `fetch` is `proxyFetch`, each `ECONNREFUSED` logged a `[ProxyFetch] Undici dispatcher failed` warning (~272× in 42 min). The forwarder now backs off after consecutive failures (60s cooldown, lazy recovery) and clears the backoff on success, so a missing sidecar no longer floods the logs. ([#4604](https://github.com/diegosouzapw/OmniRoute/issues/4604) — thanks @FikFikk)
+- **fix(api): resolve a compatible provider node by base type, not only exact id** — connection→node resolution now matches on the bare derived node type when the exact id isn't found and the match is unambiguous (ambiguous → 404), via a pure `providerNodeSelect` helper. ([#4576](https://github.com/diegosouzapw/OmniRoute/pull/4576) — thanks @aleksesipenko / @diegosouzapw)
+- **fix(cli): supervisor restarts on spontaneous exit-0 (OOM cgroup) + waits for port before respawn** — a child that exits 0 because the cgroup OOM-killer reaped it is now restarted (not treated as a clean shutdown), the restart reset window widened 30s→60s, and the supervisor waits for the port to be free before respawning. ([#4578](https://github.com/diegosouzapw/OmniRoute/pull/4578) — thanks @oyi77 / @diegosouzapw)
+- **fix(combo): attribute lockout decay & success telemetry to the dynamically-selected connection** — on the combo success path the actual connection chosen by dynamic account-selection is read from the `X-OmniRoute-Selected-Connection-Id` response header (instead of the often-empty static `target.connectionId`), so model-lockout decay, `recordProviderSuccess`, LKGP and success/failure telemetry attribute to the right connection on both the priority and round-robin paths. The pre-screen "unavailable" snapshot is also no longer a permanent skip — availability is re-checked on each retry since connection cooldowns can expire mid-request. ([#4550](https://github.com/diegosouzapw/OmniRoute/pull/4550) — thanks @Chewji9875)
+- **fix(auto): enforce the quota cutoff before scoring (opt-in)** — auto-routing now evaluates a hard quota cutoff in `buildAutoCandidates` to drop low-quota candidates before scoring, with a 429 guard when all candidates fall below cutoff. The cutoff is **opt-in** behind `QuotaPreflightSettings.enabled` (default OFF via `QUOTA_PREFLIGHT_CUTOFF_ENABLED`), so default behavior is unchanged. ([#4483](https://github.com/diegosouzapw/OmniRoute/pull/4483) — thanks @megamen32)
+- **fix(antigravity): reasoning/thinking models no longer 400 with `oneOf at '/' not met`** — the Cloud Code envelope passthrough also leaked the Claude/OpenAI-native thinking fields (`thinking`, `reasoning_effort`, `reasoning`, `enable_thinking`, `thinking_budget`) the unified thinking adapter sets at the body root; Google rejected them with `400 Bad input: oneOf at '/' not met`. The whole thinking family is now stripped before the envelope is built; Gemini's own `generationConfig.thinkingConfig` is unaffected. ([#4485](https://github.com/diegosouzapw/OmniRoute/pull/4485) — port from 9router#1926, thanks @theseven99 / @diegosouzapw)
+- **fix(integration): restore the codex and memory pipeline contracts** — realigns the CLI fingerprint + memory-tools contracts so the codex and memory pipelines pass their integration checks again. ([#4474](https://github.com/diegosouzapw/OmniRoute/pull/4474) — thanks @KooshaPari)
+- **fix(sse): RTK must preserve `cache_control`-marked `tool_result` blocks** — reasoning-token-keeping no longer drops tool_result blocks that carry a `cache_control` marker. ([#4560](https://github.com/diegosouzapw/OmniRoute/pull/4560) — thanks @diegosouzapw)
+- **fix(auto-combo): respect model visibility (`isHidden`) in the auto-combo candidate pool** — hidden models are excluded from auto-combo candidates. ([#4558](https://github.com/diegosouzapw/OmniRoute/pull/4558) — thanks @herjarsa)
+- **fix(dashboard): avoid overlapping provider health polls** — guards against concurrent provider-health poll cycles overlapping. ([#4557](https://github.com/diegosouzapw/OmniRoute/pull/4557) — thanks @KooshaPari)
+- **fix(dashboard): make the API Manager key table usable on mobile** ([#4556](https://github.com/diegosouzapw/OmniRoute/pull/4556) — thanks @janeza2)
+- **fix(executors): decode Composer/Cursor `</think>`-marked visible output** — visible text wrapped in Cursor Composer's `</think>` markers is now decoded correctly. ([#4554](https://github.com/diegosouzapw/OmniRoute/pull/4554) — thanks @diegosouzapw)
+- **fix(oauth): improve Cursor auto-import reliability on macOS** ([#4552](https://github.com/diegosouzapw/OmniRoute/pull/4552) — thanks @diegosouzapw)
+- **fix(providers/test): probe the real Codex `/responses` endpoint** — connection test hits the actual Codex `/responses` endpoint. ([#4551](https://github.com/diegosouzapw/OmniRoute/pull/4551) — thanks @diegosouzapw)
+- **fix(mcp): `webFetchInput` emits `URL is required` for a missing url** — clearer validation error for the web-fetch tool. ([#4541](https://github.com/diegosouzapw/OmniRoute/pull/4541) — thanks @ponkcore / @diegosouzapw)
+- **fix(compression): allow `enginesExplicit` through the PUT validation schema** — the compression settings PUT no longer rejects the `enginesExplicit` flag. ([#4532](https://github.com/diegosouzapw/OmniRoute/pull/4532) — thanks @DevEstacion)
+- **fix(no-think): normalize provider prefix to canonical in no-think variants** ([#4531](https://github.com/diegosouzapw/OmniRoute/pull/4531) — thanks @Rahulsharma0810)
+- **fix(combo): pass `maxCooldownMs` from settings to the `recordModelLockoutFailure` call sites** ([#4530](https://github.com/diegosouzapw/OmniRoute/pull/4530) — thanks @Chewji9875)
+- **fix(combo): allow fallback on context-overflow & param-validation 400s; preserve upstream codes** — combo fallback now triggers on recoverable 400s while keeping the original upstream status. ([#4519](https://github.com/diegosouzapw/OmniRoute/pull/4519) — thanks @adivekar-utexas)
+- **fix(command-code): cap `max_tokens` per model using the registry `maxOutputTokens`** ([#4518](https://github.com/diegosouzapw/OmniRoute/pull/4518) — thanks @adivekar-utexas)
+- **fix(mitm): gate sudo prompts on server platform, not browser UA** ([#4514](https://github.com/diegosouzapw/OmniRoute/pull/4514) — thanks @diegosouzapw)
+- **fix(mitm): graceful sudo degradation in slim Docker / non-root containers** ([#4513](https://github.com/diegosouzapw/OmniRoute/pull/4513) — thanks @diegosouzapw)
+- **fix(usage): clear auth-expired message for Kiro social-auth accounts** ([#4512](https://github.com/diegosouzapw/OmniRoute/pull/4512) — thanks @diegosouzapw)
+- **fix(pricing): default cost rows for Antigravity Gemini 3.5 Flash tiers + `gemini-pro-agent`** ([#4508](https://github.com/diegosouzapw/OmniRoute/pull/4508) — thanks @diegosouzapw)
+- **fix(api): dedupe exact-duplicate ids in `/v1/models`** — low-noise model output without alias/canonical duplicates. ([#4506](https://github.com/diegosouzapw/OmniRoute/pull/4506) — thanks @Rahulsharma0810 / @diegosouzapw)
+- **fix(dashboard): enable Codex Apply/Reset buttons when the CLI is installed** ([#4504](https://github.com/diegosouzapw/OmniRoute/pull/4504) — thanks @diegosouzapw)
+- **fix(dashboard): show API-Key-compatible providers in the Antigravity CLI Tools model picker** ([#4503](https://github.com/diegosouzapw/OmniRoute/pull/4503) — thanks @diegosouzapw)
+- **fix(dashboard): migrate ManualConfigModal copy to the shared `useCopyToClipboard` hook** ([#4502](https://github.com/diegosouzapw/OmniRoute/pull/4502) — thanks @diegosouzapw)
+- **fix(sse): skip disabled providers in combo fallback** ([#4500](https://github.com/diegosouzapw/OmniRoute/pull/4500) — thanks @diegosouzapw)
+- **fix(usage): parse numeric-string quota reset timestamps as Unix sec/ms** ([#4493](https://github.com/diegosouzapw/OmniRoute/pull/4493) — thanks @diegosouzapw)
+- **fix(db): scheduled VACUUM + persist `lastVacuumAt`** — a new `vacuumScheduler.ts` persists the last run timestamp and last error to the `key_value` table (migration 102) and feeds the database settings panel; wired into the Next.js lifecycle (default 24h, window 02:00–04:00 local). The initial env-flag control path from this entry is superseded in v3.8.34 by the Storage page settings. ([#4480](https://github.com/diegosouzapw/OmniRoute/pull/4480) — thanks @KooshaPari / @oyi77)
+- **perf(quota): stop writing redundant `quota_snapshots` rows from idle connections** — the 60s background refresh persisted a snapshot for every window of every connection regardless of change, generating 400K+ rows/day from idle accounts. `setQuotaCache` now skips the write when a window's `remaining_percentage`/`is_exhausted` is unchanged from the last cached observation; the first observation and every real change still persist. ([#4565](https://github.com/diegosouzapw/OmniRoute/pull/4565), [#4438](https://github.com/diegosouzapw/OmniRoute/issues/4438) — thanks @oyi77)
+
+### 🔒 Security
+
+- **fix(sse): crypto-secure RNG for combo/deck load-balancing selection** — replaces `Math.random()` with a crypto-secure source in the combo/deck weighted-selection path. ([#4455](https://github.com/diegosouzapw/OmniRoute/pull/4455) — thanks @diegosouzapw)
+
+### 📝 Maintenance
+
+- **perf(dashboard): shrink provider assets + fix the usage rollup cutoff** — recompresses oversized provider images (nanobot/picoclaw/zeroclaw) and adds a `check:provider-assets` gate, plus a usage-analytics rollup cutoff fix. ([#4464](https://github.com/diegosouzapw/OmniRoute/pull/4464) — thanks @KooshaPari)
+- **refactor(chatCore): extract pure leaves from `chatCore.ts`** — incremental decomposition of the chat-core handler into pure, individually-testable leaves (system-role extraction, upstream-header build, failure usage-record builder, key-health, request-format, claude-effort, target-format, Background-Task-Redirect decision, Codex quota-state persistence). ([#4548](https://github.com/diegosouzapw/OmniRoute/pull/4548), [#4547](https://github.com/diegosouzapw/OmniRoute/pull/4547), [#4544](https://github.com/diegosouzapw/OmniRoute/pull/4544), [#4538](https://github.com/diegosouzapw/OmniRoute/pull/4538), [#4526](https://github.com/diegosouzapw/OmniRoute/pull/4526), [#4492](https://github.com/diegosouzapw/OmniRoute/pull/4492) — #3501, thanks @diegosouzapw)
+- **chore(i18n): remove unused config helpers** ([#4482](https://github.com/diegosouzapw/OmniRoute/pull/4482) — thanks @KooshaPari)
+- **chore(quality): reconcile quality baselines (complexity, cognitive-complexity, file-size) across the cycle** ([#4579](https://github.com/diegosouzapw/OmniRoute/pull/4579), [#4570](https://github.com/diegosouzapw/OmniRoute/pull/4570), [#4543](https://github.com/diegosouzapw/OmniRoute/pull/4543), [#4542](https://github.com/diegosouzapw/OmniRoute/pull/4542), [#4535](https://github.com/diegosouzapw/OmniRoute/pull/4535), [#4534](https://github.com/diegosouzapw/OmniRoute/pull/4534), [#4529](https://github.com/diegosouzapw/OmniRoute/pull/4529), [#4528](https://github.com/diegosouzapw/OmniRoute/pull/4528), [#4523](https://github.com/diegosouzapw/OmniRoute/pull/4523) — thanks @diegosouzapw)
+
+---
+
+## [3.8.32] — 2026-06-20
+
+### ✨ New Features
+
+- **feat(dashboard): inline show/hide toggle for API keys on the API Manager page** — each row in the API keys list now exposes an eye / eye-off button next to the masked key. Clicking it lazy-fetches the full key via the existing `/api/keys/{id}/reveal` endpoint (so the policy gate is unchanged), caches it client-side, and renders the full value inline; clicking again hides it. The toggle only appears when `allowKeyReveal` is true (server policy), so an installation that disables reveal still sees a locked stub. Reuses the existing i18n keys `apiManager.showKey` / `apiManager.hideKey` already shipped in every locale, and clears the cached reveal when the key is deleted. Inspired-by: toanalien.
+- **feat(oauth): import accounts from CLIProxyAPI** — Settings → CLIProxyAPI now has an "Import accounts" button that reads the OAuth accounts CLIProxyAPI already saved in `~/.cli-proxy-api/` and imports them as OmniRoute connections, so you don't have to log into every account individually. CLIProxyAPI's unified auth-file format is parsed by `type` discriminator and the supported account types (Gemini, Codex, Claude/Anthropic, Antigravity, Qwen, Kimi) are upserted; unknown types are skipped. The preview never exposes tokens to the client. (thanks @powellnorma)
+- **feat(routing): opt-in setting to echo the requested alias/combo name in the response model field** — Settings → Routing now has an "Echo requested model name in responses" toggle (default off). When enabled, the response `model` field (non-streaming and every streamed SSE chunk) reports the alias or combo name the client requested instead of the upstream model name, so strict clients such as Claude Desktop — which reject a response whose `model` does not match the request with a 401 — work with aliases and combos. (thanks @thaiphuong1202)
+- **feat(providers): expand the openai and gemini direct registries with first-class variants already known elsewhere** — the `openai` provider entry now exposes `gpt-4.1-mini`, `gpt-4.1-nano`, `o3-mini`, and `o4-mini` (the latter two carry `REASONING_UNSUPPORTED` like `o3`), and the `gemini` entry now exposes `gemini-2.0-flash-lite` and `gemini-3-flash-lite-preview`. These models were already first-class throughout sibling subsystems (cost estimator, task fitness, free-model catalog, multiple aggregator registries) but happened to be missing from the direct openai/gemini namespaces. Embedding/TTS/image-gen models stay in their dedicated registries (`embeddingRegistry.ts`, `audioRegistry.ts`, `imageRegistry.ts`); legacy ids OmniRoute curated out (o1, gpt-4-turbo, …) are not restored. (thanks @East-rayyy)
+- **feat(translator): OpenAI SSE → Gemini SSE conversion for `/v1beta/models/{model}:streamGenerateContent`** — the `@google/genai` SDK (Gemini CLI) always calls `:streamGenerateContent?alt=sse` for chat and expects Gemini SSE chunks (no `[DONE]` sentinel — the stream just closes). The v1beta route was forwarding OpenAI SSE from `handleChat` unchanged, so the SDK crashed on the OpenAI `[DONE]` line with `SyntaxError: Unexpected token 'D', "[DONE]" is not valid JSON`. A new `transformOpenAISSEToGeminiSSE()` (in `open-sse/translator/response/openai-to-gemini-sse.ts`) rewrites each OpenAI delta into `candidates[].content.parts[]`, maps `finish_reason` → `finishReason` (STOP / MAX_TOKENS / SAFETY), attaches `usageMetadata` + `modelVersion` on the final chunk, and surfaces `reasoning_content` as `{ thought: true }` parts for thinking models. The non-streaming `:generateContent` action gets a sibling `convertOpenAIResponseToGemini()` for the JSON path. Streaming intent is now keyed off the URL action suffix (canonical Gemini convention) rather than the non-standard `generationConfig.stream` body field. (thanks @SteelMorgan)
+- **feat(compression): unified compression configuration panel (Phase 1)** — `/dashboard/context/settings` is now the single source of truth for compression: a master toggle plus per-engine on/off and level controls, with the dispatch pipeline derived from a stored `engines` map on `CompressionConfig`. A gate (`enginesExplicit`) ensures the new map only drives dispatch when an `engines` row was actually saved from the panel, so legacy/backfilled installs (the seeded default combo from migrations 042/043) keep their existing `defaultMode` behavior unchanged. The default-combo and per-engine routes are shimmed (410). ([#4432](https://github.com/diegosouzapw/OmniRoute/pull/4432) — thanks @diegosouzapw)
+- **feat(mcp): register the web-session pool observability tools** — the `poolTools` MCP tool set (web-session pool stats/health) was defined but never wired into `createMcpServer()`, so it was dead. It is now registered in `server.ts` with `withScopeEnforcement` against the typed `read:health` / `write:resilience` scopes (no enum inflation), giving MCP clients visibility into the pooled web-session lifecycle. ([#4399](https://github.com/diegosouzapw/OmniRoute/pull/4399), [#3368](https://github.com/diegosouzapw/OmniRoute/issues/3368) — thanks @diegosouzapw)
+- **feat(providers): stronger no-auth and web-cookie provider validation (`AUTH_007`)** — provider connection validation now handles no-auth and web-cookie providers explicitly: instead of returning a generic "Provider validation not supported", these providers report a precise `AUTH_007` status so the dashboard surfaces actionable validation feedback for cookie/no-auth flows. ([#4023](https://github.com/diegosouzapw/OmniRoute/pull/4023) — thanks @oyi77)
+- **feat(combo): per-combo `stickyRoundRobinLimit` override on the combos page** — the round-robin sticky-affinity limit can now be set per combo from the combos page UI, overriding the global default, so a combo can pin (or loosen) how many consecutive requests stick to the same round-robin member independently of the others. ([#4472](https://github.com/diegosouzapw/OmniRoute/pull/4472) — thanks @adivekar-utexas)
+- **feat(usage): quota fetch for `kimi-coding-apikey`** — usage/quota tracking now supports the `kimi-coding-apikey` provider, so its remaining quota is fetched and surfaced like the other quota-aware providers. ([#4435](https://github.com/diegosouzapw/OmniRoute/pull/4435) — thanks @janeza2)
+- **feat(cluster): opt-in memory + Bifrost cluster profiles** — adds opt-in cluster profiles that wire the memory subsystem and the Bifrost Go sidecar into a clustered deployment (follow-up to #3932). ([#4433](https://github.com/diegosouzapw/OmniRoute/pull/4433) — thanks @KooshaPari)
+- **feat(models): opt-in low-noise `/v1/models` catalog mode** — a new opt-in mode trims the `/v1/models` response to a quieter, lower-noise catalog for clients that choke on or don't need the full provider/model list. ([#4427](https://github.com/diegosouzapw/OmniRoute/pull/4427) — thanks @Rahulsharma0810)
+- **feat(ui): expose a `targetFormat` selector in the custom-models form** — the custom-models form now lets you pick the upstream target format explicitly, so a custom model can be pinned to the right wire format instead of relying on inference. ([#4475](https://github.com/diegosouzapw/OmniRoute/pull/4475) — thanks @adivekar-utexas)
+- **feat(providers): expose `gpt-4o` on the built-in GitHub Copilot (`gh`) provider** — GitHub Copilot still serves the original `gpt-4o` chat model via its `/chat/completions` endpoint, but the OmniRoute registry only shipped the GPT-5.x family, so clients that explicitly request `gpt-4o` against `gh` got an unknown-model error. `gpt-4o` is now registered under the `github` provider next to the GPT-5.x lineup (chat/completions, 128k context — no `openai-responses` targetFormat). Ported from [9router#98](https://github.com/decolua/9router/pull/98). (thanks @I3eka)
+- **feat(pricing): default pricing for Qwen `coder-model` on the `qw` provider** — the Qwen Coder Free (`qw`) registry already exposed the `coder-model` id (Qwen3.5/3.6 Coder Model) but `DEFAULT_PRICING.qw` was missing the row, so usage tracking reported `$0.00` for that model. The pricing row is now added with the same shape as the sibling `vision-model` tier, restoring non-zero cost tracking. Ported from upstream 9router PR [decolua/9router#156](https://github.com/decolua/9router/pull/156). (thanks @LinearSakana)
+- **feat(usage): Codex review-quota now surfaces the weekly window and the `additional_rate_limits` fallback shape** — the dashboard's Codex usage card showed only the **session** half of `code_review_rate_limit` and dropped review descriptors that arrived inside `additional_rate_limits` (the shape some ChatGPT Codex plans report). `buildCodexUsageQuotas` now emits the secondary window as `quotas.code_review_weekly` and, when the dedicated `code_review_rate_limit` block is empty, falls back to the matching descriptor in `additional_rate_limits` (matched on `limit_name`/`metered_feature`/`limit_id` containing `code_review` / `codex_review` / `review`). The new label `code_review_weekly → "Code Review Weekly"` is registered in `ProviderLimits/utils.tsx` so the card renders both windows side-by-side. The existing `quotas.code_review` key is preserved for back-compat. Inspired by upstream decolua/9router PR #836. (thanks @hiepau1231)
+- **feat(dashboard): per-provider dropdown filter on the quota dashboard** — the Quota dashboard now has a "Provider" dropdown alongside the existing Status / Type / Tier / Env filters. Choosing a provider narrows the visible accounts to that provider only; the selection persists in `localStorage` (`omniroute:limits:providerFilter`) and the dropdown auto-falls back to "All providers" if the persisted key no longer matches a connection in the current session. The dropdown only renders when there are at least two distinct providers in view, so single-provider setups aren't cluttered. The upstream "Expiring first" toggle is intentionally not ported — `visibleConnections` already always sorts by soonest reset within each status group, so the toggle would be redundant. Inspired by [decolua/9router#769](https://github.com/decolua/9router/pull/769) — thanks @DEYLNN.
+- **feat(dashboard): "Done" button in the model picker during combo creation** — `ModelSelectModal` now supports a `keepOpenOnSelect` prop (opt-in, off by default). When set — and the combos page now sets it — picking a model no longer auto-closes the modal, and a full-width "Done" button is rendered in the modal footer so users can add several models in a row and confirm explicitly. Single-select callers (e.g. CLI tool cards) are unchanged: the prop is opt-in, so they keep auto-close. The existing `multiSelect` mode (Clear + Done footer driven by `selectedModels`) takes precedence over `keepOpenOnSelect` to avoid two competing footers. Inspired by upstream PR [decolua/9router#1031](https://github.com/decolua/9router/pull/1031). (thanks @zanuartri)
+- **feat(dashboard): toggle-style model deselection inside the combo builder modal** — `ModelSelectModal` (used by the combo builder) now treats clicks on an already-added model as an inline remove instead of a duplicate add: the click invokes a new `onDeselect` callback when one is supplied, and a new `closeOnSelect={false}` prop keeps the modal open so several models can be added or removed in one session before the user closes it manually. Wired into the combo builder so the existing green "✓" highlight is now actionable — clicking it removes every step that points at that qualified model. Inspired-by upstream decolua/9router PR #889. (thanks @fajarhide)
+
+### 🐛 Fixed
+
+- **fix(sse): combo routing now skips a provider whose credentials are all disabled instead of failing the whole request** — when a combo like `antigravity/opus → github/opus` hit a leg whose only configured connections were disabled (or where no connections existed at all), `handleNoCredentials` returned `400 BAD_REQUEST`, which the combo target loop treats as a hard stop (combo's 400-break guard from PR #4316 / issue #4279 prevents infinite fallback loops on body-specific 4xx errors). The combo therefore died on the first leg even when later targets were perfectly healthy. The no-active-credentials branch now returns `404 NOT_FOUND` with `"No active credentials for provider: <p>"` instead — `404` flows through `checkFallbackError` as `shouldFallback: true` (generic-error catch-all path in `open-sse/services/accountFallback.ts`), so the next combo target is tried. The log level for this branch also drops from `error` to `warn` because zero active credentials is an expected operator-driven state, not a server fault. Inspired-by upstream decolua/9router PR #336. (thanks @East-rayyy)
+- **fix(dashboard): Manual Config modal "Copy" button now works on HTTP / non-secure deployments** — the copy handler in `ManualConfigModal` re-implemented the Clipboard-API-with-`execCommand`-fallback inline and gated the modern path on `window.isSecureContext`, so some non-secure-context browsers (and any future drift) silently lost the fallback. Migrated to the shared `useCopyToClipboard` hook (which delegates to `src/shared/utils/clipboard.ts`), giving consistent HTTP/HTTPS behavior with the rest of the dashboard and removing the duplicated code path. (thanks @anuragg-saxenaa)
+- **fix(dashboard): enable Codex Apply / Reset buttons when the CLI is installed** — on the Codex CLI tool card the **Apply** button was disabled whenever `selectedApiKey` was empty, but the local default `sk_omniroute` key is a valid choice when cloud mode is off or no API keys are configured — so Apply was stuck disabled even when the configuration was otherwise complete. **Reset** was also disabled when `codexStatus.hasOmniRoute` was false, which made it impossible to clear Codex configuration on installs that had never been pointed at OmniRoute. The disabled logic is now extracted into a pure helper (`codexButtonState.ts`) covered by unit tests: Apply is disabled only when no model is selected, or when cloud mode is on **and** keys exist **and** none is picked; Reset is disabled only while a reset is in flight. (thanks @anuragg-saxenaa)
+- **fix(mitm):** gate the sudo password prompt on the **server** platform, not the browser. The MITM control surface previously decided whether to ask for a sudo password by reading the browser's `navigator.userAgent`, which broke a Windows browser hitting a Linux server (no prompt → request rejected with `Missing sudoPassword`) and also forced an unnecessary modal on Linux hosts running as root, with NOPASSWD sudoers, or in minimal containers with no `sudo` binary on PATH. `GET /api/cli-tools/antigravity-mitm` now reports `isWin` and `needsSudoPassword` (probed via a safe `execFileSync("sudo", ["-n", "true"])`, per Hard Rule #13), and the Antigravity tool card uses the server-reported status to decide whether to show the modal. The POST/DELETE handlers stop returning 400 when sudo is genuinely not required. (thanks @hiepau1231)
+- **fix(embeddings):** forward output dimensions to Gemini for consistent embedding dims. (thanks @nguyenha935)
+- **fix(translator):** sanitize Read tool args from non-Anthropic models to prevent retry loops. (thanks @GodrezJr2)
+- **fix(usage):** reuse Gemini CLI project ID for quota checks (avoid re-discovery). (thanks @Delcado19)
+- **fix(dashboard):** surface manual config CTA when Claude CLI detection fails (remote deployments). (thanks @anuragg-saxenaa)
+- **fix(executors):** granular reasoning_effort handling for Claude models on GitHub Copilot. (thanks @baslr)
+- **fix(translator):** strip Claude output_config before MiniMax (rejected upstream). (thanks @hiepau1231)
+- **fix(translator): OpenAI audio input now reaches Gemini/Antigravity instead of being silently dropped** — `input_audio`/`audio` content parts on the OpenAI→Gemini path matched no handler in `convertOpenAIContentToParts` and were discarded with no error. They are now mapped to a Gemini `inlineData` part with an `audio/<format>` mime type (wav, mp3, …). (thanks @mugnimaestra)
+- **fix(combo): model lockout now honors a long upstream quota reset instead of retrying within minutes** — when a combo target returned a quota error carrying an explicit long reset (e.g. Antigravity `Resets in 160h27m24s`, a `Retry-After` header), the per-model lockout capped at the short base cooldown (~minutes) and discarded the parsed reset, so the exhausted model kept being retried far too early. The lockout now applies the parsed reset when it exceeds the base cooldown, and the Antigravity error-message parser also matches the plural `Resets in …` phrasing. (thanks @Ansh7473)
+- **fix(antigravity): Claude models no longer 400 with `Unknown name "output_config"`** — Anthropic/Claude-Code-only fields (`output_config`, legacy `output_format`) leaked into the Google Cloud Code request envelope via its top-level field passthrough, and Google rejects unknown envelope fields with `400 Invalid JSON payload received. Unknown name "output_config"` — breaking every Claude model served through Antigravity in IDEs. Those fields are now dropped before the envelope is built. (thanks @Duongkhanhtool)
+- **fix(combo): round-robin members fail over faster under concurrency saturation via a configurable queue depth** — when a round-robin combo member was saturated, requests sat in the per-model semaphore's **unbounded** queue and only failed over to the next member after the full `queueTimeoutMs` (default 30s) elapsed — so a burst of agentic requests deep-queued one hot member instead of spilling to healthy ones. The per-model semaphore now accepts a bounded queue depth and emits `SEMAPHORE_QUEUE_FULL` once it is full (the round-robin loop already cascades on that code), so a configured low depth fails over immediately. A new `queueDepth` combo-config knob (global default / provider override / per-combo, default **20** for backward compatibility; **0** = never queue → fail over now) is exposed in Settings → Combo Defaults. ([#3872](https://github.com/diegosouzapw/OmniRoute/issues/3872) — thanks @KooshaPari)
+- **fix(pricing): default cost rows for Antigravity's Gemini 3.5 Flash tiers + `gemini-pro-agent`** — the Antigravity public catalog (`ANTIGRAVITY_PUBLIC_MODELS`) ships `gemini-3-flash-agent`, `gemini-3.5-flash-low`, and `gemini-pro-agent` as user-callable client ids, but the `ag` block in the default pricing table only carried rows for `gemini-3-flash` / `gemini-3.1-pro-high`, so `getPricingForModel("ag", id)` returned `null` and cost / quota accounting silently fell back to `$0` for those three models. The missing rows are now seeded with the per-MTok rates the upstream quota tier bills at (Flash High/Medium share the legacy `gemini-3-flash` rate; `gemini-pro-agent` shares `gemini-3.1-pro-high`). (thanks @Ansh7473)
+- **fix(pricing): align Claude Code (`cc`) pricing with current Anthropic per-MTok rates** — the `cc` provider block in the default pricing table had stale numbers across every Claude 4.x family entry — most visibly, `claude-opus-4-5-20251101` was billed at the deprecated Opus 4.1 rate (`input $15` / `output $75`), and `claude-haiku-4-5-20251001` was at half the current Haiku 4.5 rate. The `cached` (cache hit) and `cache_creation` (5-minute cache write) multipliers were also off across Opus 4.6/4.7/4.8, Sonnet 4.5/4.6, Haiku 4.5, and Fable 5. All eight entries now match the rates Anthropic publishes (input, 5m cache write at 1.25x input, cache hit at 0.1x input, output; reasoning billed at the output rate), so cost accounting on the dashboard and per-request usage events stop under- or over-reporting Claude Code spend. (thanks @chulanpro5)
+- **fix(executors): sanitize Anthropic-shape content parts before GitHub Copilot `/chat/completions`** — Claude models on GitHub Copilot driven from clients like Cursor IDE (e.g. `gh/claude-sonnet-4.6`) failed with `Provider returned error: type has to be either 'image_url' or 'text' (reset after 30s)` because the client passed through Anthropic-shape content parts (`tool_use`, `tool_result`, `thinking`) untouched, and the Copilot chat-completions endpoint only accepts `text`/`image_url`. `GithubExecutor.transformRequest` now serializes any unsupported part type as `text` (preserving the model's context), drops empty parts, and collapses to `null` when an assistant message's only content was tool_calls — `tool_calls` ride alongside untouched. Codex-family models still route through `/responses` unchanged. (thanks @cngznNN)
+- **fix(sse):** refactor stall detection to reduce false positives on slow but progressing streams. (thanks @zakirkun)
+- **fix(executors): synthesize `x-opencode-request` for custom-named OpenCode providers** — the OpenCode CLI only emits the `x-opencode-*` header set when the provider id starts with `opencode`; a custom-named provider (e.g. `omniroute`) instead sends `x-session-affinity` / `x-session-id` (mapped to `x-opencode-session` since #4022) but no request-correlation id, so `x-opencode-request` was silently dropped. `OpencodeExecutor` now synthesizes a fresh `x-opencode-request` on that session-affinity fallback path so custom-named providers are not disadvantaged on the opencode.ai upstream. `x-opencode-client` / `x-opencode-project` are intentionally **not** fabricated (no valid client source — an invented value risks upstream rejection) and remain forward-only; `DefaultExecutor` is untouched. ([#4465](https://github.com/diegosouzapw/OmniRoute/issues/4465) — thanks @pizzav-xyz)
+- **fix(compression): RTK now compresses Anthropic-shape `tool_result` blocks** — `applyRtkCompression` only compressed OpenAI-shape tool results (`role:"tool"`); Anthropic-shape tool results (`tool_result` content blocks inside a `role:"user"` message) were skipped, so coding agents speaking the Anthropic Messages format got zero RTK savings even though RTK's command-aware filters (e.g. `git-status`) would have compressed the output. RTK now treats a message containing a `tool_result` block as eligible (gated by `applyToToolResults`), captures Anthropic `tool_use` blocks for command resolution, and compresses each block's inner text (string or nested text-block array) while preserving `type` + `tool_use_id` exactly — matching what `caveman`/`aggressive` already did. ([#4468](https://github.com/diegosouzapw/OmniRoute/pull/4468) — thanks @diegosouzapw)
+- **fix(dashboard): request-log auto-refresh no longer dies from a "ghost" load-more on first page load** — the request-log viewer's infinite-scroll `IntersectionObserver` uses a 200px rootMargin, so its sentinel was already intersecting on mount whenever the first page didn't fill the scroll container. That fired a `loadMore()` with no user interaction, growing the window past `PAGE_SIZE` — and auto-refresh only polls while on the first page (`limit <= pageSize`), so it stayed permanently paused (only a manual filter change re-armed it). The observer now grows the window only after a genuine user scroll (new pure `shouldTriggerInfiniteScroll` guard), and a filter change re-arms the guard, so the default first-page view resumes its ~10s auto-refresh. ([#4269](https://github.com/diegosouzapw/OmniRoute/issues/4269) — thanks @tjengbudi)
+- **fix(sse): large `/v1/chat/completions` requests no longer crash the server with a Node heap OOM** — the chat request body was parsed multiple times along the route (route guard, injection guard, handler), buffering very large payloads several times and pushing concurrent agentic traffic into an out-of-memory crash. The body is now parsed **once** at the route guard and threaded through, so each request is buffered a single time. ([#4380](https://github.com/diegosouzapw/OmniRoute/issues/4380) — thanks @NakHalal)
+- **fix(guardrails): tighten the `system_prompt_leak` heuristic to stop false positives on agent traffic** — the leak detector flagged normal agent/tool conversations as prompt-leak attempts; it now requires an additional qualifier before flagging, so legitimate agent traffic is no longer blocked. ([#4041](https://github.com/diegosouzapw/OmniRoute/issues/4041) — thanks @KooshaPari)
+- **fix(translator): drop orphan tool results on the Claude→OpenAI request path** — a `tool_result` with no preceding matching `tool_use` (orphan) produced upstream 500/502 errors for Command Code / Custom OpenAI clients on ≥3.8.26. Orphan tool results are now filtered before the request is sent. ([#4385](https://github.com/diegosouzapw/OmniRoute/issues/4385) — thanks @adityapnusantara)
+- **fix(providers): register API-key validators for Firecrawl and Jina Reader** — both providers returned "Provider validation not supported" when validating their API key; they now have proper validators registered in `SEARCH_VALIDATOR_CONFIGS`. ([#4401](https://github.com/diegosouzapw/OmniRoute/issues/4401) — thanks @ponkcore)
+- **fix(providers): generic web-cookie validator must not shadow per-provider validators** — a follow-up to the `AUTH_007` validation work (#4023): the generic web-cookie validator was matching before more specific per-provider validators, so provider-specific validation was skipped. Validator resolution now prefers the per-provider validator. ([#4467](https://github.com/diegosouzapw/OmniRoute/pull/4467) — thanks @diegosouzapw)
+- **fix(translator): inject a placeholder message when the Responses API `input[]` is empty** — a `POST /v1/responses` with `input: []` translated to `messages: []`, which every upstream Chat-Completions provider rejects (surfaced as a confusing 406); a single placeholder user message is now injected, mirroring the existing empty-string handling. ([#4393](https://github.com/diegosouzapw/OmniRoute/pull/4393) — thanks @diegosouzapw)
+- **fix(providers): serve the api.airforce live `/models` catalog instead of the stale seed** — the api.airforce provider listed a stale hard-coded seed; it now serves the upstream live `/models` catalog. ([#4395](https://github.com/diegosouzapw/OmniRoute/pull/4395) — thanks @diegosouzapw)
+- **fix(cli): non-interactive-safe prompts + `context` alias** — the CLI's `confirm()`/prompt helpers no longer hang in non-interactive (piped/CI) contexts, and a singular `context` alias is accepted alongside `contexts`; the contexts workflow is documented. ([#4439](https://github.com/diegosouzapw/OmniRoute/pull/4439), [#4397](https://github.com/diegosouzapw/OmniRoute/pull/4397) — thanks @diegosouzapw)
+- **fix(cli): `omniroute update` no longer reports a stale "latest" version from npm's cache** — `getLatestVersion()` ran `npm view omniroute version` without `--prefer-online`, so npm could serve a cached value from its HTTP cache and tell users on an older build (e.g. 3.8.30) they were already "running the latest version" even after a newer one (3.8.31) was published. The version check now passes `--prefer-online` to force npm to revalidate against the registry. ([#4376](https://github.com/diegosouzapw/OmniRoute/issues/4376) — thanks @akbardwi)
+- **fix(sse): `web_search_20250305` no longer 400s on MiniMax's Anthropic-compatible endpoint** — PR #2960 added a Claude→Claude bypass that forwards Anthropic's typed server tool `web_search_20250305` untouched, assuming the Claude-format upstream implements Anthropic server tools. MiniMax's `/anthropic` endpoint does not, so `claude → minimax` requests carrying that tool got `HTTP 400 "invalid params, function name or parameters is empty (2013)"`. `supportsNativeWebSearchFallbackBypass` now consults the (already-plumbed) `provider` and excludes providers known not to implement server tools (currently `minimax`) from the bypass, so the built-in web-search tool is converted to the `omniroute_web_search` function fallback — which MiniMax accepts as a normal function tool. ([#4481](https://github.com/diegosouzapw/OmniRoute/issues/4481) — thanks @shafqatevo)
+- **fix(command-code): pass `reasoning` / `thinking` fields through to upstream params** — Command Code requests carrying `reasoning`/`thinking` controls had those fields dropped before the upstream call, so reasoning-effort and extended-thinking settings were silently ignored; they are now forwarded to the upstream params. ([#4473](https://github.com/diegosouzapw/OmniRoute/pull/4473) — thanks @adivekar-utexas)
+- **fix(usage): keep Kiro overage-enabled accounts routable after base quota hits zero** — a Kiro account with overage enabled was excluded from routing once its base quota reached zero, even though overage billing should keep it serving; such accounts now stay routable past base-quota exhaustion. ([#4469](https://github.com/diegosouzapw/OmniRoute/issues/4469) — thanks @heaven321357 / @CleanDev-Fix)
+- **fix(providers): model-aware `supportsRedactedThinking` for mixed-format providers** — the redacted-thinking capability was resolved per provider rather than per model, so a mixed-format provider (some models support redacted thinking, others don't) got the wrong answer for some models; the check is now model-aware. ([#4479](https://github.com/diegosouzapw/OmniRoute/pull/4479) — thanks @TF0rd)
+- **fix(usage): parse numeric-string quota reset timestamps as Unix seconds/ms** — when a provider returned the quota reset timestamp as a numeric string (e.g. `"1700000000"`), `parseResetTime` passed it straight to `new Date(str)`, which returned `Invalid Date` and dropped the reset entirely (UI showed no reset). Numeric strings are now detected and treated as Unix timestamps with the same `< 1e12` seconds-vs-ms heuristic already applied to numeric values; ISO/parseable strings are untouched. Applied symmetrically in `codexUsageQuotas.parseResetTime`. (Inspired by upstream [decolua/9router#768](https://github.com/decolua/9router/pull/768) — thanks @DEYLNN)
+- **fix(usage): clearer "auth expired" message for Kiro accounts added via Google/GitHub social-auth** — a Kiro account created through the `/api/oauth/kiro/social-exchange` flow (Google or GitHub social login) uses a token format that AWS CodeWhisperer's `GetUsageLimits` quota API frequently rejects with 401/403 even when `/messages` still works. The quota card was throwing the raw upstream error blob (`Failed to fetch Kiro usage: Kiro API error (401): {…}`); social-auth accounts now get the same friendly `Kiro quota API authentication expired. Chat may still work.` message that legacy social-auth users with a stored marker already see, while Builder-ID / IDC accounts keep the existing throw-on-failure behavior so transient upstream errors don't get silently masked. (thanks @anuragg-saxenaa)
+- **fix(dashboard): Antigravity CLI Tools model picker now lists API-Key-Compatible custom providers** — the API-Key-compatible / passthrough provider groups in `ModelSelectModal` are derived from the user's `modelAliases`, but `AntigravityToolCard` was the only CLI tool card that didn't fetch `/api/models/alias` or forward the `modelAliases` prop, so a custom OpenAI-compatible provider added in OmniRoute never surfaced in the Antigravity tool's model picker — routing a custom model to Antigravity from there was impossible. The card now mirrors the pattern already used by every sibling tool card (Codex, Claude, Cline, Kilo, Droid, OpenClaw, HermesAgent). (thanks @mxskeen)
+- **fix(mitm): cert/DNS operations no longer fail with `spawn sudo ENOENT` on slim Docker images** — slim Docker base images (e.g. `node:24-trixie-slim`) do not ship `sudo`, and OmniRoute's runtime stage runs as `USER node` (UID 1000, non-root), so `execFileWithPassword("sudo", …)` failed unconditionally for any MITM operation triggered from inside the container (cert install, DNS host-file write). A new `isSudoAvailable()` probe gates the `sudo -S` wrapper; when sudo is missing and the process is not root, the underlying command runs directly (same user, no elevation) — same path already taken when running as root. Privileged operations that genuinely need elevation (system trust store, `/etc/hosts`) still error explicitly so operators can mount the CA or hosts file from the host side. (thanks @lokinh)
+
+### 🔒 Security
+
+- **fix(sse): use a crypto-secure RNG for combo/deck load-balancing selection** — random combo/deck member selection used a non-cryptographic PRNG, flagged by CodeQL (`#665`); it now uses a crypto-secure RNG. ([#4457](https://github.com/diegosouzapw/OmniRoute/pull/4457) — thanks @diegosouzapw)
+- **fix(sse): unbiased `crypto.randomInt` for combo selection (follow-up to #4457)** — the initial crypto-secure conversion used modulo reduction over the secure bytes, which introduces a small modulo bias; selection now uses `crypto.randomInt` (rejection sampling) for a uniform, unbiased distribution across combo/deck members. ([#4462](https://github.com/diegosouzapw/OmniRoute/pull/4462) — thanks @diegosouzapw)
+
+### 📝 Maintenance
+
+- **refactor(chatCore):** extract `resolveChatCoreRequestSetup` (first setup-phase slice) toward modularizing the chatCore god-file. ([#4392](https://github.com/diegosouzapw/OmniRoute/pull/4392) — thanks @diegosouzapw)
+- **refactor(chatCore):** extract the Codex service-tier resolvers into a pure `chatCore/serviceTier.ts` leaf (continues the god-file split). ([#4477](https://github.com/diegosouzapw/OmniRoute/pull/4477), [#3501](https://github.com/diegosouzapw/OmniRoute/issues/3501) — thanks @diegosouzapw)
+- **perf(dashboard):** lazy-load the usage analytics charts so the dashboard's initial bundle/paint is lighter (charts hydrate on demand). ([#4466](https://github.com/diegosouzapw/OmniRoute/pull/4466) — thanks @KooshaPari)
+- **perf(kiro):** cut request-completion hot-path CPU and cap the DB-lock event-loop block so Kiro request completion does not stall the event loop under load. ([#4459](https://github.com/diegosouzapw/OmniRoute/pull/4459) — thanks @artickc)
+- **fix(catalog):** restore-green — add OpenAI `gpt-4.1-mini`/`gpt-4.1-nano` + `o3-mini`/`o4-mini` pricing rows to keep the static-parity gate green after the registry expansion (#4394), plus the web-cookie validator shadowing fix. ([#4447](https://github.com/diegosouzapw/OmniRoute/pull/4447) — thanks @diegosouzapw)
+- **chore(quality):** reconcile file-size + complexity baselines after the `/review-prs` round, and the `server.ts` file-size baseline after the pool-tools registration (#3368). ([#4461](https://github.com/diegosouzapw/OmniRoute/pull/4461), [#4423](https://github.com/diegosouzapw/OmniRoute/pull/4423) — thanks @diegosouzapw)
+- **docs(remote-mode):** add a copy-paste end-to-end verification example. ([#4430](https://github.com/diegosouzapw/OmniRoute/pull/4430) — thanks @diegosouzapw)
+- **docs:** add operational documentation (usage/quota, database, open-sse architecture, monitoring). ([#3455](https://github.com/diegosouzapw/OmniRoute/pull/3455) — thanks @oyi77)
+
+---
+
+## [3.8.31] — 2026-06-20
+
+### ✨ New Features
+
+- **feat(translator):** Gemini accepts OpenAI `input_audio` and `audio_url` content parts. (thanks @mugnimaestra)
+- **perf(dashboard): combos UI leaf-split, Next.js config tuning, 1-click Redis & Bifrost sidecar** — delivers four of the five performance/UX tracks from the #3932 thread: the combos dashboard page is split into focused leaf components (smaller bundles, faster reloads), `next.config` is tuned for the standalone build, Redis can be provisioned in one click, and a Bifrost sidecar option is wired in. (The fifth track — chatLogHelpers extraction — was already covered upstream and dropped.) ([#4381](https://github.com/diegosouzapw/OmniRoute/pull/4381) — thanks @KooshaPari)
+
+### 🐛 Fixed
+
+- **fix(embeddings): NVIDIA NIM asymmetric embedding models inject the required `input_type`** — NVIDIA NIM asymmetric embedders (e.g. `nvidia/nv-embedqa-e5-v5`) reject requests without an `input_type` parameter with `400 "'input_type' parameter is required"`, but OmniRoute only forwarded `input_type` when the client supplied it — so callers (and OpenAI-style SDKs that don't emit the field) got a hard failure. The embedding registry now carries a model-level default (`input_type: "query"`) for the asymmetric NVIDIA model, and the embeddings handler injects a model's default params into the upstream body **only** when the client didn't already send them — a client-supplied `input_type` (e.g. `"passage"`) is respected unchanged, and symmetric models that carry no default are unaffected. ([#4341](https://github.com/diegosouzapw/OmniRoute/pull/4341) — thanks @hydraromania)
+- **fix(api): migrate the deprecated Codex `[features].codex_hooks` flag to `[features].hooks`** — Codex renamed the `codex_hooks` feature flag to `hooks`; recent Codex CLI versions ignore the old key and print a deprecation notice. When OmniRoute rewrites an existing `~/.codex/config.toml` (configuring/resetting the Codex provider) it now carries the user's intent forward by renaming `[features].codex_hooks` → `[features].hooks` (preserving its value, never clobbering an already-present `hooks`) and dropping the deprecated key. No-op when the flag is absent. ([#4342](https://github.com/diegosouzapw/OmniRoute/pull/4342) — thanks @Bian-Sh)
+- **fix(translator): same-format response path no longer leaks a `data: null` SSE event** — the streaming response translator's same-format fast path returned `[chunk]` unconditionally, so the end-of-stream null/flush signal (`chunk === null`) propagated as a literal `[null]`. Downstream this surfaced as an empty `data: null` SSE event between chunks and crashed strict clients (e.g. Factory Droid BYOK on `/v1/responses`). The fast path now drops the null flush (returns `[]`) while still passing real chunks through unchanged. ([#4344](https://github.com/diegosouzapw/OmniRoute/pull/4344) — thanks @thaitryhand)
+- **fix(translator): strip client-only assistant echo fields on the OpenAI target path (Mistral 422)** — strict OpenAI-compatible upstreams (e.g. `mistral/codestral-latest`) reject client-only assistant "echo" fields sent back as input history with `422 extra_forbidden` (the report hit `messages[].assistant.reasoning_content` via Codex `/responses`). Only `reasoning_content` was being stripped on the OpenAI target path; the sibling echo fields `reasoning`, `refusal`, `annotations` and `cache_control` leaked through and tripped the 422. They are now all dropped on the non-reasoner OpenAI target path. `audio` is deliberately preserved (OpenAI audio models reference a prior assistant audio response by id on multi-turn; Mistral never emits audio, so nothing is lost there). ([#4350](https://github.com/diegosouzapw/OmniRoute/pull/4350) — thanks @xxy9468615)
+- **fix(translator): accept AI SDK-style `{ type: "image", image: "data:…" }` content parts** — several OpenAI-input translators only recognized images shaped as `image_url.url` (or an object with `.source`/`.url`), so an AI SDK-style part where `image` is a bare data-URL **string** was silently dropped before reaching a vision provider (OpenCode is one affected client; the gap is generic). The OpenAI→Claude, OpenAI→Kiro and OpenAI→Gemini/Antigravity translators now parse a string `image` data URL into each provider's native image shape (Claude `{source:{type:"base64"}}`, Kiro `images[].source.bytes`, Gemini `inlineData`). ([#4345](https://github.com/diegosouzapw/OmniRoute/pull/4345) — thanks @mugnimaestra)
+- **fix(translator): Gemini accepts HTTP/HTTPS image URLs instead of silently dropping them** — the OpenAI→Gemini request helper (`convertOpenAIContentToParts`) discarded remote `image_url` parts (emitting only a `console.warn`) because Gemini's `inlineData` needs base64 and the synchronous helper can't fetch+encode upstream. It now uses Gemini's native `fileData: { fileUri }` part for HTTP/HTTPS URLs (the model fetches the asset itself), so vision requests carrying a URL — not a `data:` URI — reach Gemini intact. ([#4373](https://github.com/diegosouzapw/OmniRoute/pull/4373) — ported from 9router#344, thanks @diegosouzapw)
+- **fix(executors): strip `stream_options` for qwen non-streaming / thinking Claude-Code requests** — Claude-Code-compatible providers force the executor-level `stream` flag on while the outgoing body keeps the caller's original `stream: false`, so `DefaultExecutor.transformRequest` injected `stream_options: { include_usage: true }` onto a body that still said `stream: false`, and qwen rejected it with `400 "'stream_options' only set this when you set stream: true"`. The executor now strips `stream_options` whenever the body's effective `stream` is false. ([#4374](https://github.com/diegosouzapw/OmniRoute/pull/4374) — ported from 9router#663, thanks @anuragg-saxenaa / @diegosouzapw)
+- **fix(executors): don't inject `thinking` when `tool_choice` forces a tool (native Claude)** — the Claude-Code wire-image emulation injects `thinking: { type: "adaptive" }` for non-Haiku Claude models, but Anthropic rejects `thinking` when `tool_choice` forces a specific tool (`{type:"any"|"tool"}`) with `400 "Thinking may not be enabled when tool_choice forces tool use."`. Any Opus/Sonnet call that pins a tool (e.g. Claude Code's `message_user`, or agent harnesses that force a tool) hit a hard 400; the injection is now suppressed when `tool_choice` forces a tool. ([#4389](https://github.com/diegosouzapw/OmniRoute/pull/4389) — thanks @NomenAK)
+- **fix(codex): request reasoning summaries on Codex Responses requests** — Codex/OpenAI Responses can return reasoning-token accounting and empty reasoning items unless visible reasoning summaries are requested, so Codex CLI / pi.dev paths missed visible thinking text. OmniRoute now requests `reasoning.summary: "auto"` (and includes `reasoning.encrypted_content`) when reasoning is enabled — preserving an explicit client `reasoning.summary` and existing `include` entries, and skipping it for `reasoning.effort: "none"`. ([#4359](https://github.com/diegosouzapw/OmniRoute/pull/4359) — thanks @xz-dev)
+- **fix(sse): default the combo per-target timeout to 120s for fast failover** — a combo's per-target timeout inherited the full `FETCH_TIMEOUT_MS` (600s default) when the combo didn't set `targetTimeoutMs`, so a single hung/slow target (e.g. an openai-compatible upstream returning 524/504) could stall the **whole** combo for up to 10 minutes before failing over. A new `DEFAULT_COMBO_TARGET_TIMEOUT_MS = 120_000` is used as the default-when-unset in `resolveComboTargetTimeoutMs` (backward-compatible 3rd arg, wired in `phaseComboSetup`); an explicit ceiling/opt-out is preserved. ([#4365](https://github.com/diegosouzapw/OmniRoute/pull/4365) — thanks @diegosouzapw)
+- **fix(cli): Tailscale login honors `TAILSCALE_AUTHKEY` for non-interactive sign-in** — `startTailscaleLogin` built `tailscale up` without ever reading `process.env.TAILSCALE_AUTHKEY`, so on a pre-authenticated / headless daemon the login waited for an interactive auth URL and timed out (~15s). When `TAILSCALE_AUTHKEY` is set it is now passed via `--auth-key=` (as a spawn argv element — no shell interpolation) so the daemon authenticates non-interactively; when unset, behavior is unchanged. ([#4343](https://github.com/diegosouzapw/OmniRoute/pull/4343) — thanks @ipeterpetrus)
+- **fix(dashboard): OAuth modal shows the real error on a non-JSON server response** — the OAuth connect/reauth modal called `await res.json()` unconditionally, so when a build/OAuth endpoint returned a plain-text error (e.g. a `500 Internal Server Error` page) the modal threw `Unexpected token 'I'…` and hid the real failure. Two shared helpers (`parseResponseBody` / `getErrorMessage` in `src/shared/utils/api.ts`) now read the body safely (JSON when it is JSON, raw text otherwise) and surface a clean message either way; all modal fetch sites use them. ([#4351](https://github.com/diegosouzapw/OmniRoute/pull/4351) — thanks @DNNYF)
+- **fix(dashboard): a disabled connection's last error is now visible** — the provider card's error badge counts a disabled connection (`isActive === false`) that has an error (its effective status is still error/expired/unavailable), but the connection row hid the `lastError` text for disabled rows — so the operator saw the error count without being able to see what failed. The row now shows the error text whenever there is one, regardless of the active toggle. ([#4352](https://github.com/diegosouzapw/OmniRoute/pull/4352) — thanks @ntdung6868)
+- **fix(providers): the "Test Connection One-by-One" OAuth probe can no longer hang the queue forever** — the OAuth connection-test path called bare `fetch(url, { method, headers })` with no `AbortController`/signal/timeout, so when a provider's probe endpoint accepted the socket but never responded, the awaited fetch never settled and the one-by-one test queue stalled indefinitely (the API-key path was already bounded via `validateProviderApiKey`'s `timeoutMs`). Both the initial probe and the post-refresh retry are now bounded with `AbortSignal.timeout(30s)` — matching the API-key path's 30s budget — and a timed-out probe resolves as a failure with a clear `Test timed out after 30s` message in the same shape as every other test error. ([#4347](https://github.com/diegosouzapw/OmniRoute/pull/4347) — thanks @ntdung6868)
+- **fix(providers): a deactivated account is labeled distinctly from a revoked token** — a Codex connection whose OAuth refresh is fully healthy but whose ChatGPT account has been deactivated by the provider gets a `401` from the upstream API. The connection test labeled that the same as a bad credential (`Token invalid or revoked` → `upstream_auth_error`), so the operator couldn't tell a deactivated account from a revoked token. The test now reads the `401`/`403` body and, when it indicates account deactivation, classifies it as `account_deactivated` — which the dashboard already renders as "Account Deactivated". A plain auth `401` is unchanged. ([#4353](https://github.com/diegosouzapw/OmniRoute/pull/4353) — thanks @ntdung6868)
+- **fix(db): cascade-delete orphaned model aliases when a provider is removed** — deleting a custom provider removed its connections and node but left behind the imported model-alias rows (stored as `key=<alias>`, `value="<providerId>/<model>"`). Those stale aliases then blocked re-importing the same provider — the import dedup treated them as "already exists", so no new models appeared. A new `deleteModelAliasesForProvider(providerId)` DB helper drops every alias whose stored value begins with `<providerId>/` (leaving other providers and user-defined settings aliases untouched), and the provider-node DELETE handler now calls it after removing the connections and node, so a fresh import is unblocked. ([#4348](https://github.com/diegosouzapw/OmniRoute/pull/4348) — thanks @nguyenvanhuy0612)
+- **fix(api): persist `max_input_tokens` / `max_output_tokens` when adding a custom model** — `POST /api/provider-models` silently dropped the per-model token limits set in the "add custom model" form: the handler destructured the rest of the body but never read `max_input_tokens` / `max_output_tokens`, and `addCustomModel()` had no parameter for them, so the values were thrown away on write. The DB layer (`inputTokenLimit` / `outputTokenLimit`) and the `/v1/models` catalog already round-trip these fields — only the write path was missing. The validation schema now accepts the two optional limits, the handler forwards them, and `addCustomModel()` persists them so a custom model's context/output window survives into the catalog. ([#4349](https://github.com/diegosouzapw/OmniRoute/pull/4349) — thanks @codename-zen)
+- **fix(plugin): the OpenCode static-catalog plugin prefixes combo/raw model keys with the provider id** — OpenCode's static-catalog reader misdetected the `omniroute` provider: combo keys emitted as `combo/MASTER` were parsed as provider `combo` ("No credentials for provider: omniroute"), while a bare-`MASTER` form was misread as a model with no resolvable provider, and mixed `omniroute/MASTER` + bare-raw keys were rejected by OpenCode's schema. The plugin now emits every combo and raw model key prefixed with the `omniroute` provider id, emits the provider id explicitly, and drops the legacy `combo/` prefix — so the static-catalog reader detects the provider and the auth loader returns the right credentials (the catalog-fetch timeout was also raised so a cold-start server doesn't publish an empty stub). ([#4384](https://github.com/diegosouzapw/OmniRoute/pull/4384) — thanks @herjarsa)
+
+- **fix(translator): inject placeholder message when Responses API input[] is empty (prevents upstream 400)** — a client (e.g. Fabric-AI) calling `POST /v1/responses` with `input: []` used to be translated into `messages: []`, which every upstream Chat-Completions provider rejects with `400: at least one message is required` (surfaced to the client as a confusing 406). The translator now treats an empty `input[]` the same as an empty string — a placeholder user message is injected so the request is always valid. (thanks @anuragg-saxenaa)
+- **fix(embeddings): NVIDIA NIM asymmetric embedding models inject the required `input_type`** — NVIDIA NIM asymmetric embedders (e.g. `nvidia/nv-embedqa-e5-v5`) reject requests without an `input_type` parameter with `400 "'input_type' parameter is required"`, but OmniRoute only forwarded `input_type` when the client supplied it — so callers (and OpenAI-style SDKs that don't emit the field) got a hard failure. The embedding registry now carries a model-level default (`input_type: "query"`) for the asymmetric NVIDIA model, and the embeddings handler injects a model's default params into the upstream body **only** when the client didn't already send them — a client-supplied `input_type` (e.g. `"passage"`) is respected unchanged, and symmetric models that carry no default are unaffected. (thanks @hydraromania)
+
+### 🔒 Security
+
+- **fix(security): scope the OAuth callback `postMessage` to a trusted-origin allowlist** — the OAuth callback at `/callback` previously posted `{ code, state, … }` to `window.opener.postMessage(…, "*")` whenever the opener was cross-origin, so a hostile page that opened the well-known redirect URI in a popup could receive the OAuth code/state and complete the flow as the user. The wildcard fallback is replaced with iteration over a fixed allowlist (same-origin + Codex's `localhost:1455` / `127.0.0.1:1455` loopback helper); the browser silently drops `postMessage` to any opener whose origin isn't listed. ([#4372](https://github.com/diegosouzapw/OmniRoute/pull/4372) — ported from 9router#998, thanks @aeonframework / @diegosouzapw)
+- **fix(mitm): exact host membership in the MITM hosts test (CodeQL false positive)** — `tests/unit/mitm-tool-hosts.test.ts` checked host membership with `Array.includes(host)`, which CodeQL's `js/incomplete-url-substring-sanitization` heuristic misreads as a `String.includes()` URL-substring sanitization test (HIGH false positive). Switched to `.some((h) => h === host)` — identical semantics, no flagged pattern. ([#4386](https://github.com/diegosouzapw/OmniRoute/pull/4386))
+
+### 📝 Maintenance
+
+- **docs: one-time feature-documentation catch-up (v3.8.20 → v3.8.30)** — reconciled the docs with every user-facing feature shipped since v3.8.20: a new README **✨ What's New** section; new guides for [CLI integrations](docs/guides/CLI-INTEGRATIONS.md), [MITM TPROXY transparent decrypt](docs/security/MITM-TPROXY-DECRYPT.md) and [delegated Anthropic Context Editing](docs/compression/CONTEXT_EDITING.md); refreshed AUTO-COMBO (`auto/<category>:<tier>` + Arena-ELO), API_REFERENCE (`x-omniroute-no-memory`), MEMORY (int8 quantization, off-by-default), RESILIENCE (model-lockout success-decay), RTK, AGENTBRIDGE, TRAFFIC_INSPECTOR, GUARDRAILS, CLOUD_AGENT, ENVIRONMENT; regenerated PROVIDER_REFERENCE (231 providers) and synced the provider count in README/CLAUDE/AGENTS. Going forward this runs every release (generate-release step 6b). ([#4391](https://github.com/diegosouzapw/OmniRoute/pull/4391))
+- **refactor(chatCore): extract the `checkHeapPressureGuard` leaf (god-file decomposition start)** — first increment of decomposing `chatCore.ts` (~5127 LOC, the hottest path — every chat request flows through `handleChatCore`). The V8 heap-pressure guard at the top of `handleChatCore` (rejects with 503 when `heapUsed` exceeds the shed threshold) is moved to a self-contained, co-located `utils/heapPressure.ts::checkHeapPressureGuard(...)` with no behavior change. ([#4371](https://github.com/diegosouzapw/OmniRoute/pull/4371) — thanks @diegosouzapw)
+- **refactor(combo): de-dup the exhausted-target skip predicate across both dispatchers** — the byte-identical `#1731`/`#1731v2` pre-check (skip a target already exhausted on the provider/connection within a request) lived in both combo dispatchers; extracted to a shared `combo/comboPredicates.ts` helper. ([#4362](https://github.com/diegosouzapw/OmniRoute/pull/4362) — thanks @diegosouzapw)
+- **refactor(combo): de-dup the upstream-error exhaustion classification across both dispatchers** — both dispatchers ran a near-identical post-error block classifying the upstream error and updating the exhaustion Sets (`#1731` provider exhausted / `#1731v2` connection error / transient rate-limited); extracted to a shared `combo/targetExhaustion.ts::applyComboTargetExhaustion(...)`. ([#4366](https://github.com/diegosouzapw/OmniRoute/pull/4366) — thanks @diegosouzapw)
+- **chore(cli): localize CLI / scraping copy and stabilize fetch, memory & coverage handling** — localizes CLI and scraping UX copy plus the Adapta onboarding tutorial (and corrects the CLI Code page title), makes fetch retries honor the start timeout, tightens SSE/response typing, respects configured memory token limits during search, and reduces CI coverage-merge memory by merging V8 data incrementally. ([#4383](https://github.com/diegosouzapw/OmniRoute/pull/4383) — thanks @JxnLexn)
+- **test(combo): reset circuit breakers between stream-readiness cases (restore green)** — a stream-readiness fallback case failed on the release branch since the cycle-open tip due to test isolation: earlier combo-dispatch cases in the same file deliberately fail `glm` (tripping the module-level provider circuit breaker), and that OPEN state leaked into the next test so `combo.ts` skipped the model. The test now resets the circuit breakers between cases. ([#4396](https://github.com/diegosouzapw/OmniRoute/pull/4396) — thanks @diegosouzapw)
+- **chore(quality): reconcile the complexity ratchet baseline (1896 → 1900)** — absorbs the small complexity-metric increase from the v3.8.31 `/review-prs` merge batch into `quality-baseline.json` so the ratchet reflects the shipped code (no production change). ([#4410](https://github.com/diegosouzapw/OmniRoute/pull/4410) — thanks @diegosouzapw)
+- **test/gate: reconcile release-time drift surfaced by the full CI gate** — three already-merged changes left the release branch's full-CI gate red (the per-PR fast gates don't run it): the Gemini `convertOpenAIContentToParts` tests were realigned to the [#4373](https://github.com/diegosouzapw/OmniRoute/pull/4373) HTTP/HTTPS-URL `fileData` pass-through (they still asserted the old warn-and-drop behavior), the `t11` any-budget for `open-sse/executors/base.ts` was raised to 2 with a justification ([#4389](https://github.com/diegosouzapw/OmniRoute/pull/4389) compares `tool_choice` against the string literal `"any"`, not a TS `any` type), and the [#4384](https://github.com/diegosouzapw/OmniRoute/pull/4384) opencode-plugin combos test's net-assert reduction (dropping the obsolete `combo/` namespace) was allowlisted. No production behavior change. (thanks @diegosouzapw)
+
+---
+
 ## [3.8.30] — 2026-06-20
 
 ### ✨ New Features
@@ -27,6 +867,8 @@
 
 ### 🐛 Fixed
 
+- **fix(translator): Gemini accepts HTTP/HTTPS image URLs (no longer silently dropped)** — OpenAI-style `image_url` parts whose URL was `http://…` or `https://…` reached `convertOpenAIContentToParts` (the OpenAI→Gemini request helper) and were dropped with only a `console.warn`, because Gemini's `inlineData` requires base64 and the helper is synchronous (it cannot fetch + encode). Gemini's `Part` schema, however, natively accepts `fileData: { fileUri }` for remote URIs — the model fetches the asset itself. The helper now emits a `fileData` part (`mimeType: "image/*"`, inferred upstream on fetch) instead of dropping, so vision requests that pass a URL — not a data: URI — now reach Gemini intact. `data:` URIs still go through `inlineData` unchanged; unsupported schemes (e.g. `ftp:`) are still skipped. (thanks @East-rayyy)
+- **fix(security): OAuth callback page no longer relays `code`/`state` to a wildcard `postMessage` target** — the OAuth callback at `/callback` posted `{ code, state, ... }` to `window.opener.postMessage(..., "*")` whenever the opener was cross-origin (a fallback for the legitimate remote-dashboard + local-loopback callback scenario). A hostile page that opened the callback URL in a popup against the well-known redirect URI would therefore receive the OAuth code+state and could complete the OAuth flow as the user. The wildcard fallback is replaced with an iteration over a fixed allowlist of trusted target origins (same-origin + Codex's loopback helper at `localhost:1455` / `127.0.0.1:1455`); the browser silently drops the message for any opener whose origin is not in the list. Methods 2 (`BroadcastChannel`) and 3 (`localStorage`) — already in the page — still cover same-origin parents when the opener was severed by COOP. (thanks @aeonframework)
 - **fix(compliance): startup cleanup honors the dashboard data-retention setting instead of always trimming to 7 days** — on every restart, `cleanupExpiredLogs()` (run at startup) read retention only from the `CALL_LOG_RETENTION_DAYS` / `APP_LOG_RETENTION_DAYS` env vars, which default to **7 days** when unset, and trimmed `usage_history` (the Usage Analysis data) before the dashboard-based `runAutoCleanup()` — which respects the configured retention — ever ran. So a dashboard "Data Retention" of 90 days was silently overridden and the Usage Analysis page only ever showed the last 7 days after a restart. Retention now follows the precedence **explicit env var → dashboard DB setting → 7-day default**, per table (`usage_history`→`usageHistory`, `call_logs`/`proxy_logs`/`request_detail_logs`→`callLogs`, `mcp_tool_audit`→`mcpAudit`); an operator who sets the env var still wins, and non-DB deployments still fall back to it. ([#4354](https://github.com/diegosouzapw/OmniRoute/issues/4354) — thanks @akbardwi)
 - **fix(providers): bailian-coding-plan static fallback catalog matches the registry (10 models)** — the provider-model sweep (#4324) added four current Model Studio coding-plan models (`qwen3.7-plus`, `qwen3-coder-plus`, `qwen3-coder-next`, `glm-4.7`) to the `bailian-coding-plan` registry entry but missed the static fallback mirror in `staticModels.ts`, which still listed only the older six. The static catalog (served when live discovery is unavailable) therefore diverged from the registry, and the existing static↔registry parity test went red on the release branch (only surfacing when test-impact analysis happened to select it). The static mirror now carries all ten models in registry order, restoring parity. ([#4324](https://github.com/diegosouzapw/OmniRoute/pull/4324))
 - **fix(executors): ArenaLLM accepts LMArena's split Supabase SSR auth cookie** — LMArena migrated to `@supabase/ssr` chunked auth cookies: the single `arena-auth-prod-v1` cookie is now empty and the real session is split across `arena-auth-prod-v1.0`, `arena-auth-prod-v1.1`, … (ascending). A user who pasted the (now-empty) single cookie therefore sent an empty session and upstream rejected it as "invalid cookie". The LMArena executor now reconstructs the single cookie from its chunks — reading `.0`, `.1`, … in ascending numeric order until one is missing and concatenating their raw values (`@supabase/ssr`'s `combineChunks` rule: plain `join("")`, no base64-decode, no JSON-parse, the `base64-` prefix kept verbatim) — while preserving the rest of the pasted jar. A non-empty single cookie is still forwarded unchanged (back-compat). The credential UX now instructs pasting the **full Cookie header** and tracks the `.0`/`.1` storage keys. ([#4271](https://github.com/diegosouzapw/OmniRoute/issues/4271) — thanks @caussao)
@@ -42,7 +884,7 @@
 - **fix(providers): Cloudflare Workers AI model discovery shows model names, not UUIDs** — importing a Cloudflare Workers AI key listed models with internal UUID identifiers (e.g. `429b9e8b-d99e-…`) instead of their usable slugs (`@cf/meta/llama-3.1-8b-instruct`). Cloudflare's `/ai/models/search` returns `{ id: "<uuid>", name: "@cf/…" }`, and discovery was passing the raw objects through — so the UUID `id` became the callable model id. The `cloudflare-ai` discovery now maps each result's `name` → id, surfacing the real `@cf/…` model ids. ([#4259](https://github.com/diegosouzapw/OmniRoute/issues/4259) — thanks @FerLuisxd)
 - **fix(translator): clamp Responses API `call_id` to 64 characters** — the OpenAI Responses API rejects `call_id` values longer than 64 characters with a 400. Long upstream tool-call ids (some clients emit ids well over the limit) are now clamped deterministically on both the `function_call` item and its matching `function_call_output`, so the pair stays matched through the orphaned-output filter and the request is accepted. (thanks @anuragg-saxenaa, @ngapngap)
 - **fix(oauth): GitHub Copilot token refresh now sends the public client_id** — the `github` provider config never carried a `clientId`, so GitHub OAuth `refresh_token` exchanges either omitted `client_id` or sent the literal string `undefined` (and a bogus `client_secret=undefined`), which GitHub rejects — leaving a Copilot connection stuck once its short-lived token expired and the long-lived refresh path was needed. The provider now resolves its public device-flow `client_id` from the embedded public credential and omits `client_secret` entirely (GitHub's Copilot app is a public client with no secret). (thanks @baslr)
-- **fix(translator): a tool property named `pattern` survives Gemini/Antigravity schema sanitization** — the Gemini schema sanitizer strips JSON-Schema constraint keywords Gemini rejects (`pattern`, `minLength`, …) at every nesting level, but it also deleted any tool **property** literally *named* one of those keywords. glob/grep tools declare a property called `pattern`, so on `ag/*` (Antigravity) backends that argument (and its `required` entry) was silently dropped, breaking the tools. Keyword stripping is now position-aware: it only removes constraint keywords at the schema-node level and never against the user-defined names inside a `properties` map. A genuine string-level `pattern` *constraint* is still stripped. (thanks @youthanh)
+- **fix(translator): a tool property named `pattern` survives Gemini/Antigravity schema sanitization** — the Gemini schema sanitizer strips JSON-Schema constraint keywords Gemini rejects (`pattern`, `minLength`, …) at every nesting level, but it also deleted any tool **property** literally _named_ one of those keywords. glob/grep tools declare a property called `pattern`, so on `ag/*` (Antigravity) backends that argument (and its `required` entry) was silently dropped, breaking the tools. Keyword stripping is now position-aware: it only removes constraint keywords at the schema-node level and never against the user-defined names inside a `properties` map. A genuine string-level `pattern` _constraint_ is still stripped. (thanks @youthanh)
 - **fix(translator): MCP `namespace` tools flatten to individual functions on the Responses→Chat path** — when a Codex CLI client routes a Responses-API request to a non-Codex backend (e.g. `kr/claude-opus-4.7`), each MCP server is declared as a `namespace` tool (`{ type:"namespace", name, tools:[…] }`). The Responses→Chat translator had no `namespace` branch, so the whole group collapsed into a single empty-schema function named `mcp__<server>__` and every MCP call returned `unsupported call: mcp__<server>__`, breaking all MCP-based workflows (context7, codegraph, custom MCPs) for that combination. The translator now expands a namespace into one Chat function per sub-tool (preserving each sub-tool's name and parameters); an empty namespace yields no tools instead of a broken placeholder. The native Codex passthrough path was already correct. (thanks @V13t4nh)
 - **fix(cli): the active remote-context credential wins over an ambient `OMNIROUTE_API_KEY`** — when a remote context is selected, its scoped access token now takes precedence over an `OMNIROUTE_API_KEY` present in the environment, so the connected remote is targeted as expected. ([#4364](https://github.com/diegosouzapw/OmniRoute/pull/4364))
 - **fix(cli): wire the `contexts` command into the CLI program** — the `omniroute contexts` command (list/switch saved remote contexts) was implemented but never registered, so it was unreachable; it is now wired into the CLI program. ([#4369](https://github.com/diegosouzapw/OmniRoute/pull/4369))
@@ -92,6 +934,7 @@
 
 - **fix(deps): bump undici to 7.28.0 and dompurify to 3.4.11 (security)** — addresses the undici SOCKS5-TLS / cache advisories and the dompurify advisory. ([#4306](https://github.com/diegosouzapw/OmniRoute/pull/4306))
 - **chore(deps): bump actions/checkout from 4 to 7** — CI checkout-action update. ([#4297](https://github.com/diegosouzapw/OmniRoute/pull/4297))
+- **fix(executors): strip `stream_options` for qwen non-streaming / thinking-mode Claude Code requests** — Claude-Code-compatible providers force the executor-level `stream` flag on via `upstreamStream = stream || isClaudeCodeCompatible` (`open-sse/handlers/chatCore.ts`), but the outgoing body keeps the caller's original `stream: false`. The shared `stream && targetFormat === "openai"` branch in `DefaultExecutor.transformRequest` then injected `stream_options: { include_usage: true }` onto a body that still said `stream: false`, and qwen upstream rejected it with `400 "'stream_options' only set this when you set stream: true"`. Same rejection when the body carries `thinking` / `enable_thinking`. The qwen branch now skips the injection (and strips any client-sent `stream_options`) when the body explicitly says `stream: false` or requests thinking, leaving regular qwen streaming requests with the usage injection intact. (thanks @anuragg-saxenaa)
 
 ---
 
@@ -1347,7 +2190,7 @@ And thank you to the OmniRoute community for the bug reports, reproductions, and
   `tests/e2e/traffic-inspector.spec.ts`, `tests/e2e/agent-bridge-traffic-cross.spec.ts`
   (skip-gated on CI by `RUN_AGENT_BRIDGE_E2E` / `RUN_TRAFFIC_INSPECTOR_E2E` / `RUN_CROSS_E2E`).
 - **Documentation** — `docs/frameworks/AGENTBRIDGE.md` and `docs/frameworks/TRAFFIC_INSPECTOR.md`;
-  `docs/architecture/REPOSITORY_MAP.md` updated; `docs/reference/openapi.yaml` updated with
+  `docs/architecture/REPOSITORY_MAP.md` updated; `docs/openapi.yaml` updated with
   ~28 new routes and 20+ new schemas.
 - **i18n:** translate Ukrainian (uk-UA) menu and UI strings, plus complete uk-UA UI coverage (#2981 / #2988 — thanks @Lion-killer)
 - **providers:** add SiliconFlow endpoint selector (#2975 — thanks @xz-dev)

CLAUDE.md

@@ -35,22 +35,22 @@ For full test matrix, see `CONTRIBUTING.md` → "Running Tests". For deep archit
 
 ## Project at a Glance
 
-**OmniRoute** — unified AI proxy/router. One endpoint, 227 LLM providers, auto-fallback.
+**OmniRoute** — unified AI proxy/router. One endpoint, 237 LLM providers, auto-fallback.
 
-| Layer         | Location                | Purpose                                                                                                                                |
-| ------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
-| API Routes    | `src/app/api/v1/`       | Next.js App Router — entry points                                                                                                      |
-| Handlers      | `open-sse/handlers/`    | Request processing (chat, embeddings, etc)                                                                                             |
-| Executors     | `open-sse/executors/`   | Provider-specific HTTP dispatch                                                                                                        |
-| Translators   | `open-sse/translator/`  | Format conversion (OpenAI↔Claude↔Gemini)                                                                                               |
-| Transformer   | `open-sse/transformer/` | Responses API ↔ Chat Completions                                                                                                       |
-| Services      | `open-sse/services/`    | Combo routing, rate limits, caching, etc                                                                                               |
-| Database      | `src/lib/db/`           | SQLite domain modules (83 files, 97 migrations)                                                                                        |
-| Domain/Policy | `src/domain/`           | Policy engine, cost rules, fallback logic                                                                                              |
-| MCP Server    | `open-sse/mcp-server/`  | 87 tools (33 base + memory/skill/notion/obsidian/gamification/plugin modules), 3 transports (stdio / SSE / Streamable HTTP), 30 scopes |
-| A2A Server    | `src/lib/a2a/`          | JSON-RPC 2.0 agent protocol                                                                                                            |
-| Skills        | `src/lib/skills/`       | Extensible skill framework                                                                                                             |
-| Memory        | `src/lib/memory/`       | Persistent conversational memory                                                                                                       |
+| Layer         | Location                | Purpose                                                                                                                                                |
+| ------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| API Routes    | `src/app/api/v1/`       | Next.js App Router — entry points                                                                                                                      |
+| Handlers      | `open-sse/handlers/`    | Request processing (chat, embeddings, etc)                                                                                                             |
+| Executors     | `open-sse/executors/`   | Provider-specific HTTP dispatch                                                                                                                        |
+| Translators   | `open-sse/translator/`  | Format conversion (OpenAI↔Claude↔Gemini)                                                                                                               |
+| Transformer   | `open-sse/transformer/` | Responses API ↔ Chat Completions                                                                                                                       |
+| Services      | `open-sse/services/`    | Combo routing, rate limits, caching, etc                                                                                                               |
+| Database      | `src/lib/db/`           | SQLite domain modules (94 files, 106 migrations)                                                                                                       |
+| Domain/Policy | `src/domain/`           | Policy engine, cost rules, fallback logic                                                                                                              |
+| MCP Server    | `open-sse/mcp-server/`  | 94 tools (34 base + memory/skill/agentSkill/pool/notion/obsidian/gamification/plugin modules), 3 transports (stdio / SSE / Streamable HTTP), 30 scopes |
+| A2A Server    | `src/lib/a2a/`          | JSON-RPC 2.0 agent protocol                                                                                                                            |
+| Skills        | `src/lib/skills/`       | Extensible skill framework                                                                                                                             |
+| Memory        | `src/lib/memory/`       | Persistent conversational memory                                                                                                                       |
 
 Monorepo: `src/` (Next.js 16 app), `open-sse/` (streaming engine workspace), `electron/` (desktop app), `tests/`, `bin/` (CLI entry point).
 
@@ -72,7 +72,7 @@ Client → /v1/chat/completions (Next.js route)
 
 API routes follow a consistent pattern: `Route → CORS preflight → Zod body validation → Optional auth (extractApiKey/isValidApiKey) → API key policy enforcement → Handler delegation (open-sse)`. No global Next.js middleware — interception is route-specific.
 
-**Combo routing** (`open-sse/services/combo.ts`): 15 strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, reset-aware, reset-window, strict-random, auto, lkgp, context-optimized, context-relay). Each target calls `handleSingleModel()` which wraps `handleChatCore()` with per-target error handling and circuit breaker checks. See `docs/routing/AUTO-COMBO.md` for the 9-factor Auto-Combo scoring and `docs/architecture/RESILIENCE_GUIDE.md` for the 3 resilience layers.
+**Combo routing** (`open-sse/services/combo.ts`): 17 strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, reset-aware, reset-window, headroom, strict-random, auto, lkgp, context-optimized, context-relay, fusion). Each target calls `handleSingleModel()` which wraps `handleChatCore()` with per-target error handling and circuit breaker checks. The `fusion` strategy is the exception: it fans out to a panel of models in parallel, then a judge model synthesizes one final answer (`open-sse/services/fusion.ts`). See `docs/routing/AUTO-COMBO.md` for the 12-factor Auto-Combo scoring + the full strategy table and `docs/architecture/RESILIENCE_GUIDE.md` for the 3 resilience layers.
 
 ---
 
@@ -311,7 +311,7 @@ connection continue serving other models.
 4. Create 7 API endpoints under `src/app/api/services/{name}/` (`_lib.ts`, `install`, `start`, `stop`, `restart`, `update`, `status`, `auto-start`). All delegate errors through `createErrorResponse()`. The shared `logs` endpoint is already wired via `[name]/logs/route.ts`.
 5. Verify `/api/services/` is in `LOCAL_ONLY_API_PREFIXES` in `src/server/authz/routeGuard.ts`; add a test asserting `isLocalOnlyPath()` returns `true` for the new prefix if you add one (hard rule #17).
 6. Add a UI tab in `src/app/(dashboard)/dashboard/providers/services/tabs/` reusing `ServiceStatusCard`, `ServiceLifecycleButtons`, `ServiceLogsPanel`.
-7. Document in `docs/frameworks/EMBEDDED-SERVICES.md` (update §1 service table + §4 API reference) and `docs/reference/openapi.yaml`.
+7. Document in `docs/frameworks/EMBEDDED-SERVICES.md` (update §1 service table + §4 API reference) and `docs/openapi.yaml`.
 8. Write tests: unit (`tests/unit/services/`), integration (`tests/integration/services/`, gated by `RUN_SERVICES_INT=1`), and update `docs/ops/RELEASE_CHECKLIST.md` smoke section.
 
 ### Adding a New Guardrail / Eval / Skill / Webhook event
@@ -327,33 +327,33 @@ connection continue serving other models.
 
 For any non-trivial change, read the matching deep-dive first:
 
-| Area                                          | Doc                                                               |
-| --------------------------------------------- | ----------------------------------------------------------------- |
-| Repo navigation                               | `docs/architecture/REPOSITORY_MAP.md`                             |
-| Architecture                                  | `docs/architecture/ARCHITECTURE.md`                               |
-| Engineering reference                         | `docs/architecture/CODEBASE_DOCUMENTATION.md`                     |
-| Auto-Combo (9-factor scoring, 15 strategies)  | `docs/routing/AUTO-COMBO.md`                                      |
-| Resilience (3 mechanisms)                     | `docs/architecture/RESILIENCE_GUIDE.md`                           |
-| Reasoning replay                              | `docs/routing/REASONING_REPLAY.md`                                |
-| Skills framework                              | `docs/frameworks/SKILLS.md`                                       |
-| Memory system (FTS5 + Qdrant)                 | `docs/frameworks/MEMORY.md`                                       |
-| Cloud agents                                  | `docs/frameworks/CLOUD_AGENT.md`                                  |
-| Guardrails (PII / injection / vision)         | `docs/security/GUARDRAILS.md`                                     |
-| Public upstream credentials (Gemini/etc.)     | `docs/security/PUBLIC_CREDS.md`                                   |
-| Error message sanitization                    | `docs/security/ERROR_SANITIZATION.md`                             |
-| Evals                                         | `docs/frameworks/EVALS.md`                                        |
-| Compliance / audit                            | `docs/security/COMPLIANCE.md`                                     |
-| Webhooks                                      | `docs/frameworks/WEBHOOKS.md`                                     |
-| Authorization pipeline                        | `docs/architecture/AUTHZ_GUIDE.md`                                |
-| Stealth (TLS / fingerprint)                   | `docs/security/STEALTH_GUIDE.md`                                  |
-| Agent protocols (A2A / ACP / Cloud)           | `docs/frameworks/AGENT_PROTOCOLS_GUIDE.md`                        |
-| MCP server                                    | `docs/frameworks/MCP-SERVER.md`                                   |
-| A2A server                                    | `docs/frameworks/A2A-SERVER.md`                                   |
-| API reference + OpenAPI                       | `docs/reference/API_REFERENCE.md` + `docs/reference/openapi.yaml` |
-| Provider catalog (auto-generated)             | `docs/reference/PROVIDER_REFERENCE.md`                            |
-| Release flow                                  | `docs/ops/RELEASE_CHECKLIST.md`                                   |
-| Embedded services                             | `docs/frameworks/EMBEDDED-SERVICES.md`                            |
-| Quality gates (~48 scripts, allowlist policy) | `docs/architecture/QUALITY_GATES.md`                              |
+| Area                                          | Doc                                                     |
+| --------------------------------------------- | ------------------------------------------------------- |
+| Repo navigation                               | `docs/architecture/REPOSITORY_MAP.md`                   |
+| Architecture                                  | `docs/architecture/ARCHITECTURE.md`                     |
+| Engineering reference                         | `docs/architecture/CODEBASE_DOCUMENTATION.md`           |
+| Auto-Combo (12-factor scoring, 17 strategies) | `docs/routing/AUTO-COMBO.md`                            |
+| Resilience (3 mechanisms)                     | `docs/architecture/RESILIENCE_GUIDE.md`                 |
+| Reasoning replay                              | `docs/routing/REASONING_REPLAY.md`                      |
+| Skills framework                              | `docs/frameworks/SKILLS.md`                             |
+| Memory system (FTS5 + Qdrant)                 | `docs/frameworks/MEMORY.md`                             |
+| Cloud agents                                  | `docs/frameworks/CLOUD_AGENT.md`                        |
+| Guardrails (PII / injection / vision)         | `docs/security/GUARDRAILS.md`                           |
+| Public upstream credentials (Gemini/etc.)     | `docs/security/PUBLIC_CREDS.md`                         |
+| Error message sanitization                    | `docs/security/ERROR_SANITIZATION.md`                   |
+| Evals                                         | `docs/frameworks/EVALS.md`                              |
+| Compliance / audit                            | `docs/security/COMPLIANCE.md`                           |
+| Webhooks                                      | `docs/frameworks/WEBHOOKS.md`                           |
+| Authorization pipeline                        | `docs/architecture/AUTHZ_GUIDE.md`                      |
+| Stealth (TLS / fingerprint)                   | `docs/security/STEALTH_GUIDE.md`                        |
+| Agent protocols (A2A / ACP / Cloud)           | `docs/frameworks/AGENT_PROTOCOLS_GUIDE.md`              |
+| MCP server                                    | `docs/frameworks/MCP-SERVER.md`                         |
+| A2A server                                    | `docs/frameworks/A2A-SERVER.md`                         |
+| API reference + OpenAPI                       | `docs/reference/API_REFERENCE.md` + `docs/openapi.yaml` |
+| Provider catalog (auto-generated)             | `docs/reference/PROVIDER_REFERENCE.md`                  |
+| Release flow                                  | `docs/ops/RELEASE_CHECKLIST.md`                         |
+| Embedded services                             | `docs/frameworks/EMBEDDED-SERVICES.md`                  |
+| Quality gates (~48 scripts, allowlist policy) | `docs/architecture/QUALITY_GATES.md`                    |
 
 ---
 
@@ -388,6 +388,31 @@ Why this matters: fixing bug A while opening bug B is worse than not fixing at a
 
 ---
 
+## Planning & Research Artifacts (superpowers, deep-research)
+
+`_tasks/` is a **separate, isolated git repository** that is gitignored by the main
+repo (`.gitignore` → `_tasks/`). It is the canonical home for working artifacts —
+plans, specs/designs, research, hand-offs — so they stay **versioned in their own
+repo** instead of polluting the main OmniRoute tree.
+
+**Hard rule — never write superpowers / planning / research output under `docs/` or
+the repo root.** The superpowers skills ship with defaults that point at `docs/…`
+(`writing-plans` → `docs/superpowers/plans/`, `brainstorming` → `docs/superpowers/specs/`).
+Those defaults are **overridden here**. Whenever you invoke superpowers (or any
+plan/spec/research generator) in this project, save to `_tasks/` instead, using the
+same filename convention:
+
+| Artifact (skill)                   | Default (do NOT use)      | Save here instead                                             |
+| ---------------------------------- | ------------------------- | ------------------------------------------------------------- |
+| Plans (`writing-plans`)            | `docs/superpowers/plans/` | `_tasks/superpowers/plans/YYYY-MM-DD-<feature>.md`            |
+| Specs / design (`brainstorming`)   | `docs/superpowers/specs/` | `_tasks/superpowers/specs/YYYY-MM-DD-<topic>-design.md`       |
+| Research (`deep-research`, ad-hoc) | `docs/research/`          | `_tasks/research/…`                                           |
+| Hand-offs (`/handoff`)             | —                         | `_tasks/hands-off/<YYYY-MM-DD>_<branch>_v<versão>_sess-<id>/` |
+
+When a superpowers skill announces a path like "saved to `docs/superpowers/plans/…`",
+rewrite it to the `_tasks/…` equivalent before writing. Commit those artifacts inside
+the `_tasks/` repo (`git -C _tasks …`), never in the main repo.
+
 ## Git Workflow
 
 ```bash
@@ -419,25 +444,33 @@ own dedicated branch, and you MUST confirm the base branch with the operator bef
    `AskUserQuestion`, unless they already told you) from which branch the new worktree/branch
    should be cut. Do NOT assume `main` or "whatever I'm on" — the answer is usually the active
    `release/vX.Y.Z`, but it can be another feature/release branch. Get the base explicitly.
-2. **Create an isolated worktree + branch off that base** (never reuse the main checkout):
+2. **Create an isolated worktree + branch off that base** (never reuse the main checkout).
+   **🔴 MANDATORY PATH: every worktree lives under `.claude/worktrees/` — and nowhere else.**
+   This is the single canonical location (the same dir the native `EnterWorktree` tool uses). It
+   is gitignored AND in the `tsconfig.json` / `.dockerignore` excludes, so worktrees never leak
+   into the build scope. **Never** use `.worktrees/`, repo-root, or any other path — a worktree
+   outside `.claude/worktrees/` (a) escapes the build-scope excludes and poisons `next build` (the
+   `tsconfig` `include: **/*` globs ~70× the codebase → OOM; incident 2026-06-25) and (b) scatters
+   worktrees across two dirs.
 
    ```bash
    BASE_BRANCH="release/vX.Y.Z"          # ← the branch the operator confirmed in step 1
    TASK="feat/your-feature"               # feat/ fix/ refactor/ docs/ test/ chore/
    git fetch origin "$BASE_BRANCH"
-   git worktree add ".worktrees/${TASK##*/}" -b "$TASK" "origin/$BASE_BRANCH"
-   cd ".worktrees/${TASK##*/}"
+   git worktree add ".claude/worktrees/${TASK##*/}" -b "$TASK" "origin/$BASE_BRANCH"
+   cd ".claude/worktrees/${TASK##*/}"
    # symlink node_modules from the main checkout to skip a per-worktree npm install:
    ln -s "$(git -C <main_checkout> rev-parse --show-toplevel)/node_modules" node_modules
    ```
 
-   In Claude Code prefer the native `EnterWorktree` tool (create the worktree with the command
-   above, then call `EnterWorktree` with its `path`).
+   In Claude Code prefer the native `EnterWorktree` tool (it already creates worktrees under
+   `.claude/worktrees/`): create the worktree with the command above, then call `EnterWorktree`
+   with its `path`.
 
 3. **Work, commit, push, open the PR — all from inside the worktree.** Never `git checkout` a
    different branch inside a worktree another session might share.
 4. **Tear down only your own** worktree + branch when done, from the main checkout:
-   `git worktree remove .worktrees/<dir>` then `git branch -D <task>`. Never blanket-delete
+   `git worktree remove .claude/worktrees/<dir>` then `git branch -D <task>`. Never blanket-delete
    `fix/*`/`feat/*` — other sessions keep their own; delete only the branches you created, by name.
 5. **Never touch another session's worktree, branch, or uncommitted changes.** If `git worktree
 list` shows worktrees you didn't create, leave them alone. End every session with the main
@@ -505,6 +538,7 @@ the stale-enforcement added in Fase 6A.3.
 17. Never expose routes under `/api/services/` or `/dashboard/providers/services/*/embed/` without `isLocalOnlyPath()` classification in `src/server/authz/routeGuard.ts`. These routes can spawn child processes (`npm install`, `node`). Loopback enforcement happens unconditionally before any auth check — a leaked JWT via tunnel cannot trigger process spawning. See `docs/security/ROUTE_GUARD_TIERS.md`.
 18. Every bug fix must be validated before shipping: a failing-then-passing unit/integration test (TDD) OR a documented live test on the production VPS (192.168.0.15). A fix without either is not merged. See Testing → "Bug fix / issue triage protocol" for the full decision tree.
 19. Never develop on the shared main checkout. Every development task runs in its own git worktree on its own dedicated branch, and you MUST confirm the base branch with the operator (e.g. via `AskUserQuestion`) before creating the worktree/branch — never assume `main` or the currently checked-out branch. A `git checkout` in the shared checkout silently destroys other sessions' uncommitted work. Tear down only the worktrees/branches you created (by name, never `fix/*`/`feat/*` wildcards), leave other sessions' worktrees untouched, and end on the branch you started on (the active `release/vX.Y.Z`, never `main`). See Git Workflow → "Worktree isolation".
+20. PII redaction/sanitization is **opt-in — never on by default**. OmniRoute proxies for self-hosted/local LLMs where the operator owns the data, so mutating request/response payloads by default would silently corrupt legitimate traffic. The two data-mutating PII feature flags **MUST** keep `defaultValue: "false"` in `src/shared/constants/featureFlagDefinitions.ts`: `PII_REDACTION_ENABLED` (request-side) and `PII_RESPONSE_SANITIZATION` (response + streaming). All three application points — `src/lib/guardrails/piiMasker.ts` (request guardrail), `src/lib/piiSanitizer.ts` (response), `src/lib/streamingPiiTransform.ts` (SSE) — are gated on these flags; with both off the `pii-masker` guardrail still runs but never mutates payloads (data passes through untouched). Flipping either default to `"true"` requires explicit operator approval. The regression guard is `tests/unit/pii-opt-in-default.test.ts` (asserts both definition defaults + behavioral pass-through). Opt-in is per-operator via env or the settings/DB override (`src/lib/db/featureFlags.ts`), never a silent default. See `docs/security/GUARDRAILS.md`.
 
 ---
 

CONTRIBUTING.md

@@ -160,19 +160,31 @@ npm run test:protocols:e2e
 # Ecosystem compatibility tests
 npm run test:ecosystem
 
-# Coverage gate: 75% statements/lines/functions, 70% branches
+# Coverage gate: 60% statements/lines/functions/branches
 npm run test:coverage
 npm run coverage:report
 
 # Lint + format check
 npm run lint
 npm run check
+
+# Gated real-upstream combo smoke (requires VPS access + real provider credits)
+# Hits REAL providers — costs a little. NEVER runs in CI. Skips cleanly without the gate.
+# Needs: ssh root@192.168.0.15 access (sources a read-only DB snapshot from the VPS).
+RUN_COMBO_LIVE=1 npm run test:combo:live
+
+# Phase-3 VPS live smoke — plain Node ESM scripts, hit the live .15 server directly.
+# Requires: ssh root@192.168.0.15 access (combos created/torn down via SSH sqlite).
+# Hits REAL providers (small cost). Creates/deletes only __live_test__* combos. NEVER runs in CI.
+# REQUIRE_API_KEY=false on .15 so no API key needed, but honors COMBO_LIVE_BASE_URL / COMBO_LIVE_API_KEY if set.
+npm run test:combo:live:vps              # 7 HTTP scenarios (priority/round-robin/weighted/cost/fusion/auto + health)
+npm run test:combo:live:vps:failover     # adds a real cross-provider failover scenario (8 total)
 ```
 
 Coverage notes:
 
 - `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**`
-- Pull requests must keep the coverage gate at **75%+** statements/lines/functions and **70%+** branches
+- Pull requests must keep the coverage gate at **60%+** statements/lines/functions/branches
 - If a PR changes production code in `src/`, `open-sse/`, `electron/`, or `bin/`, it must add or update automated tests in the same PR
 - `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run
 - `npm run test:coverage:legacy` preserves the older metric for historical comparison
@@ -184,7 +196,7 @@ Before opening or merging a PR:
 
 - Run `npm run test:unit`
 - Run `npm run test:coverage`
-- Ensure the coverage gate stays at **75%+** statements/lines/functions, **70%+** branches
+- Ensure the coverage gate stays at **60%+** statements/lines/functions/branches
 - Include the changed or added test files in the PR description when production code changed
 - Check the SonarQube result on the PR when the project secrets are configured in CI
 

Dockerfile

@@ -2,12 +2,28 @@
 FROM node:24-trixie-slim AS base
 WORKDIR /app
 
+# `apt-get upgrade` pulls the security-patched versions of the Debian (trixie)
+# base-image packages at build time — clears the subset of container-scan CVEs
+# (perl / util-linux / systemd / ncurses / zlib / tar / sqlite / shadow / pam …)
+# that already have a fix published in trixie. CVEs without an upstream fix yet
+# (local-only TOCTOU, etc.) remain until the distro patches them and the image
+# is rebuilt; none are reachable from the proxy's request surface at runtime.
 RUN --mount=type=cache,target=/var/cache/apt,sharing=shared \
   --mount=type=cache,target=/var/lib/apt/lists,sharing=shared \
   apt-get update \
+  && apt-get upgrade -y \
   && apt-get install -y --no-install-recommends libsecret-1-0 ca-certificates \
   && rm -rf /var/lib/apt/lists/*
 
+# Refresh the globally-installed npm so its *bundled* node_modules (undici, tar)
+# ship the patched versions. These are npm's own internals — not application
+# dependencies (our app already resolves undici@8.5.0 / tar@7.5.16, both fixed) —
+# but the container scanner flags the stale copies under
+# /usr/local/lib/node_modules/npm/node_modules. npm is not invoked at runtime in
+# the runner stages, so this is hygiene, not an exploitable runtime path.
+RUN npm install -g npm@latest \
+  && npm cache clean --force
+
 # ── Builder ────────────────────────────────────────────────────────────────
 FROM base AS builder
 
@@ -20,6 +36,12 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=shared \
   && rm -rf /var/lib/apt/lists/*
 
 COPY package*.json ./
+# Workspace package manifests MUST be present before `npm ci` so npm materializes
+# the workspace and installs its *workspace-only* deps (e.g. safe-regex,
+# @toon-format/toon — declared in open-sse/package.json, not hoisted to root).
+# Without this, `npm ci` skips them and `npm run build` fails with "Module not
+# found" (root cause of the v3.8.39 Docker build break). workspaces = ["open-sse"].
+COPY open-sse/package.json ./open-sse/package.json
 COPY scripts/build/postinstall.mjs ./scripts/build/postinstall.mjs
 COPY scripts/build/postinstallSupport.mjs ./scripts/build/postinstallSupport.mjs
 COPY scripts/build/native-binary-compat.mjs ./scripts/build/native-binary-compat.mjs
@@ -49,8 +71,8 @@ ENV OMNIROUTE_USE_TURBOPACK=0
 # Raise the V8 heap ceiling for the build. The webpack production optimization
 # pass (forced above since Turbopack panics) needs more than V8's default ceiling
 # (~2 GB) for a codebase this size; a memory-constrained Docker build otherwise
-# dies with "FATAL ERROR: ... JavaScript heap out of memory" at `[builder] npm run
-# build` (#4076). NODE_OPTIONS propagates to the spawned `next build` child
+# dies with "FATAL ERROR: ... JavaScript heap out of memory" during the builder
+# stage (#4076). NODE_OPTIONS propagates to the spawned `next build` child
 # (build-next-isolated.mjs → resolveNextBuildEnv spreads process.env). Build-only;
 # the runtime heap is set separately on the runner stage (OMNIROUTE_MEMORY_MB).
 # Override for hosts with more/less RAM: `--build-arg OMNIROUTE_BUILD_MEMORY_MB=6144`.

README.md

@@ -6,7 +6,7 @@
 
 # 🚀 OmniRoute — The Free AI Gateway
 
-### Never stop coding. Connect every AI tool to **227 providers** — **50+ free** — through one endpoint.
+### Never stop coding. Connect every AI tool to **237 providers** — **50+ free** — through one endpoint.
 
 **Plug Claude Code, Codex, Cursor, Cline, Copilot & Antigravity into FREE Claude / GPT / Gemini. Auto-fallback.**
 <br/>
@@ -19,11 +19,11 @@
 
 <br/>
 
-[![227 AI Providers](https://img.shields.io/badge/227-AI_Providers-6C5CE7?style=for-the-badge)](#-227-ai-providers--50-free)
-[![50+ Free](https://img.shields.io/badge/50%2B-Free_Tiers-00B894?style=for-the-badge)](#-227-ai-providers--50-free)
+[![231 AI Providers](https://img.shields.io/badge/231-AI_Providers-6C5CE7?style=for-the-badge)](#-231-ai-providers--50-free)
+[![50+ Free](https://img.shields.io/badge/50%2B-Free_Tiers-00B894?style=for-the-badge)](#-231-ai-providers--50-free)
 [![1.6B Free Tokens/mo](https://img.shields.io/badge/1.6B-Free_Tokens%2Fmo-00B894?style=for-the-badge)](docs/reference/FREE_TIERS.md)
 [![Token Savings](https://img.shields.io/badge/up_to_95%25-Token_Savings-E17055?style=for-the-badge)](#%EF%B8%8F-save-1595-tokens--automatically)
-[![15 Strategies](https://img.shields.io/badge/15-Routing_Strategies-0984E3?style=for-the-badge)](#-combos--the-flagship)
+[![17 Strategies](https://img.shields.io/badge/17-Routing_Strategies-0984E3?style=for-the-badge)](#-combos--the-flagship)
 [![$0 to start](https://img.shields.io/badge/%240-To_Start-FDCB6E?style=for-the-badge&logoColor=black)](#-quick-start)
 
 <br/>
@@ -59,15 +59,15 @@
 
 <br/>
 
-[**🚀 Quick Start**](#-quick-start) • [**🎯 Combos**](#-combos--the-flagship) • [**🌐 Providers**](#-227-ai-providers--50-free) • [**🔌 CLI & MCP**](#-full-cli--a2a--mcp) • [**🗜️ Compression**](#%EF%B8%8F-save-1595-tokens--automatically) • [**🌍 Website**](https://omniroute.online)
+[**🚀 Quick Start**](#-quick-start) • [**🎯 Combos**](#-combos--the-flagship) • [**🌐 Providers**](#-231-ai-providers--50-free) • [**🔌 CLI & MCP**](#-full-cli--a2a--mcp) • [**🗜️ Compression**](#%EF%B8%8F-save-1595-tokens--automatically) • [**🌍 Website**](https://omniroute.online)
 
 [💥 The Promise](#-the-promise) • [🤔 Why](#-why-omniroute) • [🏆 What Sets Apart](#-what-sets-omniroute-apart) • [🤖 Compatible CLIs](#-compatible-clis--coding-agents) • [🖥️ Where It Runs](#%EF%B8%8F-where-omniroute-runs--anywhere) • [🔒 Private](#-private--local-first) • [🎬 In Action](#-omniroute-in-action) • [📚 Explore More](#-explore-more) • [📧 Support](#-support--community)
 
 </div>
 
 <div align="center">
-<b>🌐 Available in 40+ languages</b>
-<table>
+ <b>🌐 Available in 41+ languages</b>
+ <table>
   <tr>
     <td align="center"><a href="README.md">🇺🇸</a></td>
     <td align="center"><a href="docs/i18n/pt-BR/README.md">🇧🇷</a></td>
@@ -76,6 +76,7 @@
     <td align="center"><a href="docs/i18n/it/README.md">🇮🇹</a></td>
     <td align="center"><a href="docs/i18n/ru/README.md">🇷🇺</a></td>
     <td align="center"><a href="docs/i18n/zh-CN/README.md">🇨🇳</a></td>
+    <td align="center"><a href="docs/i18n/zh-TW/README.md">🇹🇼</a></td>
     <td align="center"><a href="docs/i18n/de/README.md">🇩🇪</a></td>
     <td align="center"><a href="docs/i18n/ja/README.md">🇯🇵</a></td>
     <td align="center"><a href="docs/i18n/ko/README.md">🇰🇷</a></td>
@@ -137,11 +138,11 @@
 
 </div>
 
-> One endpoint. **227 providers.** Never stop building — and let OmniRoute pick the cheapest one that works.
+> One endpoint. **237 providers.** Never stop building — and let OmniRoute pick the cheapest one that works.
 
 <table>
   <tr>
-    <td width="33%" valign="top"><b>🚫 Never hit limits</b><br/><sub>Auto-fallback across 227 providers in milliseconds. Quota out? Next provider takes over — zero downtime.</sub></td>
+    <td width="33%" valign="top"><b>🚫 Never hit limits</b><br/><sub>Auto-fallback across 237 providers in milliseconds. Quota out? Next provider takes over — zero downtime.</sub></td>
     <td width="33%" valign="top"><b>💸 Save up to 95% tokens</b><br/><sub>RTK + Caveman stacked compression cuts 15–95% of eligible tokens (~89% avg on tool-heavy sessions).</sub></td>
     <td width="33%" valign="top"><b>🆓 $0 to start</b><br/><sub>50+ providers with a free tier, 11 free <i>forever</i> (Kiro, Qoder, Pollinations, LongCat…). No card needed.</sub></td>
   </tr>
@@ -182,7 +183,7 @@
                           ▼
 ┌──────────────────────────────────────────────────────────┐
 │                  OmniRoute — Smart Router                  │
-│  RTK + Caveman compression · 15 routing strategies         │
+│  RTK + Caveman compression · 17 routing strategies         │
 │  Circuit breakers · TLS stealth · MCP · A2A · Guardrails   │
 └─────────────────────────┬──────────────────────────────────┘
         ┌─────────────┬────┴────────┬─────────────┐
@@ -220,7 +221,7 @@ No combo to create. Set your model to `auto` (or a variant) and OmniRoute builds
 
 ##
 
-### 🔀 Or build your own — 15 routing strategies
+### 🔀 Or build your own — 17 routing strategies
 
 | Goal                                    | Strategy / combo                                   |
 | --------------------------------------- | -------------------------------------------------- |
@@ -229,6 +230,8 @@ No combo to create. Set your model to `auto` (or a variant) and OmniRoute builds
 | 💸 Always cheapest viable model         | `cost-optimized` · `auto/cheap`                    |
 | 🧠 Hand off long context between models | `context-relay` · `context-optimized`              |
 | 🎲 Randomized / privacy routing         | `random` · `strict-random`                         |
+| 🧬 Fan out to a panel + judge synthesis | `fusion`                                           |
+| 📊 Route by remaining quota headroom    | `reset-window` · `headroom`                        |
 | 🤖 Just make it smart                   | `auto` (9-factor scoring) · `lkgp` · `reset-aware` |
 
 <sub>The Auto-Combo engine scores every candidate on **9 factors** (health, quota, cost, latency, success rate, freshness…) — see [`docs/routing/AUTO-COMBO.md`](docs/routing/AUTO-COMBO.md).</sub>
@@ -262,20 +265,20 @@ Result: 4 layers of fallback = zero downtime
 
 </div>
 
-| Feature                                | OmniRoute                                                   | Other routers |
-| -------------------------------------- | ----------------------------------------------------------- | ------------- |
-| 🌐 Providers                           | **227**                                                     | 20–100        |
-| 🆓 Free providers                      | **50+ (11 free forever)**                                   | 1–5           |
-| 🔀 Routing strategies                  | **15** (priority, weighted, cost-optimized, context-relay…) | 1–3           |
-| 🗜️ Token compression                   | **RTK + Caveman stacked (15–95%)**                          | None / 20–40% |
-| 🧰 Built-in MCP server                 | **87 tools, 3 transports, 30 scopes**                       | Rare          |
-| 🤝 A2A agent protocol                  | **6 skills, JSON-RPC 2.0**                                  | None          |
-| 🧠 Memory (FTS5 + vector)              | **Yes**                                                     | Rare          |
-| 🛡️ Guardrails (PII, injection, vision) | **Yes**                                                     | Rare          |
-| ☁️ Cloud agents                        | **Codex, Devin, Jules**                                     | None          |
-| 🥷 TLS fingerprint stealth             | **JA3/JA4 via wreq-js**                                     | None          |
-| 🖥️ Multi-platform                      | **Web · Desktop · Termux · PWA**                            | Web only      |
-| 🌍 i18n                                | **42 locales**                                              | 0–4           |
+| Feature                                | OmniRoute                                                           | Other routers |
+| -------------------------------------- | ------------------------------------------------------------------- | ------------- |
+| 🌐 Providers                           | **231**                                                             | 20–100        |
+| 🆓 Free providers                      | **50+ (11 free forever)**                                           | 1–5           |
+| 🔀 Routing strategies                  | **17** (priority, weighted, cost-optimized, context-relay, fusion…) | 1–3           |
+| 🗜️ Token compression                   | **RTK + Caveman stacked (15–95%)**                                  | None / 20–40% |
+| 🧰 Built-in MCP server                 | **87 tools, 3 transports, 30 scopes**                               | Rare          |
+| 🤝 A2A agent protocol                  | **6 skills, JSON-RPC 2.0**                                          | None          |
+| 🧠 Memory (FTS5 + vector)              | **Yes**                                                             | Rare          |
+| 🛡️ Guardrails (PII, injection, vision) | **Yes**                                                             | Rare          |
+| ☁️ Cloud agents                        | **Codex, Devin, Jules**                                             | None          |
+| 🥷 TLS fingerprint stealth             | **JA3/JA4 via wreq-js**                                             | None          |
+| 🖥️ Multi-platform                      | **Web · Desktop · Termux · PWA**                                    | Web only      |
+| 🌍 i18n                                | **42 locales**                                                      | 0–4           |
 
 <sub>📊 Detailed comparison vs LiteLLM, OpenRouter & Portkey → [`docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md`](docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md)</sub>
 
@@ -283,6 +286,28 @@ Result: 4 layers of fallback = zero downtime
 
 <div align="center">
 
+# ✨ What's New
+
+</div>
+
+> Recent highlights from **v3.8.20 → v3.8.39**. Full history in [`CHANGELOG.md`](CHANGELOG.md).
+
+- **⚖️ Quota-Share routing** — a dedicated combo strategy that spreads load across accounts by _available quota_: Deficit-Round-Robin scheduling, per-connection `max_concurrent` with cooldown-wait queueing, multi-window usage buckets (5h / 7d / per-model), per-(key,model) caps, session stickiness for prompt-cache integrity, and proactive saturation from upstream token-usage headers. → [Resilience Guide](docs/architecture/RESILIENCE_GUIDE.md)
+- **🤖 One-command CLI/agent setup** — a dedicated `setup-*` command configures each coding tool to route through OmniRoute (Claude Code, Codex, Cline, Continue, Cursor, Roo Code, Kilo Code, Crush, Goose, Qwen Code, Aider, OpenCode); `omniroute launch` / `omniroute launch-codex` are zero-config launchers. → [CLI Integrations](docs/guides/CLI-INTEGRATIONS.md)
+- **🛰️ Remote mode** — drive a remote OmniRoute from any machine with scoped access tokens (`omniroute connect` / `omniroute contexts` / `omniroute tokens`), plus an `omniroute login antigravity` helper that runs Google "native/desktop" OAuth on your own machine and pastes a credential blob into a remote/VPS install (where the loopback redirect is unreachable). → [Remote Mode](docs/guides/REMOTE-MODE.md)
+- **🧭 Smarter auto-routing** — OpenRouter-style `auto/<category>:<tier>` combos (e.g. `auto/coding:fast`, `auto/reasoning:pro`), a **Fusion** strategy (fan out to a panel of models in parallel, then synthesize via a judge), **task-aware routing** (best-fit connection per task type), per-request `X-Route-Model` override, live Arena-ELO + models.dev model intelligence, per-step account allowlists, provider-wildcard combo steps, nested combo-ref execution, sticky weighted selection, and `web_search`-aware routing. → [Auto-Combo](docs/routing/AUTO-COMBO.md)
+- **🗜️ Pluggable compression** — an async pipeline of **9 composable engines** with Compression Studios, an LLMLingua-2 ONNX engine and a heuristic/SLM two-tier **Ultra**, RTK, delegated Anthropic Context Editing, **Output Styles** (output-axis steering: terse-prose / less-code / terse-CJK), an **adaptive context-budget dial** (escalate only as far as needed to fit the context window), per-request `x-omniroute-compression` control, an opt-in offline eval harness, one-click **Headroom** proxy lifecycle management from the dashboard (Docker sidecar supported), a synthetic **compression playground** (Play lanes + A/B Compare with USD-capped fidelity verdicts), an opt-in **per-step fidelity gate** that rejects a lossy engine before it degrades the prompt, a **best-of-N candidate encoder** (GCF vs TOON — keep whichever is shorter, with an A/B bytes/token table in the studio), **CCR ranged/grep/stats retrieval** (pull an exact byte/line slice or summary of a stored block instead of re-expanding it), and a unified panel with named profiles + an active-profile selector. → [Compression](docs/compression/COMPRESSION_ENGINES.md)
+- **🕵️ Transparent MITM decrypt (TPROXY)** — capture & translate traffic from CLIs that ignore proxy env vars, with a per-SNI certificate authority and a trust-store installer. → [MITM/TPROXY](docs/security/MITM-TPROXY-DECRYPT.md)
+- **💸 Cost telemetry everywhere** — `X-OmniRoute-*` cost/usage headers on every endpoint (including media), a non-token cost engine, a cache-HIT `X-OmniRoute-Cost-Saved` header, and per-key USD spend quotas. → [API Reference](docs/reference/API_REFERENCE.md)
+- **🧠 Memory you control** — opt-in int8 vector quantization (Qdrant + sqlite-vec), memory off by default, and a per-request `x-omniroute-no-memory` header. → [Memory](docs/frameworks/MEMORY.md)
+- **🛡️ Security** — a prompt-injection guard across every LLM route (backed by a red-team suite), plus a free DuckDuckGo last-resort web search. → [Guardrails](docs/security/GUARDRAILS.md)
+- **🤝 More providers & agents** — Cursor Cloud Agent (a 4th cloud agent), CodeBuddy CN (`copilot.tencent.com`), a Google Flow video-generation provider, new gateways **DGrid** and **Pioneer AI** (Fastino Labs), inbound **xAI Grok** translators plus **Grok Build (xAI)** with an OAuth import-token flow, GPT-4 / GPT-4o-mini on the GitHub Copilot provider, multi-model **Factory Droid**, **ZenMux Free** (session-cookie free tier), **Alibaba DashScope** text-to-video (`wan2.7-t2v`), a refreshed 237-provider catalog (OrcaRouter, Wafer AI, OpenAdapter, dit.ai, TokenRouter, …), Vertex AI media generation (speech / transcription / music / video), and one-click account import from CLIProxyAPI (`~/.cli-proxy-api/`). → [Providers](docs/reference/PROVIDER_REFERENCE.md)
+- **⚡ Local performance & infra** — a one-click local Redis launcher (`omniroute redis up`, plus a dashboard Redis panel), one-click **Cloudflare Workers** and **Deno Deploy** relay deployers wired into the proxy pool, and an optional Bifrost Go sidecar that offloads the hottest relay path (`BIFROST_BASE_URL`, with automatic fallback to the TypeScript path on timeout). → [Environment](docs/reference/ENVIRONMENT.md)
+
+<br/>
+
+<div align="center">
+
 # 🤖 Compatible CLIs & Coding Agents
 
 > One config — `http://localhost:20128/v1` — and **every** AI IDE or CLI runs on free & low-cost models.
@@ -292,7 +317,6 @@ Result: 4 layers of fallback = zero downtime
   <tr>
     <td align="center" width="120"><a href="https://github.com/anthropics/claude-code"><img src="./public/providers/claude.svg" width="52" alt="Claude Code"/><br/><b>Claude Code</b></a></td>
     <td align="center" width="120"><a href="https://github.com/openai/codex"><img src="./public/providers/codex.svg" width="52" alt="Codex CLI"/><br/><b>Codex CLI</b></a></td>
-    <td align="center" width="120"><a href="https://github.com/google-gemini/gemini-cli"><img src="./public/providers/gemini-cli.svg" width="52" alt="Gemini CLI"/><br/><b>Gemini CLI</b></a></td>
     <td align="center" width="120"><img src="./public/providers/cursor.png" width="52" alt="Cursor"/><br/><b>Cursor</b></td>
     <td align="center" width="120"><img src="./public/providers/copilot.png" width="52" alt="Copilot"/><br/><b>Copilot</b></td>
     <td align="center" width="120"><img src="./public/providers/continue.png" width="52" alt="Continue"/><br/><b>Continue</b></td>
@@ -320,11 +344,11 @@ Result: 4 layers of fallback = zero downtime
 
 <div align="center">
 
-# 🌐 227 AI Providers — 50+ Free
+# 🌐 231 AI Providers — 50+ Free
 
 </div>
 
-> The most complete catalog of any open-source router: **227 providers**, **50+ with a free tier**, **11 free forever**.
+> The most complete catalog of any open-source router: **237 providers**, **50+ with a free tier**, **11 free forever**.
 
 <div align="center">
 
@@ -339,7 +363,6 @@ Result: 4 layers of fallback = zero downtime
   </tr>
   <tr>
     <td align="center" width="150"><img src="https://img.shields.io/badge/Cloudflare_AI-F38020?style=flat-square&logo=cloudflare&logoColor=white" alt="Cloudflare AI"/><br/><sub>50+ models<br/>10K neurons/day</sub></td>
-    <td align="center" width="150"><img src="https://img.shields.io/badge/Gemini_CLI-8E75B2?style=flat-square&logo=googlegemini&logoColor=white" alt="Gemini CLI"/><br/><sub>gemini-3-flash<br/>180K/mo free</sub></td>
     <td align="center" width="150"><img src="https://img.shields.io/badge/NVIDIA_NIM-76B900?style=flat-square&logo=nvidia&logoColor=white" alt="NVIDIA NIM"/><br/><sub>129 models<br/>~40 RPM free</sub></td>
     <td align="center" width="150"><img src="https://img.shields.io/badge/Cerebras-F15A29?style=flat-square" alt="Cerebras"/><br/><sub>Qwen3 235B<br/>1M tokens/day</sub></td>
   </tr>
@@ -358,16 +381,16 @@ Result: 4 layers of fallback = zero downtime
 
 > Same app, your machine, your rules. From a global npm install to **your phone** via Termux.
 
-| Platform                  | Install                                      | Highlights                                                |
-| ------------------------- | -------------------------------------------- | --------------------------------------------------------- |
-| 📦 **npm (global)**       | `npm install -g omniroute`                   | One command, any OS                                       |
-| 🐳 **Docker**             | `docker run … diegosouzapw/omniroute`        | Multi-arch **AMD64 + ARM64**                              |
-| 🖥️ **Desktop (Electron)** | `npm run electron:build`                     | Native window + system tray — **Windows / macOS / Linux** |
-| 💪 **ARM**                | native `arm64`                               | Raspberry Pi, ARM servers, Apple Silicon                  |
-| 📱 **Android (Termux)**   | `pkg install nodejs-lts && npx -y omniroute` | Runs **on your phone**, 24/7, no root                     |
-| 📲 **PWA**                | "Add to Home Screen"                         | Fullscreen, offline, installable from browser             |
-| 🧩 **OpenCode plugin**    | `@omniroute/opencode-provider`               | Native OpenCode integration                               |
-| 🛠️ **From source**        | `npm install && npm run dev`                 | Hack on it, contribute                                    |
+| Platform                  | Install                                  | Highlights                                                |
+| ------------------------- | ---------------------------------------- | --------------------------------------------------------- |
+| 📦 **npm (global)**       | `npm install -g omniroute`               | One command, any OS                                       |
+| 🐳 **Docker**             | `docker run … diegosouzapw/omniroute`    | Multi-arch **AMD64 + ARM64**                              |
+| 🖥️ **Desktop (Electron)** | `npm run electron:build`                 | Native window + system tray — **Windows / macOS / Linux** |
+| 💪 **ARM**                | native `arm64`                           | Raspberry Pi, ARM servers, Apple Silicon                  |
+| 📱 **Android (Termux)**   | `pkg install nodejs && npx -y omniroute` | Runs **on your phone**, 24/7, no root                     |
+| 📲 **PWA**                | "Add to Home Screen"                     | Fullscreen, offline, installable from browser             |
+| 🧩 **OpenCode plugin**    | `@omniroute/opencode-provider`           | Native OpenCode integration                               |
+| 🛠️ **From source**        | `npm install && npm run dev`             | Hack on it, contribute                                    |
 
 <sub>📖 [Docker Guide](docs/guides/DOCKER_GUIDE.md) · [Desktop](electron/README.md) · [Termux](docs/guides/TERMUX_GUIDE.md) · [PWA](docs/guides/PWA_GUIDE.md) · [OpenCode](docs/frameworks/OPENCODE.md)</sub>
 
@@ -418,6 +441,7 @@ omniroute connect 192.168.0.15            # password → scoped token, saved as
 omniroute models list                     # ← runs against the REMOTE server
 omniroute configure codex                 # ← picks a remote model, writes a local Codex profile
 omniroute tokens create --name ci --scope read   # mint narrower tokens for other machines
+omniroute contexts use default            # ← switch back to the local server
 ```
 
 Tokens are scoped `read` / `write` / `admin`; process-spawning routes stay loopback-only.
@@ -516,7 +540,20 @@ average  = 1 − (1 − 0.80) × (1 − 0.46) = 89.2%
 range    = 78.4 – 94.6%
 ```
 
-Code blocks, URLs, JSON and structured data are **always protected** by the preservation engine. Auto-trigger compression by token threshold, or assign a compression pipeline per routing combo.
+Code blocks, URLs, JSON and structured data are **always protected** by the preservation engine.
+
+### 🎚️ Beyond the engines — output styles, the adaptive dial & per-request control
+
+The 9 engines above shrink what goes **in**. Three more layers shape **how**, **when**, and what comes **out**:
+
+- **🪄 Output Styles** _(output-axis steering)_ — inject deterministic, cache-safe response-shaping instructions; combinable, each at `lite` / `full` / `ultra` intensity. Adding a style is a one-line registry entry:
+  - **Terse prose** — drop filler / articles / hedging; keep technical substance exact.
+  - **Less code** — "lazy senior dev" YAGNI: smallest working change, no unrequested scaffolding.
+  - **Terse CJK (文言)** — classical-Chinese ultra-terse style (locale-gated to `zh`).
+- **🎯 Adaptive context-budget** _(the dial)_ — instead of one on/off token threshold, escalate the cheapest, most-lossless engines only as far as needed to **fit the model's context window**. Policy: `reserve-output` (default, model-aware) · `percentage` · `absolute`. Mode: `floor` (guarantee fit) · `replace-autotrigger` (your explicit choice wins) · `off` (legacy threshold).
+- **🎛️ Where compression is decided** _(precedence, high → low)_ — per-request `x-omniroute-compression` header › routing-combo override › active named profile › adaptive / auto-trigger › panel default › off. The applied plan echoes back in the `X-OmniRoute-Compression: <mode>; source=<source>` response header.
+
+Auto-trigger by token threshold, flip on the adaptive dial, pin a named profile, set a one-off per request, or assign a pipeline per routing combo — whichever fits the workload. An opt-in offline **eval harness** (`npm run eval:compression`) scores fidelity vs. savings on a pinned corpus before you promote a change.
 
 📖 [`COMPRESSION_GUIDE.md`](docs/compression/COMPRESSION_GUIDE.md) · [`RTK_COMPRESSION.md`](docs/compression/RTK_COMPRESSION.md) · [`COMPRESSION_ENGINES.md`](docs/compression/COMPRESSION_ENGINES.md)
 
@@ -539,7 +576,7 @@ Dashboard at `http://localhost:20128` · API at `http://localhost:20128/v1`.
 
 **2) Connect a FREE provider (no signup)**
 
-Dashboard → **Providers** → connect **Kiro AI** (free Claude unlimited) or **OpenCode Free** (no auth) → done.
+Dashboard → **Providers** → connect **Kiro AI** (free Claude, ~50 credits/month per account) or **OpenCode Free** (no auth) → done.
 
 **3) Point your coding tool**
 
@@ -708,7 +745,7 @@ podman compose --profile base up -d
 **$0 forever:**
 
 ```
-1. kr/claude-sonnet-4.5   (Kiro — unlimited)
+1. kr/claude-sonnet-4.5   (Kiro — ~50 credits/mo per acct)
 2. if/kimi-k2-thinking    (Qoder — unlimited)
 3. pol/gpt-5              (Pollinations — no key)
 4. lc/longcat-flash-lite  (50M tok/day backup)
@@ -765,9 +802,9 @@ Compression: aggressive (~50%) → double your free quota · Cost: $0/mo
 | `DATA_DIR`        | `~/.omniroute` | Database & config storage        |
 
 **Will I be charged by OmniRoute?** No — it's free, open-source software on your machine. You only pay paid providers directly. OmniRoute has no billing system.
-**Are FREE providers really unlimited?** Yes — Kiro, Qoder, Pollinations, LongCat, Cloudflare. No catch.
+**Are FREE providers really unlimited?** Mostly — Qoder, Pollinations, LongCat, and Cloudflare are free with no per-account credit cap. Kiro is free too but capped at ~50 credits/month per account. Stack multiple free providers in a combo and auto-fallback keeps you serving for $0.
 **Will compression hurt quality?** No — it only compresses the **input**; code, URLs, JSON are always protected.
-**Does it work where AI is blocked?** Yes — 3-level proxy + 1proxy marketplace reach all 227 providers.
+**Does it work where AI is blocked?** Yes — 3-level proxy + 1proxy marketplace reach all 237 providers.
 
 📖 [User Guide](docs/guides/USER_GUIDE.md) · [API Reference](docs/reference/API_REFERENCE.md) · [Environment Config](docs/reference/ENVIRONMENT.md)
 
@@ -855,14 +892,14 @@ Compression: aggressive (~50%) → double your free quota · Cost: $0/mo
 
 ### 📘 Getting Started
 
-| Document                                       | Description                                                                   |
-| ---------------------------------------------- | ----------------------------------------------------------------------------- |
-| [User Guide](docs/guides/USER_GUIDE.md)        | Providers, combos, CLI integration, deployment                                |
-| [Setup Guide](docs/guides/SETUP_GUIDE.md)      | Full install methods, CLI tool configs, protocol setup, timeout tuning        |
-| [CLI Tools Guide](docs/reference/CLI-TOOLS.md) | Per-tool setup for Claude Code, Codex, Cursor, Cline, OpenClaw, Kilo, Copilot |
-| [Remote Mode](docs/guides/REMOTE-MODE.md)      | Drive a remote OmniRoute (VPS) from your laptop CLI via scoped access tokens   |
+| Document                                                       | Description                                                                      |
+| -------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md)                        | Providers, combos, CLI integration, deployment                                   |
+| [Setup Guide](docs/guides/SETUP_GUIDE.md)                      | Full install methods, CLI tool configs, protocol setup, timeout tuning           |
+| [CLI Tools Guide](docs/reference/CLI-TOOLS.md)                 | Per-tool setup for Claude Code, Codex, Cursor, Cline, OpenClaw, Kilo, Copilot    |
+| [Remote Mode](docs/guides/REMOTE-MODE.md)                      | Drive a remote OmniRoute (VPS) from your laptop CLI via scoped access tokens     |
 | [Claude Code Config](docs/guides/CLAUDE-CODE-CONFIGURATION.md) | Point Claude Code at OmniRoute (local/remote) with `launch` + per-model profiles |
-| [Quick Start](README.md#-quick-start)          | 3-step install → connect → configure                                          |
+| [Quick Start](README.md#-quick-start)                          | 3-step install → connect → configure                                             |
 
 ### 🔧 Operations & Deployment
 
@@ -899,7 +936,7 @@ Compression: aggressive (~50%) → double your free quota · Cost: $0/mo
 | Document                                          | Description                                         |
 | ------------------------------------------------- | --------------------------------------------------- |
 | [API Reference](docs/reference/API_REFERENCE.md)  | All endpoints with examples                         |
-| [OpenAPI Spec](docs/reference/openapi.yaml)       | OpenAPI 3.0 specification                           |
+| [OpenAPI Spec](docs/openapi.yaml)                 | OpenAPI 3.0 specification                           |
 | [MCP Server](open-sse/mcp-server/README.md)       | 87 MCP tools, IDE configs, Python/TS/Go clients     |
 | [MCP Server Guide](docs/frameworks/MCP-SERVER.md) | MCP installation, transports, and tool reference    |
 | [A2A Server](src/lib/a2a/README.md)               | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
@@ -1054,30 +1091,32 @@ OmniRoute stands on the shoulders of giants. It started as a fork of **[9router]
 
 ### 🗜️ Context & token compression — engines
 
-| Project                                                                      |    ⭐ | How it inspired OmniRoute                                                                                                                                             |
-| ---------------------------------------------------------------------------- | ----: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **[Caveman](https://github.com/JuliusBrussee/caveman)** · JuliusBrussee      | 74.5k | The viral "why use many token when few token do trick" project — its caveman-speak philosophy powers our standard compression mode and 30+ filler/condensation rules. |
-| **[RTK – Rust Token Killer](https://github.com/rtk-ai/rtk)** · rtk-ai        | 63.6k | High-performance command-output compression — inspired our RTK engine, JSON filter DSL, raw-output recovery and the stacked RTK → Caveman pipeline.                   |
-| **[headroom](https://github.com/chopratejas/headroom)** · chopratejas        | 33.6k | Reversible context-compression (SmartCrusher) — inspired our `headroom` engine and the `ccr` retrieve-marker pattern.                                                 |
-| **[LLMLingua](https://github.com/microsoft/LLMLingua)** · Microsoft          |  6.3k | Prompt-compression research (LLMLingua / LLMLingua-2) — inspired our async, code-safe, fail-open `llmlingua` engine.                                                  |
-| **[llmlingua-2-js](https://github.com/atjsh/llmlingua-2-js)** · atjsh        |    27 | The JS/ONNX port (MobileBERT / XLM-RoBERTa) used as the worker-thread backend for our LLMLingua engine.                                                               |
-| **[Troglodita](https://github.com/leninejunior/troglodita)** · Lenine Júnior |    15 | PT-BR token compression — powers our pt-BR language pack: pleonasm reduction and filler removal tuned for Brazilian-Portuguese grammar.                               |
+| Project                                                                      |    ⭐ | How it inspired OmniRoute                                                                                                                                                                                |
+| ---------------------------------------------------------------------------- | ----: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **[Caveman](https://github.com/JuliusBrussee/caveman)** · JuliusBrussee      | 74.5k | The viral "why use many token when few token do trick" project — its caveman-speak philosophy powers our standard compression mode and 30+ filler/condensation rules.                                    |
+| **[RTK – Rust Token Killer](https://github.com/rtk-ai/rtk)** · rtk-ai        | 63.6k | High-performance command-output compression — inspired our RTK engine, JSON filter DSL, raw-output recovery and the stacked RTK → Caveman pipeline.                                                      |
+| **[headroom](https://github.com/chopratejas/headroom)** · chopratejas        | 33.6k | Reversible context-compression (SmartCrusher) — inspired our `headroom` engine and the `ccr` retrieve-marker pattern.                                                                                    |
+| **[LLMLingua](https://github.com/microsoft/LLMLingua)** · Microsoft          |  6.3k | Prompt-compression research (LLMLingua / LLMLingua-2) — inspired our async, code-safe, fail-open `llmlingua` engine.                                                                                     |
+| **[llmlingua-2-js](https://github.com/atjsh/llmlingua-2-js)** · atjsh        |    27 | The JS/ONNX port (MobileBERT / XLM-RoBERTa) used as the worker-thread backend for our LLMLingua engine.                                                                                                  |
+| **[Troglodita](https://github.com/leninejunior/troglodita)** · Lenine Júnior |    15 | PT-BR token compression — powers our pt-BR language pack: pleonasm reduction and filler removal tuned for Brazilian-Portuguese grammar.                                                                  |
+| **[ponytail](https://github.com/DietrichGebert/ponytail)** · DietrichGebert  | 51.4k | The viral "lazy senior dev" YAGNI-coder skill — inspired our **less-code** Output Style: smallest-working-change steering that cuts _generated_ code (the output-axis sibling to Caveman's terse prose). |
 
 ### 🧩 Compact formats, token research & code-aware tooling
 
-| Project                                                                                        |    ⭐ | How it inspired OmniRoute                                                                                                            |
-| ---------------------------------------------------------------------------------------------- | ----: | ------------------------------------------------------------------------------------------------------------------------------------ |
-| **[TOON](https://github.com/toon-format/toon)** · toon-format                                  | 24.6k | Token-Oriented Object Notation — its columnar, header-plus-rows model shaped our tabular compaction stage.                           |
-| **[GCF – Graph Compact Format](https://github.com/blackwell-systems/gcf)** · Blackwell Systems |    11 | Schema-aware "JSON for LLMs" notation — co-inspired our lossless homogeneous-array compaction with `[N rows]` markers.               |
-| **[token-optimizer-mcp](https://github.com/ooples/token-optimizer-mcp)** · ooples              |   409 | Brotli/SQLite cache + per-session context-delta — inspired our `session-dedup` engine.                                               |
-| **[token-savior](https://github.com/Mibayy/token-savior)** · Mibayy                            |   993 | Bash-output compaction + MCP profiles — inspired our compression bail-out discipline and MCP tool-manifest reduction.                |
-| **[token-saver](https://github.com/ppgranger/token-saver)** · ppgranger                        |   103 | Content-aware, per-file-type output compression with failure-aware bail-out — validated our per-type dispatch and minimum-gain skip. |
-| **[token-optimizer](https://github.com/alexgreensh/token-optimizer)** · alexgreensh            |  1.4k | "Find the ghost tokens" — its offload + recoverable-handle pattern informed our CCR offload thinking.                                |
-| **[TokenMizer](https://github.com/Shweta-Mishra-ai/tokenmizer)** · Shweta-Mishra-ai            |     1 | A session-graph + cross-turn line-dedup blueprint that informed our session-dedup design.                                            |
-| **[mcp-compressor](https://github.com/atlassian-labs/mcp-compressor)** · Atlassian Labs        |    80 | MCP tool-schema/description compression — informed our MCP tool-manifest cardinality reduction.                                      |
-| **[RepoMapper](https://github.com/pdavis68/RepoMapper)** · pdavis68                            |   182 | Aider-style repo-map ranking — informed our repo-map / retrieval-ranking exploration.                                                |
-| **[quiet-shell-mcp](https://github.com/mrsimpson/quiet-shell-mcp)** · mrsimpson                |     4 | Declarative shell-output reduction over MCP — validated our declarative bash-output compaction.                                      |
-| **[ts-morph](https://github.com/dsherret/ts-morph)** · David Sherret                           |  6.1k | TypeScript Compiler API toolkit — inspired our parser-based comment removal that preserves string, template and regex literals.      |
+| Project                                                                                        |    ⭐ | How it inspired OmniRoute                                                                                                                                                                                      |
+| ---------------------------------------------------------------------------------------------- | ----: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **[TOON](https://github.com/toon-format/toon)** · toon-format                                  | 24.6k | Token-Oriented Object Notation — its columnar, header-plus-rows model shaped our tabular compaction stage.                                                                                                     |
+| **[GCF – Graph Compact Format](https://github.com/blackwell-systems/gcf)** · Blackwell Systems |    11 | Schema-aware "JSON for LLMs" notation — co-inspired our lossless homogeneous-array compaction with `[N rows]` markers.                                                                                         |
+| **[token-optimizer-mcp](https://github.com/ooples/token-optimizer-mcp)** · ooples              |   409 | Brotli/SQLite cache + per-session context-delta — inspired our `session-dedup` engine.                                                                                                                         |
+| **[token-savior](https://github.com/Mibayy/token-savior)** · Mibayy                            |   993 | Bash-output compaction + MCP profiles — inspired our compression bail-out discipline and MCP tool-manifest reduction.                                                                                          |
+| **[token-saver](https://github.com/ppgranger/token-saver)** · ppgranger                        |   103 | Content-aware, per-file-type output compression with failure-aware bail-out — validated our per-type dispatch and minimum-gain skip.                                                                           |
+| **[token-optimizer](https://github.com/alexgreensh/token-optimizer)** · alexgreensh            |  1.4k | "Find the ghost tokens" — its offload + recoverable-handle pattern informed our CCR offload thinking.                                                                                                          |
+| **[TokenMizer](https://github.com/Shweta-Mishra-ai/tokenmizer)** · Shweta-Mishra-ai            |     1 | A session-graph + cross-turn line-dedup blueprint that informed our session-dedup design.                                                                                                                      |
+| **[OmniCompress](https://github.com/jessefreitas/OmniCompress)** · jessefreitas                |     2 | Rust columnar-JSON + content-addressed retrieve + cross-message dedup — validated our `headroom`/`ccr`/`session-dedup` engine design and the cache-stable "compressed form is position-independent" invariant. |
+| **[mcp-compressor](https://github.com/atlassian-labs/mcp-compressor)** · Atlassian Labs        |    80 | MCP tool-schema/description compression — informed our MCP tool-manifest cardinality reduction.                                                                                                                |
+| **[RepoMapper](https://github.com/pdavis68/RepoMapper)** · pdavis68                            |   182 | Aider-style repo-map ranking — informed our repo-map / retrieval-ranking exploration.                                                                                                                          |
+| **[quiet-shell-mcp](https://github.com/mrsimpson/quiet-shell-mcp)** · mrsimpson                |     4 | Declarative shell-output reduction over MCP — validated our declarative bash-output compaction.                                                                                                                |
+| **[ts-morph](https://github.com/dsherret/ts-morph)** · David Sherret                           |  6.1k | TypeScript Compiler API toolkit — inspired our parser-based comment removal that preserves string, template and regex literals.                                                                                |
 
 ### 🧠 Memory & RAG
 

SECURITY.md

@@ -113,14 +113,14 @@ PII_REDACTION_ENABLED=true
 
 ### 🌐 Network Security
 
-| Feature                  | Description                                                      |
-| ------------------------ | ---------------------------------------------------------------- |
-| **CORS**                 | Configurable origin control (`CORS_ORIGIN` env var, default `*`) |
-| **IP Filtering**         | Allowlist/blocklist IP ranges in dashboard                       |
-| **Rate Limiting**        | Per-provider rate limits with automatic backoff                  |
-| **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s           |
-| **TLS Fingerprint**      | Browser-like TLS fingerprint spoofing to reduce bot detection    |
-| **CLI Fingerprint**      | Per-provider header/body ordering to match native CLI signatures |
+| Feature                  | Description                                                                    |
+| ------------------------ | ------------------------------------------------------------------------------ |
+| **CORS**                 | Explicit cross-origin allowlist (`CORS_ALLOWED_ORIGINS`; legacy `CORS_ORIGIN`) |
+| **IP Filtering**         | Allowlist/blocklist IP ranges in dashboard                                     |
+| **Rate Limiting**        | Per-provider rate limits with automatic backoff                                |
+| **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s                         |
+| **TLS Fingerprint**      | Browser-like TLS fingerprint spoofing to reduce bot detection                  |
+| **CLI Fingerprint**      | Per-provider header/body ordering to match native CLI signatures               |
 
 ### 🔌 Resilience & Availability
 

bin/_ops-common.sh

@@ -0,0 +1,70 @@
+# bin/_ops-common.sh — shared helpers for the OmniRoute ops runbook scripts.
+#
+# Sourced (not executed) by rollback.sh / snapshot-data.sh / restore-data.sh /
+# restore-policies.sh / cold-start-bench.sh — the self-hoster incident-recovery
+# and cold-start ops tooling. Each script documents its own contract via --help.
+#
+# Path resolution mirrors the app (src/lib/db/core.ts): the SQLite store is
+# $DATA_DIR/storage.sqlite and managed backups go to $DATA_DIR/db_backups
+# (overridable via DB_BACKUPS_DIR), so snapshots created here are interchangeable
+# with the ones the server writes on migrations.
+
+# Recompute the data-dir-derived paths. Called once on source, and again by
+# scripts that accept a --data-dir override.
+ops_set_data_dir() {
+  OMNIROUTE_DATA_DIR="$1"
+  OMNIROUTE_SQLITE="${OMNIROUTE_DATA_DIR}/storage.sqlite"
+  OMNIROUTE_BACKUPS_DIR="${DB_BACKUPS_DIR:-${OMNIROUTE_DATA_DIR}/db_backups}"
+}
+ops_set_data_dir "${DATA_DIR:-$HOME/.omniroute}"
+
+ops_log() { printf '[%s] %s\n' "${SCRIPT_NAME:-ops}" "$*" >&2; }
+ops_die() {
+  printf '[%s] ERROR: %s\n' "${SCRIPT_NAME:-ops}" "$*" >&2
+  exit 1
+}
+
+ops_require_cmd() {
+  command -v "$1" >/dev/null 2>&1 || ops_die "required command not found: $1"
+}
+
+# ops_confirm "<prompt>" — return 0 to proceed. Honors ASSUME_YES=1 (set by the
+# --yes flag) and REFUSES a destructive action on a non-interactive stdin unless
+# ASSUME_YES is set, so an unattended/CI invocation can never silently destroy data.
+ops_confirm() {
+  local prompt="$1" reply
+  if [ "${ASSUME_YES:-0}" = "1" ]; then return 0; fi
+  if [ ! -t 0 ]; then
+    ops_die "refusing a destructive action without a TTY; pass --yes to proceed non-interactively"
+  fi
+  read -r -p "$prompt [y/N] " reply
+  case "$reply" in
+    [yY] | [yY][eE][sS]) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+# ops_find_snapshot <id> — resolve a snapshot identifier (a snapshot dir name,
+# a bare timestamp/sha, or an explicit path) to a directory containing
+# storage.sqlite. Echoes the resolved dir or dies.
+ops_find_snapshot() {
+  local id="$1" cand
+  [ -n "$id" ] || ops_die "snapshot id required (a timestamp/sha, dir name, or path)"
+  for cand in \
+    "$id" \
+    "$id/" \
+    "$OMNIROUTE_BACKUPS_DIR/$id" \
+    "$OMNIROUTE_BACKUPS_DIR/snapshot_$id"; do
+    if [ -f "${cand%/}/storage.sqlite" ]; then
+      printf '%s\n' "${cand%/}"
+      return 0
+    fi
+  done
+  # Fall back to a prefix match against snapshot_* dirs (e.g. a short sha/date).
+  if [ -d "$OMNIROUTE_BACKUPS_DIR" ]; then
+    for cand in "$OMNIROUTE_BACKUPS_DIR"/snapshot_*"$id"*; do
+      [ -f "$cand/storage.sqlite" ] && { printf '%s\n' "$cand"; return 0; }
+    done
+  fi
+  ops_die "no snapshot matching '$id' under $OMNIROUTE_BACKUPS_DIR (run bin/snapshot-data.sh first)"
+}

bin/cli/api-commands/agent-skills.mjs

@@ -1,4 +1,4 @@
-// AUTO-GENERATED from docs/reference/openapi.yaml. Do not edit.
+// AUTO-GENERATED from docs/openapi.yaml. Do not edit.
 import { apiFetch } from "../api.mjs";
 import { emit } from "../output.mjs";
 import { readFileSync } from "node:fs";

bin/cli/api-commands/agentbridge.mjs

@@ -1,4 +1,4 @@
-// AUTO-GENERATED from docs/reference/openapi.yaml. Do not edit.
+// AUTO-GENERATED from docs/openapi.yaml. Do not edit.
 import { apiFetch } from "../api.mjs";
 import { emit } from "../output.mjs";
 import { readFileSync } from "node:fs";

bin/cli/api-commands/api-keys.mjs

@@ -1,4 +1,4 @@
-// AUTO-GENERATED from docs/reference/openapi.yaml. Do not edit.
+// AUTO-GENERATED from docs/openapi.yaml. Do not edit.
 import { apiFetch } from "../api.mjs";
 import { emit } from "../output.mjs";
 import { readFileSync } from "node:fs";

bin/cli/api-commands/audio.mjs

@@ -1,4 +1,4 @@
-// AUTO-GENERATED from docs/reference/openapi.yaml. Do not edit.
+// AUTO-GENERATED from docs/openapi.yaml. Do not edit.
 import { apiFetch } from "../api.mjs";
 import { emit } from "../output.mjs";
 import { readFileSync } from "node:fs";

bin/cli/api-commands/chat.mjs

@@ -1,4 +1,4 @@
-// AUTO-GENERATED from docs/reference/openapi.yaml. Do not edit.
+// AUTO-GENERATED from docs/openapi.yaml. Do not edit.
 import { apiFetch } from "../api.mjs";
 import { emit } from "../output.mjs";
 import { readFileSync } from "node:fs";

bin/cli/api-commands/cli-tools.mjs

@@ -1,4 +1,4 @@
-// AUTO-GENERATED from docs/reference/openapi.yaml. Do not edit.
+// AUTO-GENERATED from docs/openapi.yaml. Do not edit.
 import { apiFetch } from "../api.mjs";
 import { emit } from "../output.mjs";
 import { readFileSync } from "node:fs";

bin/cli/api-commands/cloud.mjs

@@ -1,4 +1,4 @@
-// AUTO-GENERATED from docs/reference/openapi.yaml. Do not edit.
+// AUTO-GENERATED from docs/openapi.yaml. Do not edit.
 import { apiFetch } from "../api.mjs";
 import { emit } from "../output.mjs";
 import { readFileSync } from "node:fs";

bin/cli/api-commands/combos.mjs

@@ -1,4 +1,4 @@
-// AUTO-GENERATED from docs/reference/openapi.yaml. Do not edit.
+// AUTO-GENERATED from docs/openapi.yaml. Do not edit.
 import { apiFetch } from "../api.mjs";
 import { emit } from "../output.mjs";
 import { readFileSync } from "node:fs";

bin/cli/api-commands/compression.mjs

@@ -1,4 +1,4 @@
-// AUTO-GENERATED from docs/reference/openapi.yaml. Do not edit.
+// AUTO-GENERATED from docs/openapi.yaml. Do not edit.
 import { apiFetch } from "../api.mjs";
 import { emit } from "../output.mjs";
 import { readFileSync } from "node:fs";

bin/cli/api-commands/embedded-services.mjs

@@ -1,4 +1,4 @@
-// AUTO-GENERATED from docs/reference/openapi.yaml. Do not edit.
+// AUTO-GENERATED from docs/openapi.yaml. Do not edit.
 import { apiFetch } from "../api.mjs";
 import { emit } from "../output.mjs";
 import { readFileSync } from "node:fs";

bin/cli/api-commands/embeddings.mjs

@@ -1,4 +1,4 @@
-// AUTO-GENERATED from docs/reference/openapi.yaml. Do not edit.
+// AUTO-GENERATED from docs/openapi.yaml. Do not edit.
 import { apiFetch } from "../api.mjs";
 import { emit } from "../output.mjs";
 import { readFileSync } from "node:fs";

bin/cli/api-commands/fallback.mjs

@@ -1,4 +1,4 @@
-// AUTO-GENERATED from docs/reference/openapi.yaml. Do not edit.
+// AUTO-GENERATED from docs/openapi.yaml. Do not edit.
 import { apiFetch } from "../api.mjs";
 import { emit } from "../output.mjs";
 import { readFileSync } from "node:fs";

bin/cli/api-commands/images.mjs

@@ -1,4 +1,4 @@
-// AUTO-GENERATED from docs/reference/openapi.yaml. Do not edit.
+// AUTO-GENERATED from docs/openapi.yaml. Do not edit.
 import { apiFetch } from "../api.mjs";
 import { emit } from "../output.mjs";
 import { readFileSync } from "node:fs";

bin/cli/api-commands/memory.mjs

@@ -1,4 +1,4 @@
-// AUTO-GENERATED from docs/reference/openapi.yaml. Do not edit.
+// AUTO-GENERATED from docs/openapi.yaml. Do not edit.
 import { apiFetch } from "../api.mjs";
 import { emit } from "../output.mjs";
 import { readFileSync } from "node:fs";

bin/cli/api-commands/messages.mjs

@@ -1,4 +1,4 @@
-// AUTO-GENERATED from docs/reference/openapi.yaml. Do not edit.
+// AUTO-GENERATED from docs/openapi.yaml. Do not edit.
 import { apiFetch } from "../api.mjs";
 import { emit } from "../output.mjs";
 import { readFileSync } from "node:fs";

bin/cli/api-commands/models.mjs

@@ -1,4 +1,4 @@
-// AUTO-GENERATED from docs/reference/openapi.yaml. Do not edit.
+// AUTO-GENERATED from docs/openapi.yaml. Do not edit.
 import { apiFetch } from "../api.mjs";
 import { emit } from "../output.mjs";
 import { readFileSync } from "node:fs";

bin/cli/api-commands/moderations.mjs

@@ -1,4 +1,4 @@
-// AUTO-GENERATED from docs/reference/openapi.yaml. Do not edit.
+// AUTO-GENERATED from docs/openapi.yaml. Do not edit.
 import { apiFetch } from "../api.mjs";
 import { emit } from "../output.mjs";
 import { readFileSync } from "node:fs";

bin/cli/api-commands/oauth.mjs

@@ -1,4 +1,4 @@
-// AUTO-GENERATED from docs/reference/openapi.yaml. Do not edit.
+// AUTO-GENERATED from docs/openapi.yaml. Do not edit.
 import { apiFetch } from "../api.mjs";
 import { emit } from "../output.mjs";
 import { readFileSync } from "node:fs";

bin/cli/api-commands/playground.mjs

@@ -1,4 +1,4 @@
-// AUTO-GENERATED from docs/reference/openapi.yaml. Do not edit.
+// AUTO-GENERATED from docs/openapi.yaml. Do not edit.
 import { apiFetch } from "../api.mjs";
 import { emit } from "../output.mjs";
 import { readFileSync } from "node:fs";

bin/cli/api-commands/pricing.mjs

@@ -1,4 +1,4 @@
-// AUTO-GENERATED from docs/reference/openapi.yaml. Do not edit.
+// AUTO-GENERATED from docs/openapi.yaml. Do not edit.
 import { apiFetch } from "../api.mjs";
 import { emit } from "../output.mjs";
 import { readFileSync } from "node:fs";

bin/cli/api-commands/provider-nodes.mjs

@@ -1,4 +1,4 @@
-// AUTO-GENERATED from docs/reference/openapi.yaml. Do not edit.
+// AUTO-GENERATED from docs/openapi.yaml. Do not edit.
 import { apiFetch } from "../api.mjs";
 import { emit } from "../output.mjs";
 import { readFileSync } from "node:fs";

bin/cli/api-commands/providers.mjs

@@ -1,4 +1,4 @@
-// AUTO-GENERATED from docs/reference/openapi.yaml. Do not edit.
+// AUTO-GENERATED from docs/openapi.yaml. Do not edit.
 import { apiFetch } from "../api.mjs";
 import { emit } from "../output.mjs";
 import { readFileSync } from "node:fs";

bin/cli/api-commands/quota.mjs

@@ -1,4 +1,4 @@
-// AUTO-GENERATED from docs/reference/openapi.yaml. Do not edit.
+// AUTO-GENERATED from docs/openapi.yaml. Do not edit.
 import { apiFetch } from "../api.mjs";
 import { emit } from "../output.mjs";
 import { readFileSync } from "node:fs";

bin/cli/api-commands/rerank.mjs

@@ -1,4 +1,4 @@
-// AUTO-GENERATED from docs/reference/openapi.yaml. Do not edit.
+// AUTO-GENERATED from docs/openapi.yaml. Do not edit.
 import { apiFetch } from "../api.mjs";
 import { emit } from "../output.mjs";
 import { readFileSync } from "node:fs";

bin/cli/api-commands/responses.mjs

@@ -1,4 +1,4 @@
-// AUTO-GENERATED from docs/reference/openapi.yaml. Do not edit.
+// AUTO-GENERATED from docs/openapi.yaml. Do not edit.
 import { apiFetch } from "../api.mjs";
 import { emit } from "../output.mjs";
 import { readFileSync } from "node:fs";

bin/cli/api-commands/settings.mjs

@@ -1,4 +1,4 @@
-// AUTO-GENERATED from docs/reference/openapi.yaml. Do not edit.
+// AUTO-GENERATED from docs/openapi.yaml. Do not edit.
 import { apiFetch } from "../api.mjs";
 import { emit } from "../output.mjs";
 import { readFileSync } from "node:fs";

bin/cli/api-commands/system.mjs

@@ -1,4 +1,4 @@
-// AUTO-GENERATED from docs/reference/openapi.yaml. Do not edit.
+// AUTO-GENERATED from docs/openapi.yaml. Do not edit.
 import { apiFetch } from "../api.mjs";
 import { emit } from "../output.mjs";
 import { readFileSync } from "node:fs";

bin/cli/api-commands/telemetry.mjs

@@ -1,4 +1,4 @@
-// AUTO-GENERATED from docs/reference/openapi.yaml. Do not edit.
+// AUTO-GENERATED from docs/openapi.yaml. Do not edit.
 import { apiFetch } from "../api.mjs";
 import { emit } from "../output.mjs";
 import { readFileSync } from "node:fs";

bin/cli/api-commands/traffic-inspector.mjs

@@ -1,4 +1,4 @@
-// AUTO-GENERATED from docs/reference/openapi.yaml. Do not edit.
+// AUTO-GENERATED from docs/openapi.yaml. Do not edit.
 import { apiFetch } from "../api.mjs";
 import { emit } from "../output.mjs";
 import { readFileSync } from "node:fs";

bin/cli/api-commands/translator.mjs

@@ -1,4 +1,4 @@
-// AUTO-GENERATED from docs/reference/openapi.yaml. Do not edit.
+// AUTO-GENERATED from docs/openapi.yaml. Do not edit.
 import { apiFetch } from "../api.mjs";
 import { emit } from "../output.mjs";
 import { readFileSync } from "node:fs";

bin/cli/api-commands/usage.mjs

@@ -1,4 +1,4 @@
-// AUTO-GENERATED from docs/reference/openapi.yaml. Do not edit.
+// AUTO-GENERATED from docs/openapi.yaml. Do not edit.
 import { apiFetch } from "../api.mjs";
 import { emit } from "../output.mjs";
 import { readFileSync } from "node:fs";

bin/cli/commands/contexts.mjs

@@ -9,7 +9,15 @@ function authLabel(c) {
   return "✗";
 }
 
-async function confirm(msg) {
+export async function confirm(msg) {
+  // Non-interactive stdin (pipe, CI, EOF) cannot answer a [y/N] prompt. Asking
+  // anyway leaves the readline question pending forever — Node then warns about an
+  // "unsettled top-level await" at exit. Decline cleanly instead and point at the
+  // non-interactive escape hatch so scripted callers fail safe rather than hang.
+  if (!process.stdin.isTTY) {
+    process.stderr.write(`${msg} [y/N] (non-interactive stdin — declined; pass --yes to confirm)\n`);
+    return false;
+  }
   const readline = await import("node:readline");
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   const answer = await new Promise((r) => rl.question(`${msg} [y/N] `, r));
@@ -26,6 +34,7 @@ function maskKey(k) {
 export function registerContexts(program) {
   const ctx = program
     .command("contexts")
+    .alias("context") // singular alias — docs/connect output historically said `context current`
     .description(t("config.contexts.description") || "Manage server contexts/profiles");
 
   ctx

bin/cli/commands/login.mjs

@@ -0,0 +1,192 @@
+import { createServer } from "node:http";
+import { randomUUID } from "node:crypto";
+
+/**
+ * `omniroute login antigravity` — local OAuth helper for remote installs.
+ *
+ * Why this exists: Google's `firstparty/nativeapp` consent for the embedded
+ * Antigravity desktop client only releases the authorization code when the
+ * loopback redirect (127.0.0.1:<port>) is REACHABLE. On a remote VPS install the
+ * loopback is unreachable, so the consent hangs forever and never emits a code —
+ * the dashboard's "paste the callback URL" fallback has nothing to paste. (The
+ * same flow works locally and over an SSH tunnel, where the loopback IS reachable.)
+ *
+ * This command runs the OAuth on the user's OWN machine — where 127.0.0.1 works —
+ * captures the code on a local loopback server, exchanges it for tokens, and
+ * prints a single-line credential blob. The user pastes that blob into the remote
+ * dashboard (Antigravity → "Paste credentials"), which decodes it, finalizes the
+ * onboarding server-side, and persists the connection.
+ *
+ * It talks ONLY to Google (no OmniRoute server needed locally), so it works even
+ * if the remote VPS is firewalled from the user's machine.
+ */
+
+const PROVIDER = "antigravity";
+
+/** Open the system browser; no-op if the optional `open` dependency is missing. */
+async function defaultOpenBrowser(url) {
+  try {
+    const { default: open } = await import("open");
+    await open(url);
+  } catch {
+    // `open` not available — the caller already printed the URL to paste manually.
+  }
+}
+
+/**
+ * Start a loopback HTTP server bound to 127.0.0.1 (NOT 0.0.0.0 — we never want to
+ * expose the callback to the LAN). Resolves to { port, waitForCallback, close }.
+ */
+function defaultStartServer(preferredPort) {
+  return new Promise((resolve, reject) => {
+    let resolveCallback;
+    const callbackPromise = new Promise((r) => {
+      resolveCallback = r;
+    });
+
+    const server = createServer((req, res) => {
+      const url = new URL(req.url, "http://127.0.0.1");
+      if (url.pathname !== "/callback" && url.pathname !== "/auth/callback") {
+        res.writeHead(404).end();
+        return;
+      }
+      const params = Object.fromEntries(url.searchParams.entries());
+      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+      res.end(
+        "<!doctype html><meta charset=utf-8><title>OmniRoute</title>" +
+          "<body style=\"font-family:system-ui;padding:2rem\">" +
+          "<h2>✅ Authorization received</h2>" +
+          "<p>Return to your terminal — you can close this tab.</p></body>"
+      );
+      resolveCallback(params);
+    });
+
+    server.on("error", reject);
+    server.listen(preferredPort || 0, "127.0.0.1", () => {
+      const { port } = server.address();
+      resolve({
+        port,
+        waitForCallback: () => callbackPromise,
+        close: () => new Promise((r) => server.close(() => r())),
+      });
+    });
+  });
+}
+
+/** Lazy-load the antigravity provider + blob codec (TS source via tsx). */
+async function loadDeps() {
+  const { antigravity } = await import("../../../src/lib/oauth/providers/antigravity.ts");
+  const { encodeCredentialBlob } = await import("../../../src/lib/oauth/credentialBlob.ts");
+  return { antigravity, encodeCredentialBlob };
+}
+
+/**
+ * Build the Google authorization request for a given loopback port. Uses a plain
+ * authorization_code grant (NO PKCE code_challenge) — matching the working flow:
+ * a code_challenge here would force the exchange to require a code_verifier.
+ */
+export async function buildAntigravityAuthRequest(port, makeState = randomUUID) {
+  const { antigravity } = await loadDeps();
+  const redirectUri = `http://127.0.0.1:${port}/callback`;
+  const state = makeState();
+  const authUrl = antigravity.buildAuthUrl(antigravity.config, redirectUri, state);
+  return { redirectUri, state, authUrl };
+}
+
+/** Exchange the captured code for raw Google tokens (no code_verifier — no PKCE). */
+export async function exchangeAntigravityCode(code, redirectUri) {
+  const { antigravity } = await loadDeps();
+  return antigravity.exchangeToken(antigravity.config, code, redirectUri);
+}
+
+/**
+ * Orchestrate the local login. Dependencies are injectable for testing; the real
+ * path uses a 127.0.0.1 loopback server, the system browser, and a live token
+ * exchange against Google. Returns the credential blob string.
+ */
+export async function runAntigravityLogin(opts = {}, deps = {}) {
+  const startServer = deps.startServer ?? defaultStartServer;
+  const openBrowser = deps.openBrowser ?? defaultOpenBrowser;
+  const exchange = deps.exchange ?? exchangeAntigravityCode;
+  const makeState = deps.makeState ?? randomUUID;
+  const print = deps.print ?? ((s) => process.stdout.write(s));
+  const log = deps.log ?? ((s) => process.stderr.write(s));
+  const { encodeCredentialBlob } = await loadDeps();
+
+  const server = await startServer(opts.port);
+  const { redirectUri, state, authUrl } = await buildAntigravityAuthRequest(server.port, makeState);
+
+  log(`\nOpen this URL to authorize Antigravity (it will open automatically):\n\n  ${authUrl}\n\n`);
+  if (opts.browser !== false) await openBrowser(authUrl);
+  log("Waiting for Google to redirect back to the local loopback...\n");
+
+  const timeoutMs = opts.timeout ?? 300000;
+  let timer;
+  let params;
+  try {
+    params = await Promise.race([
+      server.waitForCallback(),
+      new Promise((_, reject) => {
+        timer = setTimeout(
+          () => reject(new Error("Timed out waiting for the OAuth callback")),
+          timeoutMs
+        );
+        // Don't keep the event loop alive solely for this timer.
+        if (typeof timer.unref === "function") timer.unref();
+      }),
+    ]);
+  } finally {
+    clearTimeout(timer);
+    await server.close();
+  }
+
+  if (params.error) {
+    throw new Error(`Authorization failed: ${params.error_description || params.error}`);
+  }
+  if (params.state !== state) {
+    throw new Error("State mismatch — aborting (possible CSRF). Please retry the login.");
+  }
+  if (!params.code) {
+    throw new Error("No authorization code returned by Google.");
+  }
+
+  const tokens = await exchange(params.code, redirectUri);
+  const blob = encodeCredentialBlob({ provider: PROVIDER, tokens });
+
+  print(
+    "\n" +
+      "Antigravity authorized. Copy the line below and paste it into your remote\n" +
+      "OmniRoute dashboard: Providers → Antigravity → Connect → \"Paste credentials\".\n" +
+      "(This contains a refresh token — treat it like a password.)\n\n" +
+      blob +
+      "\n\n"
+  );
+  return blob;
+}
+
+async function runLoginAntigravity(opts) {
+  try {
+    await runAntigravityLogin({
+      browser: opts.browser,
+      timeout: opts.timeout,
+      port: opts.port,
+    });
+  } catch (err) {
+    process.stderr.write(`\nLogin failed: ${err?.message || err}\n`);
+    process.exit(1);
+  }
+}
+
+export function registerLogin(program) {
+  const login = program
+    .command("login")
+    .description("Local OAuth helpers for remote OmniRoute installs (run on your own machine)");
+
+  login
+    .command("antigravity")
+    .description("Authorize Antigravity locally and print a credential blob to paste remotely")
+    .option("--no-browser", "Do not auto-open the browser; print the URL instead")
+    .option("--port <n>", "Fixed loopback port (default: OS-assigned)", (v) => parseInt(v, 10))
+    .option("--timeout <ms>", "How long to wait for the callback", (v) => parseInt(v, 10), 300000)
+    .action(runLoginAntigravity);
+}

bin/cli/commands/logs.mjs

@@ -1,5 +1,6 @@
 import { writeFileSync, appendFileSync, existsSync, unlinkSync } from "node:fs";
 import { t } from "../i18n.mjs";
+import { getBaseUrl, buildHeaders } from "../api.mjs";
 
 export function registerLogs(program) {
   program
@@ -9,7 +10,7 @@ export function registerLogs(program) {
     .option("--filter <level>", t("logs.filter"))
     .option("--lines <n>", t("logs.lines"), "100")
     .option("--timeout <ms>", t("logs.timeout"), "30000")
-    .option("--base-url <url>", t("logs.baseUrl"), "http://localhost:20128")
+    .option("--base-url <url>", t("logs.baseUrl"))
     .option("--request-id <id>", t("logs.requestId"))
     .option("--api-key <key>", t("logs.apiKey"))
     .option("--combo <name>", t("logs.combo"))
@@ -19,7 +20,14 @@ export function registerLogs(program) {
     .option("--export <path>", t("logs.export"))
     .action(async (opts, cmd) => {
       const globalOpts = cmd.optsWithGlobals();
-      const exitCode = await runLogsCommand({ ...opts, output: globalOpts.output });
+      // `--context` and `--output` are global options, so forward them explicitly:
+      // runLogsCommand resolves the base URL via getBaseUrl({ context }), and without
+      // this a user's `--context` would be silently dropped.
+      const exitCode = await runLogsCommand({
+        ...opts,
+        context: globalOpts.context,
+        output: globalOpts.output,
+      });
       if (exitCode !== 0) process.exit(exitCode);
     });
 }
@@ -67,7 +75,10 @@ function buildLogFilter(opts) {
 }
 
 export async function runLogsCommand(opts = {}) {
-  const baseUrl = opts.baseUrl || opts["base-url"] || "http://localhost:20128";
+  // Resolve the base URL the same way every other CLI command does: an explicit
+  // --base-url wins, otherwise fall back to the active context / env / localhost.
+  // Without this, `logs` always hit localhost and ignored a connected remote.
+  const baseUrl = opts.baseUrl || opts["base-url"] || getBaseUrl({ context: opts.context });
   const follow = opts.follow ?? false;
   const timeout = parseInt(String(opts.timeout || "30000"), 10);
   const isJson = opts.output === "json";
@@ -82,8 +93,21 @@ export async function runLogsCommand(opts = {}) {
   // Pass only level filters to the stream (server-side); other filters are client-side
   const levelFilters = opts.filter ? opts.filter.split(",").map((f) => f.trim()) : [];
 
+  // Authenticate the log stream. The /api/cli-tools/logs endpoint requires the
+  // management token; build the same headers (scoped context token + CLI token)
+  // that apiFetch uses, so `logs` works against authenticated/remote servers.
+  // NOTE: --api-key here is a client-side log *filter* (see buildLogFilter), not
+  // an auth credential, so it is deliberately not forwarded to buildHeaders.
+  const headers = await buildHeaders({ baseUrl, context: opts.context });
+
   const { createLogStream } = await import("../../../src/lib/cli-helper/log-streamer.js");
-  const { stream, stop } = createLogStream({ baseUrl, filters: levelFilters, follow, timeout });
+  const { stream, stop } = createLogStream({
+    baseUrl,
+    filters: levelFilters,
+    follow,
+    timeout,
+    headers,
+  });
 
   const reader = stream.getReader();
   const decoder = new TextDecoder();

bin/cli/commands/redis.mjs

@@ -0,0 +1,294 @@
+import { spawn } from "node:child_process";
+import { promisify } from "node:util";
+import { execFile as execFileCb } from "node:child_process";
+
+import { t } from "../i18n.mjs";
+
+const execFile = promisify(execFileCb);
+
+const DEFAULT_IMAGE = "docker.io/redis:7-alpine";
+const DEFAULT_NAME = "omniroute-redis";
+const DEFAULT_PORT = "6379";
+const DEFAULT_VOLUME = "omniroute-redis-data";
+
+const RUNTIME_PREFERENCE = ["podman", "docker"];
+
+async function detectRuntime() {
+  for (const candidate of RUNTIME_PREFERENCE) {
+    try {
+      await execFile(candidate, ["--version"], { timeout: 3000 });
+      return candidate;
+    } catch {
+      // try next candidate
+    }
+  }
+  return null;
+}
+
+async function containerExists(runtime, name) {
+  try {
+    const { stdout } = await execFile(runtime, ["ps", "-a", "--filter", `name=^${name}$`, "--format", "{{.Names}}"]);
+    return stdout.trim() === name;
+  } catch {
+    return false;
+  }
+}
+
+async function containerRunning(runtime, name) {
+  try {
+    const { stdout } = await execFile(runtime, ["ps", "--filter", `name=^${name}$`, "--format", "{{.Names}}"]);
+    return stdout.trim() === name;
+  } catch {
+    return false;
+  }
+}
+
+async function pingRedis(port) {
+  // Minimal TCP probe via /dev/tcp — works in bash/zsh but Node has no
+  // native equivalent, so spawn a short-lived `redis-cli` if available,
+  // otherwise fall back to a raw socket connect.
+  return new Promise((resolve) => {
+    import("node:net").then(({ createConnection }) => {
+      const socket = createConnection({ port: Number(port), host: "127.0.0.1" });
+      const timeout = setTimeout(() => {
+        socket.destroy();
+        resolve(false);
+      }, 1500);
+      socket.once("connect", () => {
+        clearTimeout(timeout);
+        socket.end();
+        resolve(true);
+      });
+      socket.once("error", () => {
+        clearTimeout(timeout);
+        resolve(false);
+      });
+    });
+  });
+}
+
+function colorize(text, code) {
+  if (process.stdout.isTTY === false) return text;
+  return `\x1b[${code}m${text}\x1b[0m`;
+}
+
+function info(msg) {
+  console.log(colorize("•", "36") + " " + msg);
+}
+
+function success(msg) {
+  console.log(colorize("✓", "32") + " " + msg);
+}
+
+function warn(msg) {
+  console.error(colorize("!", "33") + " " + msg);
+}
+
+function fail(msg) {
+  console.error(colorize("✗", "31") + " " + msg);
+}
+
+export function registerRedis(program) {
+  const redis = program
+    .command("redis")
+    .description(
+      t("redis.description") ||
+        "Launch a 1-click local Redis container (Podman or Docker) for OmniRoute caching and quota tracking"
+    );
+
+  redis
+    .command("up")
+    .description("Start the local Redis container")
+    .option("-p, --port <port>", "Host port to expose", DEFAULT_PORT)
+    .option("-n, --name <name>", "Container name", DEFAULT_NAME)
+    .option("-i, --image <image>", "Container image", DEFAULT_IMAGE)
+    .option("--no-pull", "Skip pulling the image if it is missing")
+    .option("--runtime <runtime>", "Force a specific runtime (podman|docker)")
+    .option("--password <password>", "Set a Redis password (AUTH)")
+    .action(async (opts, cmd) => {
+      const globalOpts = cmd.parent.optsWithGlobals();
+      const exitCode = await runRedisUpCommand({ ...opts, output: globalOpts.output });
+      if (exitCode !== 0) process.exit(exitCode);
+    });
+
+  redis
+    .command("down")
+    .description("Stop and remove the local Redis container")
+    .option("-n, --name <name>", "Container name", DEFAULT_NAME)
+    .option("--keep-data", "Keep the named volume for next start")
+    .option("--runtime <runtime>", "Force a specific runtime (podman|docker)")
+    .action(async (opts, cmd) => {
+      const globalOpts = cmd.parent.optsWithGlobals();
+      const exitCode = await runRedisDownCommand({ ...opts, output: globalOpts.output });
+      if (exitCode !== 0) process.exit(exitCode);
+    });
+
+  redis
+    .command("status")
+    .description("Show status of the local Redis container")
+    .option("-n, --name <name>", "Container name", DEFAULT_NAME)
+    .option("-p, --port <port>", "Host port", DEFAULT_PORT)
+    .option("--runtime <runtime>", "Force a specific runtime (podman|docker)")
+    .action(async (opts, cmd) => {
+      const globalOpts = cmd.parent.optsWithGlobals();
+      const exitCode = await runRedisStatusCommand({ ...opts, output: globalOpts.output });
+      if (exitCode !== 0) process.exit(exitCode);
+    });
+}
+
+async function pickRuntime(forced) {
+  if (forced) {
+    try {
+      await execFile(forced, ["--version"], { timeout: 3000 });
+      return forced;
+    } catch (err) {
+      fail(`Forced runtime '${forced}' not available: ${err.message}`);
+      return null;
+    }
+  }
+  const detected = await detectRuntime();
+  if (!detected) {
+    fail("Neither podman nor docker found on PATH. Install one or pass --runtime.");
+    return null;
+  }
+  return detected;
+}
+
+export async function runRedisUpCommand(opts = {}) {
+  const runtime = await pickRuntime(opts.runtime);
+  if (!runtime) return 1;
+
+  const name = opts.name || DEFAULT_NAME;
+  const port = opts.port || DEFAULT_PORT;
+  const image = opts.image || DEFAULT_IMAGE;
+
+  const exists = await containerExists(runtime, name);
+  const running = exists && (await containerRunning(runtime, name));
+
+  if (running) {
+    success(`Container '${name}' is already running on port ${port}.`);
+    return 0;
+  }
+
+  if (exists && !opts.pull) {
+    info(`Starting existing container '${name}'…`);
+    try {
+      await execFile(runtime, ["start", name]);
+      success(`Container '${name}' started on port ${port}.`);
+      return 0;
+    } catch (err) {
+      fail(`Failed to start existing container: ${err.message}`);
+      return 1;
+    }
+  }
+
+  if (!opts.pull) {
+    info(`Checking if image '${image}' is present locally…`);
+    let present = false;
+    try {
+      const { stdout } = await execFile(runtime, ["images", "--format", "{{.Repository}}:{{.Tag}}"]);
+      present = stdout.split("\n").some((line) => line.trim() === image);
+    } catch {
+      // ignore — fall through to pull
+    }
+    if (!present) {
+      info(`Image not found locally — pulling '${image}'…`);
+      try {
+        await execFile(runtime, ["pull", image]);
+      } catch (err) {
+        fail(`Failed to pull image: ${err.message}`);
+        return 1;
+      }
+    }
+  }
+
+  const args = [
+    "run",
+    "-d",
+    "--name", name,
+    "--restart", "unless-stopped",
+    "-p", `${port}:6379`,
+    "-v", `${DEFAULT_VOLUME}:/data`,
+  ];
+  if (opts.password) {
+    args.push("-e", `REDIS_PASSWORD=${opts.password}`);
+  }
+  args.push(image, "redis-server", "--appendonly", "yes");
+  if (opts.password) args.push("--requirepass", opts.password);
+
+  info(`Launching ${runtime} run ${args.join(" ")}`);
+  try {
+    await execFile(runtime, args);
+    success(`Container '${name}' is now running on redis://127.0.0.1:${port}`);
+    info(`Set OMNIROUTE_REDIS_URL=redis://127.0.0.1:${port} in your .env to wire OmniRoute to it.`);
+    return 0;
+  } catch (err) {
+    fail(`Failed to launch container: ${err.message}`);
+    return 1;
+  }
+}
+
+export async function runRedisDownCommand(opts = {}) {
+  const runtime = await pickRuntime(opts.runtime);
+  if (!runtime) return 1;
+
+  const name = opts.name || DEFAULT_NAME;
+
+  if (!(await containerExists(runtime, name))) {
+    info(`Container '${name}' does not exist — nothing to do.`);
+    return 0;
+  }
+
+  try {
+    await execFile(runtime, ["rm", "-f", name]);
+    success(`Removed container '${name}'.`);
+  } catch (err) {
+    fail(`Failed to remove container: ${err.message}`);
+    return 1;
+  }
+
+  if (!opts.keepData) {
+    try {
+      await execFile(runtime, ["volume", "rm", DEFAULT_VOLUME]);
+      success(`Removed volume '${DEFAULT_VOLUME}'.`);
+    } catch (err) {
+      warn(`Could not remove volume '${DEFAULT_VOLUME}': ${err.message}`);
+    }
+  }
+  return 0;
+}
+
+export async function runRedisStatusCommand(opts = {}) {
+  const runtime = await pickRuntime(opts.runtime);
+  if (!runtime) return 1;
+
+  const name = opts.name || DEFAULT_NAME;
+  const port = opts.port || DEFAULT_PORT;
+
+  const exists = await containerExists(runtime, name);
+  if (!exists) {
+    console.log(JSON.stringify({ runtime, name, port, exists: false, running: false, reachable: false }, null, 2));
+    return 0;
+  }
+
+  const running = await containerRunning(runtime, name);
+  const reachable = running ? await pingRedis(port) : false;
+
+  if (opts.json || opts.output === "json") {
+    console.log(JSON.stringify({ runtime, name, port, exists, running, reachable }, null, 2));
+    return 0;
+  }
+
+  console.log(`\n\x1b[1m\x1b[36mRedis (${runtime})\x1b[0m\n`);
+  console.log(`  Container:   ${name}`);
+  console.log(`  Exists:      ${exists ? "yes" : "no"}`);
+  console.log(`  Running:     ${running ? "yes" : "no"}`);
+  console.log(`  Reachable:   ${reachable ? "yes" : "no"} (port ${port})`);
+  if (running && !reachable) {
+    warn("Container is running but the port is not reachable. Is REDIS_PASSWORD set or another process bound?");
+  }
+  if (!running) {
+    info(`Run 'omniroute redis up' to launch it.`);
+  }
+  return 0;
+}

bin/cli/commands/registry.mjs

@@ -2,6 +2,7 @@ import { registerMemory } from "./memory.mjs";
 import { registerSkills } from "./skills.mjs";
 import { registerAudit } from "./audit.mjs";
 import { registerOAuth } from "./oauth.mjs";
+import { registerLogin } from "./login.mjs";
 import { registerCloud } from "./cloud.mjs";
 import { registerEval } from "./eval.mjs";
 import { registerWebhooks } from "./webhooks.mjs";
@@ -45,6 +46,7 @@ import { registerBackup, registerRestore } from "./backup.mjs";
 import { registerHealth } from "./health.mjs";
 import { registerQuota } from "./quota.mjs";
 import { registerCache } from "./cache.mjs";
+import { registerRedis } from "./redis.mjs";
 import { registerMcp } from "./mcp.mjs";
 import { registerA2a } from "./a2a.mjs";
 import { registerTunnel } from "./tunnel.mjs";
@@ -69,7 +71,6 @@ import { registerSetupCrush } from "./setup-crush.mjs";
 import { registerSetupGoose } from "./setup-goose.mjs";
 import { registerSetupQwen } from "./setup-qwen.mjs";
 import { registerSetupAider } from "./setup-aider.mjs";
-import { registerSetupGemini } from "./setup-gemini.mjs";
 import { registerConnect } from "./connect.mjs";
 import { registerContexts } from "./contexts.mjs";
 import { registerTokens } from "./tokens.mjs";
@@ -82,6 +83,7 @@ export function registerCommands(program) {
   registerSkills(program);
   registerAudit(program);
   registerOAuth(program);
+  registerLogin(program);
   registerCloud(program);
   registerEval(program);
   registerWebhooks(program);
@@ -126,6 +128,7 @@ export function registerCommands(program) {
   registerHealth(program);
   registerQuota(program);
   registerCache(program);
+  registerRedis(program);
   registerMcp(program);
   registerA2a(program);
   registerTunnel(program);
@@ -150,7 +153,6 @@ export function registerCommands(program) {
   registerSetupGoose(program);
   registerSetupQwen(program);
   registerSetupAider(program);
-  registerSetupGemini(program);
   registerConnect(program);
   registerContexts(program);
   registerTokens(program);

bin/cli/commands/serve.mjs

@@ -2,11 +2,15 @@ import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { platform } from "node:os";
+import { platform, totalmem } from "node:os";
 import { t } from "../i18n.mjs";
 import { writePidFile, cleanupPidFile, waitForServer } from "../utils/pid.mjs";
 import { ServerSupervisor, detectMitmCrash } from "../runtime/processSupervisor.mjs";
 import { isTermux } from "../../../scripts/build/postinstallSupport.mjs";
+import {
+  resolveMaxOldSpaceMb,
+  calibrateHeapFallbackMb,
+} from "../../../scripts/build/runtime-env.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = join(__dirname, "..", "..", "..");
@@ -126,9 +130,13 @@ export async function runServe(opts = {}) {
 
   console.log(`  \x1b[2m⏳ Starting server...\x1b[0m\n`);
 
-  const rawMemory = parseInt(process.env.OMNIROUTE_MEMORY_MB || "512", 10);
-  const memoryLimit =
-    Number.isFinite(rawMemory) && rawMemory >= 64 && rawMemory <= 16384 ? rawMemory : 512;
+  // #5172/#5160/#5152: default the V8 heap to ~35% of physical RAM (clamped
+  // [512, 4096]) instead of a fixed 512MB, which OOM-crashed boxes with plenty
+  // of RAM under load. An explicit OMNIROUTE_MEMORY_MB still wins.
+  const memoryLimit = resolveMaxOldSpaceMb(
+    process.env.OMNIROUTE_MEMORY_MB,
+    calibrateHeapFallbackMb(totalmem())
+  );
 
   const env = {
     ...process.env,
@@ -136,7 +144,7 @@ export async function runServe(opts = {}) {
     PORT: String(dashboardPort),
     DASHBOARD_PORT: String(dashboardPort),
     API_PORT: String(apiPort),
-    HOSTNAME: "0.0.0.0",
+    HOSTNAME: process.env.HOSTNAME || "0.0.0.0",
     NODE_ENV: "production",
     NODE_OPTIONS: `--max-old-space-size=${memoryLimit}`,
   };
@@ -305,7 +313,7 @@ async function maybeStartTray(port, apiPort, supervisor) {
     if (!isTraySupported()) return;
     const { default: open } = await import("open").catch(() => ({ default: null }));
     const dashboardUrl = `http://localhost:${port}`;
-    const tray = initTray({
+    const tray = await initTray({
       port,
       onQuit: () => {
         killTrayIfActive();
@@ -321,8 +329,12 @@ async function maybeStartTray(port, apiPort, supervisor) {
       const { killTray } = await import("../tray/index.mjs");
       _killTray = killTray;
     }
-  } catch {
-    // tray is optional — do not fail the server
+  } catch (err) {
+    // tray is optional — do not fail the server, but surface why it failed so
+    // "--tray shows nothing" is diagnosable instead of silent (#4605).
+    process.stderr.write(
+      `[omniroute][tray] failed to start: ${err?.message ?? String(err)}\n`
+    );
   }
 }
 

bin/cli/commands/setup-gemini.mjs

@@ -1,148 +0,0 @@
-/**
- * omniroute setup-gemini — point the Gemini CLI at OmniRoute's Gemini endpoint.
- *
- * The Gemini CLI is NOT OpenAI-compatible — it speaks the native Gemini API.
- * OmniRoute exposes a Gemini-native surface at /v1beta (e.g.
- * /v1beta/models/<model>:generateContent), so the CLI can target it via the
- * @google/genai SDK env `GOOGLE_GEMINI_BASE_URL` (ROOT — the SDK appends /v1beta)
- * + `GEMINI_API_KEY`. There is no settings.json key for the base URL, so this is
- * primarily an env recipe; we optionally write ~/.gemini/settings.json `model`.
- *
- * ⚠ Known Gemini CLI caveat: it may ignore GOOGLE_GEMINI_BASE_URL if a cached
- * Google login exists — run `gemini` logged-out / API-key-only for it to take.
- */
-
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import os from "node:os";
-import { printHeading, printInfo, printSuccess, printError, createPrompt } from "../io.mjs";
-import { resolveActiveContext } from "../contexts.mjs";
-
-function stripToRoot(url) {
-  const s = String(url || "").replace(/\/+$/, "");
-  return s.endsWith("/v1beta") ? s.slice(0, -7) : s.endsWith("/v1") ? s.slice(0, -3) : s;
-}
-
-/** Resolve GOOGLE_GEMINI_BASE_URL (ROOT — SDK appends /v1beta) + apiKey. */
-export function resolveGeminiTarget(opts = {}) {
-  let root;
-  if (opts.remote) root = stripToRoot(opts.remote);
-  else {
-    try {
-      root = stripToRoot(resolveActiveContext(opts.context ?? process.env.OMNIROUTE_CONTEXT)?.baseUrl);
-    } catch {
-      /* none */
-    }
-    if (!root) root = `http://localhost:${Number(opts.port ?? process.env.PORT ?? 20128) || 20128}`;
-  }
-  let apiKey = opts.apiKey ?? opts["api-key"];
-  if (!apiKey) {
-    try {
-      const c = resolveActiveContext(opts.context ?? process.env.OMNIROUTE_CONTEXT);
-      apiKey = c?.accessToken || c?.apiKey;
-    } catch {
-      /* none */
-    }
-  }
-  if (!apiKey) apiKey = process.env.OMNIROUTE_API_KEY || "";
-  return { baseUrl: root, apiKey };
-}
-
-/** The guaranteed env recipe (pure → testable). */
-export function buildGeminiRecipe({ baseUrl, model }) {
-  return [
-    `export GOOGLE_GEMINI_BASE_URL=${baseUrl}`,
-    "export GEMINI_API_KEY=$OMNIROUTE_API_KEY",
-    `export GEMINI_MODEL=${model}`,
-    `gemini -p "reply OK"      # or: gemini  (interactive)`,
-  ].join("\n");
-}
-
-/** Merge the model into ~/.gemini/settings.json (base URL is env-only). */
-export function buildGeminiSettings(existing, { model }) {
-  const s = existing && typeof existing === "object" ? { ...existing } : {};
-  if (model) s.model = model;
-  return s;
-}
-
-function readJson(path) {
-  try {
-    if (existsSync(path)) return JSON.parse(readFileSync(path, "utf8"));
-  } catch {
-    /* corrupt/missing */
-  }
-  return {};
-}
-
-async function fetchGeminiModelIds(baseUrl, apiKey) {
-  try {
-    const res = await fetch(`${baseUrl}/v1beta/models`, {
-      headers: { "x-goog-api-key": apiKey || "" },
-      signal: AbortSignal.timeout(8000),
-    });
-    if (!res.ok) return [];
-    const body = await res.json();
-    return (body.models || []).map((m) => String(m.name || "").replace(/^models\//, "")).filter(Boolean);
-  } catch {
-    return [];
-  }
-}
-
-export async function runSetupGeminiCommand(opts = {}) {
-  const { baseUrl, apiKey } = resolveGeminiTarget(opts);
-  const dryRun = Boolean(opts.dryRun ?? opts["dry-run"]);
-  const configPath = opts.configPath ?? opts["config-path"] ?? join(os.homedir(), ".gemini", "settings.json");
-
-  printHeading("OmniRoute → Gemini CLI (native Gemini /v1beta endpoint)");
-  printInfo(`GOOGLE_GEMINI_BASE_URL: ${baseUrl}   (root — SDK appends /v1beta)`);
-
-  let model = opts.model;
-  if (!model) {
-    const ids = await fetchGeminiModelIds(baseUrl, apiKey);
-    if (ids.length && !opts.yes) {
-      printInfo(`Examples: ${ids.slice(0, 20).join(", ")}${ids.length > 20 ? " …" : ""}`);
-      const prompt = createPrompt();
-      try {
-        model = await prompt.ask("Model id for Gemini CLI");
-      } finally {
-        prompt.close();
-      }
-    }
-  }
-  if (!model) {
-    printError("A model is required. Pass --model <id>.");
-    return 2;
-  }
-
-  if (dryRun) {
-    console.log(`\n── [dry-run] ${configPath} ── { "model": "${model}" }`);
-  } else {
-    const merged = buildGeminiSettings(readJson(configPath), { model });
-    mkdirSync(join(configPath, ".."), { recursive: true });
-    writeFileSync(configPath, JSON.stringify(merged, null, 2) + "\n", "utf8");
-    printSuccess(`Wrote ${configPath} (model)`);
-  }
-
-  printInfo("\nThe base URL is env-only for Gemini CLI — export these:");
-  console.log(buildGeminiRecipe({ baseUrl, model }));
-  printInfo("\n⚠  If Gemini CLI ignores the base URL, you have a cached Google login —");
-  printInfo("   run logged-out (API-key only) so GOOGLE_GEMINI_BASE_URL takes effect.");
-  return 0;
-}
-
-export function registerSetupGemini(program) {
-  program
-    .command("setup-gemini")
-    .description("Point the Gemini CLI at OmniRoute's native Gemini /v1beta endpoint (env recipe + settings model)")
-    .option("--port <port>", "Local OmniRoute port (ignored when --remote is set)", "20128")
-    .option("--remote <url>", "Remote OmniRoute URL, e.g. http://192.168.0.15:20128")
-    .option("--api-key <key>", "OmniRoute API key (defaults to OMNIROUTE_API_KEY env var)")
-    .option("--model <id>", "Model id for Gemini CLI (required unless picked interactively)")
-    .option("--config-path <path>", "settings.json path (default: ~/.gemini/settings.json)")
-    .option("--yes", "Non-interactive: do not prompt (requires --model)")
-    .option("--dry-run", "Print what would be written without touching the filesystem")
-    .action(async (opts) => {
-      const code = await runSetupGeminiCommand(opts);
-      if (code !== 0) process.exit(code);
-    });
-}

bin/cli/commands/setup-qwen.mjs

@@ -1,7 +1,7 @@
 /**
  * omniroute setup-qwen — configure Qwen Code (QwenLM/qwen-code) for OmniRoute.
  *
- * Qwen Code is a terminal AI agent (gemini-cli fork) with a file-based config at
+ * Qwen Code is a terminal AI agent with a file-based config at
  * ~/.qwen/settings.json. For a custom OpenAI-compatible endpoint it uses a
  * `modelProviders` entry with authType "openai", baseUrl WITH /v1, and an
  * `envKey` naming the env var holding the key (secret stays in the env, never the
@@ -47,7 +47,9 @@ export function resolveQwenTarget(opts = {}) {
 /** Merge the OmniRoute modelProvider into Qwen's settings.json (preserve rest). */
 export function buildQwenSettings(existing, { baseUrl, model }) {
   const s = existing && typeof existing === "object" ? { ...existing } : {};
-  const providers = Array.isArray(s.modelProviders) ? s.modelProviders.filter((p) => p?.id !== "omniroute") : [];
+  const providers = Array.isArray(s.modelProviders)
+    ? s.modelProviders.filter((p) => p?.id !== "omniroute")
+    : [];
   providers.push({
     id: "omniroute",
     name: "OmniRoute",
@@ -82,7 +84,7 @@ async function fetchModelIds(baseUrl, apiKey) {
     });
     if (!res.ok) return [];
     const body = await res.json();
-    const list = Array.isArray(body) ? body : body.data ?? body.models ?? [];
+    const list = Array.isArray(body) ? body : (body.data ?? body.models ?? []);
     return list.map((m) => (typeof m === "string" ? m : m?.id)).filter(Boolean);
   } catch {
     return [];
@@ -92,7 +94,8 @@ async function fetchModelIds(baseUrl, apiKey) {
 export async function runSetupQwenCommand(opts = {}) {
   const { baseUrl, apiKey } = resolveQwenTarget(opts);
   const dryRun = Boolean(opts.dryRun ?? opts["dry-run"]);
-  const configPath = opts.configPath ?? opts["config-path"] ?? join(os.homedir(), ".qwen", "settings.json");
+  const configPath =
+    opts.configPath ?? opts["config-path"] ?? join(os.homedir(), ".qwen", "settings.json");
 
   printHeading("OmniRoute → Qwen Code (openai-compatible)");
   printInfo(`baseUrl: ${baseUrl}`);
@@ -126,7 +129,9 @@ export async function runSetupQwenCommand(opts = {}) {
     writeFileSync(configPath, out, "utf8");
     printSuccess(`Wrote ${configPath}`);
   }
-  printInfo("\nProvide the key (settings reference OMNIROUTE_API_KEY):  export OMNIROUTE_API_KEY=...");
+  printInfo(
+    "\nProvide the key (settings reference OMNIROUTE_API_KEY):  export OMNIROUTE_API_KEY=..."
+  );
   printInfo('Then run:  qwen        (or headless: qwen -p "reply OK")');
   return 0;
 }
@@ -134,7 +139,9 @@ export async function runSetupQwenCommand(opts = {}) {
 export function registerSetupQwen(program) {
   program
     .command("setup-qwen")
-    .description("Configure Qwen Code for OmniRoute: write ~/.qwen/settings.json (openai modelProvider)")
+    .description(
+      "Configure Qwen Code for OmniRoute: write ~/.qwen/settings.json (openai modelProvider)"
+    )
     .option("--port <port>", "Local OmniRoute port (ignored when --remote is set)", "20128")
     .option("--remote <url>", "Remote OmniRoute URL, e.g. http://192.168.0.15:20128")
     .option("--api-key <key>", "OmniRoute API key (defaults to OMNIROUTE_API_KEY env var)")

bin/cli/commands/update.mjs

@@ -25,9 +25,13 @@ export async function getCurrentVersion() {
   }
 }
 
-async function getLatestVersion() {
+// `--prefer-online` forces npm to revalidate its HTTP cache against the registry.
+// Without it `npm view` can return a stale cached version (e.g. report 3.8.30 as
+// "latest" after 3.8.31 was published), so the updater told users on an old build
+// they were already on the latest version (#4376). `execFn` is injectable for tests.
+export async function getLatestVersion(execFn = execFileAsync) {
   try {
-    const { stdout } = await execFileAsync("npm", ["view", "omniroute", "version"], {
+    const { stdout } = await execFn("npm", ["view", "omniroute", "version", "--prefer-online"], {
       timeout: 15000,
     });
     return stdout.trim();

bin/cli/data-dir.mjs

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
@@ -17,11 +18,24 @@ function safeHomeDir() {
   }
 }
 
-export function resolveDataDir() {
-  const configured = normalizeConfiguredPath(process.env.DATA_DIR);
-  if (configured) return configured;
+export function getLegacyDotDataDir(homeDir = safeHomeDir()) {
+  return path.join(homeDir, `.${APP_NAME}`);
+}
 
+export function getDefaultDataDir() {
   const homeDir = safeHomeDir();
+  const legacyDir = getLegacyDotDataDir(homeDir);
+
+  if (fs.existsSync(legacyDir)) {
+    try {
+      if (fs.statSync(legacyDir).isDirectory()) {
+        return legacyDir;
+      }
+    } catch {
+      // Ignore stat errors and continue to the platform default.
+    }
+  }
+
   if (process.platform === "win32") {
     const appData = process.env.APPDATA || path.join(homeDir, "AppData", "Roaming");
     return path.join(appData, APP_NAME);
@@ -30,7 +44,14 @@ export function resolveDataDir() {
   const xdgConfigHome = normalizeConfiguredPath(process.env.XDG_CONFIG_HOME);
   if (xdgConfigHome) return path.join(xdgConfigHome, APP_NAME);
 
-  return path.join(homeDir, `.${APP_NAME}`);
+  return legacyDir;
+}
+
+export function resolveDataDir() {
+  const configured = normalizeConfiguredPath(process.env.DATA_DIR);
+  if (configured) return configured;
+
+  return getDefaultDataDir();
 }
 
 export function resolveStoragePath(dataDir = resolveDataDir()) {

bin/cli/io.mjs

@@ -6,20 +6,43 @@ export function createPrompt() {
     output: process.stdout,
   });
 
+  // Non-interactive stdin (pipe, CI, EOF via `< /dev/null`) cannot answer an
+  // interactive prompt. Without a guard, `rl.question` never fires its callback —
+  // the await stays pending and Node warns about an "unsettled top-level await" at
+  // exit. Resolving on the readline `close` event (which fires on stdin EOF)
+  // returns the default/empty instead of hanging. A genuinely piped line still
+  // arrives via the question callback first, so `echo value | omniroute …` keeps
+  // working — only the no-input EOF case falls back.
   function ask(question, defaultValue = "") {
     const suffix = defaultValue ? ` (${defaultValue})` : "";
     return new Promise((resolve) => {
+      let settled = false;
+      const done = (v) => {
+        if (!settled) {
+          settled = true;
+          resolve(v);
+        }
+      };
+      rl.once("close", () => done(defaultValue));
       rl.question(`${question}${suffix}: `, (answer) => {
         const trimmed = answer.trim();
-        resolve(trimmed || defaultValue);
+        done(trimmed || defaultValue);
       });
     });
   }
 
   function askSecret(question) {
     return new Promise((resolve) => {
-      let prompted = false;
+      let settled = false;
       const saved = rl._writeToOutput.bind(rl);
+      const done = (v) => {
+        if (!settled) {
+          settled = true;
+          rl._writeToOutput = saved;
+          resolve(v);
+        }
+      };
+      let prompted = false;
       rl._writeToOutput = function (str) {
         if (!prompted) {
           rl.output.write(str);
@@ -29,9 +52,9 @@ export function createPrompt() {
         // Suppress character echo; allow only newlines through
         if (str === "\r\n" || str === "\n" || str === "\r") rl.output.write("\n");
       };
+      rl.once("close", () => done("")); // non-interactive EOF → empty secret, no hang
       rl.question(`${question}: `, (answer) => {
-        rl._writeToOutput = saved;
-        resolve(answer.trim());
+        done(answer.trim());
       });
     });
   }

bin/cli/locales/ar.json

@@ -25,5 +25,8 @@
     "base_url": "عنوان URL الأساسي لخادم OmniRoute",
     "context": "سياق/ملف تعريف الخادم المستخدم في هذا الأمر",
     "lang": "تعيين لغة عرض CLI (يتجاوز OMNIROUTE_LANG)"
+  },
+  "redis": {
+    "description": "تشغيل حاوية Redis محلية بضغطة واحدة (Podman أو Docker) لتخزين التخزين المؤقت وتتبع الحصة في OmniRoute"
   }
 }

bin/cli/locales/az.json

@@ -25,5 +25,8 @@
     "base_url": "OmniRoute server baza URL-i",
     "context": "Bu əmr üçün server konteksti/profili",
     "lang": "CLI ekran dilini təyin edin (OMNIROUTE_LANG-ı keçir)"
+  },
+  "redis": {
+    "description": "OmniRoute keşfi və kvota izləmə üçün 1 kliklə yerli Redis konteynerini (Podman və ya Docker) işə salın"
   }
 }

bin/cli/locales/bg.json

@@ -25,5 +25,8 @@
     "base_url": "Базов URL на сървъра OmniRoute",
     "context": "Контекст/профил на сървъра за тази команда",
     "lang": "Задай език на CLI (замества OMNIROUTE_LANG)"
+  },
+  "redis": {
+    "description": "Стартиране на локален Redis контейнер с едно щракване (Podman или Docker) за кеширане и проследяване на квота в OmniRoute"
   }
 }

bin/cli/locales/bn.json

@@ -1 +1,5 @@
-{}
+{
+  "redis": {
+    "description": "OmniRoute ক্যাশিং এবং কোটা ট্র্যাকিংয়ের জন্য এক ক্লিকে স্থানীয় Redis কন্টেইনার (Podman বা Docker) চালু করুন"
+  }
+}

bin/cli/locales/cs.json

@@ -25,5 +25,8 @@
     "base_url": "Základní URL serveru OmniRoute",
     "context": "Kontext/profil serveru pro tento příkaz",
     "lang": "Nastavit jazyk CLI (přepisuje OMNIROUTE_LANG)"
+  },
+  "redis": {
+    "description": "Spustit místní Redis kontejner jedním kliknutím (Podman nebo Docker) pro mezipaměť a sledování kvót OmniRoute"
   }
 }

bin/cli/locales/da.json

@@ -25,5 +25,8 @@
     "base_url": "OmniRoute-serverens basis-URL",
     "context": "Server-kontekst/profil til denne kommando",
     "lang": "Angiv CLI-visningssprog (tilsidesætter OMNIROUTE_LANG)"
+  },
+  "redis": {
+    "description": "Start en lokal Redis-container med ét klik (Podman eller Docker) til OmniRoute-caching og kvoteovervågning"
   }
 }

bin/cli/locales/de.json

@@ -25,5 +25,8 @@
     "base_url": "OmniRoute-Server-Basis-URL",
     "context": "Server-Kontext/Profil für diesen Befehl",
     "lang": "CLI-Anzeigesprache festlegen (überschreibt OMNIROUTE_LANG)"
+  },
+  "redis": {
+    "description": "Lokalen Redis-Container mit einem Klick starten (Podman oder Docker) für OmniRoute-Caching und Kontingentverfolgung"
   }
 }

bin/cli/locales/en.json

@@ -300,6 +300,9 @@
     "cleared": "Cache cleared.",
     "clearFailed": "Failed to clear cache."
   },
+  "redis": {
+    "description": "Launch a 1-click local Redis container (Podman or Docker) for OmniRoute caching and quota tracking"
+  },
   "test": {
     "description": "Test a provider connection",
     "noServer": "Server not running. Start with: omniroute serve",

bin/cli/locales/es.json

@@ -25,5 +25,8 @@
     "base_url": "URL base del servidor OmniRoute",
     "context": "Contexto/perfil del servidor para este comando",
     "lang": "Establecer idioma del CLI (reemplaza OMNIROUTE_LANG)"
+  },
+  "redis": {
+    "description": "Iniciar un contenedor local de Redis con un clic (Podman o Docker) para el almacenamiento en caché y seguimiento de cuotas de OmniRoute"
   }
 }

bin/cli/locales/fa.json

@@ -25,5 +25,8 @@
     "base_url": "URL پایه سرور OmniRoute",
     "context": "زمینه/پروفایل سرور برای این دستور",
     "lang": "تنظیم زبان نمایش CLI (OMNIROUTE_LANG را نادیده می‌گیرد)"
+  },
+  "redis": {
+    "description": "راه‌اندازی کانتینر Redis محلی با یک کلیک (Podman یا Docker) برای حافظه پنهان و ردیابی سهمیه OmniRoute"
   }
 }

bin/cli/locales/fi.json

@@ -25,5 +25,8 @@
     "base_url": "OmniRoute-palvelimen perus-URL",
     "context": "Palvelimen konteksti/profiili tälle komennolle",
     "lang": "Aseta CLI-näyttökieli (ohittaa OMNIROUTE_LANG)"
+  },
+  "redis": {
+    "description": "Käynnistä paikallinen Redis-säiliö yhdellä napsautuksella (Podman tai Docker) OmniRoute-välimuistia ja kiintiöiden seurantaa varten"
   }
 }

bin/cli/locales/fr.json

@@ -25,5 +25,8 @@
     "base_url": "URL de base du serveur OmniRoute",
     "context": "Contexte/profil du serveur pour cette commande",
     "lang": "Définir la langue d'affichage du CLI (remplace OMNIROUTE_LANG)"
+  },
+  "redis": {
+    "description": "Lancer un conteneur Redis local en un clic (Podman ou Docker) pour la mise en cache et le suivi des quotas OmniRoute"
   }
 }

bin/cli/locales/gu.json

@@ -1 +1,5 @@
-{}
+{
+  "redis": {
+    "description": "OmniRoute કેચિંગ અને ક્વોટા ટ્રેકિંગ માટે એક ક્લિકમાં સ્થાનિક Redis કન્ટેનર (Podman અથવા Docker) શરૂ કરો"
+  }
+}

bin/cli/locales/he.json

@@ -1 +1,5 @@
-{}
+{
+  "redis": {
+    "description": "הפעל מכולת Redis מקומית בלחיצה אחת (Podman או Docker) לשמירת מטמון ומעקב מכסות של OmniRoute"
+  }
+}

bin/cli/locales/hi.json

@@ -25,5 +25,8 @@
     "base_url": "OmniRoute सर्वर का बेस URL",
     "context": "इस कमांड के लिए सर्वर संदर्भ/प्रोफ़ाइल",
     "lang": "CLI प्रदर्शन भाषा सेट करें (OMNIROUTE_LANG को ओवरराइड करता है)"
+  },
+  "redis": {
+    "description": "OmniRoute कैशिंग और कोटा ट्रैकिंग के लिए एक क्लिक में स्थानीय Redis कंटेनर (Podman या Docker) लॉन्च करें"
   }
 }

bin/cli/locales/hu.json

@@ -25,5 +25,8 @@
     "base_url": "Az OmniRoute szerver alap URL-je",
     "context": "Szerverkontextus/profil ehhez a parancshoz",
     "lang": "CLI megjelenítési nyelv beállítása (felülírja az OMNIROUTE_LANG-ot)"
+  },
+  "redis": {
+    "description": "Helyi Redis-tároló indítása egyetlen kattintással (Podman vagy Docker) az OmniRoute gyorsítótárazáshoz és kvótafigyeléshez"
   }
 }

bin/cli/locales/id.json

@@ -25,5 +25,8 @@
     "base_url": "URL dasar server OmniRoute",
     "context": "Konteks/profil server untuk perintah ini",
     "lang": "Atur bahasa tampilan CLI (menggantikan OMNIROUTE_LANG)"
+  },
+  "redis": {
+    "description": "Luncurkan kontainer Redis lokal dengan satu klik (Podman atau Docker) untuk caching dan pelacakan kuota OmniRoute"
   }
 }

bin/cli/locales/in.json

@@ -1 +1,5 @@
-{}
+{
+  "redis": {
+    "description": "Luncurkan kontainer Redis lokal dengan satu klik (Podman atau Docker) untuk caching dan pelacakan kuota OmniRoute"
+  }
+}

bin/cli/locales/it.json

@@ -25,5 +25,8 @@
     "base_url": "URL base del server OmniRoute",
     "context": "Contesto/profilo del server per questo comando",
     "lang": "Imposta la lingua di visualizzazione della CLI (sovrascrive OMNIROUTE_LANG)"
+  },
+  "redis": {
+    "description": "Avvia un contenitore Redis locale con un clic (Podman o Docker) per la cache e il tracciamento delle quote di OmniRoute"
   }
 }

bin/cli/locales/ja.json

@@ -25,5 +25,8 @@
     "base_url": "OmniRouteサーバーのベースURL",
     "context": "このコマンドで使用するサーバーコンテキスト/プロファイル",
     "lang": "CLI表示言語を設定（OMNIROUTE_LANGを上書き）"
+  },
+  "redis": {
+    "description": "OmniRouteのキャッシュとクォータ追跡用に、ローカルRedisコンテナー（PodmanまたはDocker）をワンクリックで起動"
   }
 }

bin/cli/locales/ko.json

@@ -25,5 +25,8 @@
     "base_url": "OmniRoute 서버 기본 URL",
     "context": "이 명령에 사용할 서버 컨텍스트/프로필",
     "lang": "CLI 표시 언어 설정 (OMNIROUTE_LANG 재정의)"
+  },
+  "redis": {
+    "description": "OmniRoute 캐싱 및 할당량 추적을 위한 로컬 Redis 컨테이너(Podman 또는 Docker)를 원클릭으로 실행"
   }
 }

bin/cli/locales/mr.json

@@ -1 +1,5 @@
-{}
+{
+  "redis": {
+    "description": "OmniRoute कॅशिंग आणि कोटा ट्रॅकिंगसाठी एका क्लिकमध्ये स्थानिक Redis कंटेनर (Podman किंवा Docker) लाँच करा"
+  }
+}

bin/cli/locales/ms.json

@@ -1 +1,5 @@
-{}
+{
+  "redis": {
+    "description": "Lancarkan kontena Redis tempatan dengan satu klik (Podman atau Docker) untuk caching dan penjejakan kuota OmniRoute"
+  }
+}