@elvatis_com/openclaw-cli-bridge-elvatis 0.2.25 → 0.2.27

package/.ai/handoff/STATUS.md

@@ -11,10 +11,10 @@ _Last session: 2026-03-11 — Akido (claude-sonnet-4-6)_
 
 | Platform | Version | Status |
 |----------|---------|--------|
-| GitHub | v0.2.23 | ✅ Tagged + Release (last published) |
-| npm | 0.2.23 | ✅ Published (last published) |
-| ClawHub | 0.2.23 | ✅ Published (last published) |
-| Local | 0.2.25 | ⏳ Built + tested, not yet published |
+| GitHub | v0.2.25 | ✅ Tagged + Release |
+| npm | 0.2.25 | ✅ Published |
+| ClawHub | 0.2.25 | ✅ Published (direct API — clawhub CLI v0.7.0 bug: missing acceptLicenseTerms) |
+| Local | 0.2.25 | ✅ Up to date |
 <!-- /SECTION: version -->
 
 <!-- SECTION: build_health -->
@@ -55,7 +55,7 @@ _Last session: 2026-03-11 — Akido (claude-sonnet-4-6)_
 <!-- SECTION: what_is_missing -->
 ## What Is Missing / Open
 
-- ⏳ **Publish v0.2.25** — GitHub tag + release, npm publish, ClawHub publish (T-010)
+- ✅ **v0.2.25 published** — GitHub, npm, ClawHub alle auf 0.2.25
 - ℹ️ **Claude CLI auth expires ~90 days** — when `/cli-test` returns 401, run `claude auth login`
 - ℹ️ **Config patcher writes `openclaw.json` directly** — triggers one gateway restart on first install
 - ℹ️ **ClawHub publish ignores `.clawhubignore`** — use rsync workaround (see CONVENTIONS.md)

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:** `0.2.25`
+**Current version:** `0.2.27`
 
 ---
 
@@ -287,6 +287,20 @@ npm test            # vitest run (45 tests)
 
 ## Changelog
 
+### v0.2.27
+- **feat:** Grok persistent Chromium profile (`~/.openclaw/grok-profile/`) — cookies survive gateway restarts
+- **feat:** `/grok-login` imports cookies from OpenClaw browser into persistent profile automatically
+- **fix:** `verifySession` reuses existing grok.com page instead of opening a new one (avoids Cloudflare 403)
+- **fix:** DOM-polling strategy instead of direct fetch API — bypasses `x-statsig-id` anti-bot check completely
+- **fix:** Lazy-connect: `connectGrokContext` callback auto-reconnects on first request after restart
+
+### v0.2.26
+- **feat:** Grok web-session bridge integrated into cli-bridge proxy — routes `web-grok/*` models through grok.com browser session (SuperGrok subscription, no API credits needed)
+- **feat:** `/grok-login` — opens Chromium for X.com OAuth login, saves session to `~/.openclaw/grok-session.json`
+- **feat:** `/grok-status` — check session validity
+- **feat:** `/grok-logout` — clear session
+- **fix:** Grok web-session plugin removed as separate plugin — consolidated into cli-bridge (fewer running processes, single proxy port)
+
 ### v0.2.25
 - **feat:** Staged model switching — `/cli-*` now stages the switch instead of applying it immediately. Prevents silent session corruption when switching models mid-conversation.
   - `/cli-sonnet` → stages switch, shows warning, does NOT apply

package/SKILL.md

@@ -53,4 +53,4 @@ Each command runs `openclaw models set <model>` atomically and replies with a co
 
 See `README.md` for full configuration reference and architecture diagram.
 
-**Version:** 0.2.25
+**Version:** 0.2.27

package/index.ts

@@ -48,6 +48,16 @@ import {
 } from "./src/codex-auth.js";
 import { startProxyServer } from "./src/proxy-server.js";
 import { patchOpencllawConfig } from "./src/config-patcher.js";
+import {
+  loadSession,
+  deleteSession,
+  isSessionExpiredByAge,
+  verifySession,
+  runInteractiveLogin,
+  createContextFromSession,
+  DEFAULT_SESSION_PATH,
+} from "./src/grok-session.js";
+import type { BrowserContext, Browser } from "playwright";
 
 // ──────────────────────────────────────────────────────────────────────────────
 // Types derived from SDK (not re-exported by the package)
