@triflux/core 10.0.0-alpha.1

package/hud/hud-qos-status.mjs

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+
+// ============================================================================
+// HUD QoS Status — 메인 오케스트레이터
+// 각 모듈에서 색상, 터미널, 프로바이더, 렌더러를 가져와 조합한다.
+// ============================================================================
+
+import { DIM, RESET, bold, dim, green, claudeOrange, codexWhite, geminiBlue, colorByPercent } from "./colors.mjs";
+import {
+  QOS_PATH, ACCOUNTS_CONFIG_PATH, ACCOUNTS_STATE_PATH,
+  CLAUDE_REFRESH_FLAG, CODEX_REFRESH_FLAG,
+  GEMINI_REFRESH_FLAG, GEMINI_SESSION_REFRESH_FLAG,
+  GEMINI_PRO_POOL, GEMINI_FLASH_POOL,
+} from "./constants.mjs";
+import {
+  readJson, readStdinJson, getContextPercent, getProviderAccountId, getCliArgValue,
+} from "./utils.mjs";
+import { selectTier } from "./terminal.mjs";
+
+// Claude provider
+import {
+  readClaudeUsageSnapshot, scheduleClaudeUsageRefresh, fetchClaudeUsage,
+} from "./providers/claude.mjs";
+
+// Codex provider
+import {
+  getCodexEmail, readCodexRateLimitSnapshot,
+  refreshCodexRateLimitsCache, scheduleCodexRateLimitRefresh,
+} from "./providers/codex.mjs";
+
+// Gemini provider
+import {
+  getGeminiEmail, buildGeminiAuthContext,
+  readGeminiQuotaSnapshot, readGeminiSessionSnapshot,
+  fetchGeminiQuota, refreshGeminiSessionCache,
+  scheduleGeminiQuotaRefresh, scheduleGeminiSessionRefresh,
+} from "./providers/gemini.mjs";
+
+// Renderers
+import {
+  getClaudeRows, getProviderRow, getTeamRow,
+  renderAlignedRows, getMicroLine,
+  readLatestBenchmarkDiff, formatTokenSummary,
+  readTokenSavings, readSvAccumulator,
+} from "./renderers.mjs";
+
+// ============================================================================
+// 메인
+// ============================================================================
+async function main() {
+  // 백그라운드 Claude 사용량 리프레시
+  if (process.argv.includes(CLAUDE_REFRESH_FLAG)) {
+    await fetchClaudeUsage(true);
+    return;
+  }
+
+  if (process.argv.includes(CODEX_REFRESH_FLAG)) {
+    refreshCodexRateLimitsCache();
+    return;
+  }
+
+  if (process.argv.includes(GEMINI_SESSION_REFRESH_FLAG)) {
+    refreshGeminiSessionCache();
+    return;
+  }
+
+  // 백그라운드 Gemini 쿼터 리프레시 전용 실행 모드
+  if (process.argv.includes(GEMINI_REFRESH_FLAG)) {
+    const accountId = getCliArgValue("--account") || "gemini-main";
+    const authContext = buildGeminiAuthContext(accountId);
+    await fetchGeminiQuota(accountId, { authContext, forceRefresh: true });
+    return;
+  }
+
+  // 메인 HUD 경로: 즉시 렌더 우선
+  const stdinPromise = readStdinJson();
+
+  const qosProfile = readJson(QOS_PATH, { providers: {} });
+  const accountsConfig = readJson(ACCOUNTS_CONFIG_PATH, { providers: {} });
+  const accountsState = readJson(ACCOUNTS_STATE_PATH, { providers: {} });
+  const claudeUsageSnapshot = readClaudeUsageSnapshot();
+  if (claudeUsageSnapshot.shouldRefresh) {
+    scheduleClaudeUsageRefresh();
+  }
+  const geminiAccountId = getProviderAccountId("gemini", accountsConfig, accountsState);
+  const codexSnapshot = readCodexRateLimitSnapshot();
+  const geminiSessionSnapshot = readGeminiSessionSnapshot();
+  const geminiAuthContext = buildGeminiAuthContext(geminiAccountId);
+  const geminiQuotaSnapshot = readGeminiQuotaSnapshot(geminiAccountId, geminiAuthContext);
+  if (codexSnapshot.shouldRefresh) {
+    scheduleCodexRateLimitRefresh();
+  }
+  if (geminiSessionSnapshot.shouldRefresh) {
+    scheduleGeminiSessionRefresh();
+  }
+  if (geminiQuotaSnapshot.shouldRefresh) {
+    scheduleGeminiQuotaRefresh(geminiAccountId);
+  }
+
+  // 실측 데이터 추출
+  const stdin = await stdinPromise;
+  const codexEmail = getCodexEmail();
+  const geminiEmail = getGeminiEmail();
+  const codexBuckets = codexSnapshot.buckets;
+  const geminiSession = geminiSessionSnapshot.session;
+  const geminiQuota = geminiQuotaSnapshot.quota;
+
+  // 누적 절약 데이터 읽기
+  const svSavings = readTokenSavings();
+  const svAccumulator = readSvAccumulator();
+  const totalCostSaved = svSavings?.totalSaved || svAccumulator?.totalCostSaved || 0;
+
+  // 세션/누적 토큰 → context 대비 절약 배수 (개별 provider sv%)
+  const ctxCapacity = stdin?.context_window?.context_window_size || 200000;
+  let codexSv = null;
+  if (svAccumulator?.codex?.tokens > 0) {
+    codexSv = svAccumulator.codex.tokens / ctxCapacity;
+  } else if (codexBuckets) {
+    const main = codexBuckets.codex || codexBuckets[Object.keys(codexBuckets)[0]];
+    if (main?.tokens?.total_tokens) codexSv = main.tokens.total_tokens / ctxCapacity;
+  }
+  let geminiSv = null;
+  if (svAccumulator?.gemini?.tokens > 0) {
+    geminiSv = svAccumulator.gemini.tokens / ctxCapacity;
+  } else {
+    const geminiTokens = geminiSession?.total || null;
+    geminiSv = geminiTokens ? geminiTokens / ctxCapacity : null;
+  }
+
+  // Gemini: 3풀 버킷 추출 (Pro/Flash/Lite — 각 풀 내 모델들은 쿼터 공유)
+  const geminiModel = geminiSession?.model || "gemini-3-flash-preview";
+  const geminiBuckets = geminiQuota?.buckets || [];
+  const geminiBucket = geminiBuckets.find((b) => b.modelId === geminiModel)
+    || geminiBuckets.find((b) => b.modelId === "gemini-3-flash-preview")
+    || null;
+  const geminiProBucket = geminiBuckets.find((b) => GEMINI_PRO_POOL.has(b.modelId)) || null;
+  const geminiFlashBucket = geminiBuckets.find((b) => GEMINI_FLASH_POOL.has(b.modelId)) || null;
+  const geminiLiteBucket = geminiBuckets.find((b) => b.modelId?.includes("flash-lite")) || null;
+
+  // 합산 절약: Codex+Gemini sv% 합산 (컨텍스트 대비 위임 토큰 비율)
+  const combinedSvPct = Math.round(((codexSv ?? 0) + (geminiSv ?? 0)) * 100);
+
+  // 인디케이터 인식 tier 선택 (stdin + Claude 사용량 기반)
+  const CURRENT_TIER = selectTier(stdin, claudeUsageSnapshot.data);
+
+  // nano tier: 1줄 모드 (극소 폭 또는 알림 배너 대응)
+  if (CURRENT_TIER === "nano") {
+    const microLine = getMicroLine(stdin, claudeUsageSnapshot.data, codexBuckets,
+      geminiSession, geminiBucket, combinedSvPct);
+    process.stdout.write(`\x1b[0m${microLine}\n`);
+    return;
+  }
+
+  const codexQuotaData = codexBuckets ? { type: "codex", buckets: codexBuckets } : null;
+  const geminiQuotaData = {
+    type: "gemini",
+    quotaBucket: geminiBucket,
+    pools: { pro: geminiProBucket, flash: geminiFlashBucket, lite: geminiLiteBucket },
+    session: geminiSession,
+  };
+
+  const rows = [
+    ...getClaudeRows(CURRENT_TIER, stdin, claudeUsageSnapshot.data, combinedSvPct),
+    getProviderRow(CURRENT_TIER, "codex", "x", codexWhite, qosProfile, accountsConfig, accountsState,
+      codexQuotaData, codexEmail, codexSv, null),
+    getProviderRow(CURRENT_TIER, "gemini", "g", geminiBlue, qosProfile, accountsConfig, accountsState,
+      geminiQuotaData, geminiEmail, geminiSv, null),
+  ];
+
+  // tfx-multi 활성 시 팀 상태 행 추가 (v2.2)
+  const teamRow = getTeamRow(CURRENT_TIER);
+  if (teamRow) rows.push(teamRow);
+
+  // 최근 벤치마크 diff → 토큰 요약 행 추가
+  const latestDiff = readLatestBenchmarkDiff();
+  if (latestDiff) {
+    const summary = formatTokenSummary(latestDiff);
+    if (summary) {
+      rows.push({ prefix: `${dim("$")}:`, left: summary, right: "" });
+    }
+  }
+
+  // 비활성 프로바이더 dim 처리: 데이터 없으면 전체 줄 dim
+  const codexActive = codexBuckets != null;
+  const geminiActive = (geminiSession?.total || 0) > 0 || geminiBucket != null
+    || geminiProBucket != null || geminiFlashBucket != null;
+
+  let outputLines = renderAlignedRows(rows);
+
+  // 비활성 줄 dim 래핑 (rows 순서: [claude, codex, gemini])
+  if (outputLines.length >= 3) {
+    if (!codexActive) outputLines[1] = `${DIM}${outputLines[1]}${RESET}`;
+    if (!geminiActive) outputLines[2] = `${DIM}${outputLines[2]}${RESET}`;
+  }
+
+  // 선행 개행: 알림 배너(노란 글씨)가 빈 첫 줄에 오도록 → HUD 내용 보호
+  const contextPercent = getContextPercent(stdin);
+  const leadingBreaks = contextPercent >= 85 ? "\n\n" : "\n";
+  // 줄별 RESET: Claude Code TUI 스타일 간섭 방지 (색상 밝기 버그 수정)
+  const resetedLines = outputLines.map(line => `\x1b[0m${line}`);
+  process.stdout.write(`${leadingBreaks}${resetedLines.join("\n")}\n`);
+}
+
+main().catch(() => {
+  process.stdout.write(`\x1b[0m${bold(claudeOrange("c"))}: ${dim("5h:")}${green("0%")} ${dim("(n/a)")} ${dim("1w:")}${green("0%")} ${dim("(n/a)")} ${dim("|")} ${dim("ctx:")}${green("0%")}\n`);
+});

