chore: release v2.4.3

- fix: Codex/GitHub limits page HTTP 500 → graceful 401/403 messages
- fix: MaintenanceBanner false-positive on page load (stale closure)
- fix: add title tooltips to edit/delete buttons in ConnectionCard
- feat: add fill-first and p2c routing strategies to combo picker
- feat: Free Stack template pre-fills 7 free provider models
- feat: combo create/edit modal wider (max-w-4xl)

CHANGELOG.md

@@ -2,7 +2,21 @@
 
 ## [Unreleased]
 
-## [2.4.2] - 2026-03-14
+## [2.4.3] - 2026-03-14
+
+> UI polish, routing strategy additions, and graceful error handling for usage limits.
+
+### ✨ New Features
+
+- **Fill-First & P2C Routing Strategies**: Added `fill-first` (drain quota before moving on) and `p2c` (Power-of-Two-Choices low-latency selection) to combo strategy picker, with full guidance panels and color-coded badges.
+- **Free Stack Preset Models**: Creating a combo with the Free Stack template now auto-fills 7 best-in-class free provider models (Gemini CLI, Kiro, iFlow×2, Qwen, NVIDIA NIM, Groq). Users just activate the providers and get a $0/month combo out-of-the-box.
+- **Wider Combo Modal**: Create/Edit combo modal now uses `max-w-4xl` for comfortable editing of large combos.
+
+### 🐛 Bug Fixes
+
+- **Limits page HTTP 500 for Codex & GitHub**: `getCodexUsage()` and `getGitHubUsage()` now return a user-friendly message when the provider returns 401/403 (expired token), instead of throwing and causing a 500 error on the Limits page.
+- **MaintenanceBanner false-positive**: Banner no longer shows "Server is unreachable" spuriously on page load. Fixed by calling `checkHealth()` immediately on mount and removing stale `show`-state closure.
+- **Provider icon tooltips**: Edit (pencil) and delete icon buttons in the provider connection row now have native HTML tooltips — all 6 action icons are now self-documented.
 
 > Multiple improvements from community issue analysis, new provider support, bug fixes for token tracking, model routing, and streaming reliability.
 

docs/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: OmniRoute API
-  version: 2.4.2
+  version: 2.4.3
   description: |
     OmniRoute is a local-first AI API proxy router. It provides an OpenAI-compatible
     endpoint that routes requests to multiple AI providers with load balancing,

open-sse/services/usage.ts