@@ -66,6 +76,95 @@ interface CliPluginConfig {
   proxyPort?: number;
   proxyApiKey?: string;
   proxyTimeoutMs?: number;
+  grokSessionPath?: string;
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Grok web-session state (module-level, persists across commands)
+// ──────────────────────────────────────────────────────────────────────────────
+
+let grokBrowser: Browser | null = null;
+let grokContext: BrowserContext | null = null;
+
+// Persistent profile dir — survives gateway restarts, keeps cookies intact
+const GROK_PROFILE_DIR = join(homedir(), ".openclaw", "grok-profile");
+
+/**
+ * Launch (or reuse) a persistent headless Chromium context for grok.com.
+ * Uses launchPersistentContext so cookies survive gateway restarts.
+ * The profile lives at ~/.openclaw/grok-profile/
+ */
+async function getOrLaunchGrokContext(
+  log: (msg: string) => void
+): Promise<BrowserContext | null> {
+  // Already have a live context?
+  if (grokContext) {
+    try {
+      // Quick check: can we still enumerate pages?
+      grokContext.pages();
+      return grokContext;
+    } catch {
+      grokContext = null;
+    }
+  }
+
+  const { chromium } = await import("playwright");
+
+  // 1. Try connecting to the OpenClaw managed browser first (user may have grok.com open)
+  try {
+    const browser = await chromium.connectOverCDP("http://127.0.0.1:18800", { timeout: 2000 });
+    grokBrowser = browser;
+    const ctx = browser.contexts()[0];
+    if (ctx) {
+      log("[cli-bridge:grok] connected to OpenClaw browser");
+      return ctx;
+    }
+  } catch {
+    // OpenClaw browser not available — fall through to persistent context
+  }
+
+  // 2. Launch our own persistent headless Chromium with saved profile
+  log("[cli-bridge:grok] launching persistent Chromium…");
+  try {
+    const ctx = await chromium.launchPersistentContext(GROK_PROFILE_DIR, {
+      headless: true,
+      args: ["--no-sandbox", "--disable-setuid-sandbox"],
+    });
+    grokContext = ctx;
+    log("[cli-bridge:grok] persistent context ready");
+    return ctx;
+  } catch (err) {
+    log(`[cli-bridge:grok] failed to launch browser: ${(err as Error).message}`);
+    return null;
+  }
+}
+
+async function connectToOpenClawBrowser(
+  log: (msg: string) => void
+): Promise<BrowserContext | null> {
+  return getOrLaunchGrokContext(log);
+}
+
+async function tryRestoreGrokSession(
+  _sessionPath: string,
+  log: (msg: string) => void
+): Promise<boolean> {
+  try {
+    const ctx = await getOrLaunchGrokContext(log);
+    if (!ctx) return false;
+
+    const check = await verifySession(ctx, log);
+    if (!check.valid) {
+      log(`[cli-bridge:grok] session invalid: ${check.reason}`);
+      return false;
+    }
+    grokContext = ctx;
+    log("[cli-bridge:grok] session restored ✅");
+    return true;
+  } catch (err) {
+    log(`[cli-bridge:grok] session restore error: ${(err as Error).message}`);
+    return false;
+  }
 }
 
 const DEFAULT_PROXY_PORT = 31337;
@@ -393,7 +492,7 @@ function proxyTestRequest(
 const plugin = {
   id: "openclaw-cli-bridge-elvatis",
   name: "OpenClaw CLI Bridge",
-  version: "0.2.25",
+  version: "0.2.27",
   description:
     "Phase 1: openai-codex auth bridge. " +
     "Phase 2: HTTP proxy for gemini/claude CLIs. " +
@@ -407,6 +506,10 @@ const plugin = {
     const apiKey = cfg.proxyApiKey ?? DEFAULT_PROXY_API_KEY;
     const timeoutMs = cfg.proxyTimeoutMs ?? 120_000;
     const codexAuthPath = cfg.codexAuthPath ?? DEFAULT_CODEX_AUTH_PATH;
+    const grokSessionPath = cfg.grokSessionPath ?? DEFAULT_SESSION_PATH;
+
+    // ── Grok session restore (non-blocking) ───────────────────────────────────
+    void tryRestoreGrokSession(grokSessionPath, (msg) => api.logger.info(msg));
 
     // ── Phase 1: openai-codex auth bridge ─────────────────────────────────────
     if (enableCodex) {
@@ -503,6 +606,15 @@ const plugin = {
             timeoutMs,
             log: (msg) => api.logger.info(msg),
             warn: (msg) => api.logger.warn(msg),
+            getGrokContext: () => grokContext,
+            connectGrokContext: async () => {
+              const ctx = await connectToOpenClawBrowser((msg) => api.logger.info(msg));
+              if (ctx) {
+                const check = await verifySession(ctx, (msg) => api.logger.info(msg));
+                if (check.valid) { grokContext = ctx; return ctx; }
+              }
+              return null;
+            },
           });
           proxyServer = server;
           api.logger.info(
@@ -526,6 +638,15 @@ const plugin = {
                 port, apiKey, timeoutMs,
                 log: (msg) => api.logger.info(msg),
                 warn: (msg) => api.logger.warn(msg),
+                getGrokContext: () => grokContext,
+                connectGrokContext: async () => {
+                  const ctx = await connectToOpenClawBrowser((msg) => api.logger.info(msg));
+                  if (ctx) {
+                    const check = await verifySession(ctx, (msg) => api.logger.info(msg));
+                    if (check.valid) { grokContext = ctx; return ctx; }
+                  }
+                  return null;
+                },
               });
               proxyServer = server;
               api.logger.info(`[cli-bridge] proxy ready on :${port} (retry)`);
@@ -771,11 +892,96 @@ const plugin = {
       },
     } satisfies OpenClawPluginCommandDefinition);
 
+    // ── Phase 4: Grok web-session commands ────────────────────────────────────
+
+    api.registerCommand({
+      name: "grok-login",
+      description: "Authenticate grok.com: imports cookies from OpenClaw browser into persistent profile",
+      handler: async (): Promise<PluginCommandResult> => {
+        if (grokContext) {
+          const check = await verifySession(grokContext, (msg) => api.logger.info(msg));
+          if (check.valid) {
+            return { text: "✅ Already connected to grok.com. Use `/grok-logout` first to reset." };
+          }
+          grokContext = null;
+        }
+        api.logger.info("[cli-bridge:grok] /grok-login: importing session from OpenClaw browser…");
+        const { chromium } = await import("playwright");
+
+        // Step 1: try to grab cookies from the OpenClaw browser (user must have grok.com open)
+        let importedCookies: unknown[] = [];
+        try {
+          const ocBrowser = await chromium.connectOverCDP("http://127.0.0.1:18800", { timeout: 3000 });
+          const ocCtx = ocBrowser.contexts()[0];
+          if (ocCtx) {
+            importedCookies = await ocCtx.cookies(["https://grok.com", "https://x.ai", "https://accounts.x.ai"]);
+            api.logger.info(`[cli-bridge:grok] imported ${importedCookies.length} cookies from OpenClaw browser`);
+          }
+          await ocBrowser.close().catch(() => {});
+        } catch {
+          api.logger.info("[cli-bridge:grok] OpenClaw browser not available — using saved profile");
+        }
+
+        // Step 2: launch/connect persistent context and inject cookies
+        const ctx = await getOrLaunchGrokContext((msg) => api.logger.info(msg));
+        if (!ctx) return { text: "❌ Could not launch browser. Check server logs." };
+
+        if (importedCookies.length > 0) {
+          await ctx.addCookies(importedCookies as Parameters<typeof ctx.addCookies>[0]);
+          api.logger.info(`[cli-bridge:grok] cookies injected into persistent profile`);
+        }
+
+        // Step 3: navigate to grok.com and verify
+        const pages = ctx.pages();
+        const page = pages.find(p => p.url().includes("grok.com")) ?? await ctx.newPage();
+        if (!page.url().includes("grok.com")) {
+          await page.goto("https://grok.com", { waitUntil: "domcontentloaded", timeout: 15_000 });
+        }
+
+        const check = await verifySession(ctx, (msg) => api.logger.info(msg));
+        if (!check.valid) {
+          return { text: `❌ Session not valid: ${check.reason}\n\nMake sure grok.com is open in your browser and you're logged in, then run /grok-login again.` };
+        }
+        grokContext = ctx;
+        return { text: `✅ Grok session ready!\n\nModels available:\n• \`vllm/web-grok/grok-3\`\n• \`vllm/web-grok/grok-3-fast\`\n• \`vllm/web-grok/grok-3-mini\`\n• \`vllm/web-grok/grok-3-mini-fast\`\n\nSession persists across gateway restarts (profile: ~/.openclaw/grok-profile/)` };
+      },
+    } satisfies OpenClawPluginCommandDefinition);
+
+    api.registerCommand({
+      name: "grok-status",
+      description: "Check grok.com session status",
+      handler: async (): Promise<PluginCommandResult> => {
+        if (!grokContext) {
+          return { text: "❌ No active grok.com session\nRun `/grok-login` to authenticate." };
+        }
+        const check = await verifySession(grokContext, (msg) => api.logger.info(msg));
+        if (check.valid) {
+          return { text: `✅ grok.com session active\nProxy: \`127.0.0.1:${port}\`\nModels: web-grok/grok-3, web-grok/grok-3-fast, web-grok/grok-3-mini, web-grok/grok-3-mini-fast` };
+        }
+        grokContext = null;
+        return { text: `❌ Session expired: ${check.reason}\nRun \`/grok-login\` to re-authenticate.` };
+      },
+    } satisfies OpenClawPluginCommandDefinition);
+
+    api.registerCommand({
+      name: "grok-logout",
+      description: "Disconnect from grok.com session (does not close the browser)",
+      handler: async (): Promise<PluginCommandResult> => {
+        // Don't close the context — it belongs to the OpenClaw browser, not us
+        grokContext = null;
+        deleteSession(grokSessionPath);
+        return { text: "✅ Disconnected from grok.com. Run `/grok-login` to reconnect." };
+      },
+    } satisfies OpenClawPluginCommandDefinition);
+
     const allCommands = [
       ...CLI_MODEL_COMMANDS.map((c) => `/${c.name}`),
       "/cli-back",
       "/cli-test",
       "/cli-list",
+      "/grok-login",
+      "/grok-status",
+      "/grok-logout",
     ];
     api.logger.info(`[cli-bridge] registered ${allCommands.length} commands: ${allCommands.join(", ")}`);
   },

package/openclaw.plugin.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elvatis_com/openclaw-cli-bridge-elvatis",
-  "version": "0.2.25",
+  "version": "0.2.27",
   "description": "Bridges gemini, claude, and codex CLI tools as OpenClaw model providers. Reads existing CLI auth without re-login.",
   "type": "module",
   "openclaw": {
@@ -18,5 +18,8 @@
     "@types/node": "^25.3.2",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
+  },
+  "dependencies": {
+    "playwright": "^1.58.2"
   }
 }

