@cartanova/qgrid-cli 2.6.9 → 2.6.11

package/bundle/src/application/qgrid/qgrid.frame.test.ts

@@ -18,6 +18,7 @@ const {
   dispatcherQueryStreamMock,
   beforeQueryMock,
   afterQueryMock,
+  assertNativeRunAdmissionMock,
   finishRunWithErrorMock,
   finishRunAbortedMock,
   getRateLimitsByTokenIdMock,
@@ -33,6 +34,7 @@ const {
   dispatcherQueryStreamMock: vi.fn(),
   beforeQueryMock: vi.fn(),
   afterQueryMock: vi.fn(),
+  assertNativeRunAdmissionMock: vi.fn(),
   finishRunWithErrorMock: vi.fn(),
   finishRunAbortedMock: vi.fn(),
   getRateLimitsByTokenIdMock: vi.fn(),
@@ -56,6 +58,13 @@ vi.mock("../token/token.model", () => ({
   },
 }));
 
+// QgridFrame의 token-death 연결은 이 스위트의 관심사가 아니다. isolate:false 워커에서
+// 부분 TokenModel mock으로 token-death 실제 모듈을 먼저 캐시하지 않도록 경계를 끊는다.
+vi.mock("./token-death", () => ({
+  deactivateAuthDeadToken: vi.fn(),
+  notifyTokenAdded: vi.fn(),
+}));
+
 vi.mock("./qgrid.dispatcher", async (importOriginal) => {
   const original = await importOriginal<typeof import("./qgrid.dispatcher")>();
   return {
@@ -71,6 +80,7 @@ vi.mock("./qgrid.dispatcher", async (importOriginal) => {
 });
 
 vi.mock("./qgrid-run-lifecycle", () => ({
+  assertNativeRunAdmission: assertNativeRunAdmissionMock,
   beforeQuery: beforeQueryMock,
   afterQuery: afterQueryMock,
   finishRunWithError: finishRunWithErrorMock,
@@ -161,6 +171,7 @@ describe("QgridFrame.query request logging", () => {
   beforeEach(() => {
     beforeQueryMock.mockReset().mockResolvedValue({ requestLogId: 41, stepIndex: 0 });
     afterQueryMock.mockReset().mockResolvedValue({});
+    assertNativeRunAdmissionMock.mockReset();
     finishRunWithErrorMock.mockReset();
     dispatcherQueryMock.mockReset();
   });
@@ -258,6 +269,18 @@ describe("QgridFrame.query request logging", () => {
     expect(finishRunWithErrorMock).not.toHaveBeenCalled();
   });
 
+  it("rejects logger-disabled native dispatch while restart admission is closed", async () => {
+    assertNativeRunAdmissionMock.mockImplementationOnce(() => {
+      throw Object.assign(new Error("server restarting"), { statusCode: 503 });
+    });
+
+    await expect(
+      QgridFrame.query({ prompt: "hi", model: "openai/gpt-5-codex", logger: false }),
+    ).rejects.toMatchObject({ statusCode: 503 });
+    expect(dispatcherQueryMock).not.toHaveBeenCalled();
+    expect(beforeQueryMock).not.toHaveBeenCalled();
+  });
+
   it("merges a tool run id with the provider thread coordinate", async () => {
     dispatcherQueryMock.mockResolvedValueOnce(queryOutput());
     afterQueryMock.mockResolvedValueOnce({ runContext: { requestLogId: 41 } });
@@ -843,6 +866,7 @@ describe("QgridFrame.queryStream request logging", () => {
   beforeEach(() => {
     beforeQueryMock.mockReset().mockResolvedValue({ requestLogId: 52, stepIndex: 0 });
     afterQueryMock.mockReset().mockResolvedValue({});
+    assertNativeRunAdmissionMock.mockReset();
     finishRunWithErrorMock.mockReset();
     finishRunAbortedMock.mockReset();
     dispatcherQueryStreamMock.mockReset();
@@ -876,6 +900,27 @@ describe("QgridFrame.queryStream request logging", () => {
     };
   }
 
+  it("rejects stream preparation while restart admission is closed", async () => {
+    assertNativeRunAdmissionMock.mockImplementationOnce(() => {
+      throw Object.assign(new Error("server restarting"), { statusCode: 503 });
+    });
+
+    await expect(QgridFrame.prepareStream({ prompt: "hi" })).rejects.toMatchObject({
+      statusCode: 503,
+    });
+    expect(dispatcherQueryStreamMock).not.toHaveBeenCalled();
+  });
+
+  it("rechecks admission before dispatching a previously prepared stream", async () => {
+    const { streamId } = await QgridFrame.prepareStream({ prompt: "hi", logger: false });
+    assertNativeRunAdmissionMock.mockImplementationOnce(() => {
+      throw Object.assign(new Error("server restarting"), { statusCode: 503 });
+    });
+
+    await expect(QgridFrame.queryStream(streamId)).rejects.toMatchObject({ statusCode: 503 });
+    expect(dispatcherQueryStreamMock).not.toHaveBeenCalled();
+  });
+
   function installSseContext() {
     let closeHandler: (() => void) | undefined;
     const sse = {

package/bundle/src/application/qgrid/qgrid.frame.ts

@@ -28,6 +28,7 @@ import {
   RefreshFailedError,
 } from "./oauth";
 import {
+  assertNativeRunAdmission,
   afterQuery,
   beforeQuery,
   finishRunAborted,
@@ -210,6 +211,7 @@ class QgridFrameClass extends BaseFrameClass {
 
   @api({ httpMethod: "POST", clients: ["axios", "tanstack-mutation"] })
   async query(args: QueryInput): Promise<QueryOutput> {
+    assertNativeRunAdmission();
     rejectInvalidCallerSchemas(args);
     const disconnect = createHttpDisconnectHandle();
     try {
@@ -259,6 +261,7 @@ class QgridFrameClass extends BaseFrameClass {
 
   @api({ httpMethod: "POST", clients: ["axios", "tanstack-mutation"] })
   async prepareStream(args: QueryInput): Promise<{ streamId: string }> {
+    assertNativeRunAdmission();
     rejectImageGenerationStream(args);
     rejectInvalidCallerSchemas(args);
     const streamId = crypto.randomUUID();
@@ -273,6 +276,7 @@ class QgridFrameClass extends BaseFrameClass {
     const args = pendingStreams.get(streamId);
     pendingStreams.delete(streamId);
     if (!args) throw new Error("invalid or expired streamId");
+    assertNativeRunAdmission();
     rejectImageGenerationStream(args);
 
     const ctx = Sonamu.getContext();

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

@@ -0,0 +1,104 @@
+import { EventEmitter } from "node:events";
+
+import { Sonamu } from "sonamu";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { resetNativeRunRegistryForTests } from "../qgrid/qgrid-run-lifecycle";
+import { resetServerRestartForTests } from "../../utils/server-restart";
+import { SettingModel } from "./setting.model";
+
+function installContext(headers: Record<string, string>) {
+  const raw = Object.assign(new EventEmitter(), {
+    destroyed: false,
+    writableEnded: false,
+  });
+  vi.spyOn(Sonamu, "getContext").mockReturnValue({
+    transport: "http",
+    headers,
+    request: { protocol: "http" },
+    reply: { raw },
+  } as never);
+  return raw;
+}
+
+describe("SettingModel.restartServer", () => {
+  beforeEach(() => {
+    vi.spyOn(process, "exit").mockImplementation((() => undefined) as never);
+  });
+
+  afterEach(() => {
+    resetServerRestartForTests();
+    resetNativeRunRegistryForTests();
+    vi.unstubAllEnvs();
+    vi.restoreAllMocks();
+  });
+
+  it("rejects restart when pm2 will not respawn the process", async () => {
+    const raw = installContext({ host: "localhost:44900" });
+    vi.stubEnv("pm_id", undefined);
+
+    await expect(SettingModel.restartServer()).rejects.toMatchObject({ statusCode: 400 });
+    expect(raw.listenerCount("finish")).toBe(0);
+    expect(process.exit).not.toHaveBeenCalled();
+  });
+
+  it("rejects a browser request whose Origin host does not match Host", async () => {
+    installContext({ origin: "https://evil.example", host: "qgrid.example.com" });
+    vi.stubEnv("pm_id", "0");
+
+    await expect(SettingModel.restartServer()).rejects.toMatchObject({ statusCode: 403 });
+    expect(process.exit).not.toHaveBeenCalled();
+  });
+
+  it("rejects a malformed present Origin instead of treating it as an operational client", async () => {
+    installContext({ origin: "null", host: "qgrid.example.com" });
+    vi.stubEnv("pm_id", "0");
+
+    await expect(SettingModel.restartServer()).rejects.toMatchObject({ statusCode: 403 });
+    expect(process.exit).not.toHaveBeenCalled();
+  });
+
+  it("accepts a matching Origin using the Caddy-forwarded host", async () => {
+    const raw = installContext({
+      origin: "https://qgrid.example.com",
+      host: "127.0.0.1:44900",
+      "x-forwarded-host": "qgrid.example.com",
+    });
+    vi.stubEnv("pm_id", "0");
+
+    await expect(SettingModel.restartServer()).resolves.toEqual({ supervisor: "pm2" });
+    expect(process.exit).not.toHaveBeenCalled();
+
+    raw.emit("finish");
+    expect(process.exit).toHaveBeenCalledOnce();
+    expect(process.exit).toHaveBeenCalledWith(0);
+  });
+
+  it("accepts an Origin-less operational request", async () => {
+    const raw = installContext({ host: "qgrid.example.com" });
+    vi.stubEnv("pm_id", "0");
+
+    await expect(SettingModel.restartServer()).resolves.toEqual({ supervisor: "pm2" });
+    expect(process.exit).not.toHaveBeenCalled();
+
+    raw.emit("finish");
+    expect(process.exit).toHaveBeenCalledWith(0);
+  });
+
+  it("coordinates simultaneous calls through one process exit", async () => {
+    const firstRaw = installContext({ host: "qgrid.example.com" });
+    vi.stubEnv("pm_id", "0");
+
+    const first = SettingModel.restartServer();
+    const second = SettingModel.restartServer();
+    await expect(Promise.all([first, second])).resolves.toEqual([
+      { supervisor: "pm2" },
+      { supervisor: "pm2" },
+    ]);
+
+    firstRaw.emit("finish");
+    firstRaw.emit("close");
+    expect(process.exit).toHaveBeenCalledOnce();
+    expect(process.exit).toHaveBeenCalledWith(0);
+  });
+});

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

@@ -1,14 +1,19 @@
+import { getLogger } from "@logtape/logtape";
 import {
   BaseModelClass,
   type ListResult,
   asArray,
   NotFoundException,
   BadRequestException,
+  SoException,
+  Sonamu,
   api,
   exhaustive,
 } from "sonamu";
 
 import { SD } from "../../i18n/sd.generated";
+import { detectSupervisor } from "../../utils/process-supervisor";
+import { armServerRestartExit, beginServerRestart } from "../../utils/server-restart";
 import { type SettingSubsetKey, type SettingSubsetMapping } from "../sonamu.generated";
 import { settingSubsetQueries, settingLoaderQueries } from "../sonamu.generated.sso";
 import { findSettingDef, maskSecret, SETTING_DEFS, validateSettingValue } from "./setting.constant";
@@ -25,8 +30,37 @@ import {
   type SettingListParams,
   type SettingSaveParams,
   type SettingsResponse,
+  type SupervisorKind,
 } from "./setting.types";
 
+const logger = getLogger(["qgrid", "setting"]);
+
+class ForbiddenException extends SoException {
+  constructor() {
+    super(403, SD("error.forbidden"));
+  }
+}
+
+function firstHeaderValue(value: string | string[] | undefined): string | undefined {
+  return (Array.isArray(value) ? value[0] : value)?.split(",")[0]?.trim();
+}
+
+/** Origin 없는 운영 CLI 요청은 통과시키되, 브라우저 교차 출처 POST 는 막는다. */
+function assertRestartOrigin(): void {
+  const { headers } = Sonamu.getContext();
+  const origin = firstHeaderValue(headers.origin);
+  if (headers.origin === undefined) return;
+  if (!origin) throw new ForbiddenException();
+
+  const host = firstHeaderValue(headers["x-forwarded-host"]) ?? firstHeaderValue(headers.host);
+  try {
+    if (!host || new URL(origin).host !== host) throw new ForbiddenException();
+  } catch (error) {
+    if (error instanceof ForbiddenException) throw error;
+    throw new ForbiddenException();
+  }
+}
+
 /*
   Setting Model
 */
@@ -207,8 +241,8 @@ class SettingModelClass extends BaseModelClass<
         label: def.label,
         kind: def.kind,
         applies: def.applies,
-        // 눈 토글을 위해 secret 도 원본을 내려보낸다. 이 엔드포인트는 배포 경계에서 인증해야
-        // 하며, dev0 는 Caddy 인증을 통과한 운영자만 접근할 수 있다.
+        // 눈 토글을 위해 secret 도 원본을 내려보낸다. 이 엔드포인트는 배포 경계에서
+        // 반드시 인증해야 한다.
         value: effective,
         source,
         min: def.min ?? null,
@@ -218,7 +252,7 @@ class SettingModelClass extends BaseModelClass<
       };
     });
 
-    return { settings, runtime: this.runtimeInfo() };
+    return { settings, runtime: this.runtimeInfo(), supervisor: detectSupervisor() };
   }
 
   private runtimeInfo(): RuntimeInfoItem[] {
@@ -272,6 +306,44 @@ class SettingModelClass extends BaseModelClass<
     const { sendExpiredTokenReminderNow } = await import("../qgrid/expired-token-reminder");
     return { sent: await sendExpiredTokenReminderNow() };
   }
+
+  /**
+   * 서버를 재시작한다 — 정확히는 스스로 종료하고, pm2 가 다시 띄우는 것에 맡긴다.
+   *
+   * `restart` 로 표시된 워커 설정은 dispatcher 생성자에서 한 번만 읽히므로 이 경로 말고는
+   * 반영할 방법이 없었다. 지금까지는 SSH 로 `pm2 restart` 를 쳐야 했다.
+   *
+   * 부수 효과가 하나 더 있다: pm2 는 `ecosystem.config.cjs` 의 원래 명령으로 다시 띄우고,
+   * 그 명령에 `--skip-update` 가 없으면 CLI 가 npm 최신 버전을 받아 올린다. 즉 재시작은
+   * 배포이기도 하다 — 화면 문구가 이 사실을 함께 알린다.
+   */
+  @api({ httpMethod: "POST", clients: ["axios", "tanstack-mutation"] })
+  async restartServer(): Promise<{ supervisor: SupervisorKind }> {
+    assertRestartOrigin();
+    const supervisor = detectSupervisor();
+    if (!supervisor) {
+      // 다시 띄워줄 주체가 없으면 종료가 곧 정지다. 살릴 수 없는데 죽이지 않는다.
+      throw new BadRequestException(SD("setting.noSupervisor")());
+    }
+
+    const { reply } = Sonamu.getContext();
+    const started = beginServerRestart();
+    if (started) {
+      logger.warn(`restart requested via dashboard, exiting for ${supervisor} to respawn`);
+
+      try {
+        // 정적 import로 qgrid.frame/token 그래프를 당겨오면 모듈 목 테스트가 오염된다.
+        // 재시작이 실제로 확정된 시점에 active native run 정합성 처리만 로드한다.
+        const { finishActiveNativeRunsForRestart } = await import("../qgrid/qgrid-run-lifecycle");
+        await finishActiveNativeRunsForRestart();
+      } finally {
+        // 정합성 처리가 실패해도 응답이 flush 된 뒤에는 재시작을 끝까지 진행한다.
+        armServerRestartExit(reply.raw);
+      }
+    }
+
+    return { supervisor };
+  }
 }
 
 export const SettingModel = new SettingModelClass();

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

@@ -21,6 +21,16 @@ export type SettingApplies = z.infer<typeof SettingApplies>;
 export const SettingSource = z.enum(["db", "env", "default"]);
 export type SettingSource = z.infer<typeof SettingSource>;
 
+/**
+ * 프로세스를 다시 띄워주는 도구. 재시작은 스스로 종료하고 이 도구에 맡기므로,
+ * 없으면(null) 화면에서 재시작을 시도조차 하지 않는다.
+ *
+ * API 반환 타입에 쓰이므로 zod 로 둔다 — sonamu syncer 가 클라이언트 코드를 만들 때
+ * 타입만 있는 선언은 모듈을 찾지 못한다.
+ */
+export const SupervisorKind = z.enum(["pm2"]);
+export type SupervisorKind = z.infer<typeof SupervisorKind>;
+
 export const SettingItem = z.object({
   key: z.string(),
   group: z.string(),
@@ -49,5 +59,7 @@ export type RuntimeInfoItem = z.infer<typeof RuntimeInfoItem>;
 export const SettingsResponse = z.object({
   settings: SettingItem.array(),
   runtime: RuntimeInfoItem.array(),
+  /** null 이면 재시작 버튼을 쓸 수 없다 — 종료해도 되살릴 주체가 없다. */
+  supervisor: SupervisorKind.nullable(),
 });
 export type SettingsResponse = z.infer<typeof SettingsResponse>;

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

@@ -124,6 +124,13 @@ Content-Type: application/json
 
 ###
 
+POST {{baseUrl}}/api/setting/restartServer
+Content-Type: application/json
+
+{}
+
+###
+
 GET {{baseUrl}}/api/requestLogStep/findById
 	?subset=A
 	&id=0

package/bundle/src/i18n/en.ts

@@ -49,9 +49,12 @@ export default {
   "error.serviceUnavailable": "Service unavailable",
   "setting.invalidValue": (reason: string) => `Invalid setting value: ${reason}`,
   "setting.unknownKey": (key: string) => `Unknown setting key ${key}`,
+  "setting.noSupervisor": () =>
+    "Restart is unavailable when running locally — nothing would bring the server back up",
   "qgrid.dispatcherFailed": (provider: string) => `${provider} dispatcher failed to initialize`,
   "qgrid.dispatcherStarting": (provider: string) =>
     `${provider} dispatcher is starting up. Please retry shortly`,
+  "qgrid.restartPending": () => "Server restart is in progress. 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

@@ -48,9 +48,12 @@ export default {
   "error.serviceUnavailable": "서비스를 사용할 수 없습니다",
   "setting.invalidValue": (reason: string) => `설정 값이 올바르지 않습니다: ${reason}`,
   "setting.unknownKey": (key: string) => `알 수 없는 설정 키 ${key}`,
+  "setting.noSupervisor": () =>
+    "로컬 실행 환경에서는 재시작할 수 없습니다 — 종료하면 다시 켜줄 모니터링 도구가 없습니다",
   "qgrid.dispatcherFailed": (provider: string) => `${provider} dispatcher 초기화에 실패했습니다`,
   "qgrid.dispatcherStarting": (provider: string) =>
     `${provider} dispatcher 기동 중입니다. 잠시 후 다시 시도해주세요`,
+  "qgrid.restartPending": () => "서버 재시작 중입니다. 잠시 후 다시 시도해주세요",
   "error.unauthorized": "인증이 필요합니다",
   "error.unknownSearchField": (field: string) => `구현되지 않은 검색 필드 ${field}`,
   notFound: (name: string, id: number) => `존재하지 않는 ${name} ID ${id}`,

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

@@ -3,11 +3,18 @@ import {
   BadRequestException,
   InternalServerErrorException,
   ServiceUnavailableException,
+  SoException,
 } from "sonamu";
 import { describe, expect, it, vi } from "vitest";
 
 import { handleServerError } from "./server-error-handler";
 
+class ForbiddenException extends SoException {
+  constructor() {
+    super(403, "forbidden" as never);
+  }
+}
+
 function fakeReply() {
   const reply = {
     header: vi.fn(),
@@ -27,6 +34,14 @@ describe("handleServerError", () => {
     expect(reply.status).toHaveBeenCalledWith(400);
   });
 
+  it("local Sonamu 403 예외도 예외 경계에서 보존한다", () => {
+    const reply = fakeReply();
+
+    handleServerError(new ForbiddenException(), reply);
+
+    expect(reply.status).toHaveBeenCalledWith(403);
+  });
+
   it("Sonamu 예외가 아니면 statusCode 를 신뢰하지 않고 500 으로 내린다", () => {
     const reply = fakeReply();
     // upstream fetch 오류처럼 statusCode 를 달고 오는 예외 — 그대로 에코하면 upstream 의

package/bundle/src/utils/process-supervisor.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vitest";
+
+import { detectSupervisor } from "./process-supervisor";
+
+describe("detectSupervisor", () => {
+  it("pm2 아래에서는 pm2 로 판별한다", () => {
+    // pm2 는 자식에게 pm_id 를 넣는다. "0" 이 흔한 값이라 falsy 검사로는 놓친다.
+    expect(detectSupervisor({ pm_id: "0" })).toBe("pm2");
+  });
+
+  it("systemd 환경변수만으로는 재시작 보장을 가정하지 않는다", () => {
+    expect(detectSupervisor({ INVOCATION_ID: "abc123" })).toBeNull();
+  });
+
+  it("로컬 실행에서는 null 이다", () => {
+    // 종료해도 다시 띄워줄 주체가 없어 재시작을 막아야 한다.
+    expect(detectSupervisor({})).toBeNull();
+  });
+
+  it("빈 문자열도 pm2 로 인정한다", () => {
+    // 값이 아니라 존재 여부가 신호다. pm_id 가 빈 문자열로 오는 환경이 있어도 pm2 다.
+    expect(detectSupervisor({ pm_id: "" })).toBe("pm2");
+  });
+});

package/bundle/src/utils/process-supervisor.ts

@@ -0,0 +1,17 @@
+/**
+ * 프로세스 모니터링 도구 감지.
+ *
+ * 화면의 "재시작"은 스스로를 종료하는 것이다 — pm2 같은 도구가 죽은 프로세스를 다시
+ * 띄워주는 것이 곧 재시작이다. 그래서 그런 도구 없이 종료하면 그냥 서버가 내려간다.
+ * 로컬 개발에서 버튼을 누르면 아무도 살려주지 않으므로, 종료 전에 반드시 확인한다.
+ *
+ * 현재 배포 계약은 pm2 만 재시작을 보장한다. systemd 의 `INVOCATION_ID` 는 해당
+ * unit 이 `Restart=` 를 쓴다는 뜻이 아니므로 안전한 감독자 신호로 사용할 수 없다.
+ *
+ * 값이 아니라 존재 여부가 신호다. pm2 는 첫 프로세스에 `pm_id=0` 을 주므로 truthy 검사로
+ * 판별하면 놓친다.
+ */
+export function detectSupervisor(env: NodeJS.ProcessEnv = process.env): "pm2" | null {
+  if (env.pm_id !== undefined) return "pm2";
+  return null;
+}

package/bundle/src/utils/server-restart.test.ts

@@ -0,0 +1,76 @@
+import { EventEmitter } from "node:events";
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import {
+  armServerRestartExit,
+  beginServerRestart,
+  isRestartPending,
+  resetServerRestartForTests,
+} from "./server-restart";
+
+describe("server restart coordination", () => {
+  afterEach(() => {
+    resetServerRestartForTests();
+    vi.restoreAllMocks();
+    vi.useRealTimers();
+  });
+
+  it("exits exactly once after the first response finishes", () => {
+    const raw = new EventEmitter();
+    const exit = vi.spyOn(process, "exit").mockImplementation((() => undefined) as never);
+
+    expect(beginServerRestart()).toBe(true);
+    expect(beginServerRestart()).toBe(false);
+    expect(isRestartPending()).toBe(true);
+    expect(exit).not.toHaveBeenCalled();
+
+    armServerRestartExit(raw as never);
+    raw.emit("finish");
+    raw.emit("finish");
+
+    expect(exit).toHaveBeenCalledTimes(1);
+    expect(exit).toHaveBeenCalledWith(0);
+  });
+
+  it("uses a finite fallback when the response never finishes", () => {
+    vi.useFakeTimers();
+    const exit = vi.spyOn(process, "exit").mockImplementation((() => undefined) as never);
+
+    beginServerRestart();
+    armServerRestartExit(new EventEmitter() as never);
+    vi.advanceTimersByTime(4_999);
+    expect(exit).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(1);
+    expect(exit).toHaveBeenCalledOnce();
+    expect(exit).toHaveBeenCalledWith(0);
+  });
+
+  it("exits once when the client disconnects before the response finishes", () => {
+    const raw = Object.assign(new EventEmitter(), { destroyed: false, writableEnded: false });
+    const exit = vi.spyOn(process, "exit").mockImplementation((() => undefined) as never);
+
+    beginServerRestart();
+    armServerRestartExit(raw as never);
+    raw.emit("close");
+    raw.emit("finish");
+
+    expect(exit).toHaveBeenCalledOnce();
+    expect(exit).toHaveBeenCalledWith(0);
+  });
+
+  it("does not exit before reconciliation arms the response lifecycle", () => {
+    vi.useFakeTimers();
+    const raw = Object.assign(new EventEmitter(), { destroyed: true, writableEnded: false });
+    const exit = vi.spyOn(process, "exit").mockImplementation((() => undefined) as never);
+
+    beginServerRestart();
+    raw.emit("close");
+    vi.advanceTimersByTime(5_000);
+    expect(exit).not.toHaveBeenCalled();
+
+    armServerRestartExit(raw as never);
+    expect(exit).toHaveBeenCalledOnce();
+  });
+});

package/bundle/src/utils/server-restart.ts

@@ -0,0 +1,68 @@
+import { type ServerResponse } from "node:http";
+
+const RESTART_EXIT_FALLBACK_MS = 5_000;
+
+let restartPending = false;
+let exitTriggered = false;
+let exitArmed = false;
+let fallbackTimer: NodeJS.Timeout | undefined;
+let armedReplyRaw: ReplyRaw | undefined;
+let armedExit: (() => void) | undefined;
+
+type ReplyRaw = Pick<ServerResponse, "once" | "removeListener" | "destroyed" | "writableEnded">;
+
+/** 재시작 요청 뒤에는 새 native provider 실행을 받지 않는다. */
+export function isRestartPending(): boolean {
+  return restartPending;
+}
+
+/**
+ * 프로세스 전체에서 최초 요청만 재시작을 시작한다. 종료 신호는 active run 정합성 처리가
+ * 끝난 뒤 별도로 arm 한다. 그래야 이미 닫힌 연결이나 fallback 타이머가 DB 정리보다 앞서
+ * 프로세스를 끝내지 않는다.
+ */
+export function beginServerRestart(): boolean {
+  if (restartPending) return false;
+  restartPending = true;
+  return true;
+}
+
+function clearExitArm(): void {
+  if (fallbackTimer) clearTimeout(fallbackTimer);
+  fallbackTimer = undefined;
+  if (armedReplyRaw && armedExit) {
+    armedReplyRaw.removeListener("finish", armedExit);
+    armedReplyRaw.removeListener("close", armedExit);
+  }
+  armedReplyRaw = undefined;
+  armedExit = undefined;
+}
+
+/** 정합성 처리가 끝난 뒤 HTTP 응답 flush/연결 종료/유한 fallback 중 먼저 온 신호로 종료한다. */
+export function armServerRestartExit(replyRaw: ReplyRaw): void {
+  if (!restartPending || exitArmed) return;
+  exitArmed = true;
+
+  const exitOnce = () => {
+    if (exitTriggered) return;
+    exitTriggered = true;
+    clearExitArm();
+    process.exit(0);
+  };
+
+  armedReplyRaw = replyRaw;
+  armedExit = exitOnce;
+  replyRaw.once("finish", exitOnce);
+  replyRaw.once("close", exitOnce);
+  fallbackTimer = setTimeout(exitOnce, RESTART_EXIT_FALLBACK_MS);
+  fallbackTimer.unref();
+  if (replyRaw.destroyed && !replyRaw.writableEnded) exitOnce();
+}
+
+/** 모듈 전역 상태를 격리해야 하는 단위 테스트 전용. */
+export function resetServerRestartForTests(): void {
+  clearExitArm();
+  restartPending = false;
+  exitTriggered = false;
+  exitArmed = false;
+}