@elvatis_com/openclaw-cli-bridge-elvatis 1.8.9 → 1.9.0

package/CONTRIBUTING.md

@@ -4,11 +4,11 @@
 
 **Kein Publish ohne erfolgreichen `/bridge-status` Test!**
 
-### 1. Build
+### 1. Lint + Build
 
 ```bash
-npm run build
-# Exit 0 erwartet — TS-Fehler sind ok (--noEmitOnError false), aber Exit != 0 blockiert
+npm run lint    # ESLint — 0 errors required, warnings ok
+npm run build   # Exit 0 erwartet — TS-Fehler sind ok (--noEmitOnError false), aber Exit != 0 blockiert
 ```
 
 ### 2. Gateway neu starten
@@ -67,10 +67,12 @@ grep -rn "X\.Y\.Z\|version" \
 ```
 
 Typische Stellen:
-- `package.json` → `"version": "..."`
+- `package.json` → `"version": "..."` (Hauptquelle — `index.ts` liest automatisch daraus)
 - `openclaw.plugin.json` → `"version": "..."`
 - `README.md` → `**Current version:** ...` (falls vorhanden)
 
+> **Seit v1.9.0:** `index.ts` liest die Version automatisch aus `package.json` — kein manuelles Sync mehr nötig für die Runtime-Version.
+
 ---
 
 ## Breaking Changes
@@ -91,3 +93,24 @@ Die folgenden TS-Fehler sind bekannt und ignorierbar (kein Runtime-Problem):
 - `TS7006: Parameter implicitly has 'any' type` — minor, kein Effekt
 
 Build läuft mit `--noEmitOnError false` durch. `npm run build` → Exit 0 ist das Kriterium, nicht null TS-Fehler.
+
+---
+
+## Cookie Expiry Store (seit v1.9.0)
+
+Cookie-Expiry-Daten werden jetzt in **einer** Datei gespeichert:
+- `~/.openclaw/cookie-expiry.json` — enthält alle 4 Provider (grok, gemini, claude, chatgpt)
+
+Legacy-Dateien (`grok-cookie-expiry.json`, `gemini-cookie-expiry.json`, etc.) werden beim ersten Start automatisch migriert und gelöscht.
+
+---
+
+## Model Fallback Chain (seit v1.9.0)
+
+Wenn ein CLI-Modell fehlschlägt (Timeout, Fehler), wird automatisch ein leichteres Modell versucht:
+- `gemini-2.5-pro` → `gemini-2.5-flash`
+- `gemini-3-pro-preview` → `gemini-3-flash-preview`
+- `claude-opus-4-6` → `claude-sonnet-4-6`
+- `claude-sonnet-4-6` → `claude-haiku-4-5`
+
+Die Response enthält das tatsächlich verwendete Modell im `model`-Feld.

package/README.md

@@ -2,7 +2,7 @@
 
 > OpenClaw plugin that bridges locally installed AI CLIs (Codex, Gemini, Claude Code) as model providers — with slash commands for instant model switching, restore, health testing, and model listing.
 
-**Current version:** `1.8.9`
+**Current version:** `1.9.0`
 
 ---
 
@@ -307,6 +307,18 @@ Slash commands (requireAuth=false, gateway commands.allowFrom is the auth layer)
   /cli-back   → reads state file, restores previous model, clears state
   /cli-test   → HTTP POST → localhost:31337, no global model change
   /cli-list   → formatted table of all registered models
+
+Proxy endpoints:
+  /health     → simple {"status":"ok"}
+  /healthz    → detailed JSON (version, uptime, provider status, model count)
+  /status     → HTML dashboard (auto-refreshes every 30s)
+  /v1/models  → OpenAI-compatible model list
+
+Model fallback (v1.9.0):
+  cli-gemini/gemini-2.5-pro      → cli-gemini/gemini-2.5-flash
+  cli-gemini/gemini-3-pro-preview → cli-gemini/gemini-3-flash-preview
+  cli-claude/claude-opus-4-6     → cli-claude/claude-sonnet-4-6
+  cli-claude/claude-sonnet-4-6   → cli-claude/claude-haiku-4-5
 ```
 
 ---
@@ -334,14 +346,27 @@ Slash commands (requireAuth=false, gateway commands.allowFrom is the auth layer)
 ## Development
 
 ```bash
+npm run lint        # eslint (TypeScript-aware)
 npm run typecheck   # tsc --noEmit
-npm test            # vitest run (83 tests)
+npm test            # vitest run (121 tests)
+npm run ci          # lint + typecheck + test
 ```
 
 ---
 
 ## Changelog
 
+### v1.9.0
+- **feat:** Auto-source version from `package.json` — eliminates hardcoded version string sync issues (was stale across v1.8.2–v1.8.8)
+- **feat:** ESLint config (`eslint.config.js`) — TypeScript-aware linting with `npm run lint`, integrated into CI pipeline
+- **refactor:** Extract `/status` HTML dashboard into `src/status-template.ts` — easier to maintain and test
+- **feat:** System Chrome startup check — logs a clear warning with install instructions if `google-chrome` / `chromium` is not found (required for stealth mode browser launches)
+- **refactor:** Consolidate 4 cookie expiry files (`grok-`, `gemini-`, `claude-`, `chatgpt-cookie-expiry.json`) into single `~/.openclaw/cookie-expiry.json`. Legacy files are auto-migrated on first load.
+- **fix:** Explicit `grokBrowser` cleanup on plugin unload — prevents orphaned Chromium processes on hot-reload. Launch promises (`_geminiLaunchPromise` etc.) are also cleared.
+- **feat:** Model fallback chain — when a CLI model fails (timeout, error), automatically retries with a lighter variant: `gemini-2.5-pro` → `flash`, `claude-opus` → `sonnet` → `haiku`. Response includes the actual model used.
+- **feat:** `/healthz` JSON endpoint — returns version, uptime, provider session status, and model count. Useful for monitoring scripts and health dashboards.
+- **feat:** Status page now shows slash commands (`/cli-codex`, `/cli-sonnet`, etc.) next to model IDs
+
 ### v1.8.7
 - **fix:** Add missing cli-gemini/gemini-3-flash-preview and all Codex models to status page model list
 - **fix:** Remove duplicate cli-gemini/gemini-3-pro alias

