@cartanova/qgrid-cli 2.6.1 → 2.6.4

package/bundle/src/application/sonamu.generated.http

@@ -434,7 +434,19 @@ Content-Type: application/json
 ###
 
 GET {{baseUrl}}/api/qgrid/totalCost
-	?tokenName=TOKENNAME
+	?params[num]=24
+	&params[page]=1
+	&params[search]=id
+	&params[keyword]=KEYWORD
+	&params[orderBy]=id-desc
+	&params[queryMode]=both
+	&params[id]=0
+	&params[sonamuFilter]=unknown-custom
+	&params[token_name]=
+	&params[project_name]=
+	&params[model_name]=
+	&params[project_name_is_null]=false
+	&params[project_name_is_not_null]=false
 Content-Type: application/json
 
 ###
@@ -445,6 +457,12 @@ Content-Type: application/json
 
 ###
 
+GET {{baseUrl}}/api/qgrid/modelNames
+	?
+Content-Type: application/json
+
+###
+
 POST {{baseUrl}}/api/qgrid/addToken
 Content-Type: application/json
 

package/bundle/src/application/sonamu.generated.sso.ts

@@ -76,12 +76,28 @@ export const requestLogSubsetQueries = {
       is_image_generation: "request_logs.is_image_generation",
     });
   },
+  C: (qbWrapper: PuriWrapper<DatabaseSchemaExtend>) => {
+    return qbWrapper.from("request_logs").select({
+      id: "request_logs.id",
+      token_name: "request_logs.token_name",
+      model_name: "request_logs.model_name",
+      input_tokens: "request_logs.input_tokens",
+      output_tokens: "request_logs.output_tokens",
+      cache_read_tokens: "request_logs.cache_read_tokens",
+      cache_creation_tokens: "request_logs.cache_creation_tokens",
+      cache_creation_5m_tokens: "request_logs.cache_creation_5m_tokens",
+      cache_creation_1h_tokens: "request_logs.cache_creation_1h_tokens",
+      cost_usd: "request_logs.cost_usd",
+      cost_source: "request_logs.cost_source",
+    });
+  },
 };
 
 // LoaderQuery: RequestLog
 export const requestLogLoaderQueries = {
   A: [],
   P: [],
+  C: [],
 } as const satisfies PuriLoaderQueries<RequestLogSubsetKey>;
 
 // SubsetQuery: RequestLogStep

package/bundle/src/application/sonamu.generated.ts