package/hud/providers/claude.mjs

@@ -0,0 +1,309 @@
+// ============================================================================
+// Claude Usage API (api.anthropic.com/api/oauth/usage)
+// ============================================================================
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import https from "node:https";
+import { spawn } from "node:child_process";
+import {
+  CLAUDE_CREDENTIALS_PATH, CLAUDE_USAGE_CACHE_PATH, OMC_PLUGIN_USAGE_CACHE_PATH,
+  CLAUDE_USAGE_STALE_MS_SOLO, CLAUDE_USAGE_STALE_MS_WITH_OMC,
+  CLAUDE_USAGE_429_BACKOFF_MS, CLAUDE_USAGE_ERROR_BACKOFF_MS,
+  CLAUDE_API_TIMEOUT_MS, FIVE_HOUR_MS, SEVEN_DAY_MS,
+  DEFAULT_OAUTH_CLIENT_ID, CLAUDE_REFRESH_FLAG,
+} from "../constants.mjs";
+import { readJson, writeJsonSafe, clampPercent, advanceToNextCycle } from "../utils.mjs";
+
+// OMC 활성 여부에 따라 캐시 TTL 동적 결정
+function getClaudeUsageStaleMs() {
+  return existsSync(OMC_PLUGIN_USAGE_CACHE_PATH)
+    ? CLAUDE_USAGE_STALE_MS_WITH_OMC
+    : CLAUDE_USAGE_STALE_MS_SOLO;
+}
+
+export function readClaudeCredentials() {
+  const data = readJson(CLAUDE_CREDENTIALS_PATH, null);
+  if (!data) return null;
+  const creds = data.claudeAiOauth || data;
+  if (!creds.accessToken) return null;
+  return {
+    accessToken: creds.accessToken,
+    refreshToken: creds.refreshToken,
+    expiresAt: creds.expiresAt,
+  };
+}
+
+export function refreshClaudeAccessToken(refreshToken) {
+  return new Promise((resolve) => {
+    const clientId = process.env.CLAUDE_CODE_OAUTH_CLIENT_ID || DEFAULT_OAUTH_CLIENT_ID;
+    const body = new URLSearchParams({
+      grant_type: "refresh_token",
+      refresh_token: refreshToken,
+      client_id: clientId,
+    }).toString();
+    const req = https.request({
+      hostname: "platform.claude.com",
+      path: "/v1/oauth/token",
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        "Content-Length": Buffer.byteLength(body),
+      },
+      timeout: CLAUDE_API_TIMEOUT_MS,
+    }, (res) => {
+      let data = "";
+      res.on("data", (chunk) => { data += chunk; });
+      res.on("end", () => {
+        if (res.statusCode === 200) {
+          try {
+            const parsed = JSON.parse(data);
+            if (parsed.access_token) {
+              resolve({
+                accessToken: parsed.access_token,
+                refreshToken: parsed.refresh_token || refreshToken,
+                expiresAt: parsed.expires_in
+                  ? Date.now() + parsed.expires_in * 1000
+                  : parsed.expires_at,
+              });
+              return;
+            }
+          } catch { /* parse 실패 */ }
+        }
+        resolve(null);
+      });
+    });
+    req.on("error", () => resolve(null));
+    req.on("timeout", () => { req.destroy(); resolve(null); });
+    req.end(body);
+  });
+}
+
+export function writeBackClaudeCredentials(creds) {
+  try {
+    const data = readJson(CLAUDE_CREDENTIALS_PATH, null);
+    if (!data) return;
+    const target = data.claudeAiOauth || data;
+    target.accessToken = creds.accessToken;
+    if (creds.expiresAt != null) target.expiresAt = creds.expiresAt;
+    if (creds.refreshToken) target.refreshToken = creds.refreshToken;
+    writeFileSync(CLAUDE_CREDENTIALS_PATH, JSON.stringify(data, null, 2));
+  } catch { /* 쓰기 실패 무시 */ }
+}
+
+export function fetchClaudeUsageFromApi(accessToken) {
+  return new Promise((resolve) => {
+    const req = https.request({
+      hostname: "api.anthropic.com",
+      path: "/api/oauth/usage",
+      method: "GET",
+      headers: {
+        "Authorization": `Bearer ${accessToken}`,
+        "anthropic-beta": "oauth-2025-04-20",
+        "Content-Type": "application/json",
+      },
+      timeout: CLAUDE_API_TIMEOUT_MS,
+    }, (res) => {
+      let data = "";
+      res.on("data", (chunk) => { data += chunk; });
+      res.on("end", () => {
+        if (res.statusCode === 200) {
+          try { resolve({ ok: true, data: JSON.parse(data) }); } catch { resolve({ ok: false, status: 0 }); }
+        } else {
+          resolve({ ok: false, status: res.statusCode });
+        }
+      });
+    });
+    req.on("error", () => resolve({ ok: false, status: 0, error: "network" }));
+    req.on("timeout", () => { req.destroy(); resolve({ ok: false, status: 0, error: "timeout" }); });
+    req.end();
+  });
+}
+
+export function parseClaudeUsageResponse(response) {
+  if (!response || typeof response !== "object") return null;
+  // five_hour/seven_day 키 자체가 없으면 비정상 응답
+  if (!response.five_hour && !response.seven_day) return null;
+  const fiveHour = response.five_hour?.utilization;
+  const sevenDay = response.seven_day?.utilization;
+  // utilization이 null이면 0%로 처리 (API 200 성공 시 null = 사용량 없음)
+  return {
+    fiveHourPercent: clampPercent(fiveHour ?? 0),
+    weeklyPercent: clampPercent(sevenDay ?? 0),
+    fiveHourResetsAt: response.five_hour?.resets_at || null,
+    weeklyResetsAt: response.seven_day?.resets_at || null,
+  };
+}
+
+// stale 캐시의 과거 resetsAt → 다음 주기로 순환 추정 (null 대신 다음 reset 시간 계산)
+export function stripStaleResets(data) {
+  if (!data) return data;
+  const copy = { ...data };
+  if (copy.fiveHourResetsAt) {
+    const t = new Date(copy.fiveHourResetsAt).getTime();
+    if (!isNaN(t)) copy.fiveHourResetsAt = new Date(advanceToNextCycle(t, FIVE_HOUR_MS)).toISOString();
+  }
+  if (copy.weeklyResetsAt) {
+    const t = new Date(copy.weeklyResetsAt).getTime();
+    if (!isNaN(t)) copy.weeklyResetsAt = new Date(advanceToNextCycle(t, SEVEN_DAY_MS)).toISOString();
+  }
+  return copy;
+}
+
+export function readClaudeUsageSnapshot() {
+  const cache = readJson(CLAUDE_USAGE_CACHE_PATH, null);
+  const ts = Number(cache?.timestamp);
+  const ageMs = Number.isFinite(ts) ? Date.now() - ts : Number.MAX_SAFE_INTEGER;
+
+  // 1차: 자체 캐시에 유효 데이터가 있는 경우
+  if (cache?.data) {
+    // 에러 상태에서 보존된 stale 데이터 → backoff 존중하되 표시용 데이터 반환
+    if (cache.error) {
+      const backoffMs = cache.errorType === "rate_limit"
+        ? CLAUDE_USAGE_429_BACKOFF_MS
+        : CLAUDE_USAGE_ERROR_BACKOFF_MS;
+      return { data: stripStaleResets(cache.data), shouldRefresh: ageMs >= backoffMs };
+    }
+    const isFresh = ageMs < getClaudeUsageStaleMs();
+    // resets_at이 지난 윈도우의 percent를 0으로 보정 (stale 캐시 방지)
+    const data = { ...cache.data };
+    const now = Date.now();
+    if (data.fiveHourResetsAt && new Date(data.fiveHourResetsAt).getTime() <= now) {
+      data.fiveHourPercent = 0;
+    }
+    if (data.weeklyResetsAt && new Date(data.weeklyResetsAt).getTime() <= now) {
+      data.weeklyPercent = 0;
+    }
+    return { data, shouldRefresh: !isFresh };
+  }
+
+  // 2차: 에러 backoff — 최근 에러 시 재시도 억제 (무한 spawn 방지)
+  if (cache?.error && Number.isFinite(ts)) {
+    const backoffMs = cache.errorType === "rate_limit"
+      ? CLAUDE_USAGE_429_BACKOFF_MS
+      : CLAUDE_USAGE_ERROR_BACKOFF_MS;
+    if (ageMs < backoffMs) {
+      const omcCache = readJson(OMC_PLUGIN_USAGE_CACHE_PATH, null);
+      // OMC 캐시가 에러 이후 갱신되었으면 → 에러 캐시 덮어쓰고 그 데이터 사용
+      if (omcCache?.data?.fiveHourPercent != null && omcCache.timestamp > ts) {
+        writeClaudeUsageCache(omcCache.data);
+        return { data: omcCache.data, shouldRefresh: false };
+      }
+      // stale OMC fallback 또는 null (--% 플레이스홀더 표시, 가짜 0% 방지)
+      const staleData = omcCache?.data?.fiveHourPercent != null ? stripStaleResets(omcCache.data) : null;
+      return { data: staleData, shouldRefresh: false };
+    }
+  }
+
+  // 3차: OMC 플러그인 캐시 (같은 API 데이터, 중복 호출 방지)
+  const OMC_CACHE_MAX_AGE_MS = 30 * 60 * 1000;
+  const omcCache = readJson(OMC_PLUGIN_USAGE_CACHE_PATH, null);
+  if (omcCache?.data?.fiveHourPercent != null) {
+    const omcAge = Number.isFinite(omcCache.timestamp) ? Date.now() - omcCache.timestamp : Number.MAX_SAFE_INTEGER;
+    if (omcAge < OMC_CACHE_MAX_AGE_MS) {
+      writeClaudeUsageCache(omcCache.data);
+      return { data: omcCache.data, shouldRefresh: omcAge > getClaudeUsageStaleMs() };
+    }
+    // stale이어도 data: null보다는 오래된 데이터를 fallback으로 표시
+    return { data: stripStaleResets(omcCache.data), shouldRefresh: true };
+  }
+
+  // 캐시/fallback 모두 없음: null 반환 → --% 플레이스홀더 + 리프레시 시도
+  return { data: null, shouldRefresh: true };
+}
+
+export function writeClaudeUsageCache(data, errorInfo = null) {
+  const entry = {
+    timestamp: Date.now(),
+    data,
+    error: !!errorInfo,
+    errorType: errorInfo?.type || null,   // "rate_limit" | "auth" | "network" | "unknown"
+    errorStatus: errorInfo?.status || null, // HTTP 상태 코드
+  };
+  // 에러 시 기존 유효 데이터 보존 (--% n/a 방지)
+  if (errorInfo && data == null) {
+    const prev = readJson(CLAUDE_USAGE_CACHE_PATH, null);
+    if (prev?.data) {
+      entry.data = prev.data;
+      entry.stale = true;
+    }
+  }
+  writeJsonSafe(CLAUDE_USAGE_CACHE_PATH, entry);
+}
+
+export async function fetchClaudeUsage(forceRefresh = false) {
+  const existingSnapshot = readClaudeUsageSnapshot();
+  if (!forceRefresh && !existingSnapshot.shouldRefresh && existingSnapshot.data) {
+    return existingSnapshot.data;
+  }
+  let creds = readClaudeCredentials();
+  if (!creds) {
+    writeClaudeUsageCache(null, { type: "auth", status: 0 });
+    return existingSnapshot.data || null;
+  }
+
+  // 토큰 만료 시 리프레시
+  if (creds.expiresAt && creds.expiresAt <= Date.now() && creds.refreshToken) {
+    const refreshed = await refreshClaudeAccessToken(creds.refreshToken);
+    if (refreshed) {
+      creds = { ...creds, ...refreshed };
+      writeBackClaudeCredentials(creds);
+    } else {
+      writeClaudeUsageCache(null, { type: "auth", status: 0 });
+      return existingSnapshot.data || null;
+    }
+  }
+
+  const result = await fetchClaudeUsageFromApi(creds.accessToken);
+  if (!result.ok) {
+    // 에러 유형별 분류하여 backoff 차등 적용
+    const errorType = result.status === 429 ? "rate_limit"
+      : result.status === 401 || result.status === 403 ? "auth"
+      : result.error === "timeout" || result.error === "network" ? "network"
+      : "unknown";
+    writeClaudeUsageCache(existingSnapshot.data, { type: errorType, status: result.status });
+    return existingSnapshot.data || null;
+  }
+  const usage = parseClaudeUsageResponse(result.data);
+  writeClaudeUsageCache(usage, usage ? null : { type: "unknown", status: 0 });
+  return usage;
+}
+
+export function scheduleClaudeUsageRefresh() {
+  const scriptPath = process.argv[1];
+  if (!scriptPath) return;
+
+  // OMC 플러그인이 이미 fresh 데이터를 가지고 있으면 HUD 리프레시 불필요 (429 방지)
+  try {
+    const omcCache = readJson(OMC_PLUGIN_USAGE_CACHE_PATH, null);
+    if (omcCache?.data?.fiveHourPercent != null) {
+      const omcAge = Number.isFinite(omcCache.timestamp) ? Date.now() - omcCache.timestamp : Infinity;
+      if (omcAge < getClaudeUsageStaleMs()) {
+        writeClaudeUsageCache(omcCache.data); // HUD 캐시에 복사만
+        return;
+      }
+    }
+  } catch { /* 무시 */ }
+
+  // 스폰 락: 30초 내 이미 스폰했으면 중복 방지 (첫 설치 시 429 방지)
+  const lockPath = join(homedir(), ".claude", "cache", ".claude-refresh-lock");
+  try {
+    if (existsSync(lockPath)) {
+      const lockAge = Date.now() - readJson(lockPath, {}).t;
+      if (lockAge < 30000) return; // 30초 이내 스폰 이력 → 건너뜀
+    }
+    writeJsonSafe(lockPath, { t: Date.now() });
+  } catch { /* 락 실패 무시 — 스폰 진행 */ }
+
+  try {
+    const child = spawn(process.execPath, [scriptPath, CLAUDE_REFRESH_FLAG], {
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true,
+    });
+    child.unref();
+  } catch (spawnErr) {
+    // spawn 실패 시 에러 유형을 캐시에 기록 (HUD에서 원인 힌트 표시 가능)
+    writeClaudeUsageCache(null, { type: "network", status: 0, hint: String(spawnErr?.message || spawnErr) });
+  }
+}

package/hud/providers/codex.mjs

@@ -0,0 +1,151 @@
+// ============================================================================
+// Codex rate limits 추출 / 캐싱
+// ============================================================================
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+import {
+  CODEX_AUTH_PATH, CODEX_QUOTA_CACHE_PATH, CODEX_QUOTA_STALE_MS,
+  CODEX_MIN_BUCKETS, CODEX_REFRESH_FLAG,
+} from "../constants.mjs";
+import { readJson, writeJsonSafe, decodeJwtEmail } from "../utils.mjs";
+
+export function getCodexEmail() {
+  try {
+    const auth = JSON.parse(readFileSync(CODEX_AUTH_PATH, "utf-8"));
+    return decodeJwtEmail(auth?.tokens?.id_token);
+  } catch { return null; }
+}
+
+// resets_at이 지난 윈도우의 used_percent를 0으로 보정
+export function expireStaleCodexBuckets(buckets) {
+  if (!buckets) return buckets;
+  const nowSec = Math.floor(Date.now() / 1000);
+  const result = {};
+  for (const [key, bucket] of Object.entries(buckets)) {
+    if (!bucket) { result[key] = bucket; continue; }
+    let updated = bucket;
+    if (bucket.primary?.resets_at && bucket.primary.resets_at <= nowSec) {
+      updated = { ...updated, primary: { ...updated.primary, used_percent: 0 } };
+    }
+    if (bucket.secondary?.resets_at && bucket.secondary.resets_at <= nowSec) {
+      updated = { ...updated, secondary: { ...updated.secondary, used_percent: 0 } };
+    }
+    result[key] = updated;
+  }
+  return result;
+}
+
+// ============================================================================
+// Codex 세션 JSONL에서 실제 rate limits 추출
+// 한계: rate_limits는 세션별 스냅샷이므로 여러 세션 간 토큰 합산은 불가.
+// 최근 7일간 세션 파일을 스캔해 가장 최신 rate_limits 버킷을 수집한다.
+// 합성 버킷(token_count 기반)은 2일 이내 데이터만 허용하여 stale 방지.
+// ============================================================================
+export function getCodexRateLimits() {
+  const now = new Date();
+  let syntheticBucket = null; // 최근 token_count에서 합성 (행 활성화 + 토큰 데이터용)
+
+  // 7일간 스캔: 실제 rate_limits 우선, 합성 버킷은 폴백
+  for (let dayOffset = 0; dayOffset <= 6; dayOffset++) {
+    const d = new Date(now.getTime() - dayOffset * 86_400_000);
+    const sessDir = join(
+      homedir(), ".codex", "sessions",
+      String(d.getFullYear()),
+      String(d.getMonth() + 1).padStart(2, "0"),
+      String(d.getDate()).padStart(2, "0"),
+    );
+    if (!existsSync(sessDir)) continue;
+    let files;
+    try { files = readdirSync(sessDir).filter((f) => f.endsWith(".jsonl")).sort().reverse(); }
+    catch { continue; }
+
+    const mergedBuckets = {};
+    for (const file of files) {
+      try {
+        const content = readFileSync(join(sessDir, file), "utf-8");
+        const lines = content.trim().split("\n").reverse();
+        for (const line of lines) {
+          try {
+            const evt = JSON.parse(line);
+            const rl = evt?.payload?.rate_limits;
+            if (rl?.limit_id && !mergedBuckets[rl.limit_id]) {
+              // 실제 rate_limits: limit_id별 최신 이벤트만 기록
+              mergedBuckets[rl.limit_id] = {
+                limitId: rl.limit_id, limitName: rl.limit_name,
+                primary: rl.primary, secondary: rl.secondary,
+                credits: rl.credits,
+                tokens: evt.payload?.info?.total_token_usage,
+                contextWindow: evt.payload?.info?.model_context_window,
+                timestamp: evt.timestamp,
+              };
+            } else if (dayOffset <= 1 && !rl && evt?.payload?.info?.total_token_usage && !syntheticBucket) {
+              // 2일 이내 token_count: 합성 버킷 (rate_limits가 null일 때 행 활성화용, stale 방지)
+              syntheticBucket = {
+                limitId: "codex", limitName: "codex-session",
+                primary: null, secondary: null,
+                credits: null,
+                tokens: evt.payload.info.total_token_usage,
+                contextWindow: evt.payload.info.model_context_window,
+                timestamp: evt.timestamp,
+              };
+            }
+          } catch { /* 라인 파싱 실패 무시 */ }
+          if (Object.keys(mergedBuckets).length >= CODEX_MIN_BUCKETS) break;
+        }
+      } catch { /* 파일 읽기 실패 무시 */ }
+    }
+    // 실제 rate_limits 발견 → 토큰 데이터 병합 후 즉시 반환
+    if (Object.keys(mergedBuckets).length > 0) {
+      if (syntheticBucket) {
+        const main = mergedBuckets.codex || mergedBuckets[Object.keys(mergedBuckets)[0]];
+        if (main && !main.tokens) main.tokens = syntheticBucket.tokens;
+      }
+      expireStaleCodexBuckets(mergedBuckets);
+      return mergedBuckets;
+    }
+  }
+  // 실제 rate_limits 없음 → 합성 버킷이라도 반환 (행 활성화)
+  return syntheticBucket ? { codex: syntheticBucket } : null;
+}
+
+export function readCodexRateLimitSnapshot() {
+  const cache = readJson(CODEX_QUOTA_CACHE_PATH, null);
+  if (!cache?.buckets) {
+    return { buckets: null, shouldRefresh: true };
+  }
+  expireStaleCodexBuckets(cache.buckets);
+  const ts = Number(cache.timestamp);
+  const ageMs = Number.isFinite(ts) ? Date.now() - ts : Number.MAX_SAFE_INTEGER;
+  const isFresh = ageMs < CODEX_QUOTA_STALE_MS;
+  return { buckets: cache.buckets, shouldRefresh: !isFresh };
+}
+
+export function refreshCodexRateLimitsCache() {
+  const buckets = getCodexRateLimits();
+  // buckets가 null이어도 캐시 갱신 (stale 데이터 제거)
+  writeJsonSafe(CODEX_QUOTA_CACHE_PATH, { timestamp: Date.now(), buckets });
+  return buckets;
+}
+
+export function scheduleCodexRateLimitRefresh() {
+  const scriptPath = process.argv[1];
+  if (!scriptPath) return;
+  try {
+    const child = spawn(process.execPath, [scriptPath, CODEX_REFRESH_FLAG], {
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true,
+    });
+    child.unref();
+  } catch (spawnErr) {
+    // spawn 실패 시 캐시에 에러 힌트 기록
+    writeJsonSafe(CODEX_QUOTA_CACHE_PATH, {
+      timestamp: Date.now(),
+      buckets: null,
+      error: true,
+      errorHint: String(spawnErr?.message || spawnErr),
+    });
+  }
+}