package/SKILL.md

@@ -68,4 +68,4 @@ On gateway restart, if any session has expired, a **WhatsApp alert** is sent aut
 
 See `README.md` for full configuration reference and architecture diagram.
 
-**Version:** 1.8.9
+**Version:** 1.9.0

package/eslint.config.js

@@ -0,0 +1,26 @@
+import eslint from "@eslint/js";
+import tseslint from "typescript-eslint";
+
+export default tseslint.config(
+  eslint.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    rules: {
+      // Relaxed — this is a plugin, not a library; pragmatism over purity
+      "@typescript-eslint/no-explicit-any": "warn",
+      "@typescript-eslint/no-unused-vars": ["warn", { argsIgnorePattern: "^_", varsIgnorePattern: "^_" }],
+      "@typescript-eslint/no-require-imports": "off", // pre-existing dynamic require in index.ts
+      "no-console": "off",
+      "prefer-const": "warn", // pre-existing let-without-reassign patterns
+      "no-var": "error",
+      eqeqeq: ["error", "always"],
+      // Pre-existing patterns — suppress until dedicated cleanup
+      "no-useless-assignment": "off",
+      "no-misleading-character-class": "off",
+      "preserve-caught-error": "off",
+    },
+  },
+  {
+    ignores: ["dist/", "node_modules/", "test/"],
+  },
+);

package/index.ts

@@ -28,8 +28,20 @@
 
 import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import http from "node:http";