@@ -53,9 +53,49 @@ const ToolDefinitions = z.array(
 type ToolDefinitions = z.infer<typeof ToolDefinitions>;
 
 // Enums: RequestLog
-export const RequestLogOrderBy = z.enum(["id-desc"]).describe("RequestLogOrderBy");
+export const RequestLogOrderBy = z
+  .enum([
+    "id-desc",
+    "id-asc",
+    "created_at-desc",
+    "created_at-asc",
+    "ttft_ms-desc",
+    "ttft_ms-asc",
+    "duration_ms-desc",
+    "duration_ms-asc",
+    "input_tokens-desc",
+    "input_tokens-asc",
+    "output_tokens-desc",
+    "output_tokens-asc",
+    "cache_read_tokens-desc",
+    "cache_read_tokens-asc",
+    "cache_creation_tokens-desc",
+    "cache_creation_tokens-asc",
+    "cost_usd-desc",
+    "cost_usd-asc",
+  ])
+  .describe("RequestLogOrderBy");
 export type RequestLogOrderBy = z.infer<typeof RequestLogOrderBy>;
-export const RequestLogOrderByLabel = { "id-desc": "ID최신순" };
+export const RequestLogOrderByLabel = {
+  "id-desc": "ID최신순",
+  "id-asc": "ID오래된순",
+  "created_at-desc": "등록일시최신순",
+  "created_at-asc": "등록일시오래된순",
+  "ttft_ms-desc": "TTFT긴순",
+  "ttft_ms-asc": "TTFT짧은순",
+  "duration_ms-desc": "소요시간긴순",
+  "duration_ms-asc": "소요시간짧은순",
+  "input_tokens-desc": "입력토큰많은순",
+  "input_tokens-asc": "입력토큰적은순",
+  "output_tokens-desc": "출력토큰많은순",
+  "output_tokens-asc": "출력토큰적은순",
+  "cache_read_tokens-desc": "캐시읽기많은순",
+  "cache_read_tokens-asc": "캐시읽기적은순",
+  "cache_creation_tokens-desc": "캐시생성많은순",
+  "cache_creation_tokens-asc": "캐시생성적은순",
+  "cost_usd-desc": "비용높은순",
+  "cost_usd-asc": "비용낮은순",
+};
 export const RequestLogSearchField = z
   .enum(["id", "token_name", "user_prompt"])
   .describe("RequestLogSearchField");
@@ -353,11 +393,26 @@ export const RequestLogSubsetP = z.object({
   is_image_generation: z.boolean(),
 });
 export type RequestLogSubsetP = z.infer<typeof RequestLogSubsetP>;
+export const RequestLogSubsetC = z.object({
+  id: z.int(),
+  token_name: z.string().max(100).nullable(),
+  model_name: z.string().max(255).nullable(),
+  input_tokens: z.int(),
+  output_tokens: z.int(),
+  cache_read_tokens: z.int(),
+  cache_creation_tokens: z.int(),
+  cache_creation_5m_tokens: z.int().nullable(),
+  cache_creation_1h_tokens: z.int().nullable(),
+  cost_usd: z.int().nullable(),
+  cost_source: z.string().max(20).nullable(),
+});
+export type RequestLogSubsetC = z.infer<typeof RequestLogSubsetC>;
 export type RequestLogSubsetMapping = {
   A: RequestLogSubsetA;
   P: RequestLogSubsetP;
+  C: RequestLogSubsetC;
 };
-export const RequestLogSubsetKey = z.enum(["A", "P"]);
+export const RequestLogSubsetKey = z.enum(["A", "P", "C"]);
 export type RequestLogSubsetKey = z.infer<typeof RequestLogSubsetKey>;
 
 // Subsets: RequestLogStep

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

@@ -110,3 +110,52 @@ describe("TokenModel.updateFields", () => {
     expect(update).toHaveBeenCalledWith({ weight: 4 });
   });
 });
+
+describe("TokenModel.deactivateIfActive", () => {
+  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("deactivates in one statement that carries the last-token guard", async () => {
+    const raw = mockKnex([{ rowCount: 1 }]);
+
+    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(*)");
+  });
+
+  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);
+  });
+
+  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);
+  });
+});

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