package/src/grok-client.ts

@@ -0,0 +1,249 @@
+/**
+ * grok-client.ts
+ *
+ * Grok.com integration via Playwright DOM automation.
+ *
+ * Strategy: inject messages via the ProseMirror editor, poll `.message-bubble`
+ * DOM elements for the response. This bypasses Cloudflare anti-bot checks
+ * on direct API calls (which require signed x-statsig-id headers generated
+ * inside the page's own bundle — not accessible externally).
+ *
+ * Works by connecting to the running OpenClaw browser (CDP port 18800) which
+ * already has an authenticated grok.com session open.
+ */
+
+import type { BrowserContext, Page } from "playwright";
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Types
+// ──────────────────────────────────────────────────────────────────────────────
+
+export interface ChatMessage {
+  role: "system" | "user" | "assistant";
+  content: string;
+}
+
+export interface GrokCompleteOptions {
+  messages: ChatMessage[];
+  model?: string;
+  timeoutMs?: number;
+}
+
+export interface GrokCompleteResult {
+  content: string;
+  model: string;
+  finishReason: string;
+  promptTokens?: number;
+  completionTokens?: number;
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Constants
+// ──────────────────────────────────────────────────────────────────────────────
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+const STABLE_CHECKS = 3;       // consecutive identical reads to consider "done"
+const STABLE_INTERVAL_MS = 500; // ms between stability checks
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ──────────────────────────────────────────────────────────────────────────────
+
+function resolveModel(m?: string): string {
+  const clean = (m ?? "grok-3").replace("web-grok/", "");
+  const allowed = ["grok-3", "grok-3-fast", "grok-3-mini", "grok-3-mini-fast"];
+  return allowed.includes(clean) ? clean : "grok-3";
+}
+
+/**
+ * Flatten a multi-turn message array into a single string for the Grok UI.
+ */
+function flattenMessages(messages: ChatMessage[]): string {
+  if (messages.length === 1) return messages[0].content;
+  return messages
+    .map((m) => {
+      if (m.role === "system") return `[System]: ${m.content}`;
+      if (m.role === "assistant") return `[Assistant]: ${m.content}`;
+      return m.content;
+    })
+    .join("\n\n");
+}
+
+/**
+ * Get an existing grok.com page from the context, or navigate to grok.com.
+ */
+export async function getOrCreateGrokPage(
+  context: BrowserContext
+): Promise<{ page: Page; owned: boolean }> {
+  const existing = context.pages().filter((p) => p.url().startsWith("https://grok.com"));
+  if (existing.length > 0) return { page: existing[0], owned: false };
+  const page = await context.newPage();
+  await page.goto("https://grok.com", { waitUntil: "domcontentloaded", timeout: 15_000 });
+  return { page, owned: true };
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Core DOM automation
+// ──────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Send a message via the grok.com UI and wait for a stable response.
+ * Returns the final text content of the last `.message-bubble` element.
+ */
+async function sendAndWait(
+  page: Page,
+  message: string,
+  timeoutMs: number,
+  log: (msg: string) => void
+): Promise<string> {
+  // Count current message bubbles
+  const countBefore = await page.evaluate(
+    () => document.querySelectorAll(".message-bubble").length
+  );
+
+  // Type the message into the ProseMirror editor
+  await page.evaluate((msg: string) => {
+    const ed =
+      document.querySelector(".ProseMirror") ||
+      document.querySelector('[contenteditable="true"]');
+    if (!ed) throw new Error("Grok editor not found");
+    (ed as HTMLElement).focus();
+    document.execCommand("insertText", false, msg);
+  }, message);
+
+  await new Promise((r) => setTimeout(r, 300));
+  await page.keyboard.press("Enter");
+
+  log(`grok-client: message sent (${message.length} chars), waiting for response…`);
+
+  // Poll for a stable response
+  const deadline = Date.now() + timeoutMs;
+  let lastText = "";
+  let stableCount = 0;
+
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, STABLE_INTERVAL_MS));
+
+    const text = await page.evaluate(
+      (before: number) => {
+        const bubbles = [...document.querySelectorAll(".message-bubble")];
+        if (bubbles.length <= before) return "";
+        return bubbles[bubbles.length - 1].textContent?.trim() ?? "";
+      },
+      countBefore
+    );
+
+    if (text && text === lastText) {
+      stableCount++;
+      if (stableCount >= STABLE_CHECKS) {
+        log(`grok-client: response stable (${text.length} chars)`);
+        return text;
+      }
+    } else {
+      stableCount = 0;
+      lastText = text;
+    }
+  }
+
+  throw new Error(`grok.com response timeout after ${timeoutMs}ms`);
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Public API
+// ──────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Non-streaming completion.
+ */
+export async function grokComplete(
+  context: BrowserContext,
+  opts: GrokCompleteOptions,
+  log: (msg: string) => void
+): Promise<GrokCompleteResult> {
+  const { page, owned } = await getOrCreateGrokPage(context);
+  const model = resolveModel(opts.model);
+  const prompt = flattenMessages(opts.messages);
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+
+  log(`grok-client: complete model=${model}`);
+
+  try {
+    const content = await sendAndWait(page, prompt, timeoutMs, log);
+    return { content, model, finishReason: "stop" };
+  } finally {
+    if (owned) await page.close().catch(() => {});
+  }
+}
+
+/**
+ * Streaming completion — polls the DOM and calls onToken when new text arrives.
+ */
+export async function grokCompleteStream(
+  context: BrowserContext,
+  opts: GrokCompleteOptions,
+  onToken: (token: string) => void,
+  log: (msg: string) => void
+): Promise<GrokCompleteResult> {
+  const { page, owned } = await getOrCreateGrokPage(context);
+  const model = resolveModel(opts.model);
+  const prompt = flattenMessages(opts.messages);
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+
+  log(`grok-client: stream model=${model}`);
+
+  const countBefore = await page.evaluate(
+    () => document.querySelectorAll(".message-bubble").length
+  );
+
+  // Send message
+  await page.evaluate((msg: string) => {
+    const ed =
+      document.querySelector(".ProseMirror") ||
+      document.querySelector('[contenteditable="true"]');
+    if (!ed) throw new Error("Grok editor not found");
+    (ed as HTMLElement).focus();
+    document.execCommand("insertText", false, msg);
+  }, prompt);
+  await new Promise((r) => setTimeout(r, 300));
+  await page.keyboard.press("Enter");
+
+  log(`grok-client: message sent, streaming…`);
+
+  // Stream: poll DOM, emit new chars as tokens
+  const deadline = Date.now() + timeoutMs;
+  let emittedLength = 0;
+  let lastText = "";
+  let stableCount = 0;
+
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, STABLE_INTERVAL_MS));
+
+    const text = await page.evaluate(
+      (before: number) => {
+        const bubbles = [...document.querySelectorAll(".message-bubble")];
+        if (bubbles.length <= before) return "";
+        return bubbles[bubbles.length - 1].textContent?.trim() ?? "";
+      },
+      countBefore
+    );
+
+    if (text && text.length > emittedLength) {
+      const newChars = text.slice(emittedLength);
+      onToken(newChars);
+      emittedLength = text.length;
+    }
+
+    if (text && text === lastText) {
+      stableCount++;
+      if (stableCount >= STABLE_CHECKS) {
+        log(`grok-client: stream done (${text.length} chars)`);
+        return { content: text, model, finishReason: "stop" };
+      }
+    } else {
+      stableCount = 0;
+      lastText = text;
+    }
+  }
+
+  throw new Error(`grok.com stream timeout after ${timeoutMs}ms`);
+}

package/src/grok-session.ts

@@ -0,0 +1,195 @@
+/**
+ * grok-session.ts
+ *
+ * Manages a persistent grok.com browser session using Playwright.
+ *
+ * Auth flow:
+ *  1. First run: open Chromium, navigate to grok.com → user logs in manually via X.com OAuth
+ *  2. On success: save cookies + localStorage to SESSION_PATH
+ *  3. Subsequent runs: restore session from file, verify still valid
+ *  4. If session expired: repeat step 1
+ *
+ * The saved session file is stored at ~/.openclaw/grok-session.json
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import type { Browser, BrowserContext, Cookie } from "playwright";
+
+export const DEFAULT_SESSION_PATH = join(
+  homedir(),
+  ".openclaw",
+  "grok-session.json"
+);
+
+export const GROK_HOME = "https://grok.com";
+export const GROK_API_BASE = "https://grok.com/api";
+
+/** Stored session data */
+export interface GrokSession {
+  cookies: Cookie[];
+  savedAt: number; // epoch ms
+  userAgent?: string;
+}
+
+/** Result of a session check */
+export interface SessionCheckResult {
+  valid: boolean;
+  reason?: string;
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Persistence helpers
+// ──────────────────────────────────────────────────────────────────────────────
+
+export function loadSession(sessionPath: string): GrokSession | null {
+  if (!existsSync(sessionPath)) return null;
+  try {
+    const raw = readFileSync(sessionPath, "utf-8");
+    const parsed = JSON.parse(raw) as GrokSession;
+    if (!parsed.cookies || !Array.isArray(parsed.cookies)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+export function saveSession(
+  sessionPath: string,
+  session: GrokSession
+): void {
+  mkdirSync(dirname(sessionPath), { recursive: true });
+  writeFileSync(sessionPath, JSON.stringify(session, null, 2), "utf-8");
+}
+
+export function deleteSession(sessionPath: string): void {
+  if (existsSync(sessionPath)) {
+    unlinkSync(sessionPath);
+  }
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Session validation
+// ──────────────────────────────────────────────────────────────────────────────
+
+const SESSION_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+
+export function isSessionExpiredByAge(session: GrokSession): boolean {
+  return Date.now() - session.savedAt > SESSION_MAX_AGE_MS;
+}
+
+/**
+ * Verify the session is still valid by making a lightweight API call.
+ * Returns {valid: true} if the session works, {valid: false, reason} otherwise.
+ */
+export async function verifySession(
+  context: BrowserContext,
+  log: (msg: string) => void
+): Promise<SessionCheckResult> {
+  log("verifying grok session...");
+
+  // Prefer an existing grok.com page — don't open a new one (new pages can
+  // trigger Cloudflare checks and displace the authenticated session page).
+  const existingPages = context.pages().filter((p) => p.url().startsWith("https://grok.com"));
+  if (existingPages.length > 0) {
+    const page = existingPages[0];
+    // Check for sign-in link on existing page
+    const signIn = page.locator('a[href*="sign-in"], a[href*="/login"]');
+    const signInVisible = await signIn.isVisible().catch(() => false);
+    if (signInVisible) return { valid: false, reason: "sign-in link visible — session expired" };
+    // Check for editor (logged in indicator)
+    const editor = page.locator('.ProseMirror, [contenteditable="true"]');
+    const editorVisible = await editor.isVisible().catch(() => false);
+    if (editorVisible) {
+      log("session valid ✅");
+      return { valid: true };
+    }
+  }
+
+  // No existing page — open one to check, then leave it open for reuse
+  const page = await context.newPage();
+  try {
+    log("verifying grok session...");
+    await page.goto(GROK_HOME, { waitUntil: "domcontentloaded", timeout: 15_000 });
+
+    const signIn = page.locator('a[href*="sign-in"], a[href*="/login"]');
+    if (await signIn.isVisible().catch(() => false)) {
+      await page.close();
+      return { valid: false, reason: "sign-in link visible — session expired" };
+    }
+
+    const editor = page.locator('.ProseMirror, [contenteditable="true"]');
+    if (await editor.isVisible().catch(() => false)) {
+      // Keep page open — grokComplete will reuse it
+      log("session valid ✅");
+      return { valid: true };
+    }
+
+    // Ambiguous — assume valid, keep page open
+    log("session check ambiguous — assuming valid");
+    return { valid: true };
+  } catch (err) {
+    await page.close().catch(() => {});
+    return { valid: false, reason: (err as Error).message };
+  }
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Interactive login (opens visible browser window)
+// ──────────────────────────────────────────────────────────────────────────────
+
+export async function runInteractiveLogin(
+  browser: Browser,
+  sessionPath: string,
+  log: (msg: string) => void,
+  timeoutMs = 5 * 60 * 1000
+): Promise<GrokSession> {
+  log("opening browser for grok.com login — please sign in with your X account...");
+
+  const context = await browser.newContext({
+    viewport: { width: 1280, height: 800 },
+  });
+  const page = await context.newPage();
+
+  await page.goto(GROK_HOME, { waitUntil: "domcontentloaded", timeout: 15_000 });
+
+  // Wait for sign-in to complete: look for chat textarea to appear
+  log(`waiting for login (timeout: ${timeoutMs / 1000}s)...`);
+  await page.waitForSelector(
+    'textarea, [placeholder*="mind"], [aria-label*="message"]',
+    { timeout: timeoutMs }
+  );
+
+  log("login detected — saving session...");
+  const cookies = await context.cookies();
+  const userAgent = await page.evaluate(() => navigator.userAgent);
+
+  const session: GrokSession = {
+    cookies,
+    savedAt: Date.now(),
+    userAgent,
+  };
+
+  saveSession(sessionPath, session);
+  log(`session saved to ${sessionPath}`);
+
+  await context.close();
+  return session;
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Context factory: create a BrowserContext with restored cookies
+// ──────────────────────────────────────────────────────────────────────────────
+
+export async function createContextFromSession(
+  browser: Browser,
+  session: GrokSession
+): Promise<BrowserContext> {
+  const context = await browser.newContext({
+    userAgent: session.userAgent,
+    viewport: { width: 1280, height: 800 },
+  });
+  await context.addCookies(session.cookies);
+  return context;
+}

package/src/proxy-server.ts

@@ -12,6 +12,12 @@ import http from "node:http";
 import { randomBytes } from "node:crypto";
 import { type ChatMessage, routeToCliRunner } from "./cli-runner.js";
 import { scheduleTokenRefresh, setAuthLogger, stopTokenRefresh } from "./claude-auth.js";
+import { grokComplete, grokCompleteStream, type ChatMessage as GrokChatMessage } from "./grok-client.js";
+import type { BrowserContext } from "playwright";
+
+export type GrokCompleteOptions = Parameters<typeof grokComplete>[1];
+export type GrokCompleteStreamOptions = Parameters<typeof grokCompleteStream>[1];
+export type GrokCompleteResult = Awaited<ReturnType<typeof grokComplete>>;
 
 export interface ProxyServerOptions {
   port: number;
@@ -19,6 +25,14 @@ export interface ProxyServerOptions {
   timeoutMs?: number;
   log: (msg: string) => void;
   warn: (msg: string) => void;
+  /** Returns the current authenticated Grok BrowserContext (null if not logged in) */
+  getGrokContext?: () => BrowserContext | null;
+  /** Async lazy connect — called when getGrokContext returns null */
+  connectGrokContext?: () => Promise<BrowserContext | null>;
+  /** Override for testing — replaces grokComplete */
+  _grokComplete?: typeof grokComplete;
+  /** Override for testing — replaces grokCompleteStream */
+  _grokCompleteStream?: typeof grokCompleteStream;
 }
 
 /** Available CLI bridge models for GET /v1/models */
@@ -59,6 +73,11 @@ export const CLI_MODELS = [
     contextWindow: 200_000,
     maxTokens: 8192,
   },
+  // Grok web-session models (requires /grok-login)
+  { id: "web-grok/grok-3",           name: "Grok 3 (web session)",           contextWindow: 131_072, maxTokens: 131_072 },
+  { id: "web-grok/grok-3-fast",      name: "Grok 3 Fast (web session)",      contextWindow: 131_072, maxTokens: 131_072 },
+  { id: "web-grok/grok-3-mini",      name: "Grok 3 Mini (web session)",      contextWindow: 131_072, maxTokens: 131_072 },
+  { id: "web-grok/grok-3-mini-fast", name: "Grok 3 Mini Fast (web session)", contextWindow: 131_072, maxTokens: 131_072 },
 ];
 
 // ──────────────────────────────────────────────────────────────────────────────
@@ -176,6 +195,61 @@ async function handleRequest(
 
     opts.log(`[cli-bridge] ${model} · ${messages.length} msg(s) · stream=${stream}`);
 
+    const id = `chatcmpl-cli-${randomBytes(6).toString("hex")}`;
+    const created = Math.floor(Date.now() / 1000);
+
+    // ── Grok web-session routing ──────────────────────────────────────────────
+    if (model.startsWith("web-grok/")) {
+      let grokCtx = opts.getGrokContext?.() ?? null;
+      // Lazy connect: if context is null but a connector is provided, try now
+      if (!grokCtx && opts.connectGrokContext) {
+        grokCtx = await opts.connectGrokContext();
+      }
+      if (!grokCtx) {
+        res.writeHead(503, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: { message: "No active grok.com session. Use /grok-login to authenticate.", code: "no_grok_session" } }));
+        return;
+      }
+      const grokModel = model.replace("web-grok/", "");
+      const timeoutMs = opts.timeoutMs ?? 120_000;
+      const grokMessages = messages as GrokChatMessage[];
+      const doGrokComplete = opts._grokComplete ?? grokComplete;
+      const doGrokCompleteStream = opts._grokCompleteStream ?? grokCompleteStream;
+      try {
+        if (stream) {
+          res.writeHead(200, { "Content-Type": "text/event-stream", "Cache-Control": "no-cache", Connection: "keep-alive", ...corsHeaders() });
+          sendSseChunk(res, { id, created, model, delta: { role: "assistant" }, finish_reason: null });
+          const result = await doGrokCompleteStream(
+            grokCtx,
+            { messages: grokMessages, model: grokModel, timeoutMs },
+            (token) => sendSseChunk(res, { id, created, model, delta: { content: token }, finish_reason: null }),
+            opts.log
+          );
+          sendSseChunk(res, { id, created, model, delta: {}, finish_reason: result.finishReason });
+          res.write("data: [DONE]\n\n");
+          res.end();
+        } else {
+          const result = await doGrokComplete(grokCtx, { messages: grokMessages, model: grokModel, timeoutMs }, opts.log);
+          res.writeHead(200, { "Content-Type": "application/json", ...corsHeaders() });
+          res.end(JSON.stringify({
+            id, object: "chat.completion", created, model,
+            choices: [{ index: 0, message: { role: "assistant", content: result.content }, finish_reason: result.finishReason }],
+            usage: { prompt_tokens: result.promptTokens ?? 0, completion_tokens: result.completionTokens ?? 0, total_tokens: (result.promptTokens ?? 0) + (result.completionTokens ?? 0) },
+          }));
+        }
+      } catch (err) {
+        const msg = (err as Error).message;
+        opts.warn(`[cli-bridge] Grok error for ${model}: ${msg}`);
+        if (!res.headersSent) {
+          res.writeHead(500, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ error: { message: msg, type: "grok_error" } }));
+        }
+      }
+      return;
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+
+    // ── CLI runner routing (Gemini / Claude Code) ─────────────────────────────
     let content: string;
     try {
       content = await routeToCliRunner(model, messages, opts.timeoutMs ?? 120_000);
@@ -187,9 +261,6 @@ async function handleRequest(
       return;
     }
 
-    const id = `chatcmpl-cli-${randomBytes(6).toString("hex")}`;
-    const created = Math.floor(Date.now() / 1000);
-
     if (stream) {
       res.writeHead(200, {
         "Content-Type": "text/event-stream",

package/test/grok-proxy.test.ts

@@ -0,0 +1,301 @@
+/**
+ * test/grok-proxy.test.ts
+ *
+ * Tests for Grok web-session routing integrated into the cli-bridge proxy.
+ * Uses _grokComplete/_grokCompleteStream overrides (DI) instead of vi.mock,
+ * which avoids ESM hoisting issues entirely.
+ */
+
+import { describe, it, expect, beforeAll, afterAll, vi } from "vitest";
+import http from "node:http";
+import type { AddressInfo } from "node:net";
+import { startProxyServer, CLI_MODELS } from "../src/proxy-server.js";
+import type { BrowserContext } from "playwright";
+import type { GrokCompleteOptions, GrokCompleteResult } from "../src/proxy-server.js";
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Stub implementations (no browser needed)
+// ──────────────────────────────────────────────────────────────────────────────
+
+const stubGrokComplete = vi.fn(async (
+  _ctx: BrowserContext,
+  opts: GrokCompleteOptions,
+  _log: (msg: string) => void
+): Promise<GrokCompleteResult> => ({
+  content: `grok mock: ${opts.messages[opts.messages.length - 1]?.content ?? ""}`,
+  model: opts.model ?? "grok-3",
+  finishReason: "stop",
+  promptTokens: 8,
+  completionTokens: 4,
+}));
+
+const stubGrokCompleteStream = vi.fn(async (
+  _ctx: BrowserContext,
+  opts: GrokCompleteOptions,
+  onToken: (t: string) => void,
+  _log: (msg: string) => void
+): Promise<GrokCompleteResult> => {
+  const tokens = ["grok ", "stream ", "mock"];
+  for (const t of tokens) onToken(t);
+  return {
+    content: tokens.join(""),
+    model: opts.model ?? "grok-3",
+    finishReason: "stop",
+    promptTokens: 8,
+    completionTokens: 3,
+  };
+});
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ──────────────────────────────────────────────────────────────────────────────
+
+async function httpPost(
+  url: string,
+  body: unknown,
+  headers: Record<string, string> = {}
+): Promise<{ status: number; body: unknown }> {
+  return new Promise((resolve, reject) => {
+    const data = JSON.stringify(body);
+    const urlObj = new URL(url);
+    const req = http.request(
+      {
+        hostname: urlObj.hostname,
+        port: parseInt(urlObj.port),
+        path: urlObj.pathname,
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Content-Length": Buffer.byteLength(data),
+          ...headers,
+        },
+      },
+      (res) => {
+        let resp = "";
+        res.on("data", (c) => (resp += c));
+        res.on("end", () => {
+          try { resolve({ status: res.statusCode ?? 0, body: JSON.parse(resp) }); }
+          catch { resolve({ status: res.statusCode ?? 0, body: resp }); }
+        });
+      }
+    );
+    req.on("error", reject);
+    req.write(data);
+    req.end();
+  });
+}
+
+async function httpGet(
+  url: string,
+  headers: Record<string, string> = {}
+): Promise<{ status: number; body: unknown }> {
+  return new Promise((resolve, reject) => {
+    const req = http.get(url, { headers }, (res) => {
+      let data = "";
+      res.on("data", (c) => (data += c));
+      res.on("end", () => {
+        try { resolve({ status: res.statusCode ?? 0, body: JSON.parse(data) }); }
+        catch { resolve({ status: res.statusCode ?? 0, body: data }); }
+      });
+    });
+    req.on("error", reject);
+  });
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Setup: three servers
+//  - withCtx: has mock BrowserContext + stub overrides
+//  - noCtx: no BrowserContext (returns null)
+//  - noCtxNoOverride: no context, no overrides (tests 503)
+// ──────────────────────────────────────────────────────────────────────────────
+
+const TEST_KEY = "test-grok-key";
+const MOCK_CONTEXT = {} as BrowserContext;
+
+let serverWithCtx: http.Server;
+let serverNoCtx: http.Server;
+let urlWith: string;
+let urlNo: string;
+
+beforeAll(async () => {
+  serverWithCtx = await startProxyServer({
+    port: 0,
+    apiKey: TEST_KEY,
+    log: () => {},
+    warn: () => {},
+    getGrokContext: () => MOCK_CONTEXT,
+    _grokComplete: stubGrokComplete,
+    _grokCompleteStream: stubGrokCompleteStream,
+  });
+  const addrWith = serverWithCtx.address() as AddressInfo;
+  urlWith = `http://127.0.0.1:${addrWith.port}`;
+
+  serverNoCtx = await startProxyServer({
+    port: 0,
+    apiKey: TEST_KEY,
+    log: () => {},
+    warn: () => {},
+    getGrokContext: () => null,
+    _grokComplete: stubGrokComplete,
+    _grokCompleteStream: stubGrokCompleteStream,
+  });
+  const addrNo = serverNoCtx.address() as AddressInfo;
+  urlNo = `http://127.0.0.1:${addrNo.port}`;
+});
+
+afterAll(async () => {
+  await new Promise<void>((r) => serverWithCtx.close(() => r()));
+  await new Promise<void>((r) => serverNoCtx.close(() => r()));
+});
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Tests
+// ──────────────────────────────────────────────────────────────────────────────
+
+describe("GET /v1/models includes Grok web-session models", () => {
+  it("lists web-grok/* models", async () => {
+    const { status, body } = await httpGet(`${urlWith}/v1/models`, {
+      Authorization: `Bearer ${TEST_KEY}`,
+    });
+    expect(status).toBe(200);
+    const b = body as { data: Array<{ id: string }> };
+    const grokModels = b.data.filter((m) => m.id.startsWith("web-grok/"));
+    expect(grokModels.length).toBe(4);
+    expect(grokModels.map((m) => m.id)).toContain("web-grok/grok-3");
+    expect(grokModels.map((m) => m.id)).toContain("web-grok/grok-3-mini");
+  });
+
+  it("CLI_MODELS exports 4 grok models", () => {
+    const grok = CLI_MODELS.filter((m) => m.id.startsWith("web-grok/"));
+    expect(grok).toHaveLength(4);
+  });
+});
+
+describe("POST /v1/chat/completions — Grok routing", () => {
+  const auth = { Authorization: `Bearer ${TEST_KEY}` };
+
+  it("returns 503 when no Grok session", async () => {
+    const { status, body } = await httpPost(
+      `${urlNo}/v1/chat/completions`,
+      { model: "web-grok/grok-3", messages: [{ role: "user", content: "Hi" }] },
+      auth
+    );
+    expect(status).toBe(503);
+    const b = body as { error: { code: string } };
+    expect(b.error.code).toBe("no_grok_session");
+  });
+
+  it("returns 200 with mock context (non-streaming)", async () => {
+    stubGrokComplete.mockClear();
+    const { status, body } = await httpPost(
+      `${urlWith}/v1/chat/completions`,
+      { model: "web-grok/grok-3", messages: [{ role: "user", content: "Hello Grok" }], stream: false },
+      auth
+    );
+    expect(status).toBe(200);
+    const b = body as {
+      object: string;
+      model: string;
+      choices: Array<{ message: { content: string }; finish_reason: string }>;
+      usage: { prompt_tokens: number; completion_tokens: number };
+    };
+    expect(b.object).toBe("chat.completion");
+    expect(b.model).toBe("web-grok/grok-3");
+    expect(b.choices[0].message.content).toContain("Hello Grok");
+    expect(b.choices[0].finish_reason).toBe("stop");
+    expect(b.usage.prompt_tokens).toBe(8);
+    expect(b.usage.completion_tokens).toBe(4);
+    expect(stubGrokComplete).toHaveBeenCalledOnce();
+    // stub receives stripped model name
+    expect(stubGrokComplete.mock.calls[0][1].model).toBe("grok-3");
+  });
+
+  it("strips web-grok/ prefix before passing to grokComplete", async () => {
+    stubGrokComplete.mockClear();
+    const { status, body } = await httpPost(
+      `${urlWith}/v1/chat/completions`,
+      { model: "web-grok/grok-3-mini", messages: [{ role: "user", content: "test" }] },
+      auth
+    );
+    expect(status).toBe(200);
+    // response model should still have web-grok/ prefix
+    const b = body as { model: string };
+    expect(b.model).toBe("web-grok/grok-3-mini");
+    // stub receives stripped model
+    expect(stubGrokComplete.mock.calls[0][1].model).toBe("grok-3-mini");
+  });
+
+  it("returns SSE stream for web-grok models", async () => {
+    return new Promise<void>((resolve, reject) => {
+      const data = JSON.stringify({
+        model: "web-grok/grok-3",
+        messages: [{ role: "user", content: "stream test" }],
+        stream: true,
+      });
+      const urlObj = new URL(`${urlWith}/v1/chat/completions`);
+      const req = http.request(
+        {
+          hostname: urlObj.hostname,
+          port: parseInt(urlObj.port),
+          path: urlObj.pathname,
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "Content-Length": Buffer.byteLength(data),
+            Authorization: `Bearer ${TEST_KEY}`,
+          },
+        },
+        (res) => {
+          expect(res.statusCode).toBe(200);
+          expect(res.headers["content-type"]).toContain("text/event-stream");
+          let raw = "";
+          res.on("data", (c) => (raw += c));
+          res.on("end", () => {
+            const lines = raw.split("\n").filter((l) => l.startsWith("data: "));
+            expect(lines[lines.length - 1]).toBe("data: [DONE]");
+            const tokens = lines
+              .filter((l) => l !== "data: [DONE]")
+              .map((l) => { try { return JSON.parse(l.slice(6)); } catch { return null; } })
+              .filter(Boolean)
+              .flatMap((c) => c.choices?.[0]?.delta?.content ?? []);
+            expect(tokens.join("")).toBe("grok stream mock");
+            resolve();
+          });
+        }
+      );
+      req.on("error", reject);
+      req.write(data);
+      req.end();
+    });
+  });
+
+  it("non-web-grok models bypass Grok routing (go to CLI runner)", async () => {
+    stubGrokComplete.mockClear();
+
+    // Use a separate server with very short CLI timeout so this test finishes quickly
+    const fastSrv = await startProxyServer({
+      port: 0,
+      apiKey: TEST_KEY,
+      timeoutMs: 500, // fail fast — gemini CLI won't be available in test
+      log: () => {},
+      warn: () => {},
+      getGrokContext: () => MOCK_CONTEXT,
+      _grokComplete: stubGrokComplete,
+      _grokCompleteStream: stubGrokCompleteStream,
+    });
+    const addr = fastSrv.address() as AddressInfo;
+    const fastUrl = `http://127.0.0.1:${addr.port}`;
+
+    try {
+      const { status } = await httpPost(
+        `${fastUrl}/v1/chat/completions`,
+        { model: "cli-gemini/gemini-2.5-pro", messages: [{ role: "user", content: "test" }] },
+        auth
+      );
+      expect(status).not.toBe(503); // must NOT be "no_grok_session" — routing is different
+      expect(stubGrokComplete).not.toHaveBeenCalled(); // grokComplete never called for non-grok models
+    } finally {
+      await new Promise<void>((r) => fastSrv.close(() => r()));
+    }
+  }, 10_000);
+});

package/test/grok-session.test.ts

@@ -0,0 +1,133 @@
+/**
+ * test/session.test.ts
+ *
+ * Unit tests for grok-session.ts — persistence, age check, cookie handling.
+ * No browser needed (mocked).
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { existsSync, unlinkSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  loadSession,
+  saveSession,
+  isSessionExpiredByAge,
+  type GrokSession,
+} from "../src/grok-session.js";
+
+const TMP_SESSION = join(tmpdir(), `grok-test-session-${process.pid}.json`);
+
+const MOCK_SESSION: GrokSession = {
+  cookies: [
+    {
+      name: "auth_token",
+      value: "test-token-123",
+      domain: ".grok.com",
+      path: "/",
+      expires: Date.now() / 1000 + 86400,
+      httpOnly: true,
+      secure: true,
+      sameSite: "Lax",
+    },
+    {
+      name: "ct0",
+      value: "csrf-token-abc",
+      domain: ".x.com",
+      path: "/",
+      expires: Date.now() / 1000 + 86400,
+      httpOnly: false,
+      secure: true,
+      sameSite: "Lax",
+    },
+  ],
+  savedAt: Date.now(),
+  userAgent: "Mozilla/5.0 (test)",
+};
+
+describe("grok-session persistence", () => {
+  afterEach(() => {
+    if (existsSync(TMP_SESSION)) unlinkSync(TMP_SESSION);
+  });
+
+  it("returns null when file does not exist", () => {
+    const result = loadSession(TMP_SESSION);
+    expect(result).toBeNull();
+  });
+
+  it("saves and loads a session round-trip", () => {
+    saveSession(TMP_SESSION, MOCK_SESSION);
+    expect(existsSync(TMP_SESSION)).toBe(true);
+
+    const loaded = loadSession(TMP_SESSION);
+    expect(loaded).not.toBeNull();
+    expect(loaded!.cookies).toHaveLength(2);
+    expect(loaded!.cookies[0].name).toBe("auth_token");
+    expect(loaded!.cookies[0].value).toBe("test-token-123");
+    expect(loaded!.userAgent).toBe("Mozilla/5.0 (test)");
+  });
+
+  it("returns null for corrupted JSON", () => {
+    const { writeFileSync } = require("node:fs");
+    writeFileSync(TMP_SESSION, "{ bad json }", "utf-8");
+    const result = loadSession(TMP_SESSION);
+    expect(result).toBeNull();
+  });
+
+  it("returns null for missing cookies field", () => {
+    const { writeFileSync } = require("node:fs");
+    writeFileSync(TMP_SESSION, JSON.stringify({ savedAt: Date.now() }), "utf-8");
+    const result = loadSession(TMP_SESSION);
+    expect(result).toBeNull();
+  });
+
+  it("returns null for cookies field not being array", () => {
+    const { writeFileSync } = require("node:fs");
+    writeFileSync(TMP_SESSION, JSON.stringify({ cookies: "not-array", savedAt: Date.now() }), "utf-8");
+    const result = loadSession(TMP_SESSION);
+    expect(result).toBeNull();
+  });
+
+  it("saves valid JSON that can be parsed independently", () => {
+    saveSession(TMP_SESSION, MOCK_SESSION);
+    const raw = readFileSync(TMP_SESSION, "utf-8");
+    expect(() => JSON.parse(raw)).not.toThrow();
+    const parsed = JSON.parse(raw);
+    expect(parsed.savedAt).toBeTypeOf("number");
+  });
+
+  it("overwrites existing session file", () => {
+    saveSession(TMP_SESSION, MOCK_SESSION);
+
+    const updated: GrokSession = { ...MOCK_SESSION, userAgent: "updated-ua", savedAt: Date.now() };
+    saveSession(TMP_SESSION, updated);
+
+    const loaded = loadSession(TMP_SESSION);
+    expect(loaded!.userAgent).toBe("updated-ua");
+  });
+});
+
+describe("session age check", () => {
+  it("fresh session is not expired", () => {
+    const session: GrokSession = { ...MOCK_SESSION, savedAt: Date.now() };
+    expect(isSessionExpiredByAge(session)).toBe(false);
+  });
+
+  it("session saved 6 days ago is not expired", () => {
+    const sixDaysAgo = Date.now() - 6 * 24 * 60 * 60 * 1000;
+    const session: GrokSession = { ...MOCK_SESSION, savedAt: sixDaysAgo };
+    expect(isSessionExpiredByAge(session)).toBe(false);
+  });
+
+  it("session saved 8 days ago is expired", () => {
+    const eightDaysAgo = Date.now() - 8 * 24 * 60 * 60 * 1000;
+    const session: GrokSession = { ...MOCK_SESSION, savedAt: eightDaysAgo };
+    expect(isSessionExpiredByAge(session)).toBe(true);
+  });
+
+  it("session saved exactly 7 days ago is expired", () => {
+    const sevenDaysAgo = Date.now() - 7 * 24 * 60 * 60 * 1000 - 1;
+    const session: GrokSession = { ...MOCK_SESSION, savedAt: sevenDaysAgo };
+    expect(isSessionExpiredByAge(session)).toBe(true);
+  });
+});