@@ -161,6 +161,11 @@ async function getGitHubUsage(accessToken, providerSpecificData) {
 
     if (!response.ok) {
       const error = await response.text();
+      if (response.status === 401 || response.status === 403) {
+        return {
+          message: `GitHub token expired or permission denied. Please re-authenticate the connection.`,
+        };
+      }
       throw new Error(`GitHub API error: ${error}`);
     }
 
@@ -620,6 +625,11 @@ async function getCodexUsage(accessToken, providerSpecificData: Record<string, u
     });
 
     if (!response.ok) {
+      if (response.status === 401 || response.status === 403) {
+        return {
+          message: `Codex token expired or access denied. Please re-authenticate the connection.`,
+        };
+      }
       throw new Error(`Codex API error: ${response.status}`);
     }
 

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "omniroute",
-  "version": "2.4.1",
+  "version": "2.4.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "omniroute",
-      "version": "2.4.1",
+      "version": "2.4.2",
       "hasInstallScript": true,
       "license": "MIT",
       "workspaces": [
@@ -6866,6 +6866,7 @@
       "version": "2.3.2",
       "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz",
       "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==",
+      "dev": true,
       "hasInstallScript": true,
       "license": "MIT",
       "optional": true,

package.json

@@ -1,6 +1,6 @@
 {
   "name": "omniroute",
-  "version": "2.4.2",
+  "version": "2.4.3",
   "description": "Smart AI Router with auto fallback — route to FREE & cheap models, zero downtime. Works with Cursor, Cline, Claude Desktop, Codex, and any OpenAI-compatible tool.",
   "type": "module",
   "bin": {

src/app/(dashboard)/dashboard/combos/page.tsx

@@ -27,6 +27,13 @@ const STRATEGY_OPTIONS = [
   { value: "random", labelKey: "random", descKey: "randomDesc", icon: "shuffle" },
   { value: "least-used", labelKey: "leastUsed", descKey: "leastUsedDesc", icon: "low_priority" },
   { value: "cost-optimized", labelKey: "costOpt", descKey: "costOptimizedDesc", icon: "savings" },
+  {
+    value: "fill-first",
+    labelKey: "fillFirst",
+    descKey: "fillFirstDesc",
+    icon: "stacked_bar_chart",
+  },
+  { value: "p2c", labelKey: "p2c", descKey: "p2cDesc", icon: "compare_arrows" },
 ];
 
 const STRATEGY_GUIDANCE_FALLBACK = {
@@ -60,6 +67,16 @@ const STRATEGY_GUIDANCE_FALLBACK = {
     avoid: "Avoid when pricing data is missing or outdated.",
     example: "Example: Batch or background jobs where lower cost matters most.",
   },
+  "fill-first": {
+    when: "Use when you want to drain one provider's quota fully before moving to the next.",
+    avoid: "Avoid when you need request-level load balancing across providers.",
+    example: "Example: Use all $200 Deepgram credits before falling to Groq.",
+  },
+  p2c: {
+    when: "Use when you want low-latency selection using Power-of-Two-Choices algorithm.",
+    avoid: "Avoid for small combos with 2 or fewer models — no benefit over round-robin.",
+    example: "Example: High-throughput inference across 4+ equivalent model endpoints.",
+  },
 };
 
 const ADVANCED_FIELD_HELP_FALLBACK = {
@@ -126,6 +143,25 @@ const STRATEGY_RECOMMENDATIONS_FALLBACK = {
       "Use for batch/background jobs where cost is the main KPI.",
     ],
   },
+  "fill-first": {
+    title: "Quota drain strategy",
+    description: "Exhausts one provider's quota before moving to the next in chain.",
+    tips: [
+      "Order models by free quota size — biggest first.",
+      "Enable health checks to skip drained providers.",
+      "Ideal for free-tier stacking (Deepgram → Groq → NIM).",
+    ],
+  },
+  p2c: {
+    title: "Power-of-Two-Choices",
+    description:
+      "Picks the less-loaded of two random candidates per request — low latency at scale.",
+    tips: [
+      "Use with 4+ models for best effect.",
+      "Requires latency telemetry enabled in Settings.",
+      "Great replacement for round-robin in high-throughput combos.",
+    ],
+  },
 };
 
 const COMBO_USAGE_GUIDE_STORAGE_KEY = "omniroute:combos:hide-usage-guide";
@@ -227,6 +263,8 @@ function getStrategyBadgeClass(strategy) {
   if (strategy === "random") return "bg-purple-500/15 text-purple-600 dark:text-purple-400";
   if (strategy === "least-used") return "bg-cyan-500/15 text-cyan-600 dark:text-cyan-400";
   if (strategy === "cost-optimized") return "bg-teal-500/15 text-teal-600 dark:text-teal-400";
+  if (strategy === "fill-first") return "bg-orange-500/15 text-orange-600 dark:text-orange-400";
+  if (strategy === "p2c") return "bg-indigo-500/15 text-indigo-600 dark:text-indigo-400";
   return "bg-blue-500/15 text-blue-600 dark:text-blue-400";
 }
 
@@ -1365,10 +1403,24 @@ function ComboFormModal({ isOpen, combo, onClose, onSave, activeProviders }) {
     );
   };
 
+  const FREE_STACK_PRESET_MODELS = [
+    { model: "gc/gemini-3-flash-preview", weight: 0 },
+    { model: "kr/claude-sonnet-4.5", weight: 0 },
+    { model: "if/kimi-k2-thinking", weight: 0 },
+    { model: "if/qwen3-coder-plus", weight: 0 },
+    { model: "qw/qwen3-coder-plus", weight: 0 },
+    { model: "nvidia/llama-3.3-70b-instruct", weight: 0 },
+    { model: "groq/llama-3.3-70b-versatile", weight: 0 },
+  ];
+
   const applyTemplate = (template) => {
     setStrategy(template.strategy);
     setConfig((prev) => ({ ...prev, ...template.config }));
     if (!name.trim()) setName(template.suggestedName);
+    // Pre-fill Free Stack with 7 real free provider models
+    if (template.id === "free-stack") {
+      setModels(FREE_STACK_PRESET_MODELS);
+    }
   };
 
   // Format model display name with readable provider name
@@ -1473,7 +1525,12 @@ function ComboFormModal({ isOpen, combo, onClose, onSave, activeProviders }) {
 
   return (
     <>
-      <Modal isOpen={isOpen} onClose={onClose} title={isEdit ? t("editCombo") : t("createCombo")}>
+      <Modal
+        isOpen={isOpen}
+        onClose={onClose}
+        title={isEdit ? t("editCombo") : t("createCombo")}
+        size="full"
+      >
         <div className="flex flex-col gap-3">
           {/* Name */}
           <div>

src/app/(dashboard)/dashboard/providers/[id]/page.tsx

@@ -2411,6 +2411,7 @@ function ConnectionRow({
           <button
             onClick={onEdit}
             className="p-2 hover:bg-black/5 dark:hover:bg-white/5 rounded text-text-muted hover:text-primary"
+            title={t("edit")}
           >
             <span className="material-symbols-outlined text-[18px]">edit</span>
           </button>
@@ -2421,7 +2422,11 @@ function ConnectionRow({
           >
             <span className="material-symbols-outlined text-[18px]">vpn_lock</span>
           </button>
-          <button onClick={onDelete} className="p-2 hover:bg-red-500/10 rounded text-red-500">
+          <button
+            onClick={onDelete}
+            className="p-2 hover:bg-red-500/10 rounded text-red-500"
+            title={t("deleteConnection")}
+          >
             <span className="material-symbols-outlined text-[18px]">delete</span>
           </button>
         </div>

src/shared/components/MaintenanceBanner.tsx

@@ -8,38 +8,36 @@
  * comes back online.
  */
 
-import { useState, useEffect, useCallback } from "react";
+import { useState, useEffect } from "react";
 
 export default function MaintenanceBanner() {
   const [show, setShow] = useState(false);
   const [message, setMessage] = useState("");
 
-  const checkHealth = useCallback(async () => {
-    try {
-      const res = await fetch("/api/monitoring/health", {
-        signal: AbortSignal.timeout(3000),
-      });
-      if (res.ok) {
-        // Server is healthy — hide banner if shown
-        if (show) {
+  useEffect(() => {
+    const checkHealth = async () => {
+      try {
+        const res = await fetch("/api/monitoring/health", {
+          signal: AbortSignal.timeout(3000),
+        });
+        if (res.ok) {
           setShow(false);
           setMessage("");
+        } else {
+          setShow(true);
+          setMessage("Server is experiencing issues. Some features may be unavailable.");
         }
-      } else {
+      } catch {
         setShow(true);
-        setMessage("Server is experiencing issues. Some features may be unavailable.");
+        setMessage("Server is unreachable. Reconnecting...");
       }
-    } catch {
-      setShow(true);
-      setMessage("Server is unreachable. Reconnecting...");
-    }
-  }, [show]);
+    };
 
-  useEffect(() => {
-    // Check health every 10 seconds
+    // Run immediately on mount, then every 10 seconds
+    checkHealth();
     const interval = setInterval(checkHealth, 10000);
     return () => clearInterval(interval);
-  }, [checkHealth]);
+  }, []); // empty deps — checkHealth is defined inside effect, no stale closure
 
   if (!show) return null;