@cartanova/qgrid-cli 2.6.2 → 2.6.4

package/bundle/src/application/qgrid/token-death.test.ts

@@ -38,7 +38,7 @@ describe("deactivateAuthDeadToken", () => {
 
   it("deactivates and notifies when the failed attempt used the current refresh token", async () => {
     findOneMock.mockResolvedValue(storedRefreshToken("rt-current"));
-    deactivateMock.mockResolvedValue(true);
+    deactivateMock.mockResolvedValue({ deactivated: true, keptAsLastActive: false });
 
     await expect(
       deactivateAuthDeadToken(token, "rt-current", "anthropic:400"),
@@ -67,7 +67,7 @@ describe("deactivateAuthDeadToken", () => {
 
   it("does not notify when another process won the deactivation race", async () => {
     findOneMock.mockResolvedValue(storedRefreshToken("rt-current"));
-    deactivateMock.mockResolvedValue(false);
+    deactivateMock.mockResolvedValue({ deactivated: false, keptAsLastActive: false });
 
     await expect(deactivateAuthDeadToken(token, "rt-current", "anthropic:400")).resolves.toBe(
       false,
@@ -76,6 +76,36 @@ describe("deactivateAuthDeadToken", () => {
     expect(notifySlackMock).not.toHaveBeenCalled();
   });
 
+  it("alerts instead of deactivating when the dying token is the last active one", async () => {
+    // 알림 쿨다운이 모듈 수준 상태라 다른 테스트의 발송 기록에 가려질 수 있다.
+    vi.resetModules();
+    const { deactivateAuthDeadToken: freshDeactivate } = await import("./token-death");
+    findOneMock.mockResolvedValue(storedRefreshToken("rt-current"));
+    deactivateMock.mockResolvedValue({ deactivated: false, keptAsLastActive: true });
+
+    await expect(freshDeactivate(token, "rt-current", "anthropic:400")).resolves.toBe(false);
+
+    expect(notifySlackMock).toHaveBeenCalledTimes(1);
+    const notification = notifySlackMock.mock.calls[0]![0] as { title: string; context: string };
+    expect(notification.title).toContain("마지막");
+    expect(notification.context).toContain("anthropic:400");
+  });
+
+  it("suppresses repeat last-active alerts for the same provider within the cooldown", async () => {
+    // 이 경로는 토큰을 비활성화하지 않아 상태 변화가 없다 — 억제가 없으면 요청마다 알림이 간다.
+    // 쿨다운은 모듈 수준 상태라 앞 테스트의 발송 기록이 남는다. 새로 불러 격리한다.
+    vi.resetModules();
+    const { deactivateAuthDeadToken: freshDeactivate } = await import("./token-death");
+    findOneMock.mockResolvedValue(storedRefreshToken("rt-current"));
+    deactivateMock.mockResolvedValue({ deactivated: false, keptAsLastActive: true });
+
+    await freshDeactivate(token, "rt-current", "anthropic:400");
+    await freshDeactivate(token, "rt-current", "anthropic:400");
+    await freshDeactivate(token, "rt-current", "anthropic:401");
+
+    expect(notifySlackMock).toHaveBeenCalledTimes(1);
+  });
+
   it("does nothing when the token no longer exists", async () => {
     findOneMock.mockResolvedValue(undefined);
 
@@ -88,7 +118,7 @@ describe("deactivateAuthDeadToken", () => {
 
   it("never puts the raw provider error body in the notification", async () => {
     findOneMock.mockResolvedValue(storedRefreshToken("rt-current"));
-    deactivateMock.mockResolvedValue(true);
+    deactivateMock.mockResolvedValue({ deactivated: true, keptAsLastActive: false });
 
     await deactivateAuthDeadToken(token, "rt-current", "anthropic:400");
 

package/bundle/src/application/qgrid/token-death.ts

@@ -42,8 +42,11 @@ export async function deactivateAuthDeadToken(
     return false;
   }
 
-  const deactivated = await TokenModel.deactivateIfActive(token.id);
-  if (!deactivated) return false;
+  const { deactivated, keptAsLastActive } = await TokenModel.deactivateIfActive(token.id);
+  if (!deactivated) {
+    if (keptAsLastActive) notifyLastActiveTokenDying(token, reasonCode);
+    return false;
+  }
 
   logger.warn(`token deactivated (auth dead): ${token.name}(id=${token.id}) reason=${reasonCode}`);
   void notifySlack({
@@ -55,7 +58,33 @@ export async function deactivateAuthDeadToken(
   return true;
 }
 
-/** 처음 보는 계정이 등록됐을 때. 재로그인(기존 토큰 교체)은 알리지 않는다. */
+/**
+ * 마지막 활성 토큰이 죽었을 때의 알림 쿨다운.
+ *
+ * 이 경우 토큰은 비활성화되지 않고 살아남으므로, 뒤따르는 요청마다 같은 실패를 반복해
+ * 알림이 폭주한다. 비활성화 성공 경로가 조건부 UPDATE 로 중복을 막는 것과 달리 여기엔
+ * 상태 변화가 없어 DB 로 억제할 수 없다 — provider 단위로 시간 창을 둔다.
+ */
+const LAST_ACTIVE_ALERT_COOLDOWN_MS = 30 * 60 * 1000;
+const lastActiveAlertAt = new Map<string, number>();
+
+function notifyLastActiveTokenDying(token: DeadTokenRef, reasonCode: string): void {
+  const now = Date.now();
+  const previous = lastActiveAlertAt.get(token.provider);
+  if (previous !== undefined && now - previous < LAST_ACTIVE_ALERT_COOLDOWN_MS) return;
+  lastActiveAlertAt.set(token.provider, now);
+
+  void notifySlack({
+    title: "마지막 토큰 사망",
+    subject: token.name,
+    context:
+      `${token.provider} · ${reasonCode} · 풀이 비지 않도록 유지 중입니다. ` +
+      `전 토큰이 동시에 실패했다면 client_id 취소나 OAuth 계약 변경을 의심하세요`,
+    color: SLACK_COLOR.bad,
+  });
+}
+
+/** 로그인이 완료돼 토큰이 저장됐을 때. 신규·재로그인을 가리지 않는다. */
 export function notifyTokenAdded(name: string, provider: string): void {
   logger.info(`token added: ${name} (${provider})`);
   void notifySlack({

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

@@ -86,6 +86,9 @@ export namespace QgridService {
   export const projectNames = (): SSRQuery =>
     createSSRQuery("QgridFrame", "projectNames", [], ["Qgrid", "projectNames"]);
 
+  export const modelNames = (): SSRQuery =>
+    createSSRQuery("QgridFrame", "modelNames", [], ["Qgrid", "modelNames"]);
+
   export const usage = (tokenId?: number): SSRQuery =>
     createSSRQuery("QgridFrame", "usage", [tokenId], ["Qgrid", "usage"]);
 

package/bundle/src/application/request-log/request-log.entity.json

@@ -133,6 +133,12 @@
       "name": "request_logs_project_name_cost_usd_index",
       "columns": [{ "name": "project_name" }, { "name": "cost_usd" }],
       "using": "btree"
+    },
+    {
+      "type": "index",
+      "name": "request_logs_model_name_index",
+      "columns": [{ "name": "model_name" }],
+      "using": "btree"
     }
   ],
   "subsets": {
@@ -207,7 +213,26 @@
     ]
   },
   "enums": {
-    "RequestLogOrderBy": { "id-desc": "ID최신순" },
+    "RequestLogOrderBy": {
+      "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": "비용낮은순"
+    },
     "RequestLogSearchField": {
       "id": "ID",
       "token_name": "토큰이름",

package/bundle/src/application/request-log/request-log.model.ts

@@ -3,7 +3,6 @@ import {
   asArray,
   BadRequestException,
   BaseModelClass,
-  exhaustive,
   type ListResult,
   NotFoundException,
   Puri,
@@ -152,6 +151,43 @@ function normalizeLegacyAnthropicRow<T extends RequestLogUsageRow>(row: T): T {
   return normalized;
 }
 
+/**
+ * `orderBy` enum 값(`컬럼-방향`)을 정렬 절로 옮긴다.
+ *
+ * enum 이 18 종이라 케이스를 일일이 적는 대신 파싱하되, 컬럼은 아래 목록으로 한정한다 —
+ * 문자열을 그대로 컬럼명에 넘기면 enum 이 바뀔 때 검증 없는 식별자가 SQL 로 흘러든다.
+ * 목록에 없는 값은 기본 정렬(id desc)로 떨어진다.
+ */
+const ORDERABLE_COLUMNS = {
+  id: "request_logs.id",
+  created_at: "request_logs.created_at",
+  ttft_ms: "request_logs.ttft_ms",
+  duration_ms: "request_logs.duration_ms",
+  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",
+  cost_usd: "request_logs.cost_usd",
+} as const;
+
+function applyOrderBy(
+  qb: ReturnType<RequestLogModelClass["getSubsetQueries"]>["qb"],
+  orderBy: string,
+): void {
+  const separator = orderBy.lastIndexOf("-");
+  const key = orderBy.slice(0, separator) as keyof typeof ORDERABLE_COLUMNS;
+  const direction = orderBy.slice(separator + 1) === "asc" ? "asc" : "desc";
+  const column = ORDERABLE_COLUMNS[key];
+
+  if (!column) {
+    qb.orderBy("request_logs.id", "desc");
+    return;
+  }
+  qb.orderBy(column, direction);
+  // 동점 행의 순서가 페이지마다 흔들리지 않게 고유 컬럼으로 tie-break 한다.
+  if (key !== "id") qb.orderBy("request_logs.id", "desc");
+}
+
 /*
   RequestLog Model
 */
@@ -254,15 +290,7 @@ class RequestLogModelClass extends BaseModelClass<
 
     this.applyListFilters(qb, params);
 
-    // orderBy
-    if (params.orderBy) {
-      // default orderBy
-      if (params.orderBy === "id-desc") {
-        qb.orderBy("request_logs.id", "desc");
-      } else {
-        exhaustive(params.orderBy);
-      }
-    }
+    if (params.orderBy) applyOrderBy(qb, params.orderBy);
 
     const enhancers = this.createEnhancers({
       A: (row) => normalizeLegacyAnthropicRow(row),
@@ -705,6 +733,18 @@ class RequestLogModelClass extends BaseModelClass<
     return rows.map((r) => r.project_name!);
   }
 
+  async distinctModelNames(): Promise<string[]> {
+    const rows = await this.getPuri("r")
+      .from("request_logs")
+      .distinct("model_name")
+      .where("model_name", "!=", null)
+      .orderBy("model_name", "asc")
+      .select({
+        model_name: "model_name",
+      });
+    return rows.map((r) => r.model_name!);
+  }
+
   @api({ httpMethod: "POST", clients: ["axios", "tanstack-mutation"] })
   async del(ids: number[]): Promise<number> {
     const wdb = this.getPuri("w");

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

@@ -457,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.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");

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

@@ -128,7 +128,10 @@ describe("TokenModel.deactivateIfActive", () => {
   it("deactivates in one statement that carries the last-token guard", async () => {
     const raw = mockKnex([{ rowCount: 1 }]);
 
-    await expect(TokenModel.deactivateIfActive(7)).resolves.toBe(true);
+    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");
@@ -138,14 +141,21 @@ describe("TokenModel.deactivateIfActive", () => {
   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.toBe(false);
+    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" }] }]);
 
-    await expect(TokenModel.deactivateIfActive(7)).resolves.toBe(false);
+    // 마지막 활성 토큰은 살려두되, 호출부가 systemic 실패로 알릴 수 있게 구분해 알린다.
+    await expect(TokenModel.deactivateIfActive(7)).resolves.toEqual({
+      deactivated: false,
+      keptAsLastActive: true,
+    });
     expect(raw).toHaveBeenCalledTimes(2);
   });
 });

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

@@ -188,26 +188,17 @@ class TokenModelClass extends BaseModelClass<
   /**
    * 같은 계정의 기존 토큰을 지우고 새로 저장한다(로그인·재로그인 공통 경로).
    *
-   * @returns 처음 들어온 계정인지 — 호출부의 신규 등록 알림 게이트. 재로그인은
-   *   기존 토큰을 대체하는 것이라 알릴 사건이 아니다.
-   *
-   *   provider 응답에 계정 식별자가 없으면 dedup 자체가 불가능하므로 경고만 남기고
-   *   중복 제거 없이 저장한다(죽은 row 가 남는다). 이때는 기존 토큰 유무를 알 수 없어
-   *   신규로 보지 않는다 — 재로그인을 신규로 잘못 알리는 편보다 조용한 편이 낫다.
+   * provider 응답에 계정 식별자가 없으면 dedup 자체가 불가능하므로 경고만 남기고
+   * 중복 제거 없이 저장한다(죽은 row 가 남는다).
    */
   async replaceByAccount(
     provider: string,
     accountId: string | undefined,
     saveParams: TokenSaveParams,
-  ): Promise<{ isNew: boolean }> {
-    let isNew = false;
+  ): 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 {
-        isNew = true;
-      }
+      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"}`,
@@ -215,10 +206,16 @@ class TokenModelClass extends BaseModelClass<
     }
 
     await this.save([saveParams]);
-    return { isNew };
   }
 
-  async deactivateIfActive(id: number): Promise<boolean> {
+  /**
+   * @returns `deactivated` 는 이 호출이 실제로 비활성화를 수행했는지 — 호출부의 알림
+   *   게이트다. `keptAsLastActive` 는 마지막 활성 토큰이라 거부한 경우로, 사망 자체는
+   *   사실이지만 풀을 비우지 않으려고 살려둔 상태다(systemic 실패 신호).
+   */
+  async deactivateIfActive(
+    id: number,
+  ): Promise<{ deactivated: boolean; keptAsLastActive: boolean }> {
     const wdb = this.getPuri("w");
 
     // 활성 여부와 "마지막 남은 토큰인가"를 한 statement 안에서 판정한다. 두 조건을
@@ -231,7 +228,7 @@ class TokenModelClass extends BaseModelClass<
               WHERE peer.provider = tokens.provider AND peer.active) > 1`,
       [id],
     );
-    if ((updated.rowCount ?? 0) > 0) return true;
+    if ((updated.rowCount ?? 0) > 0) return { deactivated: true, keptAsLastActive: false };
 
     // 갱신되지 않은 이유는 둘 중 하나다: 이미 비활성이거나(정상 경쟁 결과), 마지막
     // 활성 토큰이거나. 후자는 systemic 실패 신호라 남겨야 하므로 이때만 한 번 더 읽는다.
@@ -246,8 +243,9 @@ class TokenModelClass extends BaseModelClass<
         `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 false;
+    return { deactivated: false, keptAsLastActive: false };
   }
 
   @api({ httpMethod: "POST", clients: ["axios", "tanstack-mutation"] })

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/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}`);
         }