@cartanova/qgrid-cli 2.7.5 → 2.7.6

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

@@ -104,6 +104,89 @@ describe("TokenSubscriber OpenAI notifications", () => {
     );
   });
 
+  it("Anthropic 토큰 변경 뒤 keepalive 대상 재예약을 알린다", async () => {
+    const anthropicDispatcher = { onTokenAdded: vi.fn() };
+    const subscriber = new TokenSubscriber(
+      {} as never,
+      {
+        tokens: new Map(),
+        removeCache: vi.fn(),
+        upsertCache: vi.fn(),
+        replaceCache: vi.fn(),
+        openaiDispatcher: null,
+        anthropicDispatcher,
+      } as never,
+    );
+    const onTokensChanged = vi.fn();
+    subscriber.setTokenChangeHandler(onTokensChanged);
+    findOneMock.mockResolvedValueOnce({
+      ...openaiToken(true),
+      provider: "anthropic",
+      credentials: { accessToken: "access", refreshToken: "refresh" },
+    });
+
+    await subscriber.handleNotification(JSON.stringify({ op: "INSERT", id: 1 }));
+
+    expect(onTokensChanged).toHaveBeenCalledTimes(1);
+  });
+
+  it("Anthropic credentials 갱신은 keepalive 전체 재예약을 유발하지 않는다", async () => {
+    const previous = {
+      ...openaiToken(true),
+      provider: "anthropic",
+      credentials: { accessToken: "old", refreshToken: "refresh" },
+    };
+    const anthropicDispatcher = { onTokenUpdated: vi.fn() };
+    const subscriber = new TokenSubscriber(
+      {} as never,
+      {
+        tokens: new Map([[previous.id, previous]]),
+        removeCache: vi.fn(),
+        upsertCache: vi.fn(),
+        replaceCache: vi.fn(),
+        openaiDispatcher: null,
+        anthropicDispatcher,
+      } as never,
+    );
+    const onTokensChanged = vi.fn();
+    subscriber.setTokenChangeHandler(onTokensChanged);
+    findOneMock.mockResolvedValueOnce({
+      ...previous,
+      credentials: { accessToken: "new", refreshToken: "refresh" },
+    });
+
+    await subscriber.handleNotification(JSON.stringify({ op: "UPDATE", id: previous.id }));
+
+    expect(anthropicDispatcher.onTokenUpdated).toHaveBeenCalledOnce();
+    expect(onTokensChanged).not.toHaveBeenCalled();
+  });
+
+  it("Anthropic active 전환은 keepalive 대상 재예약을 알린다", async () => {
+    const previous = {
+      ...openaiToken(true),
+      provider: "anthropic",
+      credentials: { accessToken: "access", refreshToken: "refresh" },
+    };
+    const subscriber = new TokenSubscriber(
+      {} as never,
+      {
+        tokens: new Map([[previous.id, previous]]),
+        removeCache: vi.fn(),
+        upsertCache: vi.fn(),
+        replaceCache: vi.fn(),
+        openaiDispatcher: null,
+        anthropicDispatcher: { onTokenRemoved: vi.fn() },
+      } as never,
+    );
+    const onTokensChanged = vi.fn();
+    subscriber.setTokenChangeHandler(onTokensChanged);
+    findOneMock.mockResolvedValueOnce({ ...previous, active: false });
+
+    await subscriber.handleNotification(JSON.stringify({ op: "UPDATE", id: previous.id }));
+
+    expect(onTokensChanged).toHaveBeenCalledTimes(1);
+  });
+
   it("serializes token reloads so rapid weight updates cannot apply backward", async () => {
     let resolveFirst!: (value: ReturnType<typeof openaiToken>) => void;
     const firstRow = new Promise<ReturnType<typeof openaiToken>>((resolve) => {
@@ -188,4 +271,33 @@ describe("TokenSubscriber OpenAI notifications", () => {
       expect.objectContaining({ id: 2, quotaThreshold: 80, weight: 4 }),
     ]);
   });
+
+  it("reconcile 은 Anthropic 대상 집합이 바뀔 때만 keepalive 재예약을 알린다", async () => {
+    const currentAnthropic = {
+      ...openaiToken(true),
+      provider: "anthropic",
+      credentials: { accessToken: "access-a", refreshToken: "refresh-a" },
+    };
+    const dispatcher = {
+      tokens: new Map([[currentAnthropic.id, currentAnthropic]]),
+      replaceCache: vi.fn(),
+      openaiDispatcher: null,
+      anthropicDispatcher: { replaceTokens: vi.fn() },
+    };
+    const subscriber = new TokenSubscriber({} as never, dispatcher as never);
+    const onTokensChanged = vi.fn();
+    subscriber.setTokenChangeHandler(onTokensChanged);
+    findActiveMock
+      .mockResolvedValueOnce([currentAnthropic])
+      .mockResolvedValueOnce([
+        currentAnthropic,
+        { ...currentAnthropic, id: 3, name: "anthropic/tok-C" },
+      ]);
+
+    await subscriber.reconcile();
+    expect(onTokensChanged).not.toHaveBeenCalled();
+
+    await subscriber.reconcile();
+    expect(onTokensChanged).toHaveBeenCalledTimes(1);
+  });
 });

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