+
+// ── Auto-source version from package.json (eliminates hardcoded version sync) ──
+const __dirname_local = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_VERSION: string = (() => {
+  try {
+    const pkg = JSON.parse(readFileSync(join(__dirname_local, "package.json"), "utf-8")) as { version: string };
+    return pkg.version;
+  } catch {
+    return "0.0.0"; // fallback — should never happen in normal operation
+  }
+})();
 import type {
   OpenClawPluginApi,
   ProviderAuthContext,
@@ -63,6 +75,8 @@ import {
   formatChatGPTExpiry,
 } from "./src/expiry-helpers.js";
 import type { BrowserContext, Browser } from "playwright";
+import { checkSystemChrome } from "./src/chrome-check.js";
+import { saveProviderExpiry, loadProviderExpiry, migrateLegacyFiles } from "./src/cookie-expiry-store.js";
 
 // ──────────────────────────────────────────────────────────────────────────────
 // Types derived from SDK (not re-exported by the package)
@@ -108,23 +122,22 @@ const STEALTH_IGNORE_DEFAULTS = ["--enable-automation"] as const;
 
 // ── Gemini web-session state ──────────────────────────────────────────────────
 let geminiContext: BrowserContext | null = null;
-const GEMINI_EXPIRY_FILE = join(homedir(), ".openclaw", "gemini-cookie-expiry.json");
 
 // ── Claude web-session state ─────────────────────────────────────────────────
 let claudeWebContext: BrowserContext | null = null;
-const CLAUDE_EXPIRY_FILE = join(homedir(), ".openclaw", "claude-cookie-expiry.json");
 
 // ── ChatGPT web-session state ────────────────────────────────────────────────
 let chatgptContext: BrowserContext | null = null;
-const CHATGPT_EXPIRY_FILE = join(homedir(), ".openclaw", "chatgpt-cookie-expiry.json");
 
+// ── Consolidated cookie expiry (delegates to cookie-expiry-store.ts) ─────────
+// Legacy per-provider files are auto-migrated on first load.
 interface GeminiExpiryInfo { expiresAt: number; loginAt: number; cookieName: string; }
 
 function saveGeminiExpiry(info: GeminiExpiryInfo): void {
-  try { writeFileSync(GEMINI_EXPIRY_FILE, JSON.stringify(info, null, 2)); } catch { /* ignore */ }
+  saveProviderExpiry("gemini", info);
 }
 function loadGeminiExpiry(): GeminiExpiryInfo | null {
-  try { return JSON.parse(readFileSync(GEMINI_EXPIRY_FILE, "utf-8")) as GeminiExpiryInfo; } catch { return null; }
+  return loadProviderExpiry("gemini");
 }
 // formatGeminiExpiry imported from ./src/expiry-helpers.js
 async function scanGeminiCookieExpiry(ctx: BrowserContext): Promise<GeminiExpiryInfo | null> {
@@ -141,10 +154,10 @@ async function scanGeminiCookieExpiry(ctx: BrowserContext): Promise<GeminiExpiry
 // ── Claude cookie expiry helpers ─────────────────────────────────────────────
 interface ClaudeExpiryInfo { expiresAt: number; loginAt: number; cookieName: string; }
 function saveClaudeExpiry(info: ClaudeExpiryInfo): void {
-  try { writeFileSync(CLAUDE_EXPIRY_FILE, JSON.stringify(info, null, 2)); } catch { /* ignore */ }
+  saveProviderExpiry("claude", info);
 }
 function loadClaudeExpiry(): ClaudeExpiryInfo | null {
-  try { return JSON.parse(readFileSync(CLAUDE_EXPIRY_FILE, "utf-8")) as ClaudeExpiryInfo; } catch { return null; }
+  return loadProviderExpiry("claude");
 }
 // formatClaudeExpiry imported from ./src/expiry-helpers.js
 async function scanClaudeCookieExpiry(ctx: BrowserContext): Promise<ClaudeExpiryInfo | null> {
@@ -163,10 +176,10 @@ async function scanClaudeCookieExpiry(ctx: BrowserContext): Promise<ClaudeExpiry
 // ── ChatGPT cookie expiry helpers ────────────────────────────────────────────
 interface ChatGPTExpiryInfo { expiresAt: number; loginAt: number; cookieName: string; }
 function saveChatGPTExpiry(info: ChatGPTExpiryInfo): void {
-  try { writeFileSync(CHATGPT_EXPIRY_FILE, JSON.stringify(info, null, 2)); } catch { /* ignore */ }
+  saveProviderExpiry("chatgpt", info);
 }
 function loadChatGPTExpiry(): ChatGPTExpiryInfo | null {
-  try { return JSON.parse(readFileSync(CHATGPT_EXPIRY_FILE, "utf-8")) as ChatGPTExpiryInfo; } catch { return null; }
+  return loadProviderExpiry("chatgpt");
 }
 // formatChatGPTExpiry imported from ./src/expiry-helpers.js
 async function scanChatGPTCookieExpiry(ctx: BrowserContext): Promise<ChatGPTExpiryInfo | null> {
@@ -184,9 +197,6 @@ async function scanChatGPTCookieExpiry(ctx: BrowserContext): Promise<ChatGPTExpi
 
 // ─────────────────────────────────────────────────────────────────────────────
 
-// Cookie expiry tracking file — written on /grok-login, read on startup
-const GROK_EXPIRY_FILE = join(homedir(), ".openclaw", "grok-cookie-expiry.json");
-
 interface GrokExpiryInfo {
   expiresAt: number;    // epoch ms — earliest auth cookie expiry
   loginAt: number;      // epoch ms — when /grok-login was last run
@@ -194,16 +204,11 @@ interface GrokExpiryInfo {
 }
 
 function saveGrokExpiry(info: GrokExpiryInfo): void {
-  try {
-    writeFileSync(GROK_EXPIRY_FILE, JSON.stringify(info, null, 2));
-  } catch { /* ignore */ }
+  saveProviderExpiry("grok", info);
 }
 
 function loadGrokExpiry(): GrokExpiryInfo | null {
-  try {
-    const raw = readFileSync(GROK_EXPIRY_FILE, "utf-8");
-    return JSON.parse(raw) as GrokExpiryInfo;
-  } catch { return null; }
+  return loadProviderExpiry("grok");
 }
 
 // formatExpiryInfo imported from ./src/expiry-helpers.js
@@ -501,10 +506,16 @@ async function cleanupBrowsers(log: (msg: string) => void): Promise<void> {
     clearInterval(_keepAliveInterval);
     _keepAliveInterval = null;
   }
+  // Close all browser contexts first, then the browser instances.
+  // Closing contexts before browsers prevents orphaned Chromium processes.
   if (grokContext) {
     try { await grokContext.close(); } catch { /* ignore */ }
     grokContext = null;
   }
+  if (grokBrowser) {
+    try { await grokBrowser.close(); } catch { /* ignore */ }
+    grokBrowser = null;
+  }
   if (geminiContext) {
     try { await geminiContext.close(); } catch { /* ignore */ }
     geminiContext = null;
@@ -521,6 +532,11 @@ async function cleanupBrowsers(log: (msg: string) => void): Promise<void> {
     try { await _cdpBrowser.close(); } catch { /* ignore */ }
     _cdpBrowser = null;
   }
+  // Clear any pending launch promises to prevent stale references
+  _cdpBrowserLaunchPromise = null;
+  _geminiLaunchPromise = null;
+  _claudeLaunchPromise = null;
+  _chatgptLaunchPromise = null;
   log("[cli-bridge] browser resources cleaned up");
 }
 
@@ -939,7 +955,7 @@ function proxyTestRequest(
 const plugin = {
   id: "openclaw-cli-bridge-elvatis",
   name: "OpenClaw CLI Bridge",
-  version: "1.8.9",
+  version: PACKAGE_VERSION,
   description:
     "Phase 1: openai-codex auth bridge. " +
     "Phase 2: HTTP proxy for gemini/claude CLIs. " +
@@ -956,6 +972,43 @@ const plugin = {
     const codexAuthPath = cfg.codexAuthPath ?? DEFAULT_CODEX_AUTH_PATH;
     const grokSessionPath = cfg.grokSessionPath ?? DEFAULT_SESSION_PATH;
 
+    // ── Model → slash command mapping for status page ──────────────────────────
+    const modelCommands: Record<string, string> = {};
+    for (const entry of CLI_MODEL_COMMANDS) {
+      // Strip vllm/ prefix to match CLI_MODELS IDs
+      const modelId = entry.model.replace(/^vllm\//, "");
+      modelCommands[modelId] = `/${entry.name}`;
+    }
+
+    // ── Default model fallback chain ──────────────────────────────────────────
+    // When a primary model fails (timeout, error), retry once with a lighter variant.
+    const modelFallbacks: Record<string, string> = {
+      "cli-gemini/gemini-2.5-pro":       "cli-gemini/gemini-2.5-flash",
+      "cli-gemini/gemini-3-pro-preview":  "cli-gemini/gemini-3-flash-preview",
+      "cli-claude/claude-opus-4-6":       "cli-claude/claude-sonnet-4-6",
+      "cli-claude/claude-sonnet-4-6":     "cli-claude/claude-haiku-4-5",
+    };
+
+    // ── Migrate legacy per-provider cookie expiry files to consolidated store ─
+    const migration = migrateLegacyFiles();
+    if (migration.migrated.length > 0) {
+      api.logger.info(`[cli-bridge] migrated cookie expiry data: ${migration.migrated.join(", ")} → cookie-expiry.json`);
+    }
+
+    // ── Chrome availability check ────────────────────────────────────────────
+    // Stealth mode uses channel: "chrome" (real system Chrome). If it's missing,
+    // browser launches will fail or Cloudflare will block the bundled Chromium.
+    const chromeCheck = checkSystemChrome();
+    if (chromeCheck.available) {
+      api.logger.info(`[cli-bridge] system Chrome found: ${chromeCheck.version ?? chromeCheck.path}`);
+    } else {
+      api.logger.warn(
+        `[cli-bridge] ⚠ system Chrome not found! Web browser providers (/grok-login, /gemini-login, etc.) ` +
+        `require Google Chrome or Chromium installed system-wide. ` +
+        `Install with: sudo apt install google-chrome-stable (or chromium-browser)`
+      );
+    }
+
     // ── Session restore: only on first plugin load (not on hot-reloads) ──────
     // The gateway polls every ~60s via openclaw status, which triggers a hot-reload
     // (SIGUSR1 + hybrid mode). Module-level contexts (grokContext etc.) survive
@@ -975,8 +1028,8 @@ const plugin = {
 
         const profileProviders: Array<{
           name: string;
+          providerKey: import("./src/cookie-expiry-store.js").ProviderName;
           profileDir: string;
-          cookieFile: string;
           verifySelector: string;
           homeUrl: string;
           loginCmd: string;
@@ -985,8 +1038,8 @@ const plugin = {
         }> = [
           {
             name: "grok",
+            providerKey: "grok",
             profileDir: GROK_PROFILE_DIR,
-            cookieFile: GROK_EXPIRY_FILE,
             verifySelector: "textarea",
             homeUrl: "https://grok.com",
             loginCmd: "/grok-login",
@@ -995,8 +1048,8 @@ const plugin = {
           },
           {
             name: "gemini",
+            providerKey: "gemini",
             profileDir: GEMINI_PROFILE_DIR,
-            cookieFile: join(homedir(), ".openclaw", "gemini-cookie-expiry.json"),
             verifySelector: ".ql-editor",
             homeUrl: "https://gemini.google.com/app",
             loginCmd: "/gemini-login",
@@ -1005,8 +1058,8 @@ const plugin = {
           },
           {
             name: "claude-web",
+            providerKey: "claude",
             profileDir: CLAUDE_PROFILE_DIR,
-            cookieFile: CLAUDE_EXPIRY_FILE,
             verifySelector: ".ProseMirror",
             homeUrl: "https://claude.ai/new",
             loginCmd: "/claude-login",
@@ -1015,8 +1068,8 @@ const plugin = {
           },
           {
             name: "chatgpt",
+            providerKey: "chatgpt",
             profileDir: CHATGPT_PROFILE_DIR,
-            cookieFile: CHATGPT_EXPIRY_FILE,
             verifySelector: "#prompt-textarea",
             homeUrl: "https://chatgpt.com",
             loginCmd: "/chatgpt-login",
@@ -1026,22 +1079,22 @@ const plugin = {
         ];
 
         for (const p of profileProviders) {
-          if (!existsSync(p.profileDir) && !existsSync(p.cookieFile)) {
+          const storedExpiry = loadProviderExpiry(p.providerKey);
+          if (!existsSync(p.profileDir) && !storedExpiry) {
             api.logger.info(`[cli-bridge:${p.name}] no saved profile — skipping startup restore`);
             continue;
           }
           if (p.getCtx()) continue; // already connected
 
           // ── Cookie-first check ────────────────────────────────────────────
-          // If a cookie expiry file exists and is still valid (>1h left),
+          // If cookie expiry data exists and is still valid (>1h left),
           // launch the persistent context immediately without a browser-based
           // selector check. Selector checks are fragile (slow pages, DOM changes).
           // The keep-alive (20h) will verify the session properly later.
           let cookiesValid = false;
-          if (existsSync(p.cookieFile)) {
+          if (storedExpiry) {
             try {
-              const expInfo = JSON.parse(readFileSync(p.cookieFile, "utf-8")) as { expiresAt: number };
-              const msLeft = expInfo.expiresAt - Date.now();
+              const msLeft = storedExpiry.expiresAt - Date.now();
               if (msLeft > 3_600_000) { // >1h remaining
                 cookiesValid = true;
                 api.logger.info(`[cli-bridge:${p.name}] cookie valid (${Math.floor(msLeft / 86_400_000)}d left) — restoring context without browser check`);
@@ -1274,6 +1327,8 @@ const plugin = {
               return chatgptContext;
             },
             version: plugin.version,
+            modelCommands,
+            modelFallbacks,
             getExpiryInfo: () => ({
               grok:    (() => { const e = loadGrokExpiry();    return e ? formatExpiryInfo(e)    : null; })(),
               gemini:  (() => { const e = loadGeminiExpiry();  return e ? formatGeminiExpiry(e)  : null; })(),
@@ -1309,7 +1364,7 @@ const plugin = {
             // One final attempt
             try {
               const server = await startProxyServer({
-                port, apiKey, timeoutMs,
+                port, apiKey, timeoutMs, modelCommands, modelFallbacks,
                 log: (msg) => api.logger.info(msg),
                 warn: (msg) => api.logger.warn(msg),
                 getGrokContext: () => grokContext,

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "openclaw-cli-bridge-elvatis",
   "slug": "openclaw-cli-bridge-elvatis",
   "name": "OpenClaw CLI Bridge",
-  "version": "1.8.9",
+  "version": "1.9.0",
   "license": "MIT",
   "description": "Phase 1: openai-codex auth bridge. Phase 2: local HTTP proxy routing model calls through gemini/claude CLIs (vllm provider).",
   "providers": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elvatis_com/openclaw-cli-bridge-elvatis",
-  "version": "1.8.9",
+  "version": "1.9.0",
   "description": "Bridges gemini, claude, and codex CLI tools as OpenClaw model providers. Reads existing CLI auth without re-login.",
   "type": "module",
   "openclaw": {
@@ -12,11 +12,15 @@
     "build": "tsc --noEmitOnError false",
     "typecheck": "tsc -p tsconfig.check.json",
     "test": "vitest run",
-    "ci": "npm run typecheck && npm run test"
+    "lint": "eslint .",
+    "ci": "npm run lint && npm run typecheck && npm run test"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@types/node": "^25.3.2",
+    "eslint": "^10.0.3",
     "typescript": "^5.9.3",
+    "typescript-eslint": "^8.57.0",
     "vitest": "^4.0.18"
   },
   "dependencies": {

package/src/chrome-check.ts

@@ -0,0 +1,52 @@
+/**
+ * chrome-check.ts
+ *
+ * Startup check for system Chrome availability.
+ * Playwright's stealth mode uses `channel: "chrome"` which requires a real
+ * Chrome/Chromium installation. Without it, browser launches fail silently
+ * or Cloudflare flags the bundled Chromium as automation.
+ */
+
+import { execFileSync } from "node:child_process";
+
+const CHROME_CANDIDATES = [
+  "google-chrome",
+  "google-chrome-stable",
+  "chromium-browser",
+  "chromium",
+];
+
+export interface ChromeCheckResult {
+  available: boolean;
+  path: string | null;
+  version: string | null;
+}
+
+/**
+ * Check if a system Chrome installation exists.
+ * Returns the path and version if found, or null if missing.
+ */
+export function checkSystemChrome(): ChromeCheckResult {
+  for (const candidate of CHROME_CANDIDATES) {
+    try {
+      const whichResult = execFileSync("which", [candidate], {
+        encoding: "utf-8",
+        timeout: 3000,
+      }).trim();
+
+      if (whichResult) {
+        let version: string | null = null;
+        try {
+          version = execFileSync(candidate, ["--version"], {
+            encoding: "utf-8",
+            timeout: 3000,
+          }).trim();
+        } catch { /* version check optional */ }
+        return { available: true, path: whichResult, version };
+      }
+    } catch {
+      // candidate not found — try next
+    }
+  }
+  return { available: false, path: null, version: null };
+}

package/src/cookie-expiry-store.ts

@@ -0,0 +1,108 @@
+/**
+ * cookie-expiry-store.ts
+ *
+ * Consolidated cookie expiry tracking for all web providers.
+ * Replaces 4 separate JSON files with a single unified store:
+ *   ~/.openclaw/cookie-expiry.json
+ *
+ * Migration: on first load, imports data from legacy per-provider files
+ * and deletes them.
+ */
+
+import { readFileSync, writeFileSync, existsSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+export type ProviderName = "grok" | "gemini" | "claude" | "chatgpt";
+
+export interface ExpiryInfo {
+  expiresAt: number;   // epoch ms
+  loginAt: number;     // epoch ms
+  cookieName: string;
+}
+
+export interface CookieExpiryData {
+  grok: ExpiryInfo | null;
+  gemini: ExpiryInfo | null;
+  claude: ExpiryInfo | null;
+  chatgpt: ExpiryInfo | null;
+}
+
+const STORE_PATH = join(homedir(), ".openclaw", "cookie-expiry.json");
+
+// Legacy file paths (for migration)
+const LEGACY_FILES: Record<ProviderName, string> = {
+  grok: join(homedir(), ".openclaw", "grok-cookie-expiry.json"),
+  gemini: join(homedir(), ".openclaw", "gemini-cookie-expiry.json"),
+  claude: join(homedir(), ".openclaw", "claude-cookie-expiry.json"),
+  chatgpt: join(homedir(), ".openclaw", "chatgpt-cookie-expiry.json"),
+};
+
+function emptyData(): CookieExpiryData {
+  return { grok: null, gemini: null, claude: null, chatgpt: null };
+}
+
+/**
+ * Migrate legacy per-provider files into the consolidated store.
+ * Safe to call multiple times — only imports files that exist.
+ */
+export function migrateLegacyFiles(): { migrated: ProviderName[] } {
+  const migrated: ProviderName[] = [];
+  let data = loadAll();
+
+  for (const [provider, legacyPath] of Object.entries(LEGACY_FILES) as [ProviderName, string][]) {
+    if (!existsSync(legacyPath)) continue;
+    try {
+      const legacy = JSON.parse(readFileSync(legacyPath, "utf-8")) as ExpiryInfo;
+      // Only import if we don't already have newer data
+      if (!data[provider] || legacy.loginAt > data[provider]!.loginAt) {
+        data[provider] = legacy;
+        migrated.push(provider);
+      }
+      unlinkSync(legacyPath);
+    } catch {
+      // Corrupted legacy file — just delete it
+      try { unlinkSync(legacyPath); } catch { /* ignore */ }
+    }
+  }
+
+  if (migrated.length > 0) {
+    writeAll(data);
+  }
+  return { migrated };
+}
+
+/** Load the entire expiry store. Returns empty data if file doesn't exist. */
+export function loadAll(): CookieExpiryData {
+  try {
+    const raw = readFileSync(STORE_PATH, "utf-8");
+    const parsed = JSON.parse(raw) as Partial<CookieExpiryData>;
+    return { ...emptyData(), ...parsed };
+  } catch {
+    return emptyData();
+  }
+}
+
+/** Save a single provider's expiry info. Merges with existing data. */
+export function saveProviderExpiry(provider: ProviderName, info: ExpiryInfo): void {
+  const data = loadAll();
+  data[provider] = info;
+  writeAll(data);
+}
+
+/** Load a single provider's expiry info. */
+export function loadProviderExpiry(provider: ProviderName): ExpiryInfo | null {
+  return loadAll()[provider];
+}
+
+/** Write the full store to disk. */
+function writeAll(data: CookieExpiryData): void {
+  try {
+    writeFileSync(STORE_PATH, JSON.stringify(data, null, 2));
+  } catch { /* ignore write errors */ }
+}
+
+/** Get the store file path (for existsSync checks in startup restore). */
+export function getStorePath(): string {
+  return STORE_PATH;
+}

package/src/proxy-server.ts

@@ -17,6 +17,7 @@ import { geminiComplete, geminiCompleteStream, type ChatMessage as GeminiBrowser
 import { claudeComplete, claudeCompleteStream, type ChatMessage as ClaudeBrowserChatMessage } from "./claude-browser.js";
 import { chatgptComplete, chatgptCompleteStream, type ChatMessage as ChatGPTBrowserChatMessage } from "./chatgpt-browser.js";
 import type { BrowserContext } from "playwright";
+import { renderStatusPage, type StatusProvider } from "./status-template.js";
 
 export type GrokCompleteOptions = Parameters<typeof grokComplete>[1];
 export type GrokCompleteStreamOptions = Parameters<typeof grokCompleteStream>[1];
@@ -71,6 +72,14 @@ export interface ProxyServerOptions {
   version?: string;
   /** Returns the BitNet llama-server base URL (default: http://127.0.0.1:8082) */
   getBitNetServerUrl?: () => string;
+  /** Maps model ID → slash command name for the status page display */
+  modelCommands?: Record<string, string>;
+  /**
+   * Model fallback chain — maps a model prefix to a fallback model.
+   * When a CLI model fails (timeout, error), the request is retried once
+   * with the fallback model. Example: "cli-gemini/gemini-2.5-pro" → "cli-gemini/gemini-2.5-flash"
+   */
+  modelFallbacks?: Record<string, string>;
 }
 
 /** Available CLI bridge models for GET /v1/models */
@@ -158,121 +167,56 @@ async function handleRequest(
 
   const url = req.url ?? "/";
 
-  // Health check
+  // Health check (simple)
   if (url === "/health" || url === "/v1/health") {
     res.writeHead(200, { "Content-Type": "application/json" });
     res.end(JSON.stringify({ status: "ok", service: "openclaw-cli-bridge" }));
     return;
   }
 
+  // Health check (detailed JSON — for monitoring scripts)
+  if (url === "/healthz" && req.method === "GET") {
+    const expiry = opts.getExpiryInfo?.() ?? { grok: null, gemini: null, claude: null, chatgpt: null };
+    const sessionStatus = (provider: string, ctxGetter: (() => import("playwright").BrowserContext | null) | undefined, expiryStr: string | null) => {
+      const connected = ctxGetter?.() !== null && ctxGetter?.() !== undefined;
+      let status: "connected" | "logged_in" | "expired" | "not_configured" = "not_configured";
+      if (connected) status = "connected";
+      else if (expiryStr?.startsWith("⚠️ EXPIRED")) status = "expired";
+      else if (expiryStr) status = "logged_in";
+      return { status, expiry: expiryStr };
+    };
+    const health = {
+      status: "ok",
+      service: "openclaw-cli-bridge",
+      version: opts.version ?? "?",
+      port: opts.port,
+      uptime_s: Math.floor(process.uptime()),
+      providers: {
+        grok: sessionStatus("grok", opts.getGrokContext, expiry.grok),
+        gemini: sessionStatus("gemini", opts.getGeminiContext, expiry.gemini),
+        claude: sessionStatus("claude", opts.getClaudeContext, expiry.claude),
+        chatgpt: sessionStatus("chatgpt", opts.getChatGPTContext, expiry.chatgpt),
+      },
+      models: CLI_MODELS.length,
+    };
+    res.writeHead(200, { "Content-Type": "application/json", ...corsHeaders() });
+    res.end(JSON.stringify(health, null, 2));
+    return;
+  }
+
   // Browser status page — human-readable HTML dashboard
   if ((url === "/status" || url === "/") && req.method === "GET") {
     const expiry = opts.getExpiryInfo?.() ?? { grok: null, gemini: null, claude: null, chatgpt: null };
     const version = opts.version ?? "?";
 
-    const providers = [
+    const providers: StatusProvider[] = [
       { name: "Grok",     icon: "𝕏",  expiry: expiry.grok,    loginCmd: "/grok-login",    ctx: opts.getGrokContext?.() ?? null },
       { name: "Gemini",   icon: "✦",  expiry: expiry.gemini,  loginCmd: "/gemini-login",  ctx: opts.getGeminiContext?.() ?? null },
       { name: "Claude",   icon: "◆",  expiry: expiry.claude,  loginCmd: "/claude-login",  ctx: opts.getClaudeContext?.() ?? null },
       { name: "ChatGPT",  icon: "◉",  expiry: expiry.chatgpt, loginCmd: "/chatgpt-login", ctx: opts.getChatGPTContext?.() ?? null },
     ];
 
-    function statusBadge(p: typeof providers[0]): { label: string; color: string; dot: string } {
-      if (p.ctx !== null) return { label: "Connected", color: "#22c55e", dot: "🟢" };
-      if (!p.expiry) return { label: "Never logged in", color: "#6b7280", dot: "⚪" };
-      if (p.expiry.startsWith("⚠️ EXPIRED")) return { label: "Expired", color: "#ef4444", dot: "🔴" };
-      if (p.expiry.startsWith("🚨")) return { label: "Expiring soon", color: "#f59e0b", dot: "🟡" };
-      return { label: "Logged in", color: "#3b82f6", dot: "🔵" };
-    }
-
-    const rows = providers.map(p => {
-      const badge = statusBadge(p);
-      const expiryText = p.expiry
-        ? p.expiry.replace(/[⚠️🚨✅🕐]/gu, "").trim()
-        : `Not logged in — run <code>${p.loginCmd}</code>`;
-      return `
-        <tr>
-          <td style="padding:12px 16px;font-weight:600;font-size:15px">${p.icon} ${p.name}</td>
-          <td style="padding:12px 16px">
-            <span style="background:${badge.color}22;color:${badge.color};border:1px solid ${badge.color}44;
-                         border-radius:6px;padding:3px 10px;font-size:13px;font-weight:600">
-              ${badge.dot} ${badge.label}
-            </span>
-          </td>
-          <td style="padding:12px 16px;color:#9ca3af;font-size:13px">${expiryText}</td>
-          <td style="padding:12px 16px;color:#6b7280;font-size:12px;font-family:monospace">${p.loginCmd}</td>
-        </tr>`;
-    }).join("");
-
-    const cliModels = CLI_MODELS.filter(m => m.id.startsWith("cli-"));
-    const codexModels = CLI_MODELS.filter(m => m.id.startsWith("openai-codex/"));
-    const webModels = CLI_MODELS.filter(m => m.id.startsWith("web-"));
-    const localModels = CLI_MODELS.filter(m => m.id.startsWith("local-"));
-    const modelList = (models: typeof CLI_MODELS) =>
-      models.map(m => `<li style="margin:2px 0;font-size:13px;color:#d1d5db"><code style="color:#93c5fd">${m.id}</code></li>`).join("");
-
-    const html = `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>CLI Bridge Status</title>
-  <meta http-equiv="refresh" content="30">
-  <style>
-    * { box-sizing: border-box; margin: 0; padding: 0; }
-    body { background: #0f1117; color: #e5e7eb; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; min-height: 100vh; padding: 32px 24px; }
-    h1 { font-size: 22px; font-weight: 700; color: #f9fafb; margin-bottom: 4px; }
-    .subtitle { color: #6b7280; font-size: 13px; margin-bottom: 28px; }
-    .card { background: #1a1d27; border: 1px solid #2d3148; border-radius: 12px; overflow: hidden; margin-bottom: 24px; }
-    .card-header { padding: 14px 16px; border-bottom: 1px solid #2d3148; font-size: 12px; font-weight: 600; color: #6b7280; text-transform: uppercase; letter-spacing: 0.05em; }
-    table { width: 100%; border-collapse: collapse; }
-    tr:not(:last-child) td { border-bottom: 1px solid #1f2335; }
-    .models { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; }
-    ul { list-style: none; padding: 12px 16px; }
-    .footer { color: #374151; font-size: 12px; text-align: center; margin-top: 16px; }
-    code { background: #1e2130; padding: 1px 5px; border-radius: 4px; }
-  </style>
-</head>
-<body>
-  <h1>🌉 CLI Bridge</h1>
-  <p class="subtitle">v${version} &nbsp;·&nbsp; Port ${opts.port} &nbsp;·&nbsp; Auto-refreshes every 30s</p>
-
-  <div class="card">
-    <div class="card-header">Web Session Providers</div>
-    <table>
-      <thead>
-        <tr style="background:#13151f">
-          <th style="padding:10px 16px;text-align:left;font-size:12px;color:#4b5563;font-weight:600">Provider</th>
-          <th style="padding:10px 16px;text-align:left;font-size:12px;color:#4b5563;font-weight:600">Status</th>
-          <th style="padding:10px 16px;text-align:left;font-size:12px;color:#4b5563;font-weight:600">Session</th>
-          <th style="padding:10px 16px;text-align:left;font-size:12px;color:#4b5563;font-weight:600">Login</th>
-        </tr>
-      </thead>
-      <tbody>${rows}</tbody>
-    </table>
-  </div>
-
-  <div class="models">
-    <div class="card">
-      <div class="card-header">CLI Models (${cliModels.length})</div>
-      <ul>${modelList(cliModels)}</ul>
-      <div class="card-header">Codex Models (${codexModels.length})</div>
-      <ul>${modelList(codexModels)}</ul>
-    </div>
-    <div class="card">
-      <div class="card-header">Web Session Models (${webModels.length})</div>
-      <ul>${modelList(webModels)}</ul>
-    </div>
-    <div class="card">
-      <div class="card-header">Local Models (${localModels.length})</div>
-      <ul>${modelList(localModels)}</ul>
-    </div>
-  </div>
-
-  <p class="footer">openclaw-cli-bridge-elvatis v${version} &nbsp;·&nbsp; <a href="/v1/models" style="color:#4b5563">/v1/models</a> &nbsp;·&nbsp; <a href="/health" style="color:#4b5563">/health</a></p>
-</body>
-</html>`;
-
+    const html = renderStatusPage({ version, port: opts.port, providers, models: CLI_MODELS, modelCommands: opts.modelCommands });
     res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
     res.end(html);
     return;
@@ -645,14 +589,32 @@ async function handleRequest(
 
     // ── CLI runner routing (Gemini / Claude Code) ─────────────────────────────
     let content: string;
+    let usedModel = model;
     try {
       content = await routeToCliRunner(model, messages, opts.timeoutMs ?? 120_000);
     } catch (err) {
       const msg = (err as Error).message;
-      opts.warn(`[cli-bridge] CLI error for ${model}: ${msg}`);
-      res.writeHead(500, { "Content-Type": "application/json" });
-      res.end(JSON.stringify({ error: { message: msg, type: "cli_error" } }));
-      return;
+      // ── Model fallback: retry once with a lighter model if configured ────
+      const fallbackModel = opts.modelFallbacks?.[model];
+      if (fallbackModel) {
+        opts.warn(`[cli-bridge] ${model} failed (${msg}), falling back to ${fallbackModel}`);
+        try {
+          content = await routeToCliRunner(fallbackModel, messages, opts.timeoutMs ?? 120_000);
+          usedModel = fallbackModel;
+          opts.log(`[cli-bridge] fallback to ${fallbackModel} succeeded`);
+        } catch (fallbackErr) {
+          const fallbackMsg = (fallbackErr as Error).message;
+          opts.warn(`[cli-bridge] fallback ${fallbackModel} also failed: ${fallbackMsg}`);
+          res.writeHead(500, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ error: { message: `${model}: ${msg} | fallback ${fallbackModel}: ${fallbackMsg}`, type: "cli_error" } }));
+          return;
+        }
+      } else {
+        opts.warn(`[cli-bridge] CLI error for ${model}: ${msg}`);
+        res.writeHead(500, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: { message: msg, type: "cli_error" } }));
+        return;
+      }
     }
 
     if (stream) {
@@ -664,7 +626,7 @@ async function handleRequest(
       });
 
       // Role chunk
-      sendSseChunk(res, { id, created, model, delta: { role: "assistant" }, finish_reason: null });
+      sendSseChunk(res, { id, created, model: usedModel, delta: { role: "assistant" }, finish_reason: null });
 
       // Content in chunks (~50 chars each for natural feel)
       const chunkSize = 50;
@@ -672,14 +634,14 @@ async function handleRequest(
         sendSseChunk(res, {
           id,
           created,
-          model,
+          model: usedModel,
           delta: { content: content.slice(i, i + chunkSize) },
           finish_reason: null,
         });
       }
 
       // Stop chunk
-      sendSseChunk(res, { id, created, model, delta: {}, finish_reason: "stop" });
+      sendSseChunk(res, { id, created, model: usedModel, delta: {}, finish_reason: "stop" });
       res.write("data: [DONE]\n\n");
       res.end();
     } else {
@@ -687,7 +649,7 @@ async function handleRequest(
         id,
         object: "chat.completion",
         created,
-        model,
+        model: usedModel,
         choices: [
           {
             index: 0,

package/src/status-template.ts

@@ -0,0 +1,130 @@
+/**
+ * status-template.ts
+ *
+ * Generates the HTML dashboard for the /status endpoint.
+ * Extracted from proxy-server.ts for maintainability.
+ */
+
+import type { BrowserContext } from "playwright";
+
+export interface StatusProvider {
+  name: string;
+  icon: string;
+  expiry: string | null;
+  loginCmd: string;
+  ctx: BrowserContext | null;
+}
+
+export interface StatusTemplateOptions {
+  version: string;
+  port: number;
+  providers: StatusProvider[];
+  models: Array<{ id: string; name: string; contextWindow: number; maxTokens: number }>;
+  /** Maps model ID → slash command name (e.g. "openai-codex/gpt-5.3-codex" → "/cli-codex") */
+  modelCommands?: Record<string, string>;
+}
+
+function statusBadge(p: StatusProvider): { label: string; color: string; dot: string } {
+  if (p.ctx !== null) return { label: "Connected", color: "#22c55e", dot: "🟢" };
+  if (!p.expiry) return { label: "Never logged in", color: "#6b7280", dot: "⚪" };
+  if (p.expiry.startsWith("⚠️ EXPIRED")) return { label: "Expired", color: "#ef4444", dot: "🔴" };
+  if (p.expiry.startsWith("🚨")) return { label: "Expiring soon", color: "#f59e0b", dot: "🟡" };
+  return { label: "Logged in", color: "#3b82f6", dot: "🔵" };
+}
+
+export function renderStatusPage(opts: StatusTemplateOptions): string {
+  const { version, port, providers, models } = opts;
+
+  const rows = providers.map(p => {
+    const badge = statusBadge(p);
+    const expiryText = p.expiry
+      ? p.expiry.replace(/[⚠️🚨✅🕐]/gu, "").trim()
+      : `Not logged in — run <code>${p.loginCmd}</code>`;
+    return `
+        <tr>
+          <td style="padding:12px 16px;font-weight:600;font-size:15px">${p.icon} ${p.name}</td>
+          <td style="padding:12px 16px">
+            <span style="background:${badge.color}22;color:${badge.color};border:1px solid ${badge.color}44;
+                         border-radius:6px;padding:3px 10px;font-size:13px;font-weight:600">
+              ${badge.dot} ${badge.label}
+            </span>
+          </td>
+          <td style="padding:12px 16px;color:#9ca3af;font-size:13px">${expiryText}</td>
+          <td style="padding:12px 16px;color:#6b7280;font-size:12px;font-family:monospace">${p.loginCmd}</td>
+        </tr>`;
+  }).join("");
+
+  const cliModels = models.filter(m => m.id.startsWith("cli-"));
+  const codexModels = models.filter(m => m.id.startsWith("openai-codex/"));
+  const webModels = models.filter(m => m.id.startsWith("web-"));
+  const localModels = models.filter(m => m.id.startsWith("local-"));
+  const cmds = opts.modelCommands ?? {};
+  const modelList = (items: typeof models) =>
+    items.map(m => {
+      const cmd = cmds[m.id];
+      const cmdBadge = cmd ? `<span style="color:#6b7280;font-size:11px;margin-left:8px">${cmd}</span>` : "";
+      return `<li style="margin:2px 0;font-size:13px;color:#d1d5db"><code style="color:#93c5fd">${m.id}</code>${cmdBadge}</li>`;
+    }).join("");
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>CLI Bridge Status</title>
+  <meta http-equiv="refresh" content="30">
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body { background: #0f1117; color: #e5e7eb; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; min-height: 100vh; padding: 32px 24px; }
+    h1 { font-size: 22px; font-weight: 700; color: #f9fafb; margin-bottom: 4px; }
+    .subtitle { color: #6b7280; font-size: 13px; margin-bottom: 28px; }
+    .card { background: #1a1d27; border: 1px solid #2d3148; border-radius: 12px; overflow: hidden; margin-bottom: 24px; }
+    .card-header { padding: 14px 16px; border-bottom: 1px solid #2d3148; font-size: 12px; font-weight: 600; color: #6b7280; text-transform: uppercase; letter-spacing: 0.05em; }
+    table { width: 100%; border-collapse: collapse; }
+    tr:not(:last-child) td { border-bottom: 1px solid #1f2335; }
+    .models { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; }
+    ul { list-style: none; padding: 12px 16px; }
+    .footer { color: #374151; font-size: 12px; text-align: center; margin-top: 16px; }
+    code { background: #1e2130; padding: 1px 5px; border-radius: 4px; }
+  </style>
+</head>
+<body>
+  <h1>CLI Bridge</h1>
+  <p class="subtitle">v${version} &nbsp;&middot;&nbsp; Port ${port} &nbsp;&middot;&nbsp; Auto-refreshes every 30s</p>
+
+  <div class="card">
+    <div class="card-header">Web Session Providers</div>
+    <table>
+      <thead>
+        <tr style="background:#13151f">
+          <th style="padding:10px 16px;text-align:left;font-size:12px;color:#4b5563;font-weight:600">Provider</th>
+          <th style="padding:10px 16px;text-align:left;font-size:12px;color:#4b5563;font-weight:600">Status</th>
+          <th style="padding:10px 16px;text-align:left;font-size:12px;color:#4b5563;font-weight:600">Session</th>
+          <th style="padding:10px 16px;text-align:left;font-size:12px;color:#4b5563;font-weight:600">Login</th>
+        </tr>
+      </thead>
+      <tbody>${rows}</tbody>
+    </table>
+  </div>
+
+  <div class="models">
+    <div class="card">
+      <div class="card-header">CLI Models (${cliModels.length})</div>
+      <ul>${modelList(cliModels)}</ul>
+      <div class="card-header">Codex Models (${codexModels.length})</div>
+      <ul>${modelList(codexModels)}</ul>
+    </div>
+    <div class="card">
+      <div class="card-header">Web Session Models (${webModels.length})</div>
+      <ul>${modelList(webModels)}</ul>
+    </div>
+    <div class="card">
+      <div class="card-header">Local Models (${localModels.length})</div>
+      <ul>${modelList(localModels)}</ul>
+    </div>
+  </div>
+
+  <p class="footer">openclaw-cli-bridge-elvatis v${version} &nbsp;&middot;&nbsp; <a href="/v1/models" style="color:#4b5563">/v1/models</a> &nbsp;&middot;&nbsp; <a href="/health" style="color:#4b5563">/health</a> &nbsp;&middot;&nbsp; <a href="/healthz" style="color:#4b5563">/healthz</a></p>
+</body>
+</html>`;
+}