@@ -1,3 +1,4 @@
+import { getLogger } from "@logtape/logtape";
 import {
   api,
   asArray,
@@ -13,6 +14,8 @@ import { type TokenSubsetKey, type TokenSubsetMapping } from "../sonamu.generate
 import { tokenLoaderQueries, tokenSubsetQueries } from "../sonamu.generated.sso";
 import { type TokenListParams, type TokenSaveParams } from "./token.types";
 
+const logger = getLogger(["qgrid", "token"]);
+
 const DEFAULT_QUOTA_THRESHOLD = 80;
 const DEFAULT_WEIGHT = 1;
 
@@ -173,6 +176,78 @@ 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 계약 변경처럼 전 토큰이 동시에 실패하는 상황에서 풀이
+   * 통째로 비는 것을 막는 안전판이다.
+   */
+  /**
+   * 같은 계정의 기존 토큰을 지우고 새로 저장한다(로그인·재로그인 공통 경로).
+   *
+   * provider 응답에 계정 식별자가 없으면 dedup 자체가 불가능하므로 경고만 남기고
+   * 중복 제거 없이 저장한다(죽은 row 가 남는다).
+   */
+  async replaceByAccount(
+    provider: string,
+    accountId: string | undefined,
+    saveParams: TokenSaveParams,
+  ): Promise<void> {
+    if (accountId) {
+      const oldEntries = await this.findByAccountIdentifier("A", provider, accountId);
+      if (oldEntries.length > 0) await this.del(oldEntries.map((o) => o.id));
+    } else {
+      logger.warn(
+        `${provider} login without account identifier: dedup skipped for ${saveParams.name ?? "unnamed"}`,
+      );
+    }
+
+    await this.save([saveParams]);
+  }
+
+  /**
+   * @returns `deactivated` 는 이 호출이 실제로 비활성화를 수행했는지 — 호출부의 알림
+   *   게이트다. `keptAsLastActive` 는 마지막 활성 토큰이라 거부한 경우로, 사망 자체는
+   *   사실이지만 풀을 비우지 않으려고 살려둔 상태다(systemic 실패 신호).
+   */
+  async deactivateIfActive(
+    id: number,
+  ): Promise<{ deactivated: boolean; keptAsLastActive: boolean }> {
+    const wdb = this.getPuri("w");
+
+    // 활성 여부와 "마지막 남은 토큰인가"를 한 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",
+        [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 };
+  }
+
   @api({ httpMethod: "POST", clients: ["axios", "tanstack-mutation"] })
   async reorder(ids: number[]): Promise<{ done: boolean }> {
     const wdb = this.getPuri("w");

package/bundle/src/i18n/en.ts

@@ -47,6 +47,9 @@ export default {
   "error.internalServerError": "Internal server error",
   "error.notFound": "Not found",
   "error.serviceUnavailable": "Service unavailable",
+  "qgrid.dispatcherFailed": (provider: string) => `${provider} dispatcher failed to initialize`,
+  "qgrid.dispatcherStarting": (provider: string) =>
+    `${provider} dispatcher is starting up. Please retry shortly`,
   "error.unauthorized": "Unauthorized",
   notFound: (name: string, id: number) => `${name} ID ${id} not found`,
   "validation.email": "Invalid email format",

package/bundle/src/i18n/ko.ts

@@ -46,6 +46,9 @@ export default {
   "error.internalServerError": "서버 오류가 발생했습니다",
   "error.notFound": "찾을 수 없습니다",
   "error.serviceUnavailable": "서비스를 사용할 수 없습니다",
+  "qgrid.dispatcherFailed": (provider: string) => `${provider} dispatcher 초기화에 실패했습니다`,
+  "qgrid.dispatcherStarting": (provider: string) =>
+    `${provider} dispatcher 기동 중입니다. 잠시 후 다시 시도해주세요`,
   "error.unauthorized": "인증이 필요합니다",
   "error.unknownSearchField": (field: string) => `구현되지 않은 검색 필드 ${field}`,
   notFound: (name: string, id: number) => `존재하지 않는 ${name} ID ${id}`,

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

@@ -240,6 +240,23 @@ const entityLabels = {
   "entity.RequestLog.tool_call_count": "tool call 횟수",
   "entity.RequestLog.is_image_generation": "이미지 생성 turn 여부 (quota 귀속용)",
   "enum.RequestLogOrderBy.id-desc": "ID최신순",
+  "enum.RequestLogOrderBy.id-asc": "ID오래된순",
+  "enum.RequestLogOrderBy.created_at-desc": "등록일시최신순",
+  "enum.RequestLogOrderBy.created_at-asc": "등록일시오래된순",
+  "enum.RequestLogOrderBy.ttft_ms-desc": "TTFT긴순",
+  "enum.RequestLogOrderBy.ttft_ms-asc": "TTFT짧은순",
+  "enum.RequestLogOrderBy.duration_ms-desc": "소요시간긴순",
+  "enum.RequestLogOrderBy.duration_ms-asc": "소요시간짧은순",
+  "enum.RequestLogOrderBy.input_tokens-desc": "입력토큰많은순",
+  "enum.RequestLogOrderBy.input_tokens-asc": "입력토큰적은순",
+  "enum.RequestLogOrderBy.output_tokens-desc": "출력토큰많은순",
+  "enum.RequestLogOrderBy.output_tokens-asc": "출력토큰적은순",
+  "enum.RequestLogOrderBy.cache_read_tokens-desc": "캐시읽기많은순",
+  "enum.RequestLogOrderBy.cache_read_tokens-asc": "캐시읽기적은순",
+  "enum.RequestLogOrderBy.cache_creation_tokens-desc": "캐시생성많은순",
+  "enum.RequestLogOrderBy.cache_creation_tokens-asc": "캐시생성적은순",
+  "enum.RequestLogOrderBy.cost_usd-desc": "비용높은순",
+  "enum.RequestLogOrderBy.cost_usd-asc": "비용낮은순",
   "enum.RequestLogSearchField.id": "ID",
   "enum.RequestLogSearchField.token_name": "토큰이름",
   "enum.RequestLogSearchField.user_prompt": "사용자 프롬프트",

package/bundle/src/migrations/20260807133553_manual__backfill_request_log_cost.ts

@@ -0,0 +1,110 @@
+/**
+ * legacy request_logs 의 비용을 확정값으로 백필한다.
+ *
+ * 배경: `cost_source` 가 없는 row 는 조회할 때마다 앱이 현재 가격표로 재계산해 왔다
+ * (`normalizeLegacyAnthropicRow`). 입력이 고정이라 결과도 항상 같은데, 96만 행 테이블에서
+ * 23.6만 행을 매 요청 앱으로 끌어오는 비용만 남는다. 한 번 계산해 저장하면 총비용 집계가
+ * 단일 SQL SUM 으로 끝난다.
+ *
+ * 계산식은 앱의 `normalizedUsageForCost` + `calculateCostUsd` 를 그대로 옮긴 것이다.
+ * 두 로직이 갈라지면 백필된 값과 신규 저장값의 기준이 달라지므로, 가격표를 바꿀 때는
+ * 이 마이그레이션이 아니라 앱 코드만 바꾸면 된다(이미 확정된 값은 유지되는 것이 계약).
+ *
+ * 되돌리기: down 은 `cost_source='backfilled'` 인 row 의 표식만 제거해 재계산 대상으로
+ * 되돌린다. 원본 `cost_usd` 는 복원되지 않는다 — 되돌릴 수 없는 쓰기다. 덮이는 값은
+ * NULL 이었거나, 음수였거나, 구버전 가격표로 계산된 값이고, 조회 경로는 이들을 그대로
+ * 보여준 적이 없다(항상 현재 가격표로 재계산해 표시). 그래서 화면에 보이던 총액은
+ * 백필 전후로 동일하며, 실질 손실은 없다.
+ */
+import { type Knex } from "knex";
+
+// 마이그레이션 러너는 tsconfig 의 bundler 해석을 쓰지 않는 순수 ESM 로더라 확장자가 필요하다.
+import { calculateCostUsd } from "../utils/providers/common/model-cost.js";
+
+const MICRO_USD = 1_000_000;
+const CHUNK_SIZE = 5_000;
+
+type LegacyRow = {
+  id: number;
+  token_name: string | null;
+  model_name: string | null;
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_tokens: number;
+  cache_creation_tokens: number;
+  cache_creation_5m_tokens: number | null;
+  cache_creation_1h_tokens: number | null;
+  cost_usd: number | null;
+};
+
+function isAnthropicRow(row: LegacyRow): boolean {
+  return (
+    row.token_name?.startsWith("anthropic/") === true ||
+    row.model_name?.startsWith("claude-") === true ||
+    row.model_name?.startsWith("anthropic/claude-") === true
+  );
+}
+
+function backfilledCostMicroUsd(row: LegacyRow): number {
+  if (!row.model_name) return Math.max(row.cost_usd ?? 0, 0);
+
+  // Anthropic 은 input/cache_read/cache_creation 을 상호 배타적으로 보고한다. 과거 저장 경로가
+  // 이를 합치지 않아 input_tokens 가 작게 남은 row 를 복원한다.
+  const splitInput =
+    isAnthropicRow(row) && row.input_tokens < row.cache_read_tokens + row.cache_creation_tokens;
+  const inputTokens = splitInput
+    ? row.input_tokens + row.cache_read_tokens + row.cache_creation_tokens
+    : row.input_tokens;
+
+  const model = row.model_name.includes("/") ? row.model_name.split("/").pop()! : row.model_name;
+  const usd = calculateCostUsd(model, {
+    inputTokens,
+    outputTokens: row.output_tokens,
+    cachedInputTokens: row.cache_read_tokens,
+    cacheCreationInputTokens: row.cache_creation_tokens,
+    ...(row.cache_creation_5m_tokens !== null
+      ? { cacheCreationInputTokens5m: row.cache_creation_5m_tokens }
+      : {}),
+    ...(row.cache_creation_1h_tokens !== null
+      ? { cacheCreationInputTokens1h: row.cache_creation_1h_tokens }
+      : {}),
+  });
+  return Math.max(Math.round(usd * MICRO_USD), 0);
+}
+
+export async function up(knex: Knex): Promise<void> {
+  let lastId = 0;
+  let processed = 0;
+
+  for (;;) {
+    const { rows } = await knex.raw<{ rows: LegacyRow[] }>(
+      `SELECT id, token_name, model_name, input_tokens, output_tokens,
+              cache_read_tokens, cache_creation_tokens,
+              cache_creation_5m_tokens, cache_creation_1h_tokens, cost_usd
+         FROM request_logs
+        WHERE (cost_source IS NULL OR cost_usd IS NULL) AND id > ?
+        ORDER BY id
+        LIMIT ?`,
+      [lastId, CHUNK_SIZE],
+    );
+    if (rows.length === 0) break;
+
+    // chunk 당 한 번의 UPDATE ... FROM (VALUES ...) 로 왕복을 줄인다.
+    const values = rows.map((row) => `(${row.id}, ${backfilledCostMicroUsd(row)})`).join(",");
+    await knex.raw(
+      `UPDATE request_logs AS t
+          SET cost_usd = v.cost_usd, cost_source = 'backfilled'
+         FROM (VALUES ${values}) AS v(id, cost_usd)
+        WHERE t.id = v.id`,
+    );
+
+    lastId = rows[rows.length - 1]!.id;
+    processed += rows.length;
+  }
+
+  console.log(`[backfill] request_logs cost backfilled: ${processed} rows`);
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.raw(`UPDATE request_logs SET cost_source = NULL WHERE cost_source = 'backfilled'`);
+}

package/bundle/src/migrations/20260807145144_alter_request_logs_alter1.ts

@@ -0,0 +1,13 @@
+import { type Knex } from "knex";
+
+export async function up(knex: Knex): Promise<void> {
+  await knex.raw(
+    `CREATE INDEX request_logs_project_name_cost_usd_index ON request_logs USING btree(project_name ASC NULLS LAST, cost_usd ASC NULLS LAST);`,
+  );
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.schema.alterTable("request_logs", (table) => {
+    table.dropIndex(["project_name", "cost_usd"], "request_logs_project_name_cost_usd_index");
+  });
+}

package/bundle/src/migrations/20260807164057_alter_request_logs_alter1.ts

@@ -0,0 +1,13 @@
+import { type Knex } from "knex";
+
+export async function up(knex: Knex): Promise<void> {
+  await knex.raw(
+    `CREATE INDEX request_logs_model_name_index ON request_logs USING btree(model_name ASC NULLS LAST);`,
+  );
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.schema.alterTable("request_logs", (table) => {
+    table.dropIndex(["model_name"], "request_logs_model_name_index");
+  });
+}

package/bundle/src/server-error-handler.test.ts

@@ -0,0 +1,58 @@
+import { type FastifyReply } from "fastify";
+import {
+  BadRequestException,
+  InternalServerErrorException,
+  ServiceUnavailableException,
+} from "sonamu";
+import { describe, expect, it, vi } from "vitest";
+
+import { handleServerError } from "./server-error-handler";
+
+function fakeReply() {
+  const reply = {
+    header: vi.fn(),
+    status: vi.fn(),
+    send: vi.fn(),
+  };
+  reply.status.mockReturnValue(reply);
+  return reply as unknown as FastifyReply & typeof reply;
+}
+
+describe("handleServerError", () => {
+  it("Sonamu 예외의 statusCode 를 그대로 쓴다", () => {
+    const reply = fakeReply();
+
+    handleServerError(new BadRequestException("bad" as never), reply);
+
+    expect(reply.status).toHaveBeenCalledWith(400);
+  });
+
+  it("Sonamu 예외가 아니면 statusCode 를 신뢰하지 않고 500 으로 내린다", () => {
+    const reply = fakeReply();
+    // upstream fetch 오류처럼 statusCode 를 달고 오는 예외 — 그대로 에코하면 upstream 의
+    // 401 이 호출자 자신의 오류로 둔갑한다.
+    const upstream = Object.assign(new Error("upstream said 401"), { statusCode: 401 });
+
+    handleServerError(upstream, reply);
+
+    expect(reply.status).toHaveBeenCalledWith(500);
+  });
+
+  it("503 에는 Retry-After 를 붙여 재시도 시점을 알린다", () => {
+    const reply = fakeReply();
+
+    handleServerError(new ServiceUnavailableException("starting up" as never), reply);
+
+    expect(reply.status).toHaveBeenCalledWith(503);
+    expect(reply.header).toHaveBeenCalledWith("Retry-After", expect.any(String));
+  });
+
+  it("503 이 아닌 응답에는 Retry-After 를 붙이지 않는다", () => {
+    const reply = fakeReply();
+
+    handleServerError(new InternalServerErrorException("dead" as never), reply);
+
+    expect(reply.status).toHaveBeenCalledWith(500);
+    expect(reply.header).not.toHaveBeenCalled();
+  });
+});

package/bundle/src/server-error-handler.ts

@@ -1,20 +1,31 @@
 import { getLogger } from "@logtape/logtape";
 import { type FastifyReply } from "fastify";
-import { isSoException } from "sonamu";
+import { SoException } from "sonamu";
 
-// statusCode 를 신뢰하는 범위를 Sonamu 예외 계약(isSoException)으로 한정한다. qgrid 는 프록시라
-// upstream HTTP 오류(fetch/undici 류)도 statusCode 를 달고 나오는데, 그걸 duck-typing 으로
-// 그대로 에코하면 upstream 의 401/429 가 호출자 자신의 오류로 둔갑한다. Sonamu 예외가 아니면 500.
+// dispatcher 기동은 dev0 기준 1~2분 걸린다(워커 25개 × spawn 간격). 그보다 짧게 잡으면
+// 재시도가 같은 503 을 다시 받는다.
+const RETRY_AFTER_SECONDS = "30";
+
+// statusCode 를 신뢰하는 범위를 Sonamu 예외로 한정한다. qgrid 는 프록시라 upstream HTTP
+// 오류(fetch/undici 류)도 statusCode 를 달고 나오는데, 그걸 그대로 에코하면 upstream 의
+// 401/429 가 호출자 자신의 오류로 둔갑한다. Sonamu 예외가 아니면 500.
+//
+// sonamu 의 isSoException 은 `statusCode !== undefined` 만 보는 duck-typing 이라 바로 그
+// upstream 예외를 통과시킨다. 여기서는 instanceof 로 실제 계약을 확인한다.
 export function handleServerError(error: Error, reply: FastifyReply): void {
   getLogger(["qgrid"]).error(`${error}`);
   const statusCode =
-    isSoException(error) &&
+    error instanceof SoException &&
     Number.isInteger(error.statusCode) &&
     error.statusCode >= 400 &&
     error.statusCode <= 599
       ? error.statusCode
       : 500;
 
+  // 503 은 "지금은 아니지만 곧 된다"는 뜻이라 재시도 시점을 함께 준다. 값이 없으면
+  // 클라이언트는 재시도 간격을 스스로 정해야 하고, 대개 즉시 재시도해 부하만 키운다.
+  if (statusCode === 503) reply.header("Retry-After", RETRY_AFTER_SECONDS);
+
   reply.status(statusCode).send({
     name: error.name,
     message: error.message,

package/bundle/src/sonamu.config.ts

@@ -179,11 +179,15 @@ export default defineConfig({
 
         const started = await subscriber.start();
 
+        // 기동 상태를 남긴다 — HTTP 는 이미 열려 있어서, 준비 전 요청이 "잠시 후 되는지"
+        // "재시도해도 안 되는지"를 구분해 응답해야 한다(503 vs 500).
         try {
           const openaiDispatcher = new OpenAIDispatcher();
           await openaiDispatcher.start();
           QgridDispatcher.openaiDispatcher = openaiDispatcher;
+          QgridDispatcher.startupState.openai = "ready";
         } catch (e) {
+          QgridDispatcher.startupState.openai = "failed";
           log.warn(`openai dispatcher failed: ${(e as Error).message}`);
         }
 
@@ -191,7 +195,9 @@ export default defineConfig({
           const anthropicDispatcher = new AnthropicDispatcher();
           await anthropicDispatcher.start();
           QgridDispatcher.anthropicDispatcher = anthropicDispatcher;
+          QgridDispatcher.startupState.anthropic = "ready";
         } catch (e) {
+          QgridDispatcher.startupState.anthropic = "failed";
           log.warn(`anthropic dispatcher failed: ${(e as Error).message}`);
         }
 

package/bundle/src/utils/providers/openai/openai-refresh.ts

@@ -8,6 +8,7 @@
  */
 import { getLogger } from "@logtape/logtape";
 
+import { deactivateAuthDeadToken } from "../../../application/qgrid/token-death";
 import { TokenModel } from "../../../application/token/token.model";
 import { type OpenAICredentials } from "../../../application/token/token.types";
 
@@ -15,6 +16,13 @@ const logger = getLogger(["qgrid", "openai-refresh"]);
 
 import { OPENAI_CLIENT_ID, OPENAI_TOKEN_URL } from "./openai-constants";
 
+// 재로그인 외 복구 불가한 refresh 실패 코드. 어느 것이든 토큰이 죽었다는 확정 신호다.
+const PERMANENT_FAILURE_CODES = new Set([
+  "refresh_token_expired",
+  "refresh_token_reused",
+  "refresh_token_invalidated",
+]);
+
 // per-token inflight promise dedup + minimum interval
 const inflightRefresh = new Map<number, Promise<RefreshResult>>();
 const lastRefreshTime = new Map<number, number>();
@@ -100,6 +108,15 @@ async function doRefresh(tokenId: number): Promise<RefreshResult> {
       `OpenAI refresh FAILED token=${token.name}(id=${tokenId}) status=${resp.status} ` +
         `code=${errorCode ?? "?"} body=${body}`,
     );
+    // 영구 실패는 errorCode 로만 판정한다 — status 를 함께 요구하면 provider 가
+    // 상태코드를 바꿀 때 판정이 조용히 멎는다.
+    if (errorCode && PERMANENT_FAILURE_CODES.has(errorCode)) {
+      await deactivateAuthDeadToken(
+        { id: tokenId, name: token.name, provider: "openai" },
+        creds.refreshToken,
+        `openai:${errorCode}`,
+      );
+    }
     throw new Error(`OpenAI refresh failed: ${resp.status} ${body}`);
   }