@@ -26,12 +26,25 @@ export class TokenSubscriber {
   connectedAt: Date | null = null;
   lastReconcileAt: Date | null = null;
   private operationChain: Promise<void> = Promise.resolve();
+  private tokenChangeHandler: (() => void) | null = null;
 
   constructor(
     public connConfig: ClientConfig,
     public dispatcher: QgridDispatcherClass,
   ) {}
 
+  setTokenChangeHandler(handler: (() => void) | null): void {
+    this.tokenChangeHandler = handler;
+  }
+
+  private notifyTokensChanged(): void {
+    try {
+      this.tokenChangeHandler?.();
+    } catch (error) {
+      logger.warn(`token change handler failed: ${(error as Error).message}`);
+    }
+  }
+
   async start(): Promise<boolean> {
     this.shutdownRequested = false;
     this.ensureReconcileTimer();
@@ -157,6 +170,10 @@ export class TokenSubscriber {
 
   private async handleNotificationNow(payloadJson: string): Promise<void> {
     const payload = JSON.parse(payloadJson) as Payload;
+    const previousRow = this.tokenChangeHandler
+      ? this.dispatcher.tokens.get(payload.id)
+      : undefined;
+    const wasKeepaliveTarget = previousRow?.active === true && previousRow.provider === "anthropic";
     if (payload.op === "DELETE") {
       this.dispatcher.removeCache(payload.id);
       await this.dispatcher.openaiDispatcher
@@ -165,6 +182,7 @@ export class TokenSubscriber {
       // anthropic 토큰 이벤트는 동기(void) — provider 를 모르므로 무해하게 항상 제거 시도.
       this.dispatcher.anthropicDispatcher?.onTokenRemoved(payload.id);
       logger.info(`NOTIFY ${payload.op} id=${payload.id} → removed from cache`);
+      if (previousRow === undefined || wasKeepaliveTarget) this.notifyTokensChanged();
       return;
     }
     const row = await TokenModel.findOne("A", { id: payload.id });
@@ -175,6 +193,7 @@ export class TokenSubscriber {
         .catch((e) => logger.warn(`openai token remove failed: ${(e as Error).message}`));
       this.dispatcher.anthropicDispatcher?.onTokenRemoved(payload.id);
       logger.info(`NOTIFY ${payload.op} id=${payload.id} → missing, removed from cache`);
+      if (previousRow === undefined || wasKeepaliveTarget) this.notifyTokensChanged();
       return;
     }
 
@@ -236,6 +255,8 @@ export class TokenSubscriber {
       }
     }
     logger.info(`NOTIFY ${payload.op} id=${payload.id} (${row.name}) active=${row.active}`);
+    const isKeepaliveTarget = row.active && row.provider === "anthropic";
+    if (wasKeepaliveTarget !== isKeepaliveTarget) this.notifyTokensChanged();
   }
 
   async reconcile(): Promise<void> {
@@ -243,6 +264,13 @@ export class TokenSubscriber {
   }
 
   private async reconcileNow(): Promise<void> {
+    const previousAnthropicIds = this.tokenChangeHandler
+      ? new Set(
+          [...this.dispatcher.tokens.values()]
+            .filter((row) => row.active && row.provider === "anthropic")
+            .map((row) => row.id),
+        )
+      : null;
     const rows = await TokenModel.findActive("A");
     this.dispatcher.replaceCache(rows);
     // NOTIFY 유실 대비: AnthropicDispatcher 풀도 DB active anthropic 토큰 기준으로 재동기화.
@@ -270,6 +298,13 @@ export class TokenSubscriber {
       ?.replaceTokens(openaiRows)
       .catch((e) => logger.warn(`openai reconcile failed: ${(e as Error).message}`));
     this.lastReconcileAt = new Date();
+    if (
+      previousAnthropicIds &&
+      (previousAnthropicIds.size !== anthropicRows.length ||
+        anthropicRows.some((row) => !previousAnthropicIds.has(row.id)))
+    ) {
+      this.notifyTokensChanged();
+    }
   }
 
   private enqueueOperation(operation: () => Promise<void>): Promise<void> {

package/bundle/src/application/qgrid/token-window-keepalive.test.ts

@@ -0,0 +1,223 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  KEEPALIVE_MODEL,
+  KEEPALIVE_PROJECT_NAME,
+  POST_KEEPALIVE_USAGE_DELAY_MS,
+  rescheduleTokenWindowKeepalive,
+  startTokenWindowKeepalive,
+  stopTokenWindowKeepalive,
+  type TokenWindowKeepaliveDeps,
+} from "./token-window-keepalive";
+
+const NOW = Date.parse("2026-08-19T00:00:00.000Z");
+const FIVE_HOURS_MS = 5 * 60 * 60 * 1_000;
+
+function token(
+  id: number,
+  overrides: Partial<{ name: string; provider: string; active: boolean }> = {},
+) {
+  return {
+    id,
+    name: `anthropic/token-${id}`,
+    provider: "anthropic",
+    active: true,
+    ...overrides,
+  };
+}
+
+function usage(resetsAt: string | null) {
+  return {
+    provider: "anthropic",
+    fiveHour: { utilization: 0, resetsAt },
+    sevenDay: null,
+  };
+}
+
+function deps(overrides: Partial<TokenWindowKeepaliveDeps> = {}): TokenWindowKeepaliveDeps {
+  return {
+    findTokens: vi.fn(async () => [token(1)]),
+    readUsage: vi.fn(async () => usage(new Date(NOW + FIVE_HOURS_MS).toISOString())),
+    dispatch: vi.fn(async () => undefined),
+    readSetting: () => "true",
+    now: () => Date.now(),
+    setTimer: (callback, delayMs) => setTimeout(callback, delayMs),
+    clearTimer: (handle) => clearTimeout(handle),
+    ...overrides,
+  };
+}
+
+describe("token window keepalive", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(NOW);
+  });
+
+  afterEach(() => {
+    stopTokenWindowKeepalive();
+    vi.useRealTimers();
+  });
+
+  it("resetsAt 이 없으면 지정 토큰·최저가 모델·전용 project label 로 즉시 발사한다", async () => {
+    const readUsage = vi
+      .fn()
+      .mockResolvedValueOnce(usage(null))
+      .mockResolvedValueOnce(usage(new Date(NOW + FIVE_HOURS_MS).toISOString()));
+    const dispatch = vi.fn(async () => undefined);
+
+    await startTokenWindowKeepalive(deps({ readUsage, dispatch }));
+
+    expect(dispatch).toHaveBeenCalledWith({
+      prompt: "Reply OK.",
+      model: KEEPALIVE_MODEL,
+      effort: "low",
+      projectName: KEEPALIVE_PROJECT_NAME,
+      preferredTokenId: 1,
+    });
+
+    await vi.advanceTimersByTimeAsync(POST_KEEPALIVE_USAGE_DELAY_MS);
+    expect(readUsage).toHaveBeenCalledTimes(2);
+    expect(dispatch).toHaveBeenCalledTimes(1);
+  });
+
+  it("resetsAt 이 과거면 즉시 발사한다", async () => {
+    const dispatch = vi.fn(async () => undefined);
+    await startTokenWindowKeepalive(
+      deps({
+        readUsage: vi.fn(async () => usage(new Date(NOW - 1).toISOString())),
+        dispatch,
+      }),
+    );
+
+    expect(dispatch).toHaveBeenCalledTimes(1);
+  });
+
+  it("resetsAt 이 미래면 그 시각 직후까지 발사하지 않는다", async () => {
+    const dispatch = vi.fn(async () => undefined);
+    await startTokenWindowKeepalive(
+      deps({
+        readUsage: vi.fn(async () => usage(new Date(NOW + 10_000).toISOString())),
+        dispatch,
+      }),
+    );
+
+    await vi.advanceTimersByTimeAsync(10_999);
+    expect(dispatch).not.toHaveBeenCalled();
+
+    await vi.advanceTimersByTimeAsync(1);
+    expect(dispatch).toHaveBeenCalledTimes(1);
+  });
+
+  it("비활성 토큰과 Anthropic 이 아닌 토큰은 대상에서 제외한다", async () => {
+    const readUsage = vi.fn(async () => usage(new Date(NOW + FIVE_HOURS_MS).toISOString()));
+    await startTokenWindowKeepalive(
+      deps({
+        findTokens: vi.fn(async () => [
+          token(1),
+          token(2, { provider: "openai" }),
+          token(3, { active: false }),
+        ]),
+        readUsage,
+      }),
+    );
+
+    expect(readUsage).toHaveBeenCalledTimes(1);
+    expect(readUsage).toHaveBeenCalledWith(1);
+  });
+
+  it("한 토큰의 usage 실패가 다른 토큰 예약을 막지 않는다", async () => {
+    const readUsage = vi.fn(async (tokenId: number) => {
+      if (tokenId === 1) throw new Error("usage unavailable");
+      return usage(new Date(NOW + FIVE_HOURS_MS).toISOString());
+    });
+
+    await expect(
+      startTokenWindowKeepalive(
+        deps({ findTokens: vi.fn(async () => [token(1), token(2)]), readUsage }),
+      ),
+    ).resolves.toBeUndefined();
+
+    expect(readUsage).toHaveBeenCalledTimes(2);
+    expect(vi.getTimerCount()).toBe(2);
+  });
+
+  it("발사 실패는 밖으로 전파하지 않고 5시간 안에 재시도하지 않는다", async () => {
+    const dispatch = vi.fn(async () => {
+      throw new Error("provider unavailable");
+    });
+
+    await expect(
+      startTokenWindowKeepalive(
+        deps({ readUsage: vi.fn(async () => usage(null)), dispatch }),
+      ),
+    ).resolves.toBeUndefined();
+
+    expect(dispatch).toHaveBeenCalledTimes(1);
+    await vi.advanceTimersByTimeAsync(FIVE_HOURS_MS - 1);
+    expect(dispatch).toHaveBeenCalledTimes(1);
+  });
+
+  it("발사 뒤 usage 에 아직 새 윈도우가 안 보여도 즉시 다시 발사하지 않는다", async () => {
+    const dispatch = vi.fn(async () => undefined);
+    await startTokenWindowKeepalive(
+      deps({ readUsage: vi.fn(async () => usage(null)), dispatch }),
+    );
+
+    await vi.advanceTimersByTimeAsync(POST_KEEPALIVE_USAGE_DELAY_MS);
+
+    expect(dispatch).toHaveBeenCalledTimes(1);
+    expect(vi.getTimerCount()).toBe(1);
+  });
+
+  it("발사 후 61초 대기 중 재스케줄되어도 같은 토큰을 다시 발사하지 않는다", async () => {
+    const readUsage = vi
+      .fn()
+      .mockResolvedValueOnce(usage(null))
+      .mockResolvedValueOnce(usage(new Date(NOW + FIVE_HOURS_MS).toISOString()));
+    const dispatch = vi.fn(async () => undefined);
+    const testDeps = deps({ readUsage, dispatch });
+
+    await startTokenWindowKeepalive(testDeps);
+    await rescheduleTokenWindowKeepalive(testDeps);
+
+    expect(dispatch).toHaveBeenCalledTimes(1);
+    expect(readUsage).toHaveBeenCalledTimes(1);
+
+    await vi.advanceTimersByTimeAsync(POST_KEEPALIVE_USAGE_DELAY_MS);
+    expect(dispatch).toHaveBeenCalledTimes(1);
+    expect(readUsage).toHaveBeenCalledTimes(2);
+  });
+
+  it("발사 실패 후 재스케줄되어도 5시간 안에 다시 발사하지 않는다", async () => {
+    const dispatch = vi.fn(async () => {
+      throw new Error("provider unavailable");
+    });
+    const testDeps = deps({ readUsage: vi.fn(async () => usage(null)), dispatch });
+
+    await startTokenWindowKeepalive(testDeps);
+    await rescheduleTokenWindowKeepalive(testDeps);
+    await vi.advanceTimersByTimeAsync(FIVE_HOURS_MS - 1);
+
+    expect(dispatch).toHaveBeenCalledTimes(1);
+  });
+
+  it("스위치가 꺼져 있으면 조회나 타이머를 시작하지 않는다", async () => {
+    const testDeps = deps({ readSetting: () => "false" });
+
+    await startTokenWindowKeepalive(testDeps);
+
+    expect(testDeps.findTokens).not.toHaveBeenCalled();
+    expect(testDeps.readUsage).not.toHaveBeenCalled();
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("실행 중 스위치를 끄고 재예약하면 기존 타이머를 정리한다", async () => {
+    const testDeps = deps();
+    await startTokenWindowKeepalive(testDeps);
+    expect(vi.getTimerCount()).toBe(1);
+
+    await rescheduleTokenWindowKeepalive({ ...testDeps, readSetting: () => "false" });
+
+    expect(vi.getTimerCount()).toBe(0);
+  });
+});

package/bundle/src/application/qgrid/token-window-keepalive.ts

@@ -0,0 +1,227 @@
+import { getLogger } from "@logtape/logtape";
+
+import { getSetting } from "../setting/setting.store";
+import { TokenModel } from "../token/token.model";
+import { type InternalQueryInput } from "./qgrid.dispatcher";
+import { QgridFrame } from "./qgrid.frame";
+import { type UsageResponse } from "./qgrid.types";
+
+const logger = getLogger(["qgrid", "token-window-keepalive"]);
+
+const FIVE_HOURS_MS = 5 * 60 * 60 * 1_000;
+const RESET_GRACE_MS = 1_000;
+
+// usage API 성공 응답은 1분 캐시된다. keepalive 직후 즉시 재조회하면 이전 윈도우를
+// 다시 보므로 캐시가 지난 뒤 한 번 확인하고, 그때도 새 윈도우가 없으면 다음 5h까지 기다린다.
+export const POST_KEEPALIVE_USAGE_DELAY_MS = 61_000;
+export const KEEPALIVE_MODEL = "anthropic/claude-haiku-4-5";
+export const KEEPALIVE_PROJECT_NAME = "qgrid-token-window-keepalive";
+export const KEEPALIVE_SETTING_KEY = "qgrid.tokenWindowKeepaliveEnabled";
+export const KEEPALIVE_ENV_KEY = "QGRID_TOKEN_WINDOW_KEEPALIVE_ENABLED";
+
+type KeepaliveToken = {
+  id: number;
+  name: string;
+  provider: string;
+  active: boolean;
+};
+
+type TimerHandle = ReturnType<typeof setTimeout>;
+
+export type TokenWindowKeepaliveDeps = {
+  findTokens: () => Promise<KeepaliveToken[]>;
+  readUsage: (tokenId: number) => Promise<UsageResponse>;
+  dispatch: (input: InternalQueryInput) => Promise<unknown>;
+  readSetting: typeof getSetting;
+  now: () => number;
+  setTimer: (callback: () => void, delayMs: number) => TimerHandle;
+  clearTimer: (handle: TimerHandle) => void;
+};
+
+const defaultDeps: TokenWindowKeepaliveDeps = {
+  findTokens: () => TokenModel.findActiveByProvider("A", "anthropic"),
+  readUsage: (tokenId) => QgridFrame.usage(tokenId),
+  dispatch: (input) => QgridFrame.query(input),
+  readSetting: getSetting,
+  now: () => Date.now(),
+  setTimer: (callback, delayMs) => setTimeout(callback, delayMs),
+  clearTimer: (handle) => clearTimeout(handle),
+};
+
+const timers = new Map<number, { handle: TimerHandle; clear: (handle: TimerHandle) => void }>();
+const fireGuards = new Map<number, { untilMs: number; allowFireAtExpiry: boolean }>();
+let generation = 0;
+
+function clearTokenTimer(tokenId: number): void {
+  const timer = timers.get(tokenId);
+  if (!timer) return;
+  timer.clear(timer.handle);
+  timers.delete(tokenId);
+}
+
+function scheduleToken(
+  token: KeepaliveToken,
+  deps: TokenWindowKeepaliveDeps,
+  expectedGeneration: number,
+  delayMs: number,
+  allowFire: boolean,
+): void {
+  if (generation !== expectedGeneration) return;
+  clearTokenTimer(token.id);
+  const handle = deps.setTimer(
+    () => {
+      timers.delete(token.id);
+      if (generation !== expectedGeneration) return;
+      void inspectToken(token, deps, expectedGeneration, allowFire).catch((error) => {
+        logger.warn(`keepalive cycle failed for ${token.name}: ${(error as Error).message}`);
+        scheduleFallback(token, deps, expectedGeneration);
+      });
+    },
+    Math.max(0, delayMs),
+  );
+  timers.set(token.id, { handle, clear: deps.clearTimer });
+}
+
+function deferToken(
+  token: KeepaliveToken,
+  deps: TokenWindowKeepaliveDeps,
+  expectedGeneration: number,
+  delayMs: number,
+  allowFireAtExpiry: boolean,
+): void {
+  const untilMs = deps.now() + delayMs;
+  fireGuards.set(token.id, { untilMs, allowFireAtExpiry });
+  scheduleToken(token, deps, expectedGeneration, delayMs, allowFireAtExpiry);
+}
+
+function scheduleFallback(
+  token: KeepaliveToken,
+  deps: TokenWindowKeepaliveDeps,
+  expectedGeneration: number,
+): void {
+  deferToken(token, deps, expectedGeneration, FIVE_HOURS_MS, true);
+}
+
+async function inspectToken(
+  token: KeepaliveToken,
+  deps: TokenWindowKeepaliveDeps,
+  expectedGeneration: number,
+  allowFire: boolean,
+): Promise<void> {
+  const now = deps.now();
+  const guard = fireGuards.get(token.id);
+  if (guard && guard.untilMs > now) {
+    scheduleToken(token, deps, expectedGeneration, guard.untilMs - now, guard.allowFireAtExpiry);
+    return;
+  }
+  if (guard) fireGuards.delete(token.id);
+
+  let usage: UsageResponse;
+  try {
+    usage = await deps.readUsage(token.id);
+  } catch (error) {
+    logger.warn(`usage lookup failed for ${token.name}: ${(error as Error).message}`);
+    scheduleFallback(token, deps, expectedGeneration);
+    return;
+  }
+  if (generation !== expectedGeneration) return;
+
+  if (usage.error) {
+    logger.warn(`usage lookup failed for ${token.name}: ${usage.error}`);
+    scheduleFallback(token, deps, expectedGeneration);
+    return;
+  }
+
+  const resetsAt = usage.fiveHour?.resetsAt;
+  if (resetsAt) {
+    const resetMs = Date.parse(resetsAt);
+    if (!Number.isFinite(resetMs)) {
+      logger.warn(`invalid five-hour reset for ${token.name}: ${resetsAt}`);
+      scheduleFallback(token, deps, expectedGeneration);
+      return;
+    }
+    const inspectedAt = deps.now();
+    if (resetMs > inspectedAt) {
+      fireGuards.delete(token.id);
+      scheduleToken(token, deps, expectedGeneration, resetMs - inspectedAt + RESET_GRACE_MS, true);
+      return;
+    }
+  }
+
+  // 발사 직후 확인에서는 캐시된 null/과거 reset을 봐도 다시 발사하지 않는다.
+  if (!allowFire) {
+    scheduleFallback(token, deps, expectedGeneration);
+    return;
+  }
+
+  deferToken(token, deps, expectedGeneration, POST_KEEPALIVE_USAGE_DELAY_MS, false);
+  try {
+    await deps.dispatch({
+      prompt: "Reply OK.",
+      model: KEEPALIVE_MODEL,
+      effort: "low",
+      projectName: KEEPALIVE_PROJECT_NAME,
+      preferredTokenId: token.id,
+    });
+    logger.info(`keepalive sent for ${token.name}`);
+  } catch (error) {
+    logger.warn(`keepalive failed for ${token.name}: ${(error as Error).message}`);
+    scheduleFallback(token, deps, expectedGeneration);
+    return;
+  }
+
+  const postFireGuard = fireGuards.get(token.id);
+  if (postFireGuard) {
+    scheduleToken(
+      token,
+      deps,
+      expectedGeneration,
+      Math.max(0, postFireGuard.untilMs - deps.now()),
+      postFireGuard.allowFireAtExpiry,
+    );
+  }
+}
+
+function clearScheduledTimers(): void {
+  generation++;
+  for (const tokenId of timers.keys()) clearTokenTimer(tokenId);
+}
+
+export async function startTokenWindowKeepalive(
+  deps: TokenWindowKeepaliveDeps = defaultDeps,
+): Promise<void> {
+  clearScheduledTimers();
+  if (deps.readSetting(KEEPALIVE_SETTING_KEY, KEEPALIVE_ENV_KEY) === "false") {
+    logger.info("token window keepalive disabled");
+    return;
+  }
+  const expectedGeneration = generation;
+
+  let tokens: KeepaliveToken[];
+  try {
+    tokens = await deps.findTokens();
+  } catch (error) {
+    logger.warn(`token discovery failed: ${(error as Error).message}`);
+    return;
+  }
+  if (generation !== expectedGeneration) return;
+
+  const targets = tokens.filter((token) => token.active && token.provider === "anthropic");
+  const targetIds = new Set(targets.map((token) => token.id));
+  for (const tokenId of fireGuards.keys()) {
+    if (!targetIds.has(tokenId)) fireGuards.delete(tokenId);
+  }
+  logger.info(`token window keepalive scheduling ${targets.length} token(s)`);
+  await Promise.all(targets.map((token) => inspectToken(token, deps, expectedGeneration, true)));
+}
+
+export function rescheduleTokenWindowKeepalive(
+  deps: TokenWindowKeepaliveDeps = defaultDeps,
+): Promise<void> {
+  return startTokenWindowKeepalive(deps);
+}
+
+export function stopTokenWindowKeepalive(): void {
+  clearScheduledTimers();
+  fireGuards.clear();
+}

package/bundle/src/application/setting/setting.constant.test.ts

@@ -73,6 +73,16 @@ describe("maskSecret", () => {
 });
 
 describe("SETTING_DEFS", () => {
+  it("token window keepalive 비상 스위치를 즉시 적용 설정으로 등록한다", () => {
+    expect(findSettingDef("qgrid.tokenWindowKeepaliveEnabled")).toMatchObject({
+      group: "qgrid",
+      envKey: "QGRID_TOKEN_WINDOW_KEEPALIVE_ENABLED",
+      kind: "boolean",
+      applies: "immediate",
+      fallback: "true",
+    });
+  });
+
   it("키가 중복되지 않는다", () => {
     const keys = SETTING_DEFS.map((d) => d.key);
     expect(new Set(keys).size).toBe(keys.length);

package/bundle/src/application/setting/setting.constant.ts

@@ -17,7 +17,7 @@ export type SettingKind = "boolean" | "integer" | "number" | "string" | "secret"
  * Slack 은 "언제 보낼까"(slack)와 "어디로 보낼까"(slackConnection)를 나눈다 — 앞은 운영
  * 중 자주 만지고 뒤는 한 번 맞추면 끝이라 수명이 다르다.
  */
-export type SettingGroup = "slack" | "slackConnection";
+export type SettingGroup = "qgrid" | "slack" | "slackConnection";
 
 export type SettingDef = {
   key: string;
@@ -40,6 +40,16 @@ export type SettingDef = {
 };
 
 export const SETTING_DEFS: SettingDef[] = [
+  {
+    key: "qgrid.tokenWindowKeepaliveEnabled",
+    fallback: "true",
+    group: "qgrid",
+    envKey: "QGRID_TOKEN_WINDOW_KEEPALIVE_ENABLED",
+    label: "토큰 윈도우 keepalive",
+    kind: "boolean",
+    applies: "immediate",
+    help: "끄면 활성 Anthropic 토큰의 5시간 윈도우 자동 유지 요청을 중단합니다",
+  },
   {
     key: "slack.enabled",
     fallback: "true",