@cartanova/qgrid-cli 2.3.5 → 2.3.6

package/bundle/src/sonamu.config.ts

@@ -46,6 +46,12 @@ export default defineConfig({
           database: process.env.QGRID_DB_NAME,
         },
       },
+      test: {
+        connection: {
+          ...connConfig,
+          database: process.env.QGRID_DB_NAME,
+        },
+      },
     },
   },
   api: {
@@ -105,7 +111,7 @@ export default defineConfig({
             return reply.redirect("/?oauth=error&reason=missing_params");
           }
           try {
-            await QgridFrame.handleOAuthCallback(code, state, reply);
+            return QgridFrame.handleOAuthCallback(code, state, reply);
           } catch (e) {
             return reply.redirect(
               `/?oauth=error&reason=${encodeURIComponent((e as Error).message)}`,
@@ -157,6 +163,7 @@ export default defineConfig({
             // CSR fallback (index.html): 1분 캐시
             return CachePresets.shortLived;
         }
+        return CachePresets.noCache;
       },
     },
     cache: {

package/bundle/src/utils/providers/anthropic/anthropic-dispatcher.test.ts

@@ -1,13 +1,28 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
+import { QuotaThresholdExceededError } from "../../../application/qgrid/qgrid.types";
 import { type AnthropicCredentials } from "../../../application/token/token.types";
 import { type GenerateRequest } from "../common/provider-dispatcher";
 import { ANTHROPIC_DEFAULT_MODEL } from "./anthropic-constants";
 import { AnthropicDispatcher } from "./anthropic-dispatcher";
-
-const { runClaudeSessionMock, refreshTokenMock } = vi.hoisted(() => ({
+import { type AnthropicQuotaUsageResult } from "./anthropic-quota";
+
+const {
+  runClaudeSessionMock,
+  refreshTokenMock,
+  readAnthropicQuotaUsageMock,
+  loggerInfoMock,
+  loggerWarnMock,
+} = vi.hoisted(() => ({
   runClaudeSessionMock: vi.fn(),
   refreshTokenMock: vi.fn(),
+  readAnthropicQuotaUsageMock: vi.fn(),
+  loggerInfoMock: vi.fn(),
+  loggerWarnMock: vi.fn(),
+}));
+
+vi.mock("@logtape/logtape", () => ({
+  getLogger: () => ({ info: loggerInfoMock, warn: loggerWarnMock }),
 }));
 
 vi.mock("./claude-session", async (importActual) => {
@@ -15,6 +30,10 @@ vi.mock("./claude-session", async (importActual) => {
   return { ...actual, runClaudeSession: runClaudeSessionMock };
 });
 
+vi.mock("./anthropic-quota", () => ({
+  readAnthropicQuotaUsage: readAnthropicQuotaUsageMock,
+}));
+
 vi.mock("../../../application/qgrid/qgrid.frame", () => ({
   QgridFrame: { refreshToken: refreshTokenMock },
 }));
@@ -56,12 +75,35 @@ function baseReq(overrides: Partial<GenerateRequest> = {}): GenerateRequest {
   };
 }
 
+function quotaOk(utilizationPct: number, cacheAgeMs = 100): AnthropicQuotaUsageResult {
+  return { kind: "ok", utilizationPct, cacheAgeMs };
+}
+
+function quotaFail(reason = "usage lookup failed"): AnthropicQuotaUsageResult {
+  return { kind: "lookup_failed", reason };
+}
+
+function firstRunRequest() {
+  const call = runClaudeSessionMock.mock.calls[0]?.[0];
+  if (call === undefined) throw new Error("runClaudeSession was not called");
+  return call;
+}
+
+function firstRefreshTokenArg() {
+  const call = refreshTokenMock.mock.calls[0]?.[0];
+  if (call === undefined) throw new Error("refreshToken was not called");
+  return call;
+}
+
 describe("AnthropicDispatcher", () => {
   beforeEach(() => {
     runClaudeSessionMock.mockReset();
     runClaudeSessionMock.mockResolvedValue(sessionResult());
     refreshTokenMock.mockReset();
     refreshTokenMock.mockResolvedValue("sk-ant-oat01-refreshed");
+    readAnthropicQuotaUsageMock.mockReset();
+    loggerInfoMock.mockReset();
+    loggerWarnMock.mockReset();
   });
 
   it("토큰 없으면 에러", async () => {
@@ -72,12 +114,14 @@ describe("AnthropicDispatcher", () => {
   it("happy: generate → GenerateResult (threadCoord 조립, systemHash 없음)", async () => {
     const d = new AnthropicDispatcher();
     d.onTokenAdded(1, "tok-A", creds());
+    runClaudeSessionMock.mockResolvedValueOnce(sessionResult({ ttftMs: 42 }));
 
     const result = await d.generate(baseReq());
 
     expect(result.text).toBe("hello");
     expect(result.tokenName).toBe("tok-A");
     expect(result.model).toBe("claude-sonnet-4-6");
+    expect(result.ttftMs).toBe(42);
     expect(result.threadCoord).toEqual({ workerId: 1, threadId: "sess-generated", epoch: 0 });
   });
 
@@ -89,7 +133,7 @@ describe("AnthropicDispatcher", () => {
       baseReq({ coldHistory: [{ type: "message", role: "assistant", content: [] }] }),
     );
 
-    const call = runClaudeSessionMock.mock.calls[0]![0];
+    const call = firstRunRequest();
     expect(call).not.toHaveProperty("resumeSessionId");
     expect(call.coldHistory).toBeDefined();
     expect(call.input).toEqual([{ type: "text", text: "hi", text_elements: [] }]);
@@ -107,7 +151,7 @@ describe("AnthropicDispatcher", () => {
       }),
     );
 
-    const call = runClaudeSessionMock.mock.calls[0]![0];
+    const call = firstRunRequest();
     expect(call).not.toHaveProperty("resumeSessionId");
     expect(call.coldHistory).toBeDefined();
     expect(call.input).toEqual([{ type: "text", text: "hi", text_elements: [] }]);
@@ -118,7 +162,7 @@ describe("AnthropicDispatcher", () => {
     d.onTokenAdded(1, "tok-A", creds());
     await d.generate(baseReq({ outputSchema: { type: "object", properties: {} } }));
 
-    const call = runClaudeSessionMock.mock.calls[0]![0];
+    const call = firstRunRequest();
     expect(call.jsonSchema).toBe(JSON.stringify({ type: "object", properties: {} }));
   });
 
@@ -166,6 +210,130 @@ describe("AnthropicDispatcher", () => {
     names.add(r2.tokenName);
 
     expect(names.size).toBe(2);
+    expect(readAnthropicQuotaUsageMock).not.toHaveBeenCalled();
+  });
+
+  it("threshold 초과 토큰은 후보에서 제외하고 미설정 토큰을 선택한다", async () => {
+    const d = new AnthropicDispatcher();
+    d.onTokenAdded(1, "tok-A", creds(), 80);
+    d.onTokenAdded(2, "tok-B", creds());
+    readAnthropicQuotaUsageMock.mockResolvedValueOnce(quotaOk(85, 1_000));
+
+    const result = await d.generate(baseReq());
+
+    expect(result.tokenName).toBe("tok-B");
+    expect(readAnthropicQuotaUsageMock).toHaveBeenCalledTimes(1);
+    expect(loggerInfoMock).toHaveBeenCalledWith(
+      expect.stringContaining("over_threshold"),
+      expect.objectContaining({
+        tokenId: 1,
+        tokenName: "tok-A",
+        provider: "anthropic",
+        threshold: 80,
+        cachedUtilization: 85,
+        cacheAge: 1_000,
+        reason: "over_threshold",
+      }),
+    );
+  });
+
+  it("threshold 경계는 utilization >= threshold 일 때 제외한다", async () => {
+    const d = new AnthropicDispatcher();
+    d.onTokenAdded(1, "tok-A", creds(), 80);
+    d.onTokenAdded(2, "tok-B", creds(), 80);
+    readAnthropicQuotaUsageMock
+      .mockResolvedValueOnce(quotaOk(80))
+      .mockResolvedValueOnce(quotaOk(79));
+
+    const result = await d.generate(baseReq());
+
+    expect(result.tokenName).toBe("tok-B");
+  });
+
+  it("quota 조회 실패는 fail-open 으로 통과시키고 lookup_fail_open 로그를 남긴다", async () => {
+    const d = new AnthropicDispatcher();
+    d.onTokenAdded(1, "tok-A", creds(), 80);
+    readAnthropicQuotaUsageMock.mockResolvedValueOnce(quotaFail("timeout"));
+
+    const result = await d.generate(baseReq());
+
+    expect(result.tokenName).toBe("tok-A");
+    expect(loggerWarnMock).toHaveBeenCalledWith(
+      expect.stringContaining("lookup_fail_open"),
+      expect.objectContaining({
+        tokenId: 1,
+        tokenName: "tok-A",
+        provider: "anthropic",
+        threshold: 80,
+        reason: "lookup_fail_open",
+      }),
+    );
+  });
+
+  it("utilization 0 은 정상 조회로 보고 fail-open 로그를 남기지 않는다", async () => {
+    const d = new AnthropicDispatcher();
+    d.onTokenAdded(1, "tok-A", creds(), 80);
+    readAnthropicQuotaUsageMock.mockResolvedValueOnce(quotaOk(0));
+
+    const result = await d.generate(baseReq());
+
+    expect(result.tokenName).toBe("tok-A");
+    expect(loggerWarnMock).not.toHaveBeenCalledWith(
+      expect.stringContaining("lookup_fail_open"),
+      expect.anything(),
+    );
+  });
+
+  it("모든 threshold 설정 토큰이 초과되면 typed error 로 실패한다", async () => {
+    const d = new AnthropicDispatcher();
+    d.onTokenAdded(1, "tok-A", creds(), 80);
+    d.onTokenAdded(2, "tok-B", creds(), 90);
+    readAnthropicQuotaUsageMock
+      .mockResolvedValueOnce(quotaOk(85, 100))
+      .mockResolvedValueOnce(quotaOk(95, 200));
+
+    const error = await d.generate(baseReq()).catch((e) => e);
+
+    expect(error).toBeInstanceOf(QuotaThresholdExceededError);
+    expect(error).toMatchObject({ code: "QUOTA_THRESHOLD_EXCEEDED" });
+    expect(error.message).toBe(
+      "All anthropic tokens exceeded quota threshold: tok-A (threshold 80%), tok-B (threshold 90%)",
+    );
+  });
+
+  it("minCount 는 초과 토큰을 제외한 eligible 집합에서 계산한다", async () => {
+    const d = new AnthropicDispatcher();
+    d.onTokenAdded(1, "tok-A", creds(), 80);
+    d.onTokenAdded(2, "tok-B", creds(), 80);
+    d.onTokenAdded(3, "tok-C", creds(), 80);
+
+    readAnthropicQuotaUsageMock
+      .mockResolvedValueOnce(quotaOk(10))
+      .mockResolvedValueOnce(quotaOk(10))
+      .mockResolvedValueOnce(quotaOk(10));
+    await d.generate(baseReq());
+    readAnthropicQuotaUsageMock.mockReset();
+
+    readAnthropicQuotaUsageMock
+      .mockResolvedValueOnce(quotaOk(95))
+      .mockResolvedValueOnce(quotaOk(10))
+      .mockResolvedValueOnce(quotaOk(10));
+
+    const result = await d.generate(baseReq());
+
+    expect(result.tokenName).not.toBe("tok-A");
+    expect(new Set(["tok-B", "tok-C"]).has(result.tokenName)).toBe(true);
+  });
+
+  it("동시 요청은 quota await 이후 charge 선반영으로 서로 다른 eligible 토큰을 고른다", async () => {
+    const d = new AnthropicDispatcher();
+    d.onTokenAdded(1, "tok-A", creds(), 80);
+    d.onTokenAdded(2, "tok-B", creds(), 80);
+    readAnthropicQuotaUsageMock.mockResolvedValue(quotaOk(0));
+
+    const results = await Promise.all([d.generate(baseReq()), d.generate(baseReq())]);
+
+    expect(new Set(results.map((r) => r.tokenName)).size).toBe(2);
   });
 
   it("onTokenRemoved 후 그 토큰 미선택", async () => {
@@ -183,7 +351,7 @@ describe("AnthropicDispatcher", () => {
 
     await d.generate(baseReq());
 
-    const call = runClaudeSessionMock.mock.calls[0]![0];
+    const call = firstRunRequest();
     expect(call.tokenId).toBe(1);
   });
 
@@ -193,7 +361,7 @@ describe("AnthropicDispatcher", () => {
 
     const result = await d.generate(baseReq({ model: "anthropic/claude-opus-4-8" }));
 
-    const call = runClaudeSessionMock.mock.calls[0]![0];
+    const call = firstRunRequest();
     expect(call.model).toBe("claude-opus-4-8");
     expect(result.model).toBe("claude-opus-4-8");
   });
@@ -204,7 +372,7 @@ describe("AnthropicDispatcher", () => {
 
     const result = await d.generate(baseReq({ model: "anthropic/claude-sonnet-4-6[1m]" }));
 
-    const call = runClaudeSessionMock.mock.calls[0]![0];
+    const call = firstRunRequest();
     expect(call.model).toBe("claude-sonnet-4-6");
     expect(result.model).toBe("claude-sonnet-4-6");
   });
@@ -224,7 +392,7 @@ describe("AnthropicDispatcher", () => {
 
     const result = await d.generate(baseReq({ model: undefined }));
 
-    const call = runClaudeSessionMock.mock.calls[0]![0];
+    const call = firstRunRequest();
     expect(call.model).toBe(ANTHROPIC_DEFAULT_MODEL);
     expect(result.model).toBe(ANTHROPIC_DEFAULT_MODEL);
   });
@@ -257,7 +425,7 @@ describe("AnthropicDispatcher", () => {
 
     expect(deltas).toEqual(["부분"]);
     expect(completed).not.toBeNull();
-    expect(runClaudeSessionMock.mock.calls[0]![0].includePartialMessages).toBe(true);
+    expect(firstRunRequest().includePartialMessages).toBe(true);
   });
 
   it("generateStream: Claude server error 는 onError 로 전달하고 complete 하지 않는다", async () => {
@@ -276,7 +444,7 @@ describe("AnthropicDispatcher", () => {
     expect(onDelta).not.toHaveBeenCalled();
     expect(onComplete).not.toHaveBeenCalled();
     expect(onError).toHaveBeenCalledWith(serverError);
-    expect(runClaudeSessionMock.mock.calls[0]![0].includePartialMessages).toBe(true);
+    expect(firstRunRequest().includePartialMessages).toBe(true);
   });
 
   it("refresh: 만료 임박 토큰은 provider 포함해 refreshToken 호출, 새 access token 으로 세션 진행", async () => {
@@ -287,10 +455,10 @@ describe("AnthropicDispatcher", () => {
     await d.generate(baseReq());
 
     expect(refreshTokenMock).toHaveBeenCalledTimes(1);
-    const refreshArg = refreshTokenMock.mock.calls[0]![0];
+    const refreshArg = firstRefreshTokenArg();
     expect(refreshArg.provider).toBe("anthropic");
     expect(refreshArg.id).toBe(1);
-    expect(runClaudeSessionMock.mock.calls[0]![0].token).toBe("sk-ant-oat01-refreshed");
+    expect(firstRunRequest().token).toBe("sk-ant-oat01-refreshed");
   });
 
   it("refresh: 만료 여유 있으면 refresh 안 함, 기존 access token 사용", async () => {
@@ -300,7 +468,7 @@ describe("AnthropicDispatcher", () => {
     await d.generate(baseReq());
 
     expect(refreshTokenMock).not.toHaveBeenCalled();
-    expect(runClaudeSessionMock.mock.calls[0]![0].token).toBe("sk-ant-oat01-test");
+    expect(firstRunRequest().token).toBe("sk-ant-oat01-test");
   });
 
   it("refresh 실패해도 기존 access token 으로 진행 — 요청을 죽이지 않음", async () => {
@@ -311,6 +479,6 @@ describe("AnthropicDispatcher", () => {
     const result = await d.generate(baseReq());
 
     expect(result.text).toBe("hello");
-    expect(runClaudeSessionMock.mock.calls[0]![0].token).toBe("sk-ant-oat01-test");
+    expect(firstRunRequest().token).toBe("sk-ant-oat01-test");
   });
 });

package/bundle/src/utils/providers/anthropic/anthropic-dispatcher.ts

@@ -13,6 +13,7 @@
 
 import { getLogger } from "@logtape/logtape";
 
+import { QuotaThresholdExceededError } from "../../../application/qgrid/qgrid.types";
 import { TokenModel } from "../../../application/token/token.model";
 import { type AnthropicCredentials } from "../../../application/token/token.types";
 import { getExpiresAt, getRefreshToken } from "../common/credentials";
@@ -23,6 +24,7 @@ import {
   type ProviderDispatcher,
 } from "../common/provider-dispatcher";
 import { assertSupportedOneMillionSuffix, canonicalAnthropicModel } from "./anthropic-constants";
+import { readAnthropicQuotaUsage, type AnthropicQuotaUsageResult } from "./anthropic-quota";
 import { makeAnthropicWorkerId, runClaudeSession } from "./claude-session";
 
 const logger = getLogger(["qgrid", "anthropic-dispatcher"]);
@@ -37,6 +39,19 @@ interface PooledToken {
   id: number;
   name: string;
   credentials: AnthropicCredentials;
+  quotaThreshold?: number | null;
+}
+
+function quotaThresholdExceededMessage(
+  provider: string,
+  tokens: Array<{ tokenName: string; threshold: number }>,
+): string {
+  const details = tokens
+    .map((token) => `${token.tokenName} (threshold ${token.threshold}%)`)
+    .join(", ");
+  return details.length > 0
+    ? `All ${provider} tokens exceeded quota threshold: ${details}`
+    : `All ${provider} tokens exceeded quota threshold`;
 }
 
 export class AnthropicDispatcher implements ProviderDispatcher {
@@ -57,6 +72,7 @@ export class AnthropicDispatcher implements ProviderDispatcher {
         id: t.id,
         name: t.name,
         credentials: t.credentials as AnthropicCredentials,
+        quotaThreshold: t.quota_threshold,
       });
       logger.info(`worker spawned: ${t.name}`);
     }
@@ -80,7 +96,12 @@ export class AnthropicDispatcher implements ProviderDispatcher {
   //  - DB 에 없는데 풀에 있는 토큰 → onTokenRemoved
   //  - DB 에 있는 토큰 → 신규면 onTokenAdded, 기존이면 onTokenUpdated
   replaceTokens(
-    rows: Array<{ id: number; name: string; credentials: AnthropicCredentials }>,
+    rows: Array<{
+      id: number;
+      name: string;
+      credentials: AnthropicCredentials;
+      quotaThreshold?: number | null;
+    }>,
   ): void {
     const next = new Set(rows.map((r) => r.id));
     // onTokenRemoved 가 tokenPool 을 delete 하므로 순회 중 수정을 피하려 키를 먼저 스냅샷한다.
@@ -89,18 +110,31 @@ export class AnthropicDispatcher implements ProviderDispatcher {
       if (!next.has(id)) this.onTokenRemoved(id);
     }
     for (const r of rows) {
-      if (this.tokenPool.has(r.id)) this.onTokenUpdated(r.id, r.name, r.credentials);
-      else this.onTokenAdded(r.id, r.name, r.credentials);
+      if (this.tokenPool.has(r.id)) {
+        this.onTokenUpdated(r.id, r.name, r.credentials, r.quotaThreshold);
+      } else {
+        this.onTokenAdded(r.id, r.name, r.credentials, r.quotaThreshold);
+      }
     }
   }
 
   // token events (token-subscriber 가 호출)
-  onTokenAdded(id: number, name: string, credentials: AnthropicCredentials): void {
-    this.tokenPool.set(id, { id, name, credentials });
+  onTokenAdded(
+    id: number,
+    name: string,
+    credentials: AnthropicCredentials,
+    quotaThreshold?: number | null,
+  ): void {
+    this.tokenPool.set(id, { id, name, credentials, quotaThreshold });
   }
 
-  onTokenUpdated(id: number, name: string, credentials: AnthropicCredentials): void {
-    this.tokenPool.set(id, { id, name, credentials });
+  onTokenUpdated(
+    id: number,
+    name: string,
+    credentials: AnthropicCredentials,
+    quotaThreshold?: number | null,
+  ): void {
+    this.tokenPool.set(id, { id, name, credentials, quotaThreshold });
   }
 
   onTokenRemoved(id: number): void {
@@ -113,16 +147,111 @@ export class AnthropicDispatcher implements ProviderDispatcher {
   }
 
   // 요청마다 least-used RR 로 토큰을 고른다(동점이면 rrIndex 로 회전).
-  private selectToken(): PooledToken | null {
+  private async selectToken(): Promise<PooledToken | null> {
     const rows = [...this.tokenPool.values()];
     if (rows.length === 0) return null;
-    const minCount = Math.min(...rows.map((r) => this.countOf(r.id)));
-    const idle = rows.filter((r) => this.countOf(r.id) === minCount);
-    const picked = idle[this.rrIndex % idle.length]!;
+    const { eligible, overThresholdTokens } = await this.filterEligibleTokens(rows);
+    if (eligible.length === 0) {
+      logger.warn("quota_threshold gate: all_exceeded", {
+        provider: "anthropic",
+        tokenCount: rows.length,
+        thresholdedTokenCount: rows.filter((r) => this.hasQuotaThreshold(r)).length,
+        overThresholdTokens,
+        reason: "all_exceeded",
+      });
+      throw new QuotaThresholdExceededError(
+        quotaThresholdExceededMessage("anthropic", overThresholdTokens),
+      );
+    }
+
+    const minCount = Math.min(...eligible.map((r) => this.countOf(r.id)));
+    const idle = eligible.filter((r) => this.countOf(r.id) === minCount);
+    const picked = idle[this.rrIndex % idle.length];
+    if (!picked) return null;
     this.rrIndex++;
     return this.charge(picked);
   }
 
+  private async filterEligibleTokens(rows: PooledToken[]): Promise<{
+    eligible: PooledToken[];
+    overThresholdTokens: Array<{ tokenName: string; threshold: number }>;
+  }> {
+    const thresholded = rows.filter((token) => this.hasQuotaThreshold(token));
+    if (thresholded.length === 0) return { eligible: rows, overThresholdTokens: [] };
+
+    const eligibleIds = new Set(
+      rows.filter((token) => !this.hasQuotaThreshold(token)).map((token) => token.id),
+    );
+    const overThresholdTokens: Array<{ tokenName: string; threshold: number }> = [];
+    const checks = await Promise.allSettled(
+      thresholded.map(async (token) => ({
+        token,
+        result: await readAnthropicQuotaUsage(token.credentials.accessToken),
+      })),
+    );
+
+    checks.forEach((check, index) => {
+      if (check.status === "rejected") {
+        const token = thresholded[index];
+        if (!token) return;
+        this.logQuotaLookupFailOpen(token, String(check.reason));
+        eligibleIds.add(token.id);
+        return;
+      }
+
+      const token = check.value.token;
+      const result = check.value.result;
+      if (result.kind === "lookup_failed") {
+        this.logQuotaLookupFailOpen(token, result.reason);
+        eligibleIds.add(token.id);
+        return;
+      }
+
+      if (result.utilizationPct >= token.quotaThreshold) {
+        this.logQuotaOverThreshold(token, result);
+        overThresholdTokens.push({ tokenName: token.name, threshold: token.quotaThreshold });
+        return;
+      }
+
+      eligibleIds.add(token.id);
+    });
+
+    return { eligible: rows.filter((token) => eligibleIds.has(token.id)), overThresholdTokens };
+  }
+
+  private hasQuotaThreshold(token: PooledToken): token is PooledToken & { quotaThreshold: number } {
+    return token.quotaThreshold !== undefined && token.quotaThreshold !== null;
+  }
+
+  private logQuotaOverThreshold(
+    token: PooledToken & { quotaThreshold: number },
+    result: Extract<AnthropicQuotaUsageResult, { kind: "ok" }>,
+  ): void {
+    logger.info("quota_threshold gate: over_threshold", {
+      tokenId: token.id,
+      tokenName: token.name,
+      provider: "anthropic",
+      threshold: token.quotaThreshold,
+      cachedUtilization: result.utilizationPct,
+      cacheAge: result.cacheAgeMs,
+      reason: "over_threshold",
+    });
+  }
+
+  private logQuotaLookupFailOpen(
+    token: PooledToken & { quotaThreshold: number },
+    reason: string,
+  ): void {
+    logger.warn("quota_threshold gate: lookup_fail_open", {
+      tokenId: token.id,
+      tokenName: token.name,
+      provider: "anthropic",
+      threshold: token.quotaThreshold,
+      reason: "lookup_fail_open",
+      lookupReason: reason,
+    });
+  }
+
   // 선택된 토큰의 사용 카운트를 await 전에 선반영(동시 요청이 다른 토큰을 고르도록).
   private charge(token: PooledToken): PooledToken {
     this.requestCounts.set(token.id, this.countOf(token.id) + 1);
@@ -157,7 +286,7 @@ export class AnthropicDispatcher implements ProviderDispatcher {
     const jsonSchema =
       req.outputSchema !== undefined ? JSON.stringify(req.outputSchema) : undefined;
 
-    const token = this.selectToken();
+    const token = await this.selectToken();
     if (!token) throw new Error("No anthropic tokens available");
 
     const exec = async (): Promise<GenerateResult> => {
@@ -222,6 +351,7 @@ export class AnthropicDispatcher implements ProviderDispatcher {
         tokenName: token.name,
         usage: session.usage,
         durationMs: session.durationMs,
+        ttftMs: session.ttftMs,
         costUsd: session.costUsd,
         model,
         // systemHash 는 상위 issueConvContext 가 채운다(여기선 비운다).

package/bundle/src/utils/providers/anthropic/anthropic-quota.test.ts

@@ -0,0 +1,89 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { readAnthropicQuotaUsage } from "./anthropic-quota";
+
+const { fetchUsageWithMetaMock } = vi.hoisted(() => ({
+  fetchUsageWithMetaMock: vi.fn(),
+}));
+
+vi.mock("../../../application/qgrid/oauth", () => ({
+  fetchUsageWithMeta: fetchUsageWithMetaMock,
+}));
+
+describe("readAnthropicQuotaUsage", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-06-30T12:00:05.000Z"));
+    fetchUsageWithMetaMock.mockReset();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("uses API utilization as 0..100 percent", async () => {
+    fetchUsageWithMetaMock.mockResolvedValueOnce({
+      data: { five_hour: { utilization: 17, resets_at: null } },
+      cachedAt: Date.now() - 1_250,
+    });
+
+    await expect(readAnthropicQuotaUsage("access-token")).resolves.toEqual({
+      kind: "ok",
+      utilizationPct: 17,
+      cacheAgeMs: 1_250,
+    });
+  });
+
+  it("keeps low percent utilization unchanged", async () => {
+    fetchUsageWithMetaMock.mockResolvedValueOnce({
+      data: { five_hour: { utilization: 1, resets_at: null } },
+      cachedAt: Date.now() - 500,
+    });
+
+    await expect(readAnthropicQuotaUsage("access-token")).resolves.toMatchObject({
+      kind: "ok",
+      utilizationPct: 1,
+      cacheAgeMs: 500,
+    });
+  });
+
+  it("treats utilization 0 as a successful lookup", async () => {
+    fetchUsageWithMetaMock.mockResolvedValueOnce({
+      data: { five_hour: { utilization: 0, resets_at: null } },
+      cachedAt: Date.now(),
+    });
+
+    await expect(readAnthropicQuotaUsage("access-token")).resolves.toMatchObject({
+      kind: "ok",
+      utilizationPct: 0,
+    });
+  });
+
+  it("converts API errors and rejected fetches into lookup_failed", async () => {
+    fetchUsageWithMetaMock.mockResolvedValueOnce({
+      data: { error: "rate limit API unavailable" },
+      cachedAt: Date.now(),
+    });
+    await expect(readAnthropicQuotaUsage("access-token")).resolves.toMatchObject({
+      kind: "lookup_failed",
+      reason: "rate limit API unavailable",
+    });
+
+    fetchUsageWithMetaMock.mockRejectedValueOnce(new Error("timeout"));
+    await expect(readAnthropicQuotaUsage("access-token")).resolves.toMatchObject({
+      kind: "lookup_failed",
+      reason: "timeout",
+    });
+  });
+
+  it("treats missing five_hour utilization as lookup_failed", async () => {
+    fetchUsageWithMetaMock.mockResolvedValueOnce({
+      data: { five_hour: { utilization: null, resets_at: null } },
+      cachedAt: Date.now(),
+    });
+
+    await expect(readAnthropicQuotaUsage("access-token")).resolves.toMatchObject({
+      kind: "lookup_failed",
+    });
+  });
+});