refactor: decouple AccountPool, split codex-api and web.ts, fix CI (#113)

* refactor: decouple AccountPool, split codex-api and web.ts, fix CI

Phase 0 — CI fixes:
- Fix TS2322: WS transport instructions type mismatch (Electron/Docker build)
- Remove duplicate selectAll i18n keys (Vite warning)
- Add rebase retry to sync-changelog.yml push step (race with bump-electron)

Phase 1-5 — Architecture improvements:
- Extract codex-types.ts: API type definitions separated from class
- Extract rotation-strategy.ts: pure-function selection logic (10 tests)
- Split web.ts (605 LOC) into routes/admin/ (health/update/connection/settings)
- Extract account-persistence.ts: injectable fs persistence interface (8 tests)
- Split codex-api.ts into codex-sse/usage/models modules (10 tests)

All existing import paths preserved via re-exports.
902 tests pass (70 files), build clean.

* fix: address PR #113 review issues before merge

- Fix needsPersist regression: load() now returns { entries, needsPersist }
and auto-persists when backfill is applied (restores original behavior)
- Break circular import: move CodexApiError to codex-types.ts, codex-usage.ts
imports directly from codex-types instead of codex-api
- Fix candidates.sort() mutation: leastUsed/sticky use [...candidates].sort()
- Rename createRotationStrategy → getRotationStrategy (shared singleton, not factory)
- Restore JSDoc on CodexApi methods (getUsage, getModels, WS/HTTP transport)
- Add tests: input array immutability, auto-persist on backfill

---------

Co-authored-by: icebear0828 <icebear0828@users.noreply.github.com>

.github/workflows/sync-changelog.yml

@@ -91,4 +91,11 @@ jobs:
           git diff --quiet README.md && echo "No changes" && exit 0
           git add README.md
           git commit -m "docs: auto-sync changelog to README [skip ci]"
-          git push
+          for i in 1 2 3; do
+            git push && exit 0
+            echo "Push failed (attempt $i/3), rebasing and retrying..."
+            git pull --rebase origin master
+            sleep 2
+          done
+          echo "::error::Push failed after 3 attempts"
+          exit 1

CHANGELOG.md

@@ -10,6 +10,19 @@
 
 - `/v1/responses` 不再强制要求 `instructions` 字段，未传时默认空字符串（#71）
   - 修复 Cherry 等第三方客户端不传 `instructions` 时返回 400 的兼容性问题
+- CI 构建修复：WebSocket 传输 `instructions` 类型不匹配（TS2322）导致 Electron/Docker 编译失败
+- `shared/i18n/translations.ts` 移除中英文重复 `selectAll` key（Vite 警告）
+- `sync-changelog.yml` 推送步骤加 rebase 重试（解决与 bump-electron 并行推送竞态）
+
+### Changed
+
+- 架构重构：降低模块耦合、改善可测试性
+  - 提取 `codex-types.ts`：API 类型定义与类实现分离，20+ 文件只需类型不需类
+  - 提取 `rotation-strategy.ts`：轮换策略从 AccountPool 解耦为纯函数模块（10 新测试）
+  - 拆分 `web.ts`（605 LOC）→ `routes/admin/`（health/update/connection/settings 4 子路由）
+  - 提取 `account-persistence.ts`：文件系统持久化逻辑从 AccountPool 分离为可注入接口（8 新测试）
+  - 拆分 `codex-api.ts`：SSE 解析（`codex-sse.ts`）、用量查询（`codex-usage.ts`）、模型发现（`codex-models.ts`）独立为纯函数模块（10 新测试）
+  - 所有提取模块通过 re-export 保持现有 import 路径兼容
 
 ### Added
 

shared/i18n/translations.ts

@@ -140,7 +140,6 @@ export const translations = {
     nextPage: "Next",
     totalItems: "total",
     shiftSelectHint: "Shift+click to select range",
-    selectAll: "Select all",
     exportSuccess: "Export complete",
     importFile: "Select JSON file",
     downloadJson: "Download JSON",
@@ -346,7 +345,6 @@ export const translations = {
     nextPage: "\u4e0b\u4e00\u9875",
     totalItems: "\u5171",
     shiftSelectHint: "Shift+\u70b9\u51fb\u8fde\u7eed\u591a\u9009",
-    selectAll: "\u5168\u9009",
     exportSuccess: "\u5bfc\u51fa\u6210\u529f",
     importFile: "\u9009\u62e9 JSON \u6587\u4ef6",
     downloadJson: "\u4e0b\u8f7d JSON",

src/auth/__tests__/account-persistence.test.ts

@@ -0,0 +1,174 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import type { AccountEntry, AccountsFile } from "../types.js";
+
+// Must use vi.hoisted() for mock variables referenced in vi.mock factories
+const mockFs = vi.hoisted(() => ({
+  existsSync: vi.fn(() => false),
+  readFileSync: vi.fn(() => ""),
+  writeFileSync: vi.fn(),
+  renameSync: vi.fn(),
+  mkdirSync: vi.fn(),
+}));
+
+vi.mock("fs", () => mockFs);
+
+vi.mock("../../paths.js", () => ({
+  getDataDir: vi.fn(() => "/tmp/test-persistence"),
+}));
+
+vi.mock("../jwt-utils.js", () => ({
+  extractChatGptAccountId: vi.fn((token: string) => `acct-${token}`),
+  extractUserProfile: vi.fn(() => null),
+  isTokenExpired: vi.fn(() => false),
+}));
+
+import { createFsPersistence } from "../account-persistence.js";
+
+function makeEntry(id: string): AccountEntry {
+  return {
+    id,
+    token: `tok-${id}`,
+    refreshToken: null,
+    email: `${id}@test.com`,
+    accountId: `acct-${id}`,
+    planType: "free",
+    proxyApiKey: `key-${id}`,
+    status: "active",
+    usage: {
+      request_count: 0,
+      input_tokens: 0,
+      output_tokens: 0,
+      empty_response_count: 0,
+      last_used: null,
+      rate_limit_until: null,
+      window_request_count: 0,
+      window_input_tokens: 0,
+      window_output_tokens: 0,
+      window_counters_reset_at: null,
+      limit_window_seconds: null,
+    },
+    addedAt: new Date().toISOString(),
+    cachedQuota: null,
+    quotaFetchedAt: null,
+  };
+}
+
+describe("account-persistence", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockFs.existsSync.mockReturnValue(false);
+  });
+
+  describe("load", () => {
+    it("returns empty entries when no files exist", () => {
+      const p = createFsPersistence();
+      const result = p.load();
+      expect(result.entries).toEqual([]);
+      expect(result.needsPersist).toBe(false);
+    });
+
+    it("loads from accounts.json", () => {
+      const entry = makeEntry("a");
+      const data: AccountsFile = { accounts: [entry] };
+      mockFs.existsSync.mockImplementation(((path: string) =>
+        path.includes("accounts.json")) as () => boolean,
+      );
+      mockFs.readFileSync.mockReturnValue(JSON.stringify(data));
+
+      const p = createFsPersistence();
+      const result = p.load();
+      expect(result.entries).toHaveLength(1);
+      expect(result.entries[0].id).toBe("a");
+    });
+
+    it("skips entries without id or token", () => {
+      const data = { accounts: [{ id: "", token: "x" }, { id: "b" }] };
+      mockFs.existsSync.mockImplementation(((path: string) =>
+        path.includes("accounts.json")) as () => boolean,
+      );
+      mockFs.readFileSync.mockReturnValue(JSON.stringify(data));
+
+      const p = createFsPersistence();
+      expect(p.load().entries).toEqual([]);
+    });
+
+    it("backfills missing empty_response_count and auto-persists", () => {
+      const entry = makeEntry("a");
+      (entry.usage as unknown as Record<string, unknown>).empty_response_count = undefined;
+      const data: AccountsFile = { accounts: [entry] };
+      mockFs.existsSync.mockImplementation(((path: string) =>
+        path.includes("accounts.json")) as () => boolean,
+      );
+      mockFs.readFileSync.mockReturnValue(JSON.stringify(data));
+
+      const p = createFsPersistence();
+      const result = p.load();
+      expect(result.entries[0].usage.empty_response_count).toBe(0);
+      expect(result.needsPersist).toBe(true);
+      // Verify auto-persist was triggered (write + rename for atomic save)
+      expect(mockFs.writeFileSync).toHaveBeenCalledTimes(1);
+      expect(mockFs.renameSync).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("save", () => {
+    it("writes atomically via tmp file + rename", () => {
+      mockFs.existsSync.mockReturnValue(true);
+      const p = createFsPersistence();
+      const entry = makeEntry("a");
+
+      p.save([entry]);
+
+      expect(mockFs.writeFileSync).toHaveBeenCalledTimes(1);
+      const writtenPath = mockFs.writeFileSync.mock.calls[0][0] as string;
+      expect(writtenPath).toMatch(/accounts\.json\.tmp$/);
+      expect(mockFs.renameSync).toHaveBeenCalledTimes(1);
+    });
+
+    it("creates directory if missing", () => {
+      mockFs.existsSync.mockReturnValue(false);
+      const p = createFsPersistence();
+      p.save([makeEntry("a")]);
+
+      expect(mockFs.mkdirSync).toHaveBeenCalledWith(
+        expect.any(String),
+        { recursive: true },
+      );
+    });
+
+    it("serializes accounts as JSON", () => {
+      mockFs.existsSync.mockReturnValue(true);
+      const p = createFsPersistence();
+      const entries = [makeEntry("a"), makeEntry("b")];
+      p.save(entries);
+
+      const written = JSON.parse(mockFs.writeFileSync.mock.calls[0][1] as string) as AccountsFile;
+      expect(written.accounts).toHaveLength(2);
+      expect(written.accounts[0].id).toBe("a");
+      expect(written.accounts[1].id).toBe("b");
+    });
+  });
+
+  describe("legacy migration", () => {
+    it("migrates from auth.json when accounts.json does not exist", () => {
+      const legacyData = {
+        token: "legacy-token",
+        proxyApiKey: "old-key",
+        userInfo: { email: "old@test.com", planType: "free" },
+      };
+      mockFs.existsSync.mockImplementation(((path: string) => {
+        if (path.includes("accounts.json")) return false;
+        if (path.includes("auth.json")) return true;
+        return false;
+      }) as () => boolean);
+      mockFs.readFileSync.mockReturnValue(JSON.stringify(legacyData));
+
+      const p = createFsPersistence();
+      const result = p.load();
+      expect(result.entries).toHaveLength(1);
+      expect(result.entries[0].token).toBe("legacy-token");
+      // Should rename old file
+      expect(mockFs.renameSync).toHaveBeenCalled();
+    });
+  });
+});

src/auth/__tests__/rotation-strategy.test.ts

@@ -0,0 +1,125 @@
+import { describe, it, expect } from "vitest";
+import { getRotationStrategy } from "../rotation-strategy.js";
+import type { RotationState } from "../rotation-strategy.js";
+import type { AccountEntry } from "../types.js";
+
+function makeEntry(id: string, overrides?: Partial<AccountEntry["usage"]>): AccountEntry {
+  return {
+    id,
+    token: `tok-${id}`,
+    refreshToken: null,
+    email: `${id}@test.com`,
+    accountId: `acct-${id}`,
+    planType: "free",
+    proxyApiKey: `key-${id}`,
+    status: "active",
+    usage: {
+      request_count: 0,
+      input_tokens: 0,
+      output_tokens: 0,
+      empty_response_count: 0,
+      last_used: null,
+      rate_limit_until: null,
+      window_request_count: 0,
+      window_input_tokens: 0,
+      window_output_tokens: 0,
+      window_counters_reset_at: null,
+      limit_window_seconds: null,
+      ...overrides,
+    },
+    addedAt: new Date().toISOString(),
+    cachedQuota: null,
+    quotaFetchedAt: null,
+  };
+}
+
+describe("rotation-strategy", () => {
+  describe("least_used", () => {
+    const strategy = getRotationStrategy("least_used");
+    const state: RotationState = { roundRobinIndex: 0 };
+
+    it("selects account with fewest requests", () => {
+      const a = makeEntry("a", { request_count: 5 });
+      const b = makeEntry("b", { request_count: 2 });
+      const c = makeEntry("c", { request_count: 8 });
+      expect(strategy.select([a, b, c], state).id).toBe("b");
+    });
+
+    it("breaks ties by window_reset_at (sooner wins)", () => {
+      const a = makeEntry("a", { request_count: 3, window_reset_at: 2000 });
+      const b = makeEntry("b", { request_count: 3, window_reset_at: 1000 });
+      expect(strategy.select([a, b], state).id).toBe("b");
+    });
+
+    it("breaks further ties by last_used (LRU)", () => {
+      const a = makeEntry("a", { request_count: 3, last_used: "2026-01-02T00:00:00Z" });
+      const b = makeEntry("b", { request_count: 3, last_used: "2026-01-01T00:00:00Z" });
+      expect(strategy.select([a, b], state).id).toBe("b");
+    });
+  });
+
+  describe("round_robin", () => {
+    const strategy = getRotationStrategy("round_robin");
+
+    it("cycles through candidates in order", () => {
+      const state: RotationState = { roundRobinIndex: 0 };
+      const a = makeEntry("a");
+      const b = makeEntry("b");
+      const c = makeEntry("c");
+      const candidates = [a, b, c];
+
+      expect(strategy.select(candidates, state).id).toBe("a");
+      expect(strategy.select(candidates, state).id).toBe("b");
+      expect(strategy.select(candidates, state).id).toBe("c");
+      expect(strategy.select(candidates, state).id).toBe("a"); // wraps
+    });
+
+    it("wraps index when candidates shrink", () => {
+      const state: RotationState = { roundRobinIndex: 5 };
+      const a = makeEntry("a");
+      const b = makeEntry("b");
+      // 5 % 2 = 1 → picks b
+      expect(strategy.select([a, b], state).id).toBe("b");
+    });
+  });
+
+  describe("sticky", () => {
+    const strategy = getRotationStrategy("sticky");
+    const state: RotationState = { roundRobinIndex: 0 };
+
+    it("selects most recently used account", () => {
+      const a = makeEntry("a", { last_used: "2026-01-01T00:00:00Z" });
+      const b = makeEntry("b", { last_used: "2026-01-03T00:00:00Z" });
+      const c = makeEntry("c", { last_used: "2026-01-02T00:00:00Z" });
+      expect(strategy.select([a, b, c], state).id).toBe("b");
+    });
+
+    it("selects any when none have been used", () => {
+      const a = makeEntry("a");
+      const b = makeEntry("b");
+      // Both have last_used=null → both map to 0 → stable sort keeps first
+      const result = strategy.select([a, b], state);
+      expect(["a", "b"]).toContain(result.id);
+    });
+  });
+
+  it("getRotationStrategy returns distinct strategy objects per name", () => {
+    const lu = getRotationStrategy("least_used");
+    const rr = getRotationStrategy("round_robin");
+    const st = getRotationStrategy("sticky");
+    expect(lu).not.toBe(rr);
+    expect(rr).not.toBe(st);
+  });
+
+  it("select does not mutate the input candidates array", () => {
+    const strategy = getRotationStrategy("least_used");
+    const state: RotationState = { roundRobinIndex: 0 };
+    const a = makeEntry("a", { request_count: 5 });
+    const b = makeEntry("b", { request_count: 2 });
+    const c = makeEntry("c", { request_count: 8 });
+    const candidates = [a, b, c];
+    strategy.select(candidates, state);
+    // Original order preserved
+    expect(candidates.map((e) => e.id)).toEqual(["a", "b", "c"]);
+  });
+});

src/auth/account-persistence.ts

@@ -0,0 +1,191 @@
+/**
+ * AccountPersistence — file-system persistence for AccountPool.
+ * Handles load/save/migrate operations as an injectable dependency.
+ */
+
+import {
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  existsSync,
+  mkdirSync,
+} from "fs";
+import { resolve, dirname } from "path";
+import { randomBytes } from "crypto";
+import { getDataDir } from "../paths.js";
+import {
+  extractChatGptAccountId,
+  extractUserProfile,
+  isTokenExpired,
+} from "./jwt-utils.js";
+import type { AccountEntry, AccountsFile } from "./types.js";
+
+export interface AccountPersistence {
+  load(): { entries: AccountEntry[]; needsPersist: boolean };
+  save(accounts: AccountEntry[]): void;
+}
+
+function getAccountsFile(): string {
+  return resolve(getDataDir(), "accounts.json");
+}
+function getLegacyAuthFile(): string {
+  return resolve(getDataDir(), "auth.json");
+}
+
+export function createFsPersistence(): AccountPersistence {
+  const persistence: AccountPersistence = {
+    load(): { entries: AccountEntry[]; needsPersist: boolean } {
+      // Migrate from legacy auth.json if needed
+      const migrated = migrateFromLegacy();
+
+      // Load from accounts.json
+      const { entries: loaded, needsPersist } = loadPersisted();
+
+      const entries = migrated.length > 0 && loaded.length === 0 ? migrated : loaded;
+
+      // Auto-persist when backfill was applied (preserves original behavior)
+      if (needsPersist && loaded.length > 0) {
+        persistence.save(loaded);
+      }
+
+      return { entries, needsPersist };
+    },
+
+    save(accounts: AccountEntry[]): void {
+      try {
+        const accountsFile = getAccountsFile();
+        const dir = dirname(accountsFile);
+        if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+        const data: AccountsFile = { accounts };
+        const tmpFile = accountsFile + ".tmp";
+        writeFileSync(tmpFile, JSON.stringify(data, null, 2), "utf-8");
+        renameSync(tmpFile, accountsFile);
+      } catch (err) {
+        console.error("[AccountPool] Failed to persist accounts:", err instanceof Error ? err.message : err);
+      }
+    },
+  };
+  return persistence;
+}
+
+function migrateFromLegacy(): AccountEntry[] {
+  try {
+    const accountsFile = getAccountsFile();
+    const legacyAuthFile = getLegacyAuthFile();
+    if (existsSync(accountsFile)) return []; // already migrated
+    if (!existsSync(legacyAuthFile)) return [];
+
+    const raw = readFileSync(legacyAuthFile, "utf-8");
+    const data = JSON.parse(raw) as {
+      token: string;
+      proxyApiKey?: string | null;
+      userInfo?: { email?: string; accountId?: string; planType?: string } | null;
+    };
+
+    if (!data.token) return [];
+
+    const id = randomBytes(8).toString("hex");
+    const accountId = extractChatGptAccountId(data.token);
+    const entry: AccountEntry = {
+      id,
+      token: data.token,
+      refreshToken: null,
+      email: data.userInfo?.email ?? null,
+      accountId: accountId,
+      planType: data.userInfo?.planType ?? null,
+      proxyApiKey: data.proxyApiKey ?? "codex-proxy-" + randomBytes(24).toString("hex"),
+      status: isTokenExpired(data.token) ? "expired" : "active",
+      usage: {
+        request_count: 0,
+        input_tokens: 0,
+        output_tokens: 0,
+        empty_response_count: 0,
+        last_used: null,
+        rate_limit_until: null,
+        window_request_count: 0,
+        window_input_tokens: 0,
+        window_output_tokens: 0,
+        window_counters_reset_at: null,
+        limit_window_seconds: null,
+      },
+      addedAt: new Date().toISOString(),
+      cachedQuota: null,
+      quotaFetchedAt: null,
+    };
+
+    // Write new format
+    const dir = dirname(accountsFile);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    const accountsData: AccountsFile = { accounts: [entry] };
+    writeFileSync(accountsFile, JSON.stringify(accountsData, null, 2), "utf-8");
+
+    // Rename old file
+    renameSync(legacyAuthFile, legacyAuthFile + ".bak");
+    console.log("[AccountPool] Migrated from auth.json → accounts.json");
+    return [entry];
+  } catch (err) {
+    console.warn("[AccountPool] Migration failed:", err);
+    return [];
+  }
+}
+
+function loadPersisted(): { entries: AccountEntry[]; needsPersist: boolean } {
+  try {
+    const accountsFile = getAccountsFile();
+    if (!existsSync(accountsFile)) return { entries: [], needsPersist: false };
+    const raw = readFileSync(accountsFile, "utf-8");
+    const data = JSON.parse(raw) as AccountsFile;
+    if (!Array.isArray(data.accounts)) return { entries: [], needsPersist: false };
+
+    const entries: AccountEntry[] = [];
+    let needsPersist = false;
+
+    for (const entry of data.accounts) {
+      if (!entry.id || !entry.token) continue;
+
+      // Backfill missing fields from JWT
+      if (!entry.planType || !entry.email || !entry.accountId) {
+        const profile = extractUserProfile(entry.token);
+        const accountId = extractChatGptAccountId(entry.token);
+        if (!entry.planType && profile?.chatgpt_plan_type) {
+          entry.planType = profile.chatgpt_plan_type;
+          needsPersist = true;
+        }
+        if (!entry.email && profile?.email) {
+          entry.email = profile.email;
+          needsPersist = true;
+        }
+        if (!entry.accountId && accountId) {
+          entry.accountId = accountId;
+          needsPersist = true;
+        }
+      }
+      // Backfill empty_response_count
+      if (entry.usage.empty_response_count == null) {
+        entry.usage.empty_response_count = 0;
+        needsPersist = true;
+      }
+      // Backfill window counter fields
+      if (entry.usage.window_request_count == null) {
+        entry.usage.window_request_count = 0;
+        entry.usage.window_input_tokens = 0;
+        entry.usage.window_output_tokens = 0;
+        entry.usage.window_counters_reset_at = null;
+        entry.usage.limit_window_seconds = null;
+        needsPersist = true;
+      }
+      // Backfill cachedQuota fields
+      if (entry.cachedQuota === undefined) {
+        entry.cachedQuota = null;
+        entry.quotaFetchedAt = null;
+        needsPersist = true;
+      }
+      entries.push(entry);
+    }
+
+    return { entries, needsPersist };
+  } catch (err) {
+    console.warn("[AccountPool] Failed to load accounts:", err instanceof Error ? err.message : err);
+    return { entries: [], needsPersist: false };
+  }
+}

src/auth/account-pool.ts

@@ -3,17 +3,8 @@
  * Replaces the single-account AuthManager.
  */
 
-import {
-  readFileSync,
-  writeFileSync,
-  renameSync,
-  existsSync,
-  mkdirSync,
-} from "fs";
-import { resolve, dirname } from "path";
 import { randomBytes } from "crypto";
 import { getConfig } from "../config.js";
-import { getDataDir } from "../paths.js";
 import { jitter } from "../utils/jitter.js";
 import {
   decodeJwtPayload,
@@ -22,6 +13,10 @@ import {
   isTokenExpired,
 } from "./jwt-utils.js";
 import { getModelPlanTypes } from "../models/model-store.js";
+import { getRotationStrategy } from "./rotation-strategy.js";
+import { createFsPersistence } from "./account-persistence.js";
+import type { AccountPersistence } from "./account-persistence.js";
+import type { RotationStrategy, RotationState } from "./rotation-strategy.js";
 import type {
   AccountEntry,
   AccountInfo,
@@ -31,28 +26,29 @@ import type {
   CodexQuota,
 } from "./types.js";
 
-function getAccountsFile(): string {
-  return resolve(getDataDir(), "accounts.json");
-}
-function getLegacyAuthFile(): string {
-  return resolve(getDataDir(), "auth.json");
-}
-
 // P1-4: Lock TTL — auto-release locks older than this
 const ACQUIRE_LOCK_TTL_MS = 5 * 60 * 1000; // 5 minutes
 
 export class AccountPool {
   private accounts: Map<string, AccountEntry> = new Map();
   private acquireLocks: Map<string, number> = new Map(); // entryId → timestamp
-  private roundRobinIndex = 0;
+  private strategy: RotationStrategy;
+  private rotationState: RotationState = { roundRobinIndex: 0 };
+  private persistence: AccountPersistence;
   private persistTimer: ReturnType<typeof setTimeout> | null = null;
 
-  constructor() {
-    this.migrateFromLegacy();
-    this.loadPersisted();
+  constructor(options?: { persistence?: AccountPersistence }) {
+    this.persistence = options?.persistence ?? createFsPersistence();
+    const config = getConfig();
+    this.strategy = getRotationStrategy(config.auth.rotation_strategy);
+
+    // Load persisted accounts (handles migration from legacy format)
+    const { entries } = this.persistence.load();
+    for (const entry of entries) {
+      this.accounts.set(entry.id, entry);
+    }
 
     // Override with config jwt_token if set
-    const config = getConfig();
     if (config.auth.jwt_token) {
       this.addAccount(config.auth.jwt_token);
     }
@@ -113,7 +109,7 @@ export class AccountPool {
       }
     }
 
-    const selected = this.selectByStrategy(candidates);
+    const selected = this.strategy.select(candidates, this.rotationState);
     this.acquireLocks.set(selected.id, Date.now());
     return {
       entryId: selected.id,
@@ -123,38 +119,11 @@ export class AccountPool {
   }
 
   /**
-   * Select an account from candidates using the configured rotation strategy.
+   * Switch rotation strategy at runtime (e.g. from admin API).
    */
-  private selectByStrategy(candidates: AccountEntry[]): AccountEntry {
-    const config = getConfig();
-    if (config.auth.rotation_strategy === "round_robin") {
-      this.roundRobinIndex = this.roundRobinIndex % candidates.length;
-      const selected = candidates[this.roundRobinIndex];
-      this.roundRobinIndex++;
-      return selected;
-    }
-    if (config.auth.rotation_strategy === "sticky") {
-      // Sticky: prefer most recently used account (keep reusing until unavailable)
-      candidates.sort((a, b) => {
-        const aTime = a.usage.last_used ? new Date(a.usage.last_used).getTime() : 0;
-        const bTime = b.usage.last_used ? new Date(b.usage.last_used).getTime() : 0;
-        return bTime - aTime; // desc — most recent first
-      });
-      return candidates[0];
-    }
-    // least_used: sort by request_count asc → window_reset_at asc → last_used asc (LRU)
-    candidates.sort((a, b) => {
-      const diff = a.usage.request_count - b.usage.request_count;
-      if (diff !== 0) return diff;
-      // Prefer accounts whose quota window resets sooner (more fresh capacity)
-      const aReset = a.usage.window_reset_at ?? Infinity;
-      const bReset = b.usage.window_reset_at ?? Infinity;
-      if (aReset !== bReset) return aReset - bReset;
-      const aTime = a.usage.last_used ? new Date(a.usage.last_used).getTime() : 0;
-      const bTime = b.usage.last_used ? new Date(b.usage.last_used).getTime() : 0;
-      return aTime - bTime;
-    });
-    return candidates[0];
+  setRotationStrategy(name: "least_used" | "round_robin" | "sticky"): void {
+    this.strategy = getRotationStrategy(name);
+    this.rotationState.roundRobinIndex = 0;
   }
 
   /**
@@ -185,7 +154,7 @@ export class AccountPool {
 
     const result: Array<{ planType: string; entryId: string; token: string; accountId: string | null }> = [];
     for (const [plan, group] of byPlan) {
-      const selected = this.selectByStrategy(group);
+      const selected = this.strategy.select(group, this.rotationState);
       this.acquireLocks.set(selected.id, Date.now());
       result.push({
         planType: plan,
@@ -622,135 +591,7 @@ export class AccountPool {
       clearTimeout(this.persistTimer);
       this.persistTimer = null;
     }
-    try {
-      const accountsFile = getAccountsFile();
-      const dir = dirname(accountsFile);
-      if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-      const data: AccountsFile = { accounts: [...this.accounts.values()] };
-      const tmpFile = accountsFile + ".tmp";
-      writeFileSync(tmpFile, JSON.stringify(data, null, 2), "utf-8");
-      renameSync(tmpFile, accountsFile);
-    } catch (err) {
-      console.error("[AccountPool] Failed to persist accounts:", err instanceof Error ? err.message : err);
-    }
-  }
-
-  private loadPersisted(): void {
-    try {
-      const accountsFile = getAccountsFile();
-      if (!existsSync(accountsFile)) return;
-      const raw = readFileSync(accountsFile, "utf-8");
-      const data = JSON.parse(raw) as AccountsFile;
-      if (Array.isArray(data.accounts)) {
-        let needsPersist = false;
-        for (const entry of data.accounts) {
-          if (entry.id && entry.token) {
-            // Backfill missing fields from JWT (e.g. planType was null before fix)
-            if (!entry.planType || !entry.email || !entry.accountId) {
-              const profile = extractUserProfile(entry.token);
-              const accountId = extractChatGptAccountId(entry.token);
-              if (!entry.planType && profile?.chatgpt_plan_type) {
-                entry.planType = profile.chatgpt_plan_type;
-                needsPersist = true;
-              }
-              if (!entry.email && profile?.email) {
-                entry.email = profile.email;
-                needsPersist = true;
-              }
-              if (!entry.accountId && accountId) {
-                entry.accountId = accountId;
-                needsPersist = true;
-              }
-            }
-            // Backfill empty_response_count for old entries
-            if (entry.usage.empty_response_count == null) {
-              entry.usage.empty_response_count = 0;
-              needsPersist = true;
-            }
-            // Backfill window counter fields for old entries
-            if (entry.usage.window_request_count == null) {
-              entry.usage.window_request_count = 0;
-              entry.usage.window_input_tokens = 0;
-              entry.usage.window_output_tokens = 0;
-              entry.usage.window_counters_reset_at = null;
-              entry.usage.limit_window_seconds = null;
-              needsPersist = true;
-            }
-            // Backfill cachedQuota fields for old entries
-            if (entry.cachedQuota === undefined) {
-              entry.cachedQuota = null;
-              entry.quotaFetchedAt = null;
-              needsPersist = true;
-            }
-            this.accounts.set(entry.id, entry);
-          }
-        }
-        if (needsPersist) this.persistNow();
-      }
-    } catch (err) {
-      console.warn("[AccountPool] Failed to load accounts:", err instanceof Error ? err.message : err);
-    }
-  }
-
-  private migrateFromLegacy(): void {
-    try {
-      const accountsFile = getAccountsFile();
-      const legacyAuthFile = getLegacyAuthFile();
-      if (existsSync(accountsFile)) return; // already migrated
-      if (!existsSync(legacyAuthFile)) return;
-
-      const raw = readFileSync(legacyAuthFile, "utf-8");
-      const data = JSON.parse(raw) as {
-        token: string;
-        proxyApiKey?: string | null;
-        userInfo?: { email?: string; accountId?: string; planType?: string } | null;
-      };
-
-      if (!data.token) return;
-
-      const id = randomBytes(8).toString("hex");
-      const accountId = extractChatGptAccountId(data.token);
-      const entry: AccountEntry = {
-        id,
-        token: data.token,
-        refreshToken: null,
-        email: data.userInfo?.email ?? null,
-        accountId: accountId,
-        planType: data.userInfo?.planType ?? null,
-        proxyApiKey: data.proxyApiKey ?? "codex-proxy-" + randomBytes(24).toString("hex"),
-        status: isTokenExpired(data.token) ? "expired" : "active",
-        usage: {
-          request_count: 0,
-          input_tokens: 0,
-          output_tokens: 0,
-          empty_response_count: 0,
-          last_used: null,
-          rate_limit_until: null,
-          window_request_count: 0,
-          window_input_tokens: 0,
-          window_output_tokens: 0,
-          window_counters_reset_at: null,
-          limit_window_seconds: null,
-        },
-        addedAt: new Date().toISOString(),
-        cachedQuota: null,
-        quotaFetchedAt: null,
-      };
-
-      this.accounts.set(id, entry);
-
-      // Write new format
-      const dir = dirname(accountsFile);
-      if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-      const accountsData: AccountsFile = { accounts: [entry] };
-      writeFileSync(accountsFile, JSON.stringify(accountsData, null, 2), "utf-8");
-
-      // Rename old file
-      renameSync(legacyAuthFile, legacyAuthFile + ".bak");
-      console.log("[AccountPool] Migrated from auth.json → accounts.json");
-    } catch (err) {
-      console.warn("[AccountPool] Migration failed:", err);
-    }
+    this.persistence.save([...this.accounts.values()]);
   }
 
   /** Flush pending writes on shutdown */

src/auth/rotation-strategy.ts

@@ -0,0 +1,65 @@
+/**
+ * Rotation strategy — stateless selection logic for AccountPool.
+ * Strategies do not mutate input arrays or read config.
+ */
+
+import type { AccountEntry } from "./types.js";
+
+export type RotationStrategyName = "least_used" | "round_robin" | "sticky";
+
+export interface RotationState {
+  roundRobinIndex: number;
+}
+
+export interface RotationStrategy {
+  select(candidates: AccountEntry[], state: RotationState): AccountEntry;
+}
+
+const leastUsed: RotationStrategy = {
+  select(candidates) {
+    const sorted = [...candidates].sort((a, b) => {
+      const diff = a.usage.request_count - b.usage.request_count;
+      if (diff !== 0) return diff;
+      const aReset = a.usage.window_reset_at ?? Infinity;
+      const bReset = b.usage.window_reset_at ?? Infinity;
+      if (aReset !== bReset) return aReset - bReset;
+      const aTime = a.usage.last_used ? new Date(a.usage.last_used).getTime() : 0;
+      const bTime = b.usage.last_used ? new Date(b.usage.last_used).getTime() : 0;
+      return aTime - bTime;
+    });
+    return sorted[0];
+  },
+};
+
+const roundRobin: RotationStrategy = {
+  select(candidates, state) {
+    state.roundRobinIndex = state.roundRobinIndex % candidates.length;
+    const selected = candidates[state.roundRobinIndex];
+    state.roundRobinIndex++;
+    return selected;
+  },
+};
+
+const sticky: RotationStrategy = {
+  select(candidates) {
+    const sorted = [...candidates].sort((a, b) => {
+      const aTime = a.usage.last_used ? new Date(a.usage.last_used).getTime() : 0;
+      const bTime = b.usage.last_used ? new Date(b.usage.last_used).getTime() : 0;
+      return bTime - aTime;
+    });
+    return sorted[0];
+  },
+};
+
+const strategies: Record<RotationStrategyName, RotationStrategy> = {
+  least_used: leastUsed,
+  round_robin: roundRobin,
+  sticky,
+};
+
+export function getRotationStrategy(name: RotationStrategyName): RotationStrategy {
+  return strategies[name] ?? strategies.least_used;
+}
+
+/** @deprecated Use getRotationStrategy instead */
+export const createRotationStrategy = getRotationStrategy;

src/proxy/__tests__/codex-sse.test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect } from "vitest";
+import { parseSSEBlock, parseSSEStream } from "../codex-sse.js";
+
+describe("parseSSEBlock", () => {
+  it("parses event + data", () => {
+    const block = "event: response.created\ndata: {\"id\":\"resp_1\"}";
+    const result = parseSSEBlock(block);
+    expect(result).toEqual({
+      event: "response.created",
+      data: { id: "resp_1" },
+    });
+  });
+
+  it("returns null for empty block", () => {
+    expect(parseSSEBlock("")).toBeNull();
+    expect(parseSSEBlock("   ")).toBeNull();
+  });
+
+  it("returns null for [DONE]", () => {
+    const block = "data: [DONE]";
+    expect(parseSSEBlock(block)).toBeNull();
+  });
+
+  it("handles data without event", () => {
+    const block = 'data: {"type":"text"}';
+    const result = parseSSEBlock(block);
+    expect(result).toEqual({ event: "", data: { type: "text" } });
+  });
+
+  it("handles event without data", () => {
+    const block = "event: done";
+    const result = parseSSEBlock(block);
+    expect(result).toEqual({ event: "done", data: "" });
+  });
+
+  it("joins multi-line data", () => {
+    const block = "event: test\ndata: line1\ndata: line2";
+    const result = parseSSEBlock(block);
+    expect(result?.data).toBe("line1\nline2");
+  });
+
+  it("handles non-JSON data gracefully", () => {
+    const block = "event: error\ndata: plain text error";
+    const result = parseSSEBlock(block);
+    expect(result?.data).toBe("plain text error");
+  });
+});
+
+describe("parseSSEStream", () => {
+  function makeResponse(text: string): Response {
+    const encoder = new TextEncoder();
+    const stream = new ReadableStream({
+      start(controller) {
+        controller.enqueue(encoder.encode(text));
+        controller.close();
+      },
+    });
+    return new Response(stream);
+  }
+
+  it("yields events from SSE stream", async () => {
+    const sse = "event: response.created\ndata: {\"id\":\"r1\"}\n\nevent: response.done\ndata: {\"id\":\"r1\"}\n\n";
+    const events = [];
+    for await (const evt of parseSSEStream(makeResponse(sse))) {
+      events.push(evt);
+    }
+    expect(events).toHaveLength(2);
+    expect(events[0].event).toBe("response.created");
+    expect(events[1].event).toBe("response.done");
+  });
+
+  it("handles non-SSE response as error event", async () => {
+    const json = '{"detail":"unauthorized"}';
+    const events = [];
+    for await (const evt of parseSSEStream(makeResponse(json))) {
+      events.push(evt);
+    }
+    expect(events).toHaveLength(1);
+    expect(events[0].event).toBe("error");
+    const data = events[0].data as Record<string, Record<string, string>>;
+    expect(data.error.message).toBe("unauthorized");
+  });
+
+  it("throws on null body", async () => {
+    const response = new Response(null);
+    const gen = parseSSEStream(response);
+    await expect(gen.next()).rejects.toThrow("Response body is null");
+  });
+});

src/proxy/codex-api.ts

@@ -16,57 +16,32 @@ import {
   buildHeadersWithContentType,
 } from "../fingerprint/manager.js";
 import { createWebSocketResponse, type WsCreateRequest } from "./ws-transport.js";
+import { parseSSEBlock, parseSSEStream } from "./codex-sse.js";
+import { fetchUsage } from "./codex-usage.js";
+import { fetchModels, probeEndpoint as probeEndpointFn } from "./codex-models.js";
 import type { CookieJar } from "./cookie-jar.js";
 import type { BackendModelEntry } from "../models/model-store.js";
 
-let _firstModelFetchLogged = false;
+// Re-export types from codex-types.ts for backward compatibility
+export type {
+  CodexResponsesRequest,
+  CodexContentPart,
+  CodexInputItem,
+  CodexSSEEvent,
+  CodexUsageRateWindow,
+  CodexUsageRateLimit,
+  CodexUsageResponse,
+} from "./codex-types.js";
 
-export interface CodexResponsesRequest {
-  model: string;
-  instructions?: string | null;
-  input: CodexInputItem[];
-  stream: true;
-  store: false;
-  /** Optional: reasoning effort + summary mode */
-  reasoning?: { effort?: string; summary?: string };
-  /** Optional: service tier ("fast" / "flex") */
-  service_tier?: string | null;
-  /** Optional: tools available to the model */
-  tools?: unknown[];
-  /** Optional: tool choice strategy */
-  tool_choice?: string | { type: string; name: string };
-  /** Optional: text output format (JSON mode / structured outputs) */
-  text?: {
-    format: {
-      type: "text" | "json_object" | "json_schema";
-      name?: string;
-      schema?: Record<string, unknown>;
-      strict?: boolean;
-    };
-  };
-  /** Optional: reference a previous response for multi-turn (WebSocket only). */
-  previous_response_id?: string;
-  /** When true, use WebSocket transport (enables previous_response_id and server-side storage). */
-  useWebSocket?: boolean;
-}
-
-/** Structured content part for multimodal Codex input. */
-export type CodexContentPart =
-  | { type: "input_text"; text: string }
-  | { type: "input_image"; image_url: string };
+// Re-export SSE utilities for consumers that used them via CodexApi
+export { parseSSEBlock, parseSSEStream } from "./codex-sse.js";
 
-export type CodexInputItem =
-  | { role: "user"; content: string | CodexContentPart[] }
-  | { role: "assistant"; content: string }
-  | { role: "system"; content: string }
-  | { type: "function_call"; id?: string; call_id: string; name: string; arguments: string }
-  | { type: "function_call_output"; call_id: string; output: string };
-
-/** Parsed SSE event from the Codex Responses stream */
-export interface CodexSSEEvent {
-  event: string;
-  data: unknown;
-}
+import {
+  CodexApiError,
+  type CodexResponsesRequest,
+  type CodexSSEEvent,
+  type CodexUsageResponse,
+} from "./codex-types.js";
 
 export class CodexApi {
   private token: string;
@@ -109,142 +84,28 @@ export class CodexApi {
     }
   }
 
-  /**
-   * Query official Codex usage/quota.
-   * GET /backend-api/codex/usage
-   */
+  /** Query official Codex usage/quota. Delegates to standalone fetchUsage(). */
   async getUsage(): Promise<CodexUsageResponse> {
-    const config = getConfig();
-    const transport = getTransport();
-    const url = `${config.api.base_url}/codex/usage`;
-
     const headers = this.applyHeaders(
       buildHeaders(this.token, this.accountId),
     );
-    headers["Accept"] = "application/json";
-    // When transport lacks Chrome TLS fingerprint, downgrade Accept-Encoding
-    // to encodings system curl can always decompress.
-    if (!transport.isImpersonate()) {
-      headers["Accept-Encoding"] = "gzip, deflate";
-    }
-
-    let body: string;
-    try {
-      const result = await transport.get(url, headers, 15, this.proxyUrl);
-      body = result.body;
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      throw new CodexApiError(0, `transport GET failed: ${msg}`);
-    }
-
-    try {
-      const parsed = JSON.parse(body) as CodexUsageResponse;
-      // Validate we got actual usage data (not an error page)
-      if (!parsed.rate_limit) {
-        throw new CodexApiError(502, `Unexpected response: ${body.slice(0, 200)}`);
-      }
-      return parsed;
-    } catch (e) {
-      if (e instanceof CodexApiError) throw e;
-      throw new CodexApiError(502, `Invalid JSON from /codex/usage: ${body.slice(0, 200)}`);
-    }
+    return fetchUsage(headers, this.proxyUrl);
   }
 
-  /**
-   * Fetch available models from the Codex backend.
-   * Probes known endpoints; returns null if none respond.
-   */
+  /** Fetch available models from the Codex backend. Probes known endpoints; returns null if none respond. */
   async getModels(): Promise<BackendModelEntry[] | null> {
-    const config = getConfig();
-    const transport = getTransport();
-    const baseUrl = config.api.base_url;
-
-    // Endpoints to probe (most specific first)
-    // /codex/models now requires ?client_version= query parameter
-    const clientVersion = config.client.app_version;
-    const endpoints = [
-      `${baseUrl}/codex/models?client_version=${clientVersion}`,
-      `${baseUrl}/models`,
-      `${baseUrl}/sentinel/chat-requirements`,
-    ];
-
     const headers = this.applyHeaders(
       buildHeaders(this.token, this.accountId),
     );
-    headers["Accept"] = "application/json";
-    if (!transport.isImpersonate()) {
-      headers["Accept-Encoding"] = "gzip, deflate";
-    }
-
-    for (const url of endpoints) {
-      try {
-        const result = await transport.get(url, headers, 15, this.proxyUrl);
-        const parsed = JSON.parse(result.body) as Record<string, unknown>;
-
-        // sentinel/chat-requirements returns { chat_models: { models: [...], ... } }
-        const sentinel = parsed.chat_models as Record<string, unknown> | undefined;
-        const models = sentinel?.models ?? parsed.models ?? parsed.data ?? parsed.categories;
-        if (Array.isArray(models) && models.length > 0) {
-          console.log(`[CodexApi] getModels() found ${models.length} entries from ${url}`);
-          if (!_firstModelFetchLogged) {
-            console.log(`[CodexApi] Raw response keys: ${Object.keys(parsed).join(", ")}`);
-            console.log(`[CodexApi] Raw model sample: ${JSON.stringify(models[0]).slice(0, 500)}`);
-            if (models.length > 1) {
-              console.log(`[CodexApi] Raw model sample[1]: ${JSON.stringify(models[1]).slice(0, 500)}`);
-            }
-            _firstModelFetchLogged = true;
-          }
-          // Flatten nested categories into a single list
-          const flattened: BackendModelEntry[] = [];
-          for (const item of models) {
-            if (item && typeof item === "object") {
-              const entry = item as Record<string, unknown>;
-              if (Array.isArray(entry.models)) {
-                for (const sub of entry.models as BackendModelEntry[]) {
-                  flattened.push(sub);
-                }
-              } else {
-                flattened.push(item as BackendModelEntry);
-              }
-            }
-          }
-          if (flattened.length > 0) {
-            console.log(`[CodexApi] getModels() total after flatten: ${flattened.length} models`);
-            return flattened;
-          }
-        }
-      } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        console.log(`[CodexApi] Probe ${url} failed: ${msg}`);
-        continue;
-      }
-    }
-
-    return null;
+    return fetchModels(headers, this.proxyUrl);
   }
 
-  /**
-   * Probe a backend endpoint and return raw JSON (for debug).
-   */
+  /** Probe a backend endpoint and return raw JSON (for debug). */
   async probeEndpoint(path: string): Promise<Record<string, unknown> | null> {
-    const config = getConfig();
-    const transport = getTransport();
-    const url = `${config.api.base_url}${path}`;
-
     const headers = this.applyHeaders(
       buildHeaders(this.token, this.accountId),
     );
-    headers["Accept"] = "application/json";
-    if (!transport.isImpersonate()) {
-      headers["Accept-Encoding"] = "gzip, deflate";
-    }
-
-    try {
-      const result = await transport.get(url, headers, 15, this.proxyUrl);
-      return JSON.parse(result.body) as Record<string, unknown>;
-    } catch {
-      return null;
-    }
+    return probeEndpointFn(path, headers, this.proxyUrl);
   }
 
   /**
@@ -262,7 +123,6 @@ export class CodexApi {
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         console.warn(`[CodexApi] WebSocket failed (${msg}), falling back to HTTP SSE`);
-        // Fallback: strip previous_response_id and use HTTP
         const { previous_response_id: _, useWebSocket: _ws, ...httpRequest } = request;
         return this.createResponseViaHttp(httpRequest as CodexResponsesRequest, signal);
       }
@@ -273,6 +133,7 @@ export class CodexApi {
   /**
    * Create a response via WebSocket (for previous_response_id support).
    * Returns a Response with SSE-formatted body, compatible with parseStream().
+   * No Content-Type header — WebSocket upgrade handles auth via same headers.
    */
   private async createResponseViaWebSocket(
     request: CodexResponsesRequest,
@@ -282,18 +143,16 @@ export class CodexApi {
     const baseUrl = config.api.base_url;
     const wsUrl = baseUrl.replace(/^https?:/, "wss:") + "/codex/responses";
 
-    // Build headers — same auth but no Content-Type (WebSocket upgrade)
     const headers = this.applyHeaders(
       buildHeaders(this.token, this.accountId),
     );
     headers["OpenAI-Beta"] = "responses_websockets=2026-02-06";
     headers["x-openai-internal-codex-residency"] = "us";
 
-    // Build flat WebSocket message — omit store, stream, service_tier
     const wsRequest: WsCreateRequest = {
       type: "response.create",
       model: request.model,
-      instructions: request.instructions,
+      instructions: request.instructions ?? "",
       input: request.input,
     };
     if (request.previous_response_id) {
@@ -310,6 +169,7 @@ export class CodexApi {
   /**
    * Create a response via HTTP SSE (default transport).
    * Uses curl-impersonate for TLS fingerprinting.
+   * No wall-clock timeout — header timeout + AbortSignal provide protection.
    */
   private async createResponseViaHttp(
     request: CodexResponsesRequest,
@@ -324,14 +184,11 @@ export class CodexApi {
       buildHeadersWithContentType(this.token, this.accountId),
     );
     headers["Accept"] = "text/event-stream";
-    // Codex Desktop sends this beta header to enable newer API features
     headers["OpenAI-Beta"] = "responses_websockets=2026-02-06";
 
-    // Strip non-API fields from body — not supported by HTTP SSE.
     const { service_tier: _st, previous_response_id: _pid, useWebSocket: _ws, ...bodyFields } = request;
     const body = JSON.stringify(bodyFields);
 
-    // No wall-clock timeout for streaming SSE — header timeout + AbortSignal provide protection
     let transportRes;
     try {
       transportRes = await transport.post(url, headers, body, signal, undefined, this.proxyUrl);
@@ -340,12 +197,10 @@ export class CodexApi {
       throw new CodexApiError(0, msg);
     }
 
-    // Capture cookies
     this.captureCookies(transportRes.setCookieHeaders);
 
     if (transportRes.status < 200 || transportRes.status >= 300) {
-      // Read the body for error details (cap at 1MB to prevent memory spikes)
-      const MAX_ERROR_BODY = 1024 * 1024; // 1MB
+      const MAX_ERROR_BODY = 1024 * 1024;
       const reader = transportRes.body.getReader();
       const chunks: Uint8Array[] = [];
       let totalSize = 0;
@@ -376,140 +231,12 @@ export class CodexApi {
 
   /**
    * Parse SSE stream from a Codex Responses API response.
-   * Yields individual events.
+   * Delegates to the standalone parseSSEStream() function.
    */
-  async *parseStream(
-    response: Response,
-  ): AsyncGenerator<CodexSSEEvent> {
-    if (!response.body) {
-      throw new Error("Response body is null — cannot stream");
-    }
-
-    const reader = response.body
-      .pipeThrough(new TextDecoderStream())
-      .getReader();
-
-    const MAX_SSE_BUFFER = 10 * 1024 * 1024; // 10MB
-    let buffer = "";
-    let yieldedAny = false;
-    try {
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-
-        buffer += value;
-        if (buffer.length > MAX_SSE_BUFFER) {
-          throw new Error(`SSE buffer exceeded ${MAX_SSE_BUFFER} bytes — aborting stream`);
-        }
-        const parts = buffer.split("\n\n");
-        buffer = parts.pop()!;
-
-        for (const part of parts) {
-          if (!part.trim()) continue;
-          const evt = this.parseSSEBlock(part);
-          if (evt) {
-            yieldedAny = true;
-            yield evt;
-          }
-        }
-      }
-
-      // Process remaining buffer
-      if (buffer.trim()) {
-        const evt = this.parseSSEBlock(buffer);
-        if (evt) {
-          yieldedAny = true;
-          yield evt;
-        }
-      }
-
-      // Non-SSE response detection: if the entire stream yielded no SSE events
-      // but has content, the upstream likely returned a plain JSON error body.
-      if (!yieldedAny && buffer.trim()) {
-        let errorMessage = buffer.trim();
-        try {
-          const parsed = JSON.parse(errorMessage) as Record<string, unknown>;
-          const errObj = typeof parsed.error === "object" && parsed.error !== null
-            ? (parsed.error as Record<string, unknown>)
-            : undefined;
-          errorMessage =
-            (typeof parsed.detail === "string" ? parsed.detail : null)
-            ?? (typeof errObj?.message === "string" ? errObj.message : null)
-            ?? errorMessage;
-        } catch { /* use raw text */ }
-        yield {
-          event: "error",
-          data: { error: { type: "error", code: "non_sse_response", message: errorMessage } },
-        };
-      }
-    } finally {
-      reader.releaseLock();
-    }
-  }
-
-  private parseSSEBlock(block: string): CodexSSEEvent | null {
-    let event = "";
-    const dataLines: string[] = [];
-
-    for (const line of block.split("\n")) {
-      if (line.startsWith("event:")) {
-        event = line.slice(6).trim();
-      } else if (line.startsWith("data:")) {
-        dataLines.push(line.slice(5).trimStart());
-      }
-    }
-
-    if (!event && dataLines.length === 0) return null;
-
-    const raw = dataLines.join("\n");
-    if (raw === "[DONE]") return null;
-
-    let data: unknown;
-    try {
-      data = JSON.parse(raw);
-    } catch {
-      data = raw;
-    }
-
-    return { event, data };
+  async *parseStream(response: Response): AsyncGenerator<CodexSSEEvent> {
+    yield* parseSSEStream(response);
   }
 }
 
-/** Response from GET /backend-api/codex/usage */
-export interface CodexUsageRateWindow {
-  used_percent: number;
-  limit_window_seconds: number;
-  reset_after_seconds: number;
-  reset_at: number;
-}
-
-export interface CodexUsageRateLimit {
-  allowed: boolean;
-  limit_reached: boolean;
-  primary_window: CodexUsageRateWindow | null;
-  secondary_window: CodexUsageRateWindow | null;
-}
-
-export interface CodexUsageResponse {
-  plan_type: string;
-  rate_limit: CodexUsageRateLimit;
-  code_review_rate_limit: CodexUsageRateLimit | null;
-  credits: unknown;
-  promo: unknown;
-}
-
-export class CodexApiError extends Error {
-  constructor(
-    public readonly status: number,
-    public readonly body: string,
-  ) {
-    let detail: string;
-    try {
-      const parsed = JSON.parse(body);
-      detail = parsed.detail ?? parsed.error?.message ?? body;
-    } catch {
-      detail = body;
-    }
-    super(`Codex API error (${status}): ${detail}`);
-  }
-}
+// Re-export CodexApiError for backward compatibility
+export { CodexApiError } from "./codex-types.js";

src/proxy/codex-models.ts

@@ -0,0 +1,97 @@
+/**
+ * Codex model discovery — probes backend endpoints for available models.
+ */
+
+import { getConfig } from "../config.js";
+import { getTransport } from "../tls/transport.js";
+import type { BackendModelEntry } from "../models/model-store.js";
+
+let _firstModelFetchLogged = false;
+
+export async function fetchModels(
+  headers: Record<string, string>,
+  proxyUrl?: string | null,
+): Promise<BackendModelEntry[] | null> {
+  const config = getConfig();
+  const transport = getTransport();
+  const baseUrl = config.api.base_url;
+
+  const clientVersion = config.client.app_version;
+  const endpoints = [
+    `${baseUrl}/codex/models?client_version=${clientVersion}`,
+    `${baseUrl}/models`,
+    `${baseUrl}/sentinel/chat-requirements`,
+  ];
+
+  headers["Accept"] = "application/json";
+  if (!transport.isImpersonate()) {
+    headers["Accept-Encoding"] = "gzip, deflate";
+  }
+
+  for (const url of endpoints) {
+    try {
+      const result = await transport.get(url, headers, 15, proxyUrl);
+      const parsed = JSON.parse(result.body) as Record<string, unknown>;
+
+      const sentinel = parsed.chat_models as Record<string, unknown> | undefined;
+      const models = sentinel?.models ?? parsed.models ?? parsed.data ?? parsed.categories;
+      if (Array.isArray(models) && models.length > 0) {
+        console.log(`[CodexApi] getModels() found ${models.length} entries from ${url}`);
+        if (!_firstModelFetchLogged) {
+          console.log(`[CodexApi] Raw response keys: ${Object.keys(parsed).join(", ")}`);
+          console.log(`[CodexApi] Raw model sample: ${JSON.stringify(models[0]).slice(0, 500)}`);
+          if (models.length > 1) {
+            console.log(`[CodexApi] Raw model sample[1]: ${JSON.stringify(models[1]).slice(0, 500)}`);
+          }
+          _firstModelFetchLogged = true;
+        }
+        // Flatten nested categories into a single list
+        const flattened: BackendModelEntry[] = [];
+        for (const item of models) {
+          if (item && typeof item === "object") {
+            const entry = item as Record<string, unknown>;
+            if (Array.isArray(entry.models)) {
+              for (const sub of entry.models as BackendModelEntry[]) {
+                flattened.push(sub);
+              }
+            } else {
+              flattened.push(item as BackendModelEntry);
+            }
+          }
+        }
+        if (flattened.length > 0) {
+          console.log(`[CodexApi] getModels() total after flatten: ${flattened.length} models`);
+          return flattened;
+        }
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.log(`[CodexApi] Probe ${url} failed: ${msg}`);
+      continue;
+    }
+  }
+
+  return null;
+}
+
+export async function probeEndpoint(
+  path: string,
+  headers: Record<string, string>,
+  proxyUrl?: string | null,
+): Promise<Record<string, unknown> | null> {
+  const config = getConfig();
+  const transport = getTransport();
+  const url = `${config.api.base_url}${path}`;
+
+  headers["Accept"] = "application/json";
+  if (!transport.isImpersonate()) {
+    headers["Accept-Encoding"] = "gzip, deflate";
+  }
+
+  try {
+    const result = await transport.get(url, headers, 15, proxyUrl);
+    return JSON.parse(result.body) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}

src/proxy/codex-sse.ts

@@ -0,0 +1,102 @@
+/**
+ * SSE stream parser for Codex Responses API.
+ * Pure functions — no side effects or external dependencies.
+ */
+
+import type { CodexSSEEvent } from "./codex-types.js";
+
+export function parseSSEBlock(block: string): CodexSSEEvent | null {
+  let event = "";
+  const dataLines: string[] = [];
+
+  for (const line of block.split("\n")) {
+    if (line.startsWith("event:")) {
+      event = line.slice(6).trim();
+    } else if (line.startsWith("data:")) {
+      dataLines.push(line.slice(5).trimStart());
+    }
+  }
+
+  if (!event && dataLines.length === 0) return null;
+
+  const raw = dataLines.join("\n");
+  if (raw === "[DONE]") return null;
+
+  let data: unknown;
+  try {
+    data = JSON.parse(raw);
+  } catch {
+    data = raw;
+  }
+
+  return { event, data };
+}
+
+const MAX_SSE_BUFFER = 10 * 1024 * 1024; // 10MB
+
+export async function* parseSSEStream(
+  response: Response,
+): AsyncGenerator<CodexSSEEvent> {
+  if (!response.body) {
+    throw new Error("Response body is null — cannot stream");
+  }
+
+  const reader = response.body
+    .pipeThrough(new TextDecoderStream())
+    .getReader();
+
+  let buffer = "";
+  let yieldedAny = false;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      buffer += value;
+      if (buffer.length > MAX_SSE_BUFFER) {
+        throw new Error(`SSE buffer exceeded ${MAX_SSE_BUFFER} bytes — aborting stream`);
+      }
+      const parts = buffer.split("\n\n");
+      buffer = parts.pop()!;
+
+      for (const part of parts) {
+        if (!part.trim()) continue;
+        const evt = parseSSEBlock(part);
+        if (evt) {
+          yieldedAny = true;
+          yield evt;
+        }
+      }
+    }
+
+    // Process remaining buffer
+    if (buffer.trim()) {
+      const evt = parseSSEBlock(buffer);
+      if (evt) {
+        yieldedAny = true;
+        yield evt;
+      }
+    }
+
+    // Non-SSE response detection
+    if (!yieldedAny && buffer.trim()) {
+      let errorMessage = buffer.trim();
+      try {
+        const parsed = JSON.parse(errorMessage) as Record<string, unknown>;
+        const errObj = typeof parsed.error === "object" && parsed.error !== null
+          ? (parsed.error as Record<string, unknown>)
+          : undefined;
+        errorMessage =
+          (typeof parsed.detail === "string" ? parsed.detail : null)
+          ?? (typeof errObj?.message === "string" ? errObj.message : null)
+          ?? errorMessage;
+      } catch { /* use raw text */ }
+      yield {
+        event: "error",
+        data: { error: { type: "error", code: "non_sse_response", message: errorMessage } },
+      };
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}

src/proxy/codex-types.ts

@@ -0,0 +1,90 @@
+/**
+ * Type definitions for the Codex Responses API.
+ * Extracted from codex-api.ts for consumers that only need types.
+ */
+
+export interface CodexResponsesRequest {
+  model: string;
+  instructions?: string | null;
+  input: CodexInputItem[];
+  stream: true;
+  store: false;
+  /** Optional: reasoning effort + summary mode */
+  reasoning?: { effort?: string; summary?: string };
+  /** Optional: service tier ("fast" / "flex") */
+  service_tier?: string | null;
+  /** Optional: tools available to the model */
+  tools?: unknown[];
+  /** Optional: tool choice strategy */
+  tool_choice?: string | { type: string; name: string };
+  /** Optional: text output format (JSON mode / structured outputs) */
+  text?: {
+    format: {
+      type: "text" | "json_object" | "json_schema";
+      name?: string;
+      schema?: Record<string, unknown>;
+      strict?: boolean;
+    };
+  };
+  /** Optional: reference a previous response for multi-turn (WebSocket only). */
+  previous_response_id?: string;
+  /** When true, use WebSocket transport (enables previous_response_id and server-side storage). */
+  useWebSocket?: boolean;
+}
+
+/** Structured content part for multimodal Codex input. */
+export type CodexContentPart =
+  | { type: "input_text"; text: string }
+  | { type: "input_image"; image_url: string };
+
+export type CodexInputItem =
+  | { role: "user"; content: string | CodexContentPart[] }
+  | { role: "assistant"; content: string }
+  | { role: "system"; content: string }
+  | { type: "function_call"; id?: string; call_id: string; name: string; arguments: string }
+  | { type: "function_call_output"; call_id: string; output: string };
+
+/** Parsed SSE event from the Codex Responses stream */
+export interface CodexSSEEvent {
+  event: string;
+  data: unknown;
+}
+
+/** Response from GET /backend-api/codex/usage */
+export interface CodexUsageRateWindow {
+  used_percent: number;
+  limit_window_seconds: number;
+  reset_after_seconds: number;
+  reset_at: number;
+}
+
+export interface CodexUsageRateLimit {
+  allowed: boolean;
+  limit_reached: boolean;
+  primary_window: CodexUsageRateWindow | null;
+  secondary_window: CodexUsageRateWindow | null;
+}
+
+export interface CodexUsageResponse {
+  plan_type: string;
+  rate_limit: CodexUsageRateLimit;
+  code_review_rate_limit: CodexUsageRateLimit | null;
+  credits: unknown;
+  promo: unknown;
+}
+
+export class CodexApiError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly body: string,
+  ) {
+    let detail: string;
+    try {
+      const parsed = JSON.parse(body);
+      detail = parsed.detail ?? parsed.error?.message ?? body;
+    } catch {
+      detail = body;
+    }
+    super(`Codex API error (${status}): ${detail}`);
+  }
+}

src/proxy/codex-usage.ts

@@ -0,0 +1,41 @@
+/**
+ * Codex usage/quota API query.
+ */
+
+import { getConfig } from "../config.js";
+import { getTransport } from "../tls/transport.js";
+import { CodexApiError, type CodexUsageResponse } from "./codex-types.js";
+
+export async function fetchUsage(
+  headers: Record<string, string>,
+  proxyUrl?: string | null,
+): Promise<CodexUsageResponse> {
+  const config = getConfig();
+  const transport = getTransport();
+  const url = `${config.api.base_url}/codex/usage`;
+
+  headers["Accept"] = "application/json";
+  if (!transport.isImpersonate()) {
+    headers["Accept-Encoding"] = "gzip, deflate";
+  }
+
+  let body: string;
+  try {
+    const result = await transport.get(url, headers, 15, proxyUrl);
+    body = result.body;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new CodexApiError(0, `transport GET failed: ${msg}`);
+  }
+
+  try {
+    const parsed = JSON.parse(body) as CodexUsageResponse;
+    if (!parsed.rate_limit) {
+      throw new CodexApiError(502, `Unexpected response: ${body.slice(0, 200)}`);
+    }
+    return parsed;
+  } catch (e) {
+    if (e instanceof CodexApiError) throw e;
+    throw new CodexApiError(502, `Invalid JSON from /codex/usage: ${body.slice(0, 200)}`);
+  }
+}

src/routes/admin/connection.ts

@@ -0,0 +1,134 @@
+import { Hono } from "hono";
+import { existsSync } from "fs";
+import { resolve } from "path";
+import type { AccountPool } from "../../auth/account-pool.js";
+import { getConfig } from "../../config.js";
+import { getBinDir } from "../../paths.js";
+import { getTransport, getTransportInfo } from "../../tls/transport.js";
+import { buildHeaders } from "../../fingerprint/manager.js";
+
+export function createConnectionRoutes(accountPool: AccountPool): Hono {
+  const app = new Hono();
+
+  app.post("/admin/test-connection", async (c) => {
+    type DiagStatus = "pass" | "fail" | "skip";
+    interface DiagCheck { name: string; status: DiagStatus; latencyMs: number; detail: string | null; error: string | null; }
+    const checks: DiagCheck[] = [];
+    let overallFailed = false;
+
+    // 1. Server check
+    const serverStart = Date.now();
+    checks.push({
+      name: "server",
+      status: "pass",
+      latencyMs: Date.now() - serverStart,
+      detail: `PID ${process.pid}`,
+      error: null,
+    });
+
+    // 2. Accounts check
+    const accountsStart = Date.now();
+    const poolSummary = accountPool.getPoolSummary();
+    const hasActive = poolSummary.active > 0;
+    checks.push({
+      name: "accounts",
+      status: hasActive ? "pass" : "fail",
+      latencyMs: Date.now() - accountsStart,
+      detail: hasActive
+        ? `${poolSummary.active} active / ${poolSummary.total} total`
+        : `0 active / ${poolSummary.total} total`,
+      error: hasActive ? null : "No active accounts",
+    });
+    if (!hasActive) overallFailed = true;
+
+    // 3. Transport check
+    const transportStart = Date.now();
+    const transportInfo = getTransportInfo();
+    const caCertPath = resolve(getBinDir(), "cacert.pem");
+    const caCertExists = existsSync(caCertPath);
+    const transportOk = transportInfo.initialized;
+    checks.push({
+      name: "transport",
+      status: transportOk ? "pass" : "fail",
+      latencyMs: Date.now() - transportStart,
+      detail: transportOk
+        ? `${transportInfo.type}, impersonate=${transportInfo.impersonate}, ca_cert=${caCertExists}`
+        : null,
+      error: transportOk
+        ? (transportInfo.ffi_error ? `FFI fallback: ${transportInfo.ffi_error}` : null)
+        : (transportInfo.ffi_error ?? "Transport not initialized"),
+    });
+    if (!transportOk) overallFailed = true;
+
+    // 4. Upstream check
+    if (!hasActive) {
+      checks.push({
+        name: "upstream",
+        status: "skip",
+        latencyMs: 0,
+        detail: "Skipped (no active accounts)",
+        error: null,
+      });
+    } else {
+      const upstreamStart = Date.now();
+      const acquired = accountPool.acquire();
+      if (!acquired) {
+        checks.push({
+          name: "upstream",
+          status: "fail",
+          latencyMs: Date.now() - upstreamStart,
+          detail: null,
+          error: "Could not acquire account for test",
+        });
+        overallFailed = true;
+      } else {
+        try {
+          const transport = getTransport();
+          const config = getConfig();
+          const url = `${config.api.base_url}/codex/usage`;
+          const headers = buildHeaders(acquired.token, acquired.accountId);
+          const resp = await transport.get(url, headers, 15);
+          const latency = Date.now() - upstreamStart;
+          if (resp.status >= 200 && resp.status < 400) {
+            checks.push({
+              name: "upstream",
+              status: "pass",
+              latencyMs: latency,
+              detail: `HTTP ${resp.status} (${latency}ms)`,
+              error: null,
+            });
+          } else {
+            checks.push({
+              name: "upstream",
+              status: "fail",
+              latencyMs: latency,
+              detail: `HTTP ${resp.status}`,
+              error: `Upstream returned ${resp.status}`,
+            });
+            overallFailed = true;
+          }
+        } catch (err) {
+          const latency = Date.now() - upstreamStart;
+          checks.push({
+            name: "upstream",
+            status: "fail",
+            latencyMs: latency,
+            detail: null,
+            error: err instanceof Error ? err.message : String(err),
+          });
+          overallFailed = true;
+        } finally {
+          accountPool.releaseWithoutCounting(acquired.entryId);
+        }
+      }
+    }
+
+    return c.json({
+      checks,
+      overall: overallFailed ? "fail" as const : "pass" as const,
+      timestamp: new Date().toISOString(),
+    });
+  });
+
+  return app;
+}

src/routes/admin/health.ts

@@ -0,0 +1,134 @@
+import { Hono } from "hono";
+import { getConnInfo } from "@hono/node-server/conninfo";
+import { existsSync, readFileSync } from "fs";
+import { resolve } from "path";
+import type { AccountPool } from "../../auth/account-pool.js";
+import { getConfig, getFingerprint } from "../../config.js";
+import { getConfigDir, getDataDir, getBinDir, isEmbedded } from "../../paths.js";
+import { getTransportInfo } from "../../tls/transport.js";
+import { getCurlDiagnostics } from "../../tls/curl-binary.js";
+
+export function createHealthRoutes(accountPool: AccountPool): Hono {
+  const app = new Hono();
+
+  app.get("/health", async (c) => {
+    const authenticated = accountPool.isAuthenticated();
+    const poolSummary = accountPool.getPoolSummary();
+    return c.json({
+      status: "ok",
+      authenticated,
+      pool: { total: poolSummary.total, active: poolSummary.active },
+      timestamp: new Date().toISOString(),
+    });
+  });
+
+  app.get("/debug/fingerprint", (c) => {
+    const isProduction = process.env.NODE_ENV === "production";
+    const remoteAddr = getConnInfo(c).remote.address ?? "";
+    const isLocalhost = remoteAddr === "" || remoteAddr === "127.0.0.1" || remoteAddr === "::1" || remoteAddr === "::ffff:127.0.0.1";
+    if (isProduction && !isLocalhost) {
+      c.status(404);
+      return c.json({ error: { message: "Not found", type: "invalid_request_error" } });
+    }
+
+    const config = getConfig();
+    const fp = getFingerprint();
+
+    const ua = fp.user_agent_template
+      .replace("{version}", config.client.app_version)
+      .replace("{platform}", config.client.platform)
+      .replace("{arch}", config.client.arch);
+
+    const promptsDir = resolve(getConfigDir(), "prompts");
+    const prompts: Record<string, boolean> = {
+      "desktop-context.md": existsSync(resolve(promptsDir, "desktop-context.md")),
+      "title-generation.md": existsSync(resolve(promptsDir, "title-generation.md")),
+      "pr-generation.md": existsSync(resolve(promptsDir, "pr-generation.md")),
+      "automation-response.md": existsSync(resolve(promptsDir, "automation-response.md")),
+    };
+
+    let updateState = null;
+    const statePath = resolve(getDataDir(), "update-state.json");
+    if (existsSync(statePath)) {
+      try {
+        updateState = JSON.parse(readFileSync(statePath, "utf-8"));
+      } catch {}
+    }
+
+    return c.json({
+      headers: {
+        "User-Agent": ua,
+        originator: config.client.originator,
+      },
+      client: {
+        app_version: config.client.app_version,
+        build_number: config.client.build_number,
+        platform: config.client.platform,
+        arch: config.client.arch,
+      },
+      api: {
+        base_url: config.api.base_url,
+      },
+      model: {
+        default: config.model.default,
+      },
+      codex_fields: {
+        developer_instructions: "loaded from config/prompts/desktop-context.md",
+        approval_policy: "never",
+        sandbox: "workspace-write",
+        personality: null,
+        ephemeral: null,
+      },
+      prompts_loaded: prompts,
+      update_state: updateState,
+    });
+  });
+
+  app.get("/debug/diagnostics", (c) => {
+    const remoteAddr = getConnInfo(c).remote.address ?? "";
+    const isLocalhost = remoteAddr === "" || remoteAddr === "127.0.0.1" || remoteAddr === "::1" || remoteAddr === "::ffff:127.0.0.1";
+    if (process.env.NODE_ENV === "production" && !isLocalhost) {
+      c.status(404);
+      return c.json({ error: { message: "Not found", type: "invalid_request_error" } });
+    }
+
+    const transport = getTransportInfo();
+    const curl = getCurlDiagnostics();
+    const poolSummary = accountPool.getPoolSummary();
+    const caCertPath = resolve(getBinDir(), "cacert.pem");
+
+    return c.json({
+      transport: {
+        type: transport.type,
+        initialized: transport.initialized,
+        impersonate: transport.impersonate,
+        ffi_error: transport.ffi_error,
+      },
+      curl: {
+        binary: curl.binary,
+        is_impersonate: curl.is_impersonate,
+        profile: curl.profile,
+      },
+      proxy: { url: curl.proxy_url },
+      ca_cert: { found: existsSync(caCertPath), path: caCertPath },
+      accounts: {
+        total: poolSummary.total,
+        active: poolSummary.active,
+        authenticated: accountPool.isAuthenticated(),
+      },
+      paths: {
+        bin: getBinDir(),
+        config: getConfigDir(),
+        data: getDataDir(),
+      },
+      runtime: {
+        platform: process.platform,
+        arch: process.arch,
+        node_version: process.version,
+        embedded: isEmbedded(),
+      },
+    });
+  });
+
+  return app;
+}

src/routes/admin/settings.ts

@@ -0,0 +1,164 @@
+import { Hono } from "hono";
+import { resolve } from "path";
+import { getConfig, reloadAllConfigs, ROTATION_STRATEGIES } from "../../config.js";
+import { getConfigDir } from "../../paths.js";
+import { mutateYaml } from "../../utils/yaml-mutate.js";
+
+export function createSettingsRoutes(): Hono {
+  const app = new Hono();
+
+  // --- Rotation settings ---
+
+  app.get("/admin/rotation-settings", (c) => {
+    const config = getConfig();
+    return c.json({
+      rotation_strategy: config.auth.rotation_strategy,
+    });
+  });
+
+  app.post("/admin/rotation-settings", async (c) => {
+    const config = getConfig();
+    const currentKey = config.server.proxy_api_key;
+
+    if (currentKey) {
+      const authHeader = c.req.header("Authorization") ?? "";
+      const token = authHeader.startsWith("Bearer ") ? authHeader.slice(7) : "";
+      if (token !== currentKey) {
+        c.status(401);
+        return c.json({ error: "Invalid current API key" });
+      }
+    }
+
+    const body = await c.req.json() as { rotation_strategy?: string };
+    const valid: readonly string[] = ROTATION_STRATEGIES;
+    if (!body.rotation_strategy || !valid.includes(body.rotation_strategy)) {
+      c.status(400);
+      return c.json({ error: `rotation_strategy must be one of: ${ROTATION_STRATEGIES.join(", ")}` });
+    }
+
+    const configPath = resolve(getConfigDir(), "default.yaml");
+    mutateYaml(configPath, (data) => {
+      if (!data.auth) data.auth = {};
+      (data.auth as Record<string, unknown>).rotation_strategy = body.rotation_strategy;
+    });
+    reloadAllConfigs();
+
+    const updated = getConfig();
+    return c.json({
+      success: true,
+      rotation_strategy: updated.auth.rotation_strategy,
+    });
+  });
+
+  // --- General settings ---
+
+  app.get("/admin/settings", (c) => {
+    const config = getConfig();
+    return c.json({ proxy_api_key: config.server.proxy_api_key });
+  });
+
+  app.post("/admin/settings", async (c) => {
+    const config = getConfig();
+    const currentKey = config.server.proxy_api_key;
+
+    if (currentKey) {
+      const authHeader = c.req.header("Authorization") ?? "";
+      const token = authHeader.startsWith("Bearer ") ? authHeader.slice(7) : "";
+      if (token !== currentKey) {
+        c.status(401);
+        return c.json({ error: "Invalid current API key" });
+      }
+    }
+
+    const body = await c.req.json() as { proxy_api_key?: string | null };
+    const newKey = body.proxy_api_key === undefined ? currentKey : (body.proxy_api_key || null);
+
+    const configPath = resolve(getConfigDir(), "default.yaml");
+    mutateYaml(configPath, (data) => {
+      const server = data.server as Record<string, unknown>;
+      server.proxy_api_key = newKey;
+    });
+    reloadAllConfigs();
+
+    return c.json({ success: true, proxy_api_key: newKey });
+  });
+
+  // --- Quota settings ---
+
+  app.get("/admin/quota-settings", (c) => {
+    const config = getConfig();
+    return c.json({
+      refresh_interval_minutes: config.quota.refresh_interval_minutes,
+      warning_thresholds: config.quota.warning_thresholds,
+      skip_exhausted: config.quota.skip_exhausted,
+    });
+  });
+
+  app.post("/admin/quota-settings", async (c) => {
+    const config = getConfig();
+    const currentKey = config.server.proxy_api_key;
+
+    if (currentKey) {
+      const authHeader = c.req.header("Authorization") ?? "";
+      const token = authHeader.startsWith("Bearer ") ? authHeader.slice(7) : "";
+      if (token !== currentKey) {
+        c.status(401);
+        return c.json({ error: "Invalid current API key" });
+      }
+    }
+
+    const body = await c.req.json() as {
+      refresh_interval_minutes?: number;
+      warning_thresholds?: { primary?: number[]; secondary?: number[] };
+      skip_exhausted?: boolean;
+    };
+
+    if (body.refresh_interval_minutes !== undefined) {
+      if (!Number.isInteger(body.refresh_interval_minutes) || body.refresh_interval_minutes < 1) {
+        c.status(400);
+        return c.json({ error: "refresh_interval_minutes must be an integer >= 1" });
+      }
+    }
+
+    const validateThresholds = (arr?: number[]): boolean => {
+      if (!arr) return true;
+      return arr.every((v) => Number.isInteger(v) && v >= 1 && v <= 100);
+    };
+    if (body.warning_thresholds) {
+      if (!validateThresholds(body.warning_thresholds.primary) ||
+          !validateThresholds(body.warning_thresholds.secondary)) {
+        c.status(400);
+        return c.json({ error: "Thresholds must be integers between 1 and 100" });
+      }
+    }
+
+    const configPath = resolve(getConfigDir(), "default.yaml");
+    mutateYaml(configPath, (data) => {
+      if (!data.quota) data.quota = {};
+      const quota = data.quota as Record<string, unknown>;
+      if (body.refresh_interval_minutes !== undefined) {
+        quota.refresh_interval_minutes = body.refresh_interval_minutes;
+      }
+      if (body.warning_thresholds) {
+        const existing = (quota.warning_thresholds ?? {}) as Record<string, unknown>;
+        if (body.warning_thresholds.primary) existing.primary = body.warning_thresholds.primary;
+        if (body.warning_thresholds.secondary) existing.secondary = body.warning_thresholds.secondary;
+        quota.warning_thresholds = existing;
+      }
+      if (body.skip_exhausted !== undefined) {
+        quota.skip_exhausted = body.skip_exhausted;
+      }
+    });
+    reloadAllConfigs();
+
+    const updated = getConfig();
+    return c.json({
+      success: true,
+      refresh_interval_minutes: updated.quota.refresh_interval_minutes,
+      warning_thresholds: updated.quota.warning_thresholds,
+      skip_exhausted: updated.quota.skip_exhausted,
+    });
+  });
+
+  return app;
+}

src/routes/admin/update.ts

@@ -0,0 +1,137 @@
+import { Hono } from "hono";
+import { stream } from "hono/streaming";
+import { getUpdateState, checkForUpdate, isUpdateInProgress } from "../../update-checker.js";
+import { getProxyInfo, canSelfUpdate, checkProxySelfUpdate, applyProxySelfUpdate, isProxyUpdateInProgress, getCachedProxyUpdateResult, getDeployMode } from "../../self-update.js";
+import { isEmbedded } from "../../paths.js";
+
+export function createUpdateRoutes(): Hono {
+  const app = new Hono();
+
+  app.get("/admin/update-status", (c) => {
+    const proxyInfo = getProxyInfo();
+    const codexState = getUpdateState();
+    const cached = getCachedProxyUpdateResult();
+
+    return c.json({
+      proxy: {
+        version: proxyInfo.version,
+        commit: proxyInfo.commit,
+        can_self_update: canSelfUpdate(),
+        mode: getDeployMode(),
+        commits_behind: cached?.commitsBehind ?? null,
+        commits: cached?.commits ?? [],
+        release: cached?.release ? { version: cached.release.version, body: cached.release.body, url: cached.release.url } : null,
+        update_available: cached?.updateAvailable ?? false,
+        update_in_progress: isProxyUpdateInProgress(),
+      },
+      codex: {
+        current_version: codexState?.current_version ?? null,
+        current_build: codexState?.current_build ?? null,
+        latest_version: codexState?.latest_version ?? null,
+        latest_build: codexState?.latest_build ?? null,
+        update_available: codexState?.update_available ?? false,
+        update_in_progress: isUpdateInProgress(),
+        last_check: codexState?.last_check ?? null,
+      },
+    });
+  });
+
+  app.post("/admin/check-update", async (c) => {
+    const results: {
+      proxy?: {
+        commits_behind: number;
+        current_commit: string | null;
+        latest_commit: string | null;
+        commits: Array<{ hash: string; message: string }>;
+        release: { version: string; body: string; url: string } | null;
+        update_available: boolean;
+        mode: string;
+        error?: string;
+      };
+      codex?: { update_available: boolean; current_version: string; latest_version: string | null; version_changed?: boolean; error?: string };
+    } = {};
+
+    try {
+      const proxyResult = await checkProxySelfUpdate();
+      results.proxy = {
+        commits_behind: proxyResult.commitsBehind,
+        current_commit: proxyResult.currentCommit,
+        latest_commit: proxyResult.latestCommit,
+        commits: proxyResult.commits,
+        release: proxyResult.release ? { version: proxyResult.release.version, body: proxyResult.release.body, url: proxyResult.release.url } : null,
+        update_available: proxyResult.updateAvailable,
+        mode: proxyResult.mode,
+      };
+    } catch (err) {
+      results.proxy = {
+        commits_behind: 0,
+        current_commit: null,
+        latest_commit: null,
+        commits: [],
+        release: null,
+        update_available: false,
+        mode: getDeployMode(),
+        error: err instanceof Error ? err.message : String(err),
+      };
+    }
+
+    if (!isEmbedded()) {
+      try {
+        const prevVersion = getUpdateState()?.current_version ?? null;
+        const codexState = await checkForUpdate();
+        results.codex = {
+          update_available: codexState.update_available,
+          current_version: codexState.current_version,
+          latest_version: codexState.latest_version,
+          version_changed: prevVersion !== null && codexState.current_version !== prevVersion,
+        };
+      } catch (err) {
+        results.codex = {
+          update_available: false,
+          current_version: "unknown",
+          latest_version: null,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    }
+
+    return c.json({
+      ...results,
+      proxy_update_in_progress: isProxyUpdateInProgress(),
+      codex_update_in_progress: isUpdateInProgress(),
+    });
+  });
+
+  app.post("/admin/apply-update", async (c) => {
+    if (!canSelfUpdate()) {
+      const mode = getDeployMode();
+      c.status(400);
+      return c.json({
+        started: false,
+        error: "Self-update not available in this deploy mode",
+        mode,
+        hint: mode === "docker"
+          ? "Run: docker compose pull && docker compose up -d (or enable Watchtower for automatic updates)"
+          : mode === "electron"
+            ? "Updates are handled automatically by the desktop app. Check the system tray for update notifications, or restart the app to trigger a check."
+            : "Git is not available in this environment",
+      });
+    }
+
+    c.header("Content-Type", "text/event-stream");
+    c.header("Cache-Control", "no-cache");
+    c.header("Connection", "keep-alive");
+
+    return stream(c, async (s) => {
+      const send = (data: Record<string, unknown>) => s.write(`data: ${JSON.stringify(data)}\n\n`);
+
+      const result = await applyProxySelfUpdate((step, status, detail) => {
+        void send({ step, status, detail });
+      });
+
+      await send({ ...result, done: true });
+    });
+  });
+
+  return app;
+}

src/routes/web.ts

@@ -1,18 +1,13 @@
 import { Hono } from "hono";
-import { stream } from "hono/streaming";
 import { serveStatic } from "@hono/node-server/serve-static";
-import { getConnInfo } from "@hono/node-server/conninfo";
 import { readFileSync, existsSync } from "fs";
 import { resolve } from "path";
 import type { AccountPool } from "../auth/account-pool.js";
-import { getConfig, getFingerprint, reloadAllConfigs, ROTATION_STRATEGIES } from "../config.js";
-import { getPublicDir, getDesktopPublicDir, getConfigDir, getDataDir, getBinDir, isEmbedded } from "../paths.js";
-import { getTransport, getTransportInfo } from "../tls/transport.js";
-import { getCurlDiagnostics } from "../tls/curl-binary.js";
-import { buildHeaders } from "../fingerprint/manager.js";
-import { getUpdateState, checkForUpdate, isUpdateInProgress } from "../update-checker.js";
-import { getProxyInfo, canSelfUpdate, checkProxySelfUpdate, applyProxySelfUpdate, isProxyUpdateInProgress, getCachedProxyUpdateResult, getDeployMode } from "../self-update.js";
-import { mutateYaml } from "../utils/yaml-mutate.js";
+import { getPublicDir, getDesktopPublicDir } from "../paths.js";
+import { createHealthRoutes } from "./admin/health.js";
+import { createUpdateRoutes } from "./admin/update.js";
+import { createConnectionRoutes } from "./admin/connection.js";
+import { createSettingsRoutes } from "./admin/settings.js";
 
 export function createWebRoutes(accountPool: AccountPool): Hono {
   const app = new Hono();
@@ -62,544 +57,17 @@ export function createWebRoutes(accountPool: AccountPool): Hono {
       return c.html(html);
     });
   } else {
-    // Fallback: redirect /desktop to web UI so the app is still usable
     app.get("/desktop", (c) => {
       console.warn(`[Web] Desktop UI not found at ${desktopIndexPath}, falling back to web UI`);
       return c.redirect("/");
     });
   }
 
-  app.get("/health", async (c) => {
-    const authenticated = accountPool.isAuthenticated();
-    const poolSummary = accountPool.getPoolSummary();
-    return c.json({
-      status: "ok",
-      authenticated,
-      pool: { total: poolSummary.total, active: poolSummary.active },
-      timestamp: new Date().toISOString(),
-    });
-  });
-
-  app.get("/debug/fingerprint", (c) => {
-    // Only allow in development or from localhost
-    const isProduction = process.env.NODE_ENV === "production";
-    const remoteAddr = getConnInfo(c).remote.address ?? "";
-    const isLocalhost = remoteAddr === "" || remoteAddr === "127.0.0.1" || remoteAddr === "::1" || remoteAddr === "::ffff:127.0.0.1";
-    if (isProduction && !isLocalhost) {
-      c.status(404);
-      return c.json({ error: { message: "Not found", type: "invalid_request_error" } });
-    }
-
-    const config = getConfig();
-    const fp = getFingerprint();
-
-    const ua = fp.user_agent_template
-      .replace("{version}", config.client.app_version)
-      .replace("{platform}", config.client.platform)
-      .replace("{arch}", config.client.arch);
-
-    const promptsDir = resolve(getConfigDir(), "prompts");
-    const prompts: Record<string, boolean> = {
-      "desktop-context.md": existsSync(resolve(promptsDir, "desktop-context.md")),
-      "title-generation.md": existsSync(resolve(promptsDir, "title-generation.md")),
-      "pr-generation.md": existsSync(resolve(promptsDir, "pr-generation.md")),
-      "automation-response.md": existsSync(resolve(promptsDir, "automation-response.md")),
-    };
-
-    // Check for update state
-    let updateState = null;
-    const statePath = resolve(getDataDir(), "update-state.json");
-    if (existsSync(statePath)) {
-      try {
-        updateState = JSON.parse(readFileSync(statePath, "utf-8"));
-      } catch {}
-    }
-
-    return c.json({
-      headers: {
-        "User-Agent": ua,
-        originator: config.client.originator,
-      },
-      client: {
-        app_version: config.client.app_version,
-        build_number: config.client.build_number,
-        platform: config.client.platform,
-        arch: config.client.arch,
-      },
-      api: {
-        base_url: config.api.base_url,
-      },
-      model: {
-        default: config.model.default,
-      },
-      codex_fields: {
-        developer_instructions: "loaded from config/prompts/desktop-context.md",
-        approval_policy: "never",
-        sandbox: "workspace-write",
-        personality: null,
-        ephemeral: null,
-      },
-      prompts_loaded: prompts,
-      update_state: updateState,
-    });
-  });
-
-  app.get("/debug/diagnostics", (c) => {
-    const remoteAddr = getConnInfo(c).remote.address ?? "";
-    const isLocalhost = remoteAddr === "" || remoteAddr === "127.0.0.1" || remoteAddr === "::1" || remoteAddr === "::ffff:127.0.0.1";
-    if (process.env.NODE_ENV === "production" && !isLocalhost) {
-      c.status(404);
-      return c.json({ error: { message: "Not found", type: "invalid_request_error" } });
-    }
-
-    const transport = getTransportInfo();
-    const curl = getCurlDiagnostics();
-    const poolSummary = accountPool.getPoolSummary();
-    const caCertPath = resolve(getBinDir(), "cacert.pem");
-
-    return c.json({
-      transport: {
-        type: transport.type,
-        initialized: transport.initialized,
-        impersonate: transport.impersonate,
-        ffi_error: transport.ffi_error,
-      },
-      curl: {
-        binary: curl.binary,
-        is_impersonate: curl.is_impersonate,
-        profile: curl.profile,
-      },
-      proxy: { url: curl.proxy_url },
-      ca_cert: { found: existsSync(caCertPath), path: caCertPath },
-      accounts: {
-        total: poolSummary.total,
-        active: poolSummary.active,
-        authenticated: accountPool.isAuthenticated(),
-      },
-      paths: {
-        bin: getBinDir(),
-        config: getConfigDir(),
-        data: getDataDir(),
-      },
-      runtime: {
-        platform: process.platform,
-        arch: process.arch,
-        node_version: process.version,
-        embedded: isEmbedded(),
-      },
-    });
-  });
-
-  // --- Update management endpoints ---
-
-  app.get("/admin/update-status", (c) => {
-    const proxyInfo = getProxyInfo();
-    const codexState = getUpdateState();
-    const cached = getCachedProxyUpdateResult();
-
-    return c.json({
-      proxy: {
-        version: proxyInfo.version,
-        commit: proxyInfo.commit,
-        can_self_update: canSelfUpdate(),
-        mode: getDeployMode(),
-        commits_behind: cached?.commitsBehind ?? null,
-        commits: cached?.commits ?? [],
-        release: cached?.release ? { version: cached.release.version, body: cached.release.body, url: cached.release.url } : null,
-        update_available: cached?.updateAvailable ?? false,
-        update_in_progress: isProxyUpdateInProgress(),
-      },
-      codex: {
-        current_version: codexState?.current_version ?? null,
-        current_build: codexState?.current_build ?? null,
-        latest_version: codexState?.latest_version ?? null,
-        latest_build: codexState?.latest_build ?? null,
-        update_available: codexState?.update_available ?? false,
-        update_in_progress: isUpdateInProgress(),
-        last_check: codexState?.last_check ?? null,
-      },
-    });
-  });
-
-  app.post("/admin/check-update", async (c) => {
-    const results: {
-      proxy?: {
-        commits_behind: number;
-        current_commit: string | null;
-        latest_commit: string | null;
-        commits: Array<{ hash: string; message: string }>;
-        release: { version: string; body: string; url: string } | null;
-        update_available: boolean;
-        mode: string;
-        error?: string;
-      };
-      codex?: { update_available: boolean; current_version: string; latest_version: string | null; version_changed?: boolean; error?: string };
-    } = {};
-
-    // 1. Proxy update check (all modes)
-    try {
-      const proxyResult = await checkProxySelfUpdate();
-      results.proxy = {
-        commits_behind: proxyResult.commitsBehind,
-        current_commit: proxyResult.currentCommit,
-        latest_commit: proxyResult.latestCommit,
-        commits: proxyResult.commits,
-        release: proxyResult.release ? { version: proxyResult.release.version, body: proxyResult.release.body, url: proxyResult.release.url } : null,
-        update_available: proxyResult.updateAvailable,
-        mode: proxyResult.mode,
-      };
-    } catch (err) {
-      results.proxy = {
-        commits_behind: 0,
-        current_commit: null,
-        latest_commit: null,
-        commits: [],
-        release: null,
-        update_available: false,
-        mode: getDeployMode(),
-        error: err instanceof Error ? err.message : String(err),
-      };
-    }
-
-    // 2. Codex fingerprint check
-    if (!isEmbedded()) {
-      try {
-        const prevVersion = getUpdateState()?.current_version ?? null;
-        const codexState = await checkForUpdate();
-        results.codex = {
-          update_available: codexState.update_available,
-          current_version: codexState.current_version,
-          latest_version: codexState.latest_version,
-          version_changed: prevVersion !== null && codexState.current_version !== prevVersion,
-        };
-      } catch (err) {
-        results.codex = {
-          update_available: false,
-          current_version: "unknown",
-          latest_version: null,
-          error: err instanceof Error ? err.message : String(err),
-        };
-      }
-    }
-
-    return c.json({
-      ...results,
-      proxy_update_in_progress: isProxyUpdateInProgress(),
-      codex_update_in_progress: isUpdateInProgress(),
-    });
-  });
-
-  app.post("/admin/apply-update", async (c) => {
-    if (!canSelfUpdate()) {
-      const mode = getDeployMode();
-      c.status(400);
-      return c.json({
-        started: false,
-        error: "Self-update not available in this deploy mode",
-        mode,
-        hint: mode === "docker"
-          ? "Run: docker compose pull && docker compose up -d (or enable Watchtower for automatic updates)"
-          : mode === "electron"
-            ? "Updates are handled automatically by the desktop app. Check the system tray for update notifications, or restart the app to trigger a check."
-            : "Git is not available in this environment",
-      });
-    }
-
-    // SSE stream for progress updates
-    c.header("Content-Type", "text/event-stream");
-    c.header("Cache-Control", "no-cache");
-    c.header("Connection", "keep-alive");
-
-    return stream(c, async (s) => {
-      const send = (data: Record<string, unknown>) => s.write(`data: ${JSON.stringify(data)}\n\n`);
-
-      const result = await applyProxySelfUpdate((step, status, detail) => {
-        void send({ step, status, detail });
-      });
-
-      await send({ ...result, done: true });
-    });
-  });
-
-  // --- Test connection endpoint ---
-
-  app.post("/admin/test-connection", async (c) => {
-    type DiagStatus = "pass" | "fail" | "skip";
-    interface DiagCheck { name: string; status: DiagStatus; latencyMs: number; detail: string | null; error: string | null; }
-    const checks: DiagCheck[] = [];
-    let overallFailed = false;
-
-    // 1. Server check — if we're responding, it's a pass
-    const serverStart = Date.now();
-    checks.push({
-      name: "server",
-      status: "pass",
-      latencyMs: Date.now() - serverStart,
-      detail: `PID ${process.pid}`,
-      error: null,
-    });
-
-    // 2. Accounts check — any authenticated accounts?
-    const accountsStart = Date.now();
-    const poolSummary = accountPool.getPoolSummary();
-    const hasActive = poolSummary.active > 0;
-    checks.push({
-      name: "accounts",
-      status: hasActive ? "pass" : "fail",
-      latencyMs: Date.now() - accountsStart,
-      detail: hasActive
-        ? `${poolSummary.active} active / ${poolSummary.total} total`
-        : `0 active / ${poolSummary.total} total`,
-      error: hasActive ? null : "No active accounts",
-    });
-    if (!hasActive) overallFailed = true;
-
-    // 3. Transport check — TLS transport initialized?
-    const transportStart = Date.now();
-    const transportInfo = getTransportInfo();
-    const caCertPath = resolve(getBinDir(), "cacert.pem");
-    const caCertExists = existsSync(caCertPath);
-    const transportOk = transportInfo.initialized;
-    checks.push({
-      name: "transport",
-      status: transportOk ? "pass" : "fail",
-      latencyMs: Date.now() - transportStart,
-      detail: transportOk
-        ? `${transportInfo.type}, impersonate=${transportInfo.impersonate}, ca_cert=${caCertExists}`
-        : null,
-      error: transportOk
-        ? (transportInfo.ffi_error ? `FFI fallback: ${transportInfo.ffi_error}` : null)
-        : (transportInfo.ffi_error ?? "Transport not initialized"),
-    });
-    if (!transportOk) overallFailed = true;
-
-    // 4. Upstream check — can we reach chatgpt.com?
-    if (!hasActive) {
-      // Skip upstream if no accounts
-      checks.push({
-        name: "upstream",
-        status: "skip",
-        latencyMs: 0,
-        detail: "Skipped (no active accounts)",
-        error: null,
-      });
-    } else {
-      const upstreamStart = Date.now();
-      const acquired = accountPool.acquire();
-      if (!acquired) {
-        checks.push({
-          name: "upstream",
-          status: "fail",
-          latencyMs: Date.now() - upstreamStart,
-          detail: null,
-          error: "Could not acquire account for test",
-        });
-        overallFailed = true;
-      } else {
-        try {
-          const transport = getTransport();
-          const config = getConfig();
-          const url = `${config.api.base_url}/codex/usage`;
-          const headers = buildHeaders(acquired.token, acquired.accountId);
-          const resp = await transport.get(url, headers, 15);
-          const latency = Date.now() - upstreamStart;
-          if (resp.status >= 200 && resp.status < 400) {
-            checks.push({
-              name: "upstream",
-              status: "pass",
-              latencyMs: latency,
-              detail: `HTTP ${resp.status} (${latency}ms)`,
-              error: null,
-            });
-          } else {
-            checks.push({
-              name: "upstream",
-              status: "fail",
-              latencyMs: latency,
-              detail: `HTTP ${resp.status}`,
-              error: `Upstream returned ${resp.status}`,
-            });
-            overallFailed = true;
-          }
-        } catch (err) {
-          const latency = Date.now() - upstreamStart;
-          checks.push({
-            name: "upstream",
-            status: "fail",
-            latencyMs: latency,
-            detail: null,
-            error: err instanceof Error ? err.message : String(err),
-          });
-          overallFailed = true;
-        } finally {
-          accountPool.releaseWithoutCounting(acquired.entryId);
-        }
-      }
-    }
-
-    return c.json({
-      checks,
-      overall: overallFailed ? "fail" as const : "pass" as const,
-      timestamp: new Date().toISOString(),
-    });
-  });
-
-  // --- Settings endpoints ---
-
-  // --- Rotation settings endpoints ---
-
-  app.get("/admin/rotation-settings", (c) => {
-    const config = getConfig();
-    return c.json({
-      rotation_strategy: config.auth.rotation_strategy,
-    });
-  });
-
-  app.post("/admin/rotation-settings", async (c) => {
-    const config = getConfig();
-    const currentKey = config.server.proxy_api_key;
-
-    if (currentKey) {
-      const authHeader = c.req.header("Authorization") ?? "";
-      const token = authHeader.startsWith("Bearer ") ? authHeader.slice(7) : "";
-      if (token !== currentKey) {
-        c.status(401);
-        return c.json({ error: "Invalid current API key" });
-      }
-    }
-
-    const body = await c.req.json() as { rotation_strategy?: string };
-    const valid: readonly string[] = ROTATION_STRATEGIES;
-    if (!body.rotation_strategy || !valid.includes(body.rotation_strategy)) {
-      c.status(400);
-      return c.json({ error: `rotation_strategy must be one of: ${ROTATION_STRATEGIES.join(", ")}` });
-    }
-
-    const configPath = resolve(getConfigDir(), "default.yaml");
-    mutateYaml(configPath, (data) => {
-      if (!data.auth) data.auth = {};
-      (data.auth as Record<string, unknown>).rotation_strategy = body.rotation_strategy;
-    });
-    reloadAllConfigs();
-
-    const updated = getConfig();
-    return c.json({
-      success: true,
-      rotation_strategy: updated.auth.rotation_strategy,
-    });
-  });
-
-  app.get("/admin/settings", (c) => {
-    const config = getConfig();
-    return c.json({ proxy_api_key: config.server.proxy_api_key });
-  });
-
-  // --- Quota settings endpoints ---
-
-  app.get("/admin/quota-settings", (c) => {
-    const config = getConfig();
-    return c.json({
-      refresh_interval_minutes: config.quota.refresh_interval_minutes,
-      warning_thresholds: config.quota.warning_thresholds,
-      skip_exhausted: config.quota.skip_exhausted,
-    });
-  });
-
-  app.post("/admin/quota-settings", async (c) => {
-    const config = getConfig();
-    const currentKey = config.server.proxy_api_key;
-
-    // Auth: if a key is currently set, require Bearer token matching it
-    if (currentKey) {
-      const authHeader = c.req.header("Authorization") ?? "";
-      const token = authHeader.startsWith("Bearer ") ? authHeader.slice(7) : "";
-      if (token !== currentKey) {
-        c.status(401);
-        return c.json({ error: "Invalid current API key" });
-      }
-    }
-
-    const body = await c.req.json() as {
-      refresh_interval_minutes?: number;
-      warning_thresholds?: { primary?: number[]; secondary?: number[] };
-      skip_exhausted?: boolean;
-    };
-
-    // Validate refresh_interval_minutes
-    if (body.refresh_interval_minutes !== undefined) {
-      if (!Number.isInteger(body.refresh_interval_minutes) || body.refresh_interval_minutes < 1) {
-        c.status(400);
-        return c.json({ error: "refresh_interval_minutes must be an integer >= 1" });
-      }
-    }
-
-    // Validate thresholds (1-100)
-    const validateThresholds = (arr?: number[]): boolean => {
-      if (!arr) return true;
-      return arr.every((v) => Number.isInteger(v) && v >= 1 && v <= 100);
-    };
-    if (body.warning_thresholds) {
-      if (!validateThresholds(body.warning_thresholds.primary) ||
-          !validateThresholds(body.warning_thresholds.secondary)) {
-        c.status(400);
-        return c.json({ error: "Thresholds must be integers between 1 and 100" });
-      }
-    }
-
-    const configPath = resolve(getConfigDir(), "default.yaml");
-    mutateYaml(configPath, (data) => {
-      if (!data.quota) data.quota = {};
-      const quota = data.quota as Record<string, unknown>;
-      if (body.refresh_interval_minutes !== undefined) {
-        quota.refresh_interval_minutes = body.refresh_interval_minutes;
-      }
-      if (body.warning_thresholds) {
-        const existing = (quota.warning_thresholds ?? {}) as Record<string, unknown>;
-        if (body.warning_thresholds.primary) existing.primary = body.warning_thresholds.primary;
-        if (body.warning_thresholds.secondary) existing.secondary = body.warning_thresholds.secondary;
-        quota.warning_thresholds = existing;
-      }
-      if (body.skip_exhausted !== undefined) {
-        quota.skip_exhausted = body.skip_exhausted;
-      }
-    });
-    reloadAllConfigs();
-
-    const updated = getConfig();
-    return c.json({
-      success: true,
-      refresh_interval_minutes: updated.quota.refresh_interval_minutes,
-      warning_thresholds: updated.quota.warning_thresholds,
-      skip_exhausted: updated.quota.skip_exhausted,
-    });
-  });
-
-  app.post("/admin/settings", async (c) => {
-    const config = getConfig();
-    const currentKey = config.server.proxy_api_key;
-
-    // Auth: if a key is currently set, require Bearer token matching it
-    if (currentKey) {
-      const authHeader = c.req.header("Authorization") ?? "";
-      const token = authHeader.startsWith("Bearer ") ? authHeader.slice(7) : "";
-      if (token !== currentKey) {
-        c.status(401);
-        return c.json({ error: "Invalid current API key" });
-      }
-    }
-
-    const body = await c.req.json() as { proxy_api_key?: string | null };
-    const newKey = body.proxy_api_key === undefined ? currentKey : (body.proxy_api_key || null);
-
-    const configPath = resolve(getConfigDir(), "default.yaml");
-    mutateYaml(configPath, (data) => {
-      const server = data.server as Record<string, unknown>;
-      server.proxy_api_key = newKey;
-    });
-    reloadAllConfigs();
-
-    return c.json({ success: true, proxy_api_key: newKey });
-  });
+  // Mount admin subroutes
+  app.route("/", createHealthRoutes(accountPool));
+  app.route("/", createUpdateRoutes());
+  app.route("/", createConnectionRoutes(accountPool));
+  app.route("/", createSettingsRoutes());
 
   return app;
 }