@cartanova/qgrid-cli 2.7.9 → 2.9.0

package/bundle/src/application/token/token.model.test.ts

@@ -1,4 +1,7 @@
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { randomUUID } from "node:crypto";
+
+import { Sonamu } from "sonamu";
+import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
 
 import { TokenModel } from "./token.model";
 
@@ -122,6 +125,7 @@ describe("TokenModel.replaceByAccount", () => {
         id: 1,
         created_at: new Date(),
         active: true,
+        reauth_required: false,
         ord: 0,
         quota_threshold: 80,
         weight: 1,
@@ -177,51 +181,122 @@ describe("TokenModel.findActiveByProviderAndName", () => {
   });
 });
 
-describe("TokenModel.deactivateIfActive", () => {
+describe("TokenModel.findReauthRequired", () => {
   afterEach(() => {
     vi.restoreAllMocks();
   });
 
-  function mockKnex(responses: unknown[]) {
-    const raw = vi.fn();
-    for (const response of responses) raw.mockResolvedValueOnce(response);
-    vi.spyOn(TokenModel as unknown as { getPuri: (mode: "w") => unknown }, "getPuri").mockReturnValue(
-      { knex: { raw } } as unknown as MockPuri,
-    );
-    return raw;
-  }
+  it("queries auth-dead tokens instead of every inactive token", async () => {
+    const where = vi.fn();
+    const orderBy = vi.fn();
+    const qb = { where, orderBy };
+    vi.spyOn(
+      TokenModel as unknown as { getSubsetQueries: (subset: "A") => { qb: typeof qb } },
+      "getSubsetQueries",
+    ).mockReturnValue({ qb });
+    vi.spyOn(
+      TokenModel as unknown as {
+        executeSubsetQuery: (input: unknown) => Promise<{ rows: unknown[] }>;
+      },
+      "executeSubsetQuery",
+    ).mockResolvedValue({ rows: [] });
 
-  it("deactivates in one statement that carries the last-token guard", async () => {
-    const raw = mockKnex([{ rowCount: 1 }]);
+    await TokenModel.findReauthRequired("A");
 
-    await expect(TokenModel.deactivateIfActive(7)).resolves.toEqual({
-      deactivated: true,
-      keptAsLastActive: false,
-    });
-    expect(raw).toHaveBeenCalledTimes(1);
-    const sql = raw.mock.calls[0]![0] as string;
-    expect(sql).toContain("UPDATE tokens SET active = false");
-    expect(sql).toContain("count(*)");
+    expect(where).toHaveBeenCalledWith("tokens.reauth_required", true);
+    expect(where).not.toHaveBeenCalledWith("tokens.active", false);
   });
+});
 
-  it("returns false without a diagnostic read when the token is already inactive", async () => {
-    const raw = mockKnex([{ rowCount: 0 }, { rows: [] }]);
-
-    await expect(TokenModel.deactivateIfActive(7)).resolves.toEqual({
-      deactivated: false,
-      keptAsLastActive: false,
-    });
-    expect(raw).toHaveBeenCalledTimes(2);
+describe("TokenModel.markReauthRequired", () => {
+  beforeAll(async () => {
+    await Sonamu.initForTesting();
   });
 
-  it("refuses to deactivate the provider's last active token", async () => {
-    const raw = mockKnex([{ rowCount: 0 }, { rows: [{ provider: "anthropic" }] }]);
-
-    // 마지막 활성 토큰은 살려두되, 호출부가 systemic 실패로 알릴 수 있게 구분해 알린다.
-    await expect(TokenModel.deactivateIfActive(7)).resolves.toEqual({
-      deactivated: false,
-      keptAsLastActive: true,
-    });
-    expect(raw).toHaveBeenCalledTimes(2);
+  it("serializes provider deaths, preserves one active token, and rejects stale credentials", async () => {
+    const suffix = randomUUID();
+    const tokens = [
+      {
+        ...baseToken,
+        name: `auth-state-a-${suffix}`,
+        credentials: { ...baseToken.credentials, accountUuid: `account-a-${suffix}` },
+      },
+      {
+        ...baseToken,
+        name: `auth-state-b-${suffix}`,
+        credentials: { ...baseToken.credentials, accountUuid: `account-b-${suffix}` },
+      },
+    ];
+    const ids = await TokenModel.save(tokens);
+
+    try {
+      await expect(
+        TokenModel.markReauthRequired(ids[0]!, {
+          ...tokens[0]!.credentials,
+          accessToken: "stale-access-token",
+        }),
+      ).resolves.toEqual({
+        marked: false,
+        keptAsLastActive: false,
+        staleCredentials: true,
+      });
+
+      const results = await Promise.all([
+        TokenModel.markReauthRequired(ids[0]!, tokens[0]!.credentials),
+        TokenModel.markReauthRequired(ids[1]!, tokens[1]!.credentials),
+      ]);
+      expect(results.every((result) => result.marked)).toBe(true);
+
+      const { rows } = await TokenModel.findMany("A", { id: ids, num: 2 });
+      expect(rows.every((row) => row.reauth_required)).toBe(true);
+      expect(rows.filter((row) => row.active)).toHaveLength(1);
+
+      await expect(
+        TokenModel.markReauthRequired(ids[0]!, tokens[0]!.credentials),
+      ).resolves.toEqual({
+        marked: false,
+        keptAsLastActive: false,
+        staleCredentials: false,
+      });
+
+      const inactive = rows.find((row) => !row.active)!;
+      const refreshedCredentials = {
+        ...inactive.credentials,
+        accessToken: "refreshed-access-token",
+        refreshToken: "refreshed-refresh-token",
+      };
+      await TokenModel.save([
+        {
+          id: inactive.id,
+          provider: inactive.provider,
+          credentials: refreshedCredentials,
+          name: inactive.name,
+          reauth_required: false,
+        },
+      ]);
+      await expect(
+        TokenModel.markReauthRequired(inactive.id, inactive.credentials),
+      ).resolves.toEqual({
+        marked: false,
+        keptAsLastActive: false,
+        staleCredentials: true,
+      });
+
+      await expect(TokenModel.toggleActive(inactive.id)).resolves.toEqual({
+        active: true,
+        reauthRequired: false,
+      });
+      await TokenModel.toggleActive(inactive.id);
+      await Promise.all([
+        TokenModel.toggleActive(inactive.id),
+        TokenModel.markReauthRequired(inactive.id, refreshedCredentials),
+      ]);
+      await expect(TokenModel.findById("A", inactive.id)).resolves.toMatchObject({
+        active: false,
+        reauth_required: true,
+      });
+    } finally {
+      await TokenModel.del(ids);
+    }
   });
 });

package/bundle/src/application/token/token.model.ts

@@ -1,3 +1,5 @@
+import { isDeepStrictEqual } from "node:util";
+
 import { getLogger } from "@logtape/logtape";
 import {
   api,
@@ -12,12 +14,13 @@ import {
 import { SD } from "../../i18n/sd.generated";
 import { type TokenSubsetKey, type TokenSubsetMapping } from "../sonamu.generated";
 import { tokenLoaderQueries, tokenSubsetQueries } from "../sonamu.generated.sso";
-import { type TokenListParams, type TokenSaveParams } from "./token.types";
+import { type TokenCredentials, type TokenListParams, type TokenSaveParams } from "./token.types";
 
 const logger = getLogger(["qgrid", "token"]);
 
 const DEFAULT_QUOTA_THRESHOLD = 80;
 const DEFAULT_WEIGHT = 1;
+const TOKEN_AUTH_DEATH_LOCK_CLASS_ID = 719;
 
 export type TokenUpdateFields = {
   name?: string;
@@ -167,13 +170,10 @@ class TokenModelClass extends BaseModelClass<
     return result.rows[0];
   }
 
-  /**
-   * 라우팅에서 빠진 토큰들. 세션 만료로 자동 비활성화된 것과 수동으로 끈 것이 섞여 있다 —
-   * 둘 다 "재로그인하면 살아나는" 상태라 알림 대상으로는 같게 본다.
-   */
-  async findInactive<T extends TokenSubsetKey>(subset: T): Promise<TokenSubsetMapping[T][]> {
+  /** 실제 인증 만료가 확인돼 재로그인이 필요한 토큰들. 수동 비활성화는 제외한다. */
+  async findReauthRequired<T extends TokenSubsetKey>(subset: T): Promise<TokenSubsetMapping[T][]> {
     const { qb } = this.getSubsetQueries(subset);
-    qb.where("tokens.active", false);
+    qb.where("tokens.reauth_required", true);
     qb.orderBy("tokens.name", "asc");
     const enhancers = this.createEnhancers({ A: (row) => ({ ...row }) });
     const result = await this.executeSubsetQuery({
@@ -200,7 +200,6 @@ class TokenModelClass extends BaseModelClass<
     return result.rows;
   }
 
-  @api({ httpMethod: "POST", clients: ["axios", "tanstack-mutation"] })
   async save(spa: TokenSaveParams[]): Promise<number[]> {
     const wdb = this.getPuri("w");
     spa.forEach((sp) => {
@@ -216,15 +215,26 @@ class TokenModelClass extends BaseModelClass<
     return wdb.transaction((trx) => trx.table("tokens").where("id", id).update(fields));
   }
 
-  /**
-   * 세션 만료 토큰을 라우팅에서 제외한다. `active=true` 조건부 갱신이므로 공유 DB 를 쓰는
-   * 여러 인스턴스가 동시에 같은 만료를 감지해도 true 를 받는 프로세스는 하나뿐이다
-   * (호출부의 알림 발송 게이트).
-   *
-   * 단, 대상이 해당 provider 의 마지막 활성 토큰이면 갱신하지 않고 false 를 반환한다.
-   * client_id 취소나 OAuth 계약 변경처럼 전 토큰이 동시에 실패하는 상황에서 풀이
-   * 통째로 비는 것을 막는 안전판이다.
-   */
+  async toggleActive(id: number): Promise<{ active: boolean; reauthRequired: boolean } | null> {
+    const wdb = this.getPuri("w");
+    return wdb.transaction(async (trx) => {
+      const token = await trx
+        .from("tokens")
+        .select({ active: "active", reauth_required: "reauth_required" })
+        .where("id", id)
+        .forUpdate()
+        .first();
+      if (!token) return null;
+      if (!token.active && token.reauth_required) {
+        return { active: false, reauthRequired: true };
+      }
+
+      const active = !token.active;
+      await trx.from("tokens").where("id", id).update({ active });
+      return { active, reauthRequired: false };
+    });
+  }
+
   /**
    * 같은 계정의 기존 토큰을 지우고 새로 저장한다(로그인·재로그인 공통 경로).
    *
@@ -257,43 +267,61 @@ class TokenModelClass extends BaseModelClass<
   }
 
   /**
-   * @returns `deactivated` 는 이 호출이 실제로 비활성화를 수행했는지 — 호출부의 알림
-   *   게이트다. `keptAsLastActive` 는 마지막 활성 토큰이라 거부한 경우로, 사망 자체는
-   *   사실이지만 풀을 비우지 않으려고 살려둔 상태다(systemic 실패 신호).
+   * 인증 사망을 한 번만 기록하고, 다른 활성 토큰이 있으면 라우팅에서도 제외한다.
+   * 마지막 활성 토큰은 systemic 장애 안전판 때문에 active 상태를 유지하되 재로그인
+   * 필요 상태는 기록한다. `marked`가 공유 DB 인스턴스들의 알림 발송 게이트다.
    */
-  async deactivateIfActive(
+  async markReauthRequired(
     id: number,
-  ): Promise<{ deactivated: boolean; keptAsLastActive: boolean }> {
+    expectedCredentials: TokenCredentials,
+  ): Promise<{ marked: boolean; keptAsLastActive: boolean; staleCredentials: boolean }> {
     const wdb = this.getPuri("w");
+    return wdb.transaction(async (trx) => {
+      const token = await trx
+        .from("tokens")
+        .select({
+          provider: "provider",
+          credentials: "credentials",
+          reauth_required: "reauth_required",
+        })
+        .where("id", id)
+        .forUpdate()
+        .first();
+      if (!token || token.reauth_required) {
+        return { marked: false, keptAsLastActive: false, staleCredentials: false };
+      }
+      if (!isDeepStrictEqual(token.credentials, expectedCredentials)) {
+        return { marked: false, keptAsLastActive: false, staleCredentials: true };
+      }
 
-    // 활성 여부와 "마지막 남은 토큰인가"를 한 statement 안에서 판정한다. 두 조건을
-    // 따로 읽고 나중에 갱신하면 그 사이에 다른 인스턴스가 같은 provider 의 토큰을
-    // 비활성화해 풀이 통째로 빌 수 있다.
-    const updated = await wdb.knex.raw<{ rowCount: number }>(
-      `UPDATE tokens SET active = false
-       WHERE id = ? AND active = true
-         AND (SELECT count(*) FROM tokens peer
-              WHERE peer.provider = tokens.provider AND peer.active) > 1`,
-      [id],
-    );
-    if ((updated.rowCount ?? 0) > 0) return { deactivated: true, keptAsLastActive: false };
-
-    // 갱신되지 않은 이유는 둘 중 하나다: 이미 비활성이거나(정상 경쟁 결과), 마지막
-    // 활성 토큰이거나. 후자는 systemic 실패 신호라 남겨야 하므로 이때만 한 번 더 읽는다.
-    const survivor = (
-      await wdb.knex.raw<{ rows: { provider: string }[] }>(
-        "SELECT provider FROM tokens WHERE id = ? AND active = true",
+      await trx.knex.raw("SELECT pg_advisory_xact_lock(?, hashtext(?))", [
+        TOKEN_AUTH_DEATH_LOCK_CLASS_ID,
+        token.provider,
+      ]);
+      const updated = await trx.knex.raw<{ rows: { active: boolean }[] }>(
+        `UPDATE tokens
+         SET reauth_required = true,
+             active = CASE
+               WHEN active AND (SELECT count(*) FROM tokens peer
+                 WHERE peer.provider = tokens.provider AND peer.active) > 1
+               THEN false
+               ELSE active
+             END
+         WHERE id = ? AND reauth_required = false
+         RETURNING active`,
         [id],
-      )
-    ).rows[0];
-    if (survivor) {
-      logger.error(
-        `refusing to auto-deactivate token ${id}: last active ${survivor.provider} token — ` +
-          `systemic refresh failure suspected, keeping the pool non-empty`,
       );
-      return { deactivated: false, keptAsLastActive: true };
-    }
-    return { deactivated: false, keptAsLastActive: false };
+      const marked = updated.rows[0];
+      if (!marked) return { marked: false, keptAsLastActive: false, staleCredentials: false };
+
+      if (marked.active) {
+        logger.error(
+          `refusing to auto-deactivate token ${id}: last active provider token — ` +
+            `systemic refresh failure suspected, keeping the pool non-empty`,
+        );
+      }
+      return { marked: true, keptAsLastActive: marked.active, staleCredentials: false };
+    });
   }
 
   @api({ httpMethod: "POST", clients: ["axios", "tanstack-mutation"] })

package/bundle/src/application/token/token.types.ts

@@ -38,6 +38,7 @@ export const TokenSaveParams = TokenBaseSchema.partial({
   id: true,
   created_at: true,
   active: true,
+  reauth_required: true,
   ord: true,
   quota_threshold: true,
   weight: true,

package/bundle/src/i18n/sd.generated.ts

@@ -317,6 +317,7 @@ const entityLabels = {
   "entity.Token.credentials": "인증 정보 (JSONB)",
   "entity.Token.name": "토큰 이름",
   "entity.Token.active": "활성 여부",
+  "entity.Token.reauth_required": "인증 만료로 재로그인이 필요한지 여부",
   "entity.Token.ord": "정렬 순서",
   "entity.Token.quota_threshold": "quota 사용률 임계치(%). null이면 미설정",
   "entity.Token.weight": "가중 라운드로빈 라우팅 가중치 (1..100)",

package/bundle/src/migrations/20260901163614_alter_tokens_add1_alter1.ts

@@ -0,0 +1,15 @@
+import { type Knex } from "knex";
+
+export async function up(knex: Knex): Promise<void> {
+  await knex.schema.alterTable("tokens", (table) => {
+    // add
+    table.boolean("reauth_required").notNullable().defaultTo(knex.raw("false"));
+  });
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.schema.alterTable("tokens", (table) => {
+    // rollback - add
+    table.dropColumns("reauth_required");
+  });
+}

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

@@ -5,6 +5,7 @@ import {
   assertSupportedOneMillionSuffix,
   canonicalAnthropicModel,
   hasOneMillionSuffix,
+  isFableFamilyModel,
   needsCli1mSuffix,
   supports1MContext,
   usesAdaptiveThinking,
@@ -18,6 +19,7 @@ describe("canonicalAnthropicModel", () => {
   it("provider prefix 를 제거한다", () => {
     expect(canonicalAnthropicModel("anthropic/claude-opus-4-8")).toBe("claude-opus-4-8");
     expect(canonicalAnthropicModel("anthropic/claude-fable-5")).toBe("claude-fable-5");
+    expect(canonicalAnthropicModel("anthropic/claude-fable-5-1")).toBe("claude-fable-5-1");
   });
 
   it("[1m] suffix 를 base canonical 에서 제거한다", () => {
@@ -28,6 +30,7 @@ describe("canonicalAnthropicModel", () => {
 
 describe("Anthropic 1M context policy", () => {
   it("지원 모델은 실측 확인된 exact set 만 true", () => {
+    expect(supports1MContext("claude-fable-5-1")).toBe(true);
     expect(supports1MContext("claude-fable-5")).toBe(true);
     expect(supports1MContext("claude-opus-5")).toBe(true);
     expect(supports1MContext("claude-sonnet-5")).toBe(true);
@@ -42,6 +45,7 @@ describe("Anthropic 1M context policy", () => {
   });
 
   it("CLI suffix 필요 모델과 기본 1M 모델을 분리한다", () => {
+    expect(needsCli1mSuffix("claude-fable-5-1")).toBe(false);
     expect(needsCli1mSuffix("claude-fable-5")).toBe(false);
     expect(needsCli1mSuffix("claude-opus-5")).toBe(false);
     expect(needsCli1mSuffix("claude-sonnet-5")).toBe(false);
@@ -65,10 +69,18 @@ describe("Anthropic 1M context policy", () => {
     );
     expect(() => assertSupportedOneMillionSuffix("anthropic/claude-sonnet-4-6[1m]")).not.toThrow();
   });
+
+  it("native 1M 모델의 [1m] suffix 는 허용하되 CLI 에는 suffix 없이 전달한다", () => {
+    expect(() => assertSupportedOneMillionSuffix("anthropic/claude-fable-5-1[1m]")).not.toThrow();
+    expect(supports1MContext("anthropic/claude-fable-5-1[1m]")).toBe(true);
+    expect(needsCli1mSuffix("anthropic/claude-fable-5-1[1m]")).toBe(false);
+  });
 });
 
 describe("Anthropic thinking policy", () => {
-  it("Fable 5 와 Opus 5 는 adaptive thinking 을 보존한다", () => {
+  it("Fable 5/5.1 과 Opus 5 는 adaptive thinking 을 보존한다", () => {
+    expect(usesAdaptiveThinking("claude-fable-5-1")).toBe(true);
+    expect(usesAdaptiveThinking("anthropic/claude-fable-5-1")).toBe(true);
     expect(usesAdaptiveThinking("claude-fable-5")).toBe(true);
     expect(usesAdaptiveThinking("anthropic/claude-fable-5")).toBe(true);
     expect(usesAdaptiveThinking("claude-opus-5")).toBe(true);
@@ -77,3 +89,15 @@ describe("Anthropic thinking policy", () => {
     expect(usesAdaptiveThinking("claude-opus-4-8")).toBe(false);
   });
 });
+
+describe("Anthropic Fable family", () => {
+  it("Fable 5/5.1 만 Fable 계열로 판정하고 prefix/[1m] 은 무시한다", () => {
+    expect(isFableFamilyModel("claude-fable-5-1")).toBe(true);
+    expect(isFableFamilyModel("claude-fable-5")).toBe(true);
+    expect(isFableFamilyModel("anthropic/claude-fable-5-1[1m]")).toBe(true);
+
+    expect(isFableFamilyModel("claude-opus-5")).toBe(false);
+    expect(isFableFamilyModel("claude-sonnet-4-6")).toBe(false);
+    expect(isFableFamilyModel(undefined)).toBe(false);
+  });
+});

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

@@ -45,6 +45,7 @@ export function hasOneMillionSuffix(model?: string): boolean {
 // 1M 지원 여부는 Claude Code 내부의 광범위한 prefix 판정이 아니라 qgrid에서 확인한 exact set 으로
 // 고정한다. opus-4-7 은 실측 전까지 미포함. 새 모델 추가 시 공식 사양과 실제 CLI 동작을 확인한다.
 const ONE_MILLION_CONTEXT_MODELS = new Set([
+  "claude-fable-5-1",
   "claude-fable-5",
   "claude-opus-5",
   "claude-sonnet-5",
@@ -54,10 +55,16 @@ const ONE_MILLION_CONTEXT_MODELS = new Set([
 ]);
 
 const CLI_ONE_MILLION_SUFFIX_MODELS = new Set(["claude-sonnet-4-6", "claude-opus-4-6"]);
-// Fable 5 는 adaptive thinking 이 유일한 모드다. Opus 5 는 disabled 를 high 이하에서 지원하지만,
-// 공식 기본값·권장 동작인 adaptive thinking 을 유지한다. qgrid 기본 effort=low 가 비용/지연 제어를
-// 맡으며, 이 정책은 disabled+xhigh/max 400 오류와 disabled 시 tool/XML 출력 오염도 피한다.
-const ADAPTIVE_THINKING_MODELS = new Set(["claude-fable-5", "claude-opus-5"]);
+// Fable 5/5.1 은 adaptive thinking 이 유일한 모드다(CLI 카탈로그 `rejects_disabled_thinking`). Opus 5 는
+// disabled 를 high 이하에서 지원하지만, 공식 기본값·권장 동작인 adaptive thinking 을 유지한다. qgrid
+// 기본 effort=low 가 비용/지연 제어를 맡으며, 이 정책은 disabled+xhigh/max 400 오류와 disabled 시
+// tool/XML 출력 오염도 피한다.
+const ADAPTIVE_THINKING_MODELS = new Set(["claude-fable-5-1", "claude-fable-5", "claude-opus-5"]);
+
+// Fable 계열: 구독 플랜에서 usage credits 가 필요한 최상위 티어. 구독 usage API 의
+// `seven_day_overage_included` 버킷은 이 계열에만 적용되므로 quota threshold 판정이 참조한다.
+// Mythos 는 Project Glasswing 조직 전용이라 구독 토큰 경로에서 도달할 수 없어 포함하지 않는다.
+const FABLE_FAMILY_MODELS = new Set(["claude-fable-5-1", "claude-fable-5"]);
 
 // 불변 계약: suffix 가 필요한 모델은 반드시 1M 지원 모델의 부분집합이어야 한다. 역방향 불일치(suffix
 // 대상인데 지원 집합엔 없음)면 needsCli1mSuffix=true·supports1MContext=false 가 동시에 나서
@@ -68,6 +75,13 @@ for (const model of CLI_ONE_MILLION_SUFFIX_MODELS) {
     throw new Error(`[invariant] CLI 1M suffix model not in context set: ${model}`);
   }
 }
+// Fable 계열은 공식 사양상 1M 기본 컨텍스트 + adaptive thinking 필수다. 새 Fable 버전을 계열 Set
+// 에만 넣고 나머지를 빠뜨리는 실수를 같은 방식으로 모듈 로드 시점에 잡는다.
+for (const model of FABLE_FAMILY_MODELS) {
+  if (!ONE_MILLION_CONTEXT_MODELS.has(model) || !ADAPTIVE_THINKING_MODELS.has(model)) {
+    throw new Error(`[invariant] Fable family model missing from 1M/adaptive set: ${model}`);
+  }
+}
 
 export function supports1MContext(model?: string): boolean {
   return ONE_MILLION_CONTEXT_MODELS.has(canonicalAnthropicModel(model));
@@ -83,6 +97,11 @@ export function usesAdaptiveThinking(model?: string): boolean {
   return ADAPTIVE_THINKING_MODELS.has(canonicalAnthropicModel(model));
 }
 
+// 구독 usage 의 Fable 전용 7일 버킷을 quota 판정에 포함할지 결정한다.
+export function isFableFamilyModel(model?: string): boolean {
+  return FABLE_FAMILY_MODELS.has(canonicalAnthropicModel(model));
+}
+
 export function assertSupportedOneMillionSuffix(model?: string): void {
   if (!hasOneMillionSuffix(model)) return;
   const canonical = canonicalAnthropicModel(model);

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

@@ -12,12 +12,14 @@ const {
   runClaudeSessionMock,
   refreshTokenMock,
   readAnthropicQuotaUsageMock,
+  invalidateAnthropicQuotaUsageMock,
   loggerInfoMock,
   loggerWarnMock,
 } = vi.hoisted(() => ({
   runClaudeSessionMock: vi.fn(),
   refreshTokenMock: vi.fn(),
   readAnthropicQuotaUsageMock: vi.fn(),
+  invalidateAnthropicQuotaUsageMock: vi.fn(),
   loggerInfoMock: vi.fn(),
   loggerWarnMock: vi.fn(),
 }));
@@ -33,6 +35,7 @@ vi.mock("./claude-session", async (importActual) => {
 
 vi.mock("./anthropic-quota", () => ({
   readAnthropicQuotaUsage: readAnthropicQuotaUsageMock,
+  invalidateAnthropicQuotaUsage: invalidateAnthropicQuotaUsageMock,
 }));
 
 vi.mock("../../../application/qgrid/qgrid.frame", () => ({
@@ -112,6 +115,7 @@ describe("AnthropicDispatcher", () => {
     refreshTokenMock.mockReset();
     refreshTokenMock.mockResolvedValue("sk-ant-oat01-refreshed");
     readAnthropicQuotaUsageMock.mockReset();
+    invalidateAnthropicQuotaUsageMock.mockReset();
     loggerInfoMock.mockReset();
     loggerWarnMock.mockReset();
   });
@@ -211,6 +215,21 @@ describe("AnthropicDispatcher", () => {
     runClaudeSessionMock.mockResolvedValueOnce(sessionResult({ quotaExhausted: true }));
 
     await expect(d.generate(baseReq())).rejects.toThrow(/quota exhausted/);
+    expect(invalidateAnthropicQuotaUsageMock).toHaveBeenCalledWith("sk-ant-oat01-test");
+  });
+
+  it("refresh 후 quota 소진은 선택 전후 access token cache를 모두 무효화한다", async () => {
+    const d = new AnthropicDispatcher();
+    d.onTokenAdded(1, "tok-A", creds(10_000), null, 1);
+    runClaudeSessionMock.mockResolvedValueOnce(sessionResult({ quotaExhausted: true }));
+
+    await expect(d.generate(baseReq())).rejects.toThrow(/quota exhausted/);
+
+    expect(invalidateAnthropicQuotaUsageMock).toHaveBeenNthCalledWith(1, "sk-ant-oat01-test");
+    expect(invalidateAnthropicQuotaUsageMock).toHaveBeenNthCalledWith(
+      2,
+      "sk-ant-oat01-refreshed",
+    );
   });
 
   it("claude 에러 → 에러", async () => {
@@ -306,6 +325,23 @@ describe("AnthropicDispatcher", () => {
     expect((await d.generate(baseReq())).tokenName).toBe("tok-B");
   });
 
+  it("Fable 요청은 Fable 전용 quota가 소진된 토큰을 건너뛴다", async () => {
+    const d = new AnthropicDispatcher();
+    d.onTokenAdded(1, "tok-A", creds(), 80, 1);
+    d.onTokenAdded(2, "tok-B", creds(), 80, 1);
+    readAnthropicQuotaUsageMock
+      .mockResolvedValueOnce(quotaOk(100))
+      .mockResolvedValueOnce(quotaOk(10));
+
+    const result = await d.generate(baseReq({ model: "claude-fable-5" }));
+
+    expect(result.tokenName).toBe("tok-B");
+    expect(readAnthropicQuotaUsageMock).toHaveBeenCalledWith(
+      expect.any(String),
+      "claude-fable-5",
+    );
+  });
+
   it("resets the schedule when a token weight changes", async () => {
     const d = new AnthropicDispatcher();
     d.onTokenAdded(1, "tok-A", creds(), null, 1);

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

@@ -26,7 +26,11 @@ import {
 import { serializeAndValidateDispatchSchema } from "../common/schema-validation";
 import { SmoothWeightedRoundRobin } from "../common/smooth-weighted-round-robin";
 import { assertSupportedOneMillionSuffix, canonicalAnthropicModel } from "./anthropic-constants";
-import { readAnthropicQuotaUsage, type AnthropicQuotaUsageResult } from "./anthropic-quota";
+import {
+  invalidateAnthropicQuotaUsage,
+  readAnthropicQuotaUsage,
+  type AnthropicQuotaUsageResult,
+} from "./anthropic-quota";
 import { makeAnthropicWorkerId, runClaudeSession } from "./claude-session";
 
 const logger = getLogger(["qgrid", "anthropic-dispatcher"]);
@@ -163,7 +167,7 @@ export class AnthropicDispatcher implements ProviderDispatcher {
 
   // 지정 요청은 해당 토큰만 quota 판정하고 weighted 상태를 건드리지 않는다.
   // 미지정 요청만 quota 통과 후보로 smooth weighted round-robin 을 진행한다.
-  private async selectToken(preferredTokenId?: number): Promise<PooledToken | null> {
+  private async selectToken(model: string, preferredTokenId?: number): Promise<PooledToken | null> {
     const preferred =
       preferredTokenId === undefined ? undefined : this.tokenPool.get(preferredTokenId);
     if (preferredTokenId !== undefined && !preferred) {
@@ -172,7 +176,7 @@ export class AnthropicDispatcher implements ProviderDispatcher {
 
     const rows = preferred ? [preferred] : [...this.tokenPool.values()];
     if (rows.length === 0) return null;
-    const { eligible, overThresholdTokens } = await this.filterEligibleTokens(rows);
+    const { eligible, overThresholdTokens } = await this.filterEligibleTokens(rows, model);
     if (eligible.length === 0) {
       logger.warn("quota_threshold gate: all_exceeded", {
         provider: "anthropic",
@@ -193,7 +197,10 @@ export class AnthropicDispatcher implements ProviderDispatcher {
     return this.tokenPool.get(selectedId) ?? null;
   }
 
-  private async filterEligibleTokens(rows: PooledToken[]): Promise<{
+  private async filterEligibleTokens(
+    rows: PooledToken[],
+    model: string,
+  ): Promise<{
     eligible: PooledToken[];
     overThresholdTokens: Array<{ tokenName: string; threshold: number }>;
   }> {
@@ -207,7 +214,7 @@ export class AnthropicDispatcher implements ProviderDispatcher {
     const checks = await Promise.allSettled(
       thresholded.map(async (token) => ({
         token,
-        result: await readAnthropicQuotaUsage(token.credentials.accessToken),
+        result: await readAnthropicQuotaUsage(token.credentials.accessToken, model),
       })),
     );
 
@@ -314,7 +321,7 @@ export class AnthropicDispatcher implements ProviderDispatcher {
     const model = canonicalAnthropicModel(req.model);
     const jsonSchema = serializeAndValidateDispatchSchema(req.outputSchema, "anthropic");
 
-    const token = await this.selectToken(req.preferredTokenId);
+    const token = await this.selectToken(model, req.preferredTokenId);
     if (!token) throw new Error("No anthropic tokens available");
 
     const exec = async (): Promise<GenerateResult> => {
@@ -359,7 +366,13 @@ export class AnthropicDispatcher implements ProviderDispatcher {
         onDelta,
       );
 
-      if (session.quotaExhausted) throw new Error(`quota exhausted (${token.name})`);
+      if (session.quotaExhausted) {
+        invalidateAnthropicQuotaUsage(token.credentials.accessToken);
+        if (accessToken !== token.credentials.accessToken) {
+          invalidateAnthropicQuotaUsage(accessToken);
+        }
+        throw new Error(`quota exhausted (${token.name})`);
+      }
       if (session.isError) {
         // 진단(SON-495): isError 판정 사유(subtype/terminal_reason)를 메시지 앞에 드러낸다.
         // 그동안 detail 이 session.text(완전한 JSON 본문)뿐이라 "schema 위반인지 / max retries 인지 /