@tonyclaw/agent-inspector 3.0.29 → 3.0.31

package/src/proxy/rawStreamCapture.ts

@@ -1,10 +1,18 @@
+import assert from "node:assert/strict";
 import { Buffer } from "node:buffer";
 import { randomUUID } from "node:crypto";
-import { mkdir, appendFile, writeFile } from "node:fs/promises";
+import { open, unlink, type FileHandle } from "node:fs/promises";
 import { join } from "node:path";
 import { getDataDir } from "./dataDir";
+import {
+  ensurePrivateDirectorySync,
+  PRIVATE_FILE_MODE,
+  securePrivateFileSync,
+} from "./privateDataPath";
 
 const DEFAULT_MEMORY_LIMIT_BYTES = 1024 * 1024;
+const FILE_WRITE_BATCH_BYTES = 64 * 1024;
+const activeCaptures = new Set<RawStreamCapture>();
 
 export type RawStreamSource =
   | {
@@ -37,10 +45,16 @@ export class RawStreamCapture {
   private chunks: string[] = [];
   private byteLength = 0;
   private filePath: string | null = null;
+  private fileHandle: FileHandle | null = null;
+  private pendingFileChunks: string[] = [];
+  private pendingFileBytes = 0;
+  private operation = Promise.resolve();
+  private closed = false;
   private sawChunk = false;
 
   constructor(memoryLimitBytes: number = resolveMemoryLimitBytes()) {
     this.memoryLimitBytes = memoryLimitBytes;
+    activeCaptures.add(this);
   }
 
   get hasChunks(): boolean {
@@ -49,6 +63,22 @@ export class RawStreamCapture {
 
   async append(text: string): Promise<void> {
     if (text === "") return;
+    const next = this.operation.then(() => this.appendInternal(text));
+    this.operation = next.catch(() => undefined);
+    return next;
+  }
+
+  async finalize(): Promise<RawStreamSource> {
+    const next = this.operation.then(() => this.finalizeInternal());
+    this.operation = next.then(
+      () => undefined,
+      () => undefined,
+    );
+    return next.finally(() => activeCaptures.delete(this));
+  }
+
+  private async appendInternal(text: string): Promise<void> {
+    if (this.closed) return;
     this.sawChunk = true;
 
     const nextBytes = Buffer.byteLength(text, "utf-8");
@@ -63,12 +93,23 @@ export class RawStreamCapture {
     }
 
     if (this.filePath !== null) {
-      await appendFile(this.filePath, text, "utf-8");
+      this.pendingFileChunks.push(text);
+      this.pendingFileBytes += nextBytes;
       this.byteLength += nextBytes;
+      if (this.pendingFileBytes >= FILE_WRITE_BATCH_BYTES) await this.flushFileBuffer();
     }
   }
 
-  snapshot(): RawStreamSource {
+  private async finalizeInternal(): Promise<RawStreamSource> {
+    if (!this.closed) {
+      this.closed = true;
+      await this.flushFileBuffer();
+      if (this.fileHandle !== null) {
+        await this.fileHandle.sync();
+        await this.fileHandle.close();
+        this.fileHandle = null;
+      }
+    }
     if (this.filePath !== null) {
       return { type: "file", path: this.filePath };
     }
@@ -77,9 +118,29 @@ export class RawStreamCapture {
 
   private async spillToFile(): Promise<void> {
     const path = createRawStreamPath();
-    await mkdir(getRawStreamDir(), { recursive: true });
-    await writeFile(path, this.chunks.join(""), "utf-8");
+    assert(ensurePrivateDirectorySync(getRawStreamDir()), "Could not secure raw-stream directory");
+    const handle = await open(path, "wx", PRIVATE_FILE_MODE);
+    const memoryText = this.chunks.join("");
+    if (memoryText.length > 0) await handle.write(memoryText, undefined, "utf-8");
+    if (!securePrivateFileSync(path)) {
+      await handle.close();
+      await unlink(path);
+      assert(false, "Could not secure raw-stream file");
+    }
     this.filePath = path;
+    this.fileHandle = handle;
     this.chunks = [];
   }
+
+  private async flushFileBuffer(): Promise<void> {
+    if (this.fileHandle === null || this.pendingFileChunks.length === 0) return;
+    const text = this.pendingFileChunks.join("");
+    this.pendingFileChunks = [];
+    this.pendingFileBytes = 0;
+    await this.fileHandle.write(text, undefined, "utf-8");
+  }
+}
+
+export async function flushAllRawStreamCaptures(): Promise<void> {
+  await Promise.all([...activeCaptures].map((capture) => capture.finalize()));
 }

package/src/proxy/runStore.ts

@@ -1,4 +1,5 @@
-import { mkdirSync, writeFileSync } from "node:fs";
+import assert from "node:assert/strict";
+import { writeFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { dirname, join } from "node:path";
 import { z } from "zod";
@@ -14,6 +15,11 @@ import {
 import { getDataDir } from "./dataDir";
 import { addGroupSession, getGroup } from "./groupStore";
 import { readJsonFile } from "../lib/jsonFile";
+import {
+  ensurePrivateDirectorySync,
+  PRIVATE_FILE_MODE,
+  securePrivateFileSync,
+} from "./privateDataPath";
 
 const RunsFileSchema = z.object({
   runs: z.array(InspectorRunSchema),
@@ -102,8 +108,12 @@ function readRuns(): InspectorRun[] {
 
 function writeRuns(runs: readonly InspectorRun[]): void {
   const filePath = runsFilePath();
-  mkdirSync(dirname(filePath), { recursive: true });
-  writeFileSync(filePath, `${JSON.stringify({ runs }, null, 2)}\n`, "utf8");
+  assert(ensurePrivateDirectorySync(dirname(filePath)), "Could not secure runs directory");
+  writeFileSync(filePath, `${JSON.stringify({ runs }, null, 2)}\n`, {
+    encoding: "utf8",
+    mode: PRIVATE_FILE_MODE,
+  });
+  assert(securePrivateFileSync(filePath), "Could not secure runs file");
 }
 
 export function listRuns(): InspectorRun[] {

package/src/proxy/runtimeAdmission.ts

@@ -0,0 +1,52 @@
+export type RuntimeRequestLease = {
+  release: () => void;
+};
+
+let acceptingRequests = true;
+let activeRequests = 0;
+const drainWaiters = new Set<() => void>();
+
+function notifyDrained(): void {
+  if (activeRequests !== 0) return;
+  for (const resolve of drainWaiters) resolve();
+  drainWaiters.clear();
+}
+
+export function acquireRuntimeRequest(): RuntimeRequestLease | null {
+  if (!acceptingRequests) return null;
+  activeRequests += 1;
+  let released = false;
+  return {
+    release(): void {
+      if (released) return;
+      released = true;
+      activeRequests = Math.max(0, activeRequests - 1);
+      notifyDrained();
+    },
+  };
+}
+
+export function stopRuntimeAdmission(): void {
+  acceptingRequests = false;
+  notifyDrained();
+}
+
+export async function waitForRuntimeTrafficDrain(): Promise<void> {
+  if (activeRequests === 0) return;
+  await new Promise<void>((resolve) => {
+    drainWaiters.add(resolve);
+  });
+}
+
+export function getRuntimeAdmissionState(): {
+  acceptingRequests: boolean;
+  activeRequests: number;
+} {
+  return { acceptingRequests, activeRequests };
+}
+
+export function _resetRuntimeAdmissionForTests(): void {
+  acceptingRequests = true;
+  activeRequests = 0;
+  notifyDrained();
+}

package/src/proxy/runtimeHealth.ts

@@ -0,0 +1,206 @@
+import { randomUUID } from "node:crypto";
+import { writeFile, rm, statfs } from "node:fs/promises";
+import { join } from "node:path";
+import { getDataDir } from "./dataDir";
+import { getFinalizerRuntimeHealth } from "./logFinalizer";
+import { ensurePrivateDirectorySync, PRIVATE_FILE_MODE } from "./privateDataPath";
+import { isSqliteLogIndexReady } from "./sqliteLogIndex";
+
+const DEFAULT_CACHE_MS = 2_000;
+const DEFAULT_MIN_DISK_HEADROOM_BYTES = 256 * 1024 * 1024;
+const DEFAULT_MAX_FINALIZER_QUEUE = 256;
+
+export type ReadinessLevel = "ready" | "degraded" | "unavailable";
+export type ReadinessCheckLevel = "ok" | "degraded" | "unavailable";
+
+export type SafeReadiness = {
+  status: ReadinessLevel;
+  checks: {
+    storage: ReadinessCheckLevel;
+    disk: ReadinessCheckLevel;
+    workers: ReadinessCheckLevel;
+    index: ReadinessCheckLevel;
+    queue: ReadinessCheckLevel;
+    shutdown: ReadinessCheckLevel;
+  };
+  checkedAt: string;
+};
+
+export type ReadinessDependencies = {
+  checkStorage: () => Promise<ReadinessCheckLevel>;
+  checkDisk: () => Promise<ReadinessCheckLevel>;
+  checkWorkers: () => Promise<ReadinessCheckLevel>;
+  checkIndex: () => Promise<ReadinessCheckLevel>;
+  checkQueue: () => Promise<ReadinessCheckLevel>;
+  checkShutdown: () => Promise<ReadinessCheckLevel>;
+  now: () => number;
+};
+
+export type ReadinessService = {
+  get: () => Promise<SafeReadiness>;
+  invalidate: () => void;
+};
+
+let runtimeShuttingDown = false;
+
+function configuredPositiveInteger(name: string, fallback: number): number {
+  const raw = process.env[name];
+  if (raw === undefined || raw === "") return fallback;
+  const parsed = Number(raw);
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+async function checkStorageWritable(): Promise<ReadinessCheckLevel> {
+  const dataDir = getDataDir();
+  if (!ensurePrivateDirectorySync(dataDir)) return "unavailable";
+  const probePath = join(dataDir, `.readiness-${String(process.pid)}-${randomUUID()}`);
+  try {
+    await writeFile(probePath, "", { flag: "wx", mode: PRIVATE_FILE_MODE });
+    return "ok";
+  } catch {
+    return "unavailable";
+  } finally {
+    await rm(probePath, { force: true }).catch(() => undefined);
+  }
+}
+
+async function checkDiskHeadroom(): Promise<ReadinessCheckLevel> {
+  try {
+    const stats = await statfs(getDataDir());
+    const availableBytes = stats.bavail * stats.bsize;
+    const minimumBytes = configuredPositiveInteger(
+      "AGENT_INSPECTOR_MIN_DISK_HEADROOM_BYTES",
+      DEFAULT_MIN_DISK_HEADROOM_BYTES,
+    );
+    return availableBytes >= minimumBytes ? "ok" : "unavailable";
+  } catch {
+    return "degraded";
+  }
+}
+
+function finalizerChecks(): {
+  workers: ReadinessCheckLevel;
+  queue: ReadinessCheckLevel;
+} {
+  const health = getFinalizerRuntimeHealth();
+  const runtimeArtifactMissing = health.runtime !== "inline" && !health.artifactAvailable;
+  const initializedWorkerMissing =
+    health.runtime === "worker" &&
+    health.activeWorkers !== null &&
+    health.activeWorkers < health.configuredWorkers;
+  const workers =
+    runtimeArtifactMissing || initializedWorkerMissing
+      ? "unavailable"
+      : health.runtime === "inline"
+        ? "degraded"
+        : "ok";
+
+  const queueLimit = configuredPositiveInteger(
+    "AGENT_INSPECTOR_READY_MAX_FINALIZER_QUEUE",
+    DEFAULT_MAX_FINALIZER_QUEUE,
+  );
+  const warningThreshold = Math.max(1, Math.floor(queueLimit * 0.8));
+  const queue =
+    health.pendingJobs >= queueLimit
+      ? "unavailable"
+      : health.pendingJobs >= warningThreshold
+        ? "degraded"
+        : "ok";
+  return { workers, queue };
+}
+
+function checkWorkers(): Promise<ReadinessCheckLevel> {
+  return Promise.resolve(finalizerChecks().workers);
+}
+
+function checkQueue(): Promise<ReadinessCheckLevel> {
+  return Promise.resolve(finalizerChecks().queue);
+}
+
+async function checkIndex(): Promise<ReadinessCheckLevel> {
+  return (await isSqliteLogIndexReady()) ? "ok" : "degraded";
+}
+
+function checkShutdown(): Promise<ReadinessCheckLevel> {
+  return Promise.resolve(runtimeShuttingDown ? "unavailable" : "ok");
+}
+
+function readinessLevel(checks: SafeReadiness["checks"]): ReadinessLevel {
+  const levels = Object.values(checks);
+  if (levels.some((level) => level === "unavailable")) return "unavailable";
+  return levels.some((level) => level === "degraded") ? "degraded" : "ready";
+}
+
+export function createReadinessService(
+  dependencies: ReadinessDependencies,
+  cacheMs = DEFAULT_CACHE_MS,
+): ReadinessService {
+  let cached: { expiresAt: number; value: SafeReadiness } | null = null;
+  let inFlight: Promise<SafeReadiness> | null = null;
+
+  async function evaluate(): Promise<SafeReadiness> {
+    // Establish the directory before checking its filesystem. On a clean install
+    // the data directory may not exist until the first write probe creates it.
+    const storage = await dependencies.checkStorage();
+    const [disk, workers, index, queue, shutdown] = await Promise.all([
+      dependencies.checkDisk(),
+      dependencies.checkWorkers(),
+      dependencies.checkIndex(),
+      dependencies.checkQueue(),
+      dependencies.checkShutdown(),
+    ]);
+    const checks = { storage, disk, workers, index, queue, shutdown };
+    return {
+      status: readinessLevel(checks),
+      checks,
+      checkedAt: new Date(dependencies.now()).toISOString(),
+    };
+  }
+
+  async function get(): Promise<SafeReadiness> {
+    const now = dependencies.now();
+    if (cached !== null && cached.expiresAt > now) return cached.value;
+    if (inFlight !== null) return await inFlight;
+
+    const evaluation = evaluate();
+    inFlight = evaluation;
+    try {
+      const value = await evaluation;
+      cached = { expiresAt: dependencies.now() + Math.max(0, cacheMs), value };
+      return value;
+    } finally {
+      if (inFlight === evaluation) inFlight = null;
+    }
+  }
+
+  function invalidate(): void {
+    cached = null;
+  }
+
+  return { get, invalidate };
+}
+
+const readinessService = createReadinessService({
+  checkStorage: checkStorageWritable,
+  checkDisk: checkDiskHeadroom,
+  checkWorkers,
+  checkIndex,
+  checkQueue,
+  checkShutdown,
+  now: Date.now,
+});
+
+export async function getRuntimeReadiness(): Promise<SafeReadiness> {
+  return await readinessService.get();
+}
+
+/** Shutdown coordination will call this before stopping admission. */
+export function setRuntimeShuttingDown(shuttingDown: boolean): void {
+  runtimeShuttingDown = shuttingDown;
+  readinessService.invalidate();
+}
+
+export function _resetRuntimeHealthForTests(): void {
+  runtimeShuttingDown = false;
+  readinessService.invalidate();
+}

package/src/proxy/runtimeShutdown.ts

@@ -0,0 +1,75 @@
+import { closeLogFinalizerWorkers, forceCloseLogFinalizerWorkers } from "./logFinalizer";
+import { flushIndex } from "./logIndex";
+import { flushApplicationLog, flushLogBuffer } from "./logger";
+import { flushAllRawStreamCaptures } from "./rawStreamCapture";
+import { setRuntimeShuttingDown } from "./runtimeHealth";
+import { stopRuntimeAdmission, waitForRuntimeTrafficDrain } from "./runtimeAdmission";
+import { createShutdownCoordinator, createShutdownSignalHandler } from "./shutdownCoordinator";
+import { destroyAllSessionProcesses } from "./sessionProcess";
+import { flushSessionTasks } from "./sessionRuntime";
+import { closeSqliteLogIndex } from "./sqliteLogIndex";
+import { flushSessionArchiveWrites } from "./store";
+import { flushToolSchemaWarningAnalysis } from "./logFinalizer";
+
+const DEFAULT_SHUTDOWN_DEADLINE_MS = 15_000;
+
+function shutdownDeadlineMs(): number {
+  const raw = process.env["AGENT_INSPECTOR_SHUTDOWN_TIMEOUT_MS"];
+  if (raw === undefined || raw === "") return DEFAULT_SHUTDOWN_DEADLINE_MS;
+  const parsed = Number(raw);
+  return Number.isSafeInteger(parsed) && parsed > 0 && parsed <= 300_000
+    ? parsed
+    : DEFAULT_SHUTDOWN_DEADLINE_MS;
+}
+
+async function drainFinalizers(): Promise<void> {
+  await flushAllRawStreamCaptures();
+  await flushSessionTasks();
+  await flushToolSchemaWarningAnalysis();
+}
+
+async function flushPersistence(): Promise<void> {
+  await flushLogBuffer();
+  await flushSessionArchiveWrites();
+  await flushIndex();
+  await flushApplicationLog();
+}
+
+async function closeResources(): Promise<void> {
+  await closeLogFinalizerWorkers();
+  destroyAllSessionProcesses();
+  closeSqliteLogIndex();
+  await flushApplicationLog();
+}
+
+function forceCloseResources(): void {
+  forceCloseLogFinalizerWorkers();
+  destroyAllSessionProcesses();
+  closeSqliteLogIndex();
+}
+
+const runtimeShutdownCoordinator = createShutdownCoordinator(
+  {
+    markShuttingDown: () => setRuntimeShuttingDown(true),
+    stopAdmission: stopRuntimeAdmission,
+    drainTraffic: waitForRuntimeTrafficDrain,
+    drainFinalizers,
+    flushPersistence,
+    closeResources,
+    forceClose: forceCloseResources,
+  },
+  shutdownDeadlineMs(),
+);
+
+let signalHandlersInstalled = false;
+
+/** Install once in the server runtime; the CLI supervisor owns its own public-ingress signals. */
+export function installRuntimeShutdownSignalHandlers(): void {
+  if (signalHandlersInstalled) return;
+  signalHandlersInstalled = true;
+  const handleSignal = createShutdownSignalHandler(runtimeShutdownCoordinator, (result) => {
+    process.exit(result.forced ? 1 : 0);
+  });
+  process.on("SIGINT", () => handleSignal("SIGINT"));
+  process.on("SIGTERM", () => handleSignal("SIGTERM"));
+}

package/src/proxy/sessionArchive.ts

@@ -1,9 +1,10 @@
 import { createHash } from "node:crypto";
 import { existsSync } from "node:fs";
-import { mkdir, readdir, rm } from "node:fs/promises";
+import { readdir, rm } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { CapturedLogSchema, type CapturedLog } from "./schemas";
 import { logger, resolveLogDir } from "./logger";
+import { ensurePrivateDirectorySync, securePrivateFileSync } from "./privateDataPath";
 
 type SqliteConstructorResult = {
   constructor: ((path: string) => unknown) | null;
@@ -207,10 +208,22 @@ async function openSessionArchiveDb(filePath: string, create: boolean): Promise<
   }
 
   try {
-    if (create) await mkdir(dirname(filePath), { recursive: true });
+    if (!create && !existsSync(filePath)) return null;
+    if (!ensurePrivateDirectorySync(dirname(filePath))) {
+      logger.warn("[sessionArchive] Failed to secure archive directory:", dirname(filePath));
+      return null;
+    }
     const db = sqliteConstructor.constructor(filePath);
     execSql(db, "PRAGMA journal_mode = WAL");
     execSql(db, "PRAGMA synchronous = NORMAL");
+    if (!securePrivateFileSync(filePath, true)) {
+      closeDatabase(db);
+      logger.warn("[sessionArchive] Failed to secure archive database:", filePath);
+      return null;
+    }
+    for (const sidecarPath of [`${filePath}-wal`, `${filePath}-shm`]) {
+      if (existsSync(sidecarPath)) void securePrivateFileSync(sidecarPath);
+    }
     if (!execSql(db, CREATE_SCHEMA_SQL)) {
       closeDatabase(db);
       logger.warn("[sessionArchive] Failed to initialize schema:", filePath);

package/src/proxy/sessionProcess.ts

@@ -1,6 +1,7 @@
 import { spawn, type ChildProcess } from "node:child_process";
 import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
+import { join } from "node:path";
 import { logger } from "./logger";
 import type { FinalizeLogJob, FinalizeLogResult } from "./logFinalizer";
 import { isPlainRecord, safeGetOwnProperty } from "../lib/objectUtils";
@@ -20,6 +21,11 @@ function errorMessage(err: unknown): string {
 }
 
 function resolveSessionWorkerPath(): string {
+  const workerDir = process.env["AGENT_INSPECTOR_WORKER_DIR"];
+  if (workerDir !== undefined && workerDir.trim().length > 0) {
+    const builtWorkerPath = join(workerDir, "sessionWorkerEntry.js");
+    if (existsSync(builtWorkerPath)) return builtWorkerPath;
+  }
   return fileURLToPath(new URL("./sessionWorkerEntry.ts", import.meta.url));
 }
 
@@ -153,6 +159,10 @@ export class SessionProcess {
       this.child.kill();
       this.child = null;
     }
+    for (const [, pending] of this.pending) {
+      pending.reject(new Error(`Session process shut down, session=${this.sessionId}`));
+    }
+    this.pending.clear();
     _processes.delete(this.sessionId);
   }
 }
@@ -167,6 +177,15 @@ export function getSessionProcess(sessionId: string): SessionProcess {
   return sp;
 }
 
+/** Aggregate only queue depth for readiness; session identifiers remain private. */
+export function getSessionProcessPendingCount(): number {
+  let pending = 0;
+  for (const processWorker of _processes.values()) {
+    pending += processWorker.pendingCount;
+  }
+  return pending;
+}
+
 /** Forcefully tear down all session processes (e.g. on server shutdown). */
 export function destroyAllSessionProcesses(): void {
   for (const [, sp] of _processes) {

package/src/proxy/sessionRuntime.ts

@@ -74,3 +74,10 @@ export function enqueueFinalizeLogJob(job: FinalizeLogJob): Promise<void> {
     executeFinalizeLogJob(job),
   );
 }
+
+/** Wait until every per-session finalizer queue has settled. */
+export async function flushSessionTasks(): Promise<void> {
+  while (queues.size > 0) {
+    await Promise.all([...queues.values()]);
+  }
+}

package/src/proxy/shutdownCoordinator.ts

@@ -0,0 +1,90 @@
+export type ShutdownReason = "SIGINT" | "SIGTERM" | "manual";
+
+export type ShutdownResult = {
+  forced: boolean;
+  reason: "completed" | "deadline" | "error";
+};
+
+export type ShutdownDependencies = {
+  markShuttingDown: () => void;
+  stopAdmission: () => void;
+  drainTraffic: () => Promise<void>;
+  drainFinalizers: () => Promise<void>;
+  flushPersistence: () => Promise<void>;
+  closeResources: () => Promise<void>;
+  forceClose: () => void;
+};
+
+export type ShutdownCoordinator = {
+  shutdown: (reason?: ShutdownReason) => Promise<ShutdownResult>;
+};
+
+export function createShutdownCoordinator(
+  dependencies: ShutdownDependencies,
+  deadlineMs: number,
+): ShutdownCoordinator {
+  let shutdownPromise: Promise<ShutdownResult> | null = null;
+
+  async function shutdown(_reason: ShutdownReason = "manual"): Promise<ShutdownResult> {
+    if (shutdownPromise !== null) return await shutdownPromise;
+
+    dependencies.markShuttingDown();
+    dependencies.stopAdmission();
+
+    let forced = false;
+    let forceClosed = false;
+    let deadline: ReturnType<typeof setTimeout> | null = null;
+
+    function forceCloseOnce(): void {
+      if (forceClosed) return;
+      forceClosed = true;
+      dependencies.forceClose();
+    }
+
+    async function gracefulShutdown(): Promise<ShutdownResult> {
+      try {
+        await dependencies.drainTraffic();
+        if (forced) return { forced: true, reason: "deadline" };
+        await dependencies.drainFinalizers();
+        if (forced) return { forced: true, reason: "deadline" };
+        await dependencies.flushPersistence();
+        if (forced) return { forced: true, reason: "deadline" };
+        await dependencies.closeResources();
+        return { forced: false, reason: "completed" };
+      } catch {
+        forceCloseOnce();
+        return { forced: true, reason: "error" };
+      }
+    }
+
+    const timedOut = new Promise<ShutdownResult>((resolve) => {
+      deadline = setTimeout(
+        () => {
+          forced = true;
+          forceCloseOnce();
+          resolve({ forced: true, reason: "deadline" });
+        },
+        Math.max(1, deadlineMs),
+      );
+    });
+
+    shutdownPromise = Promise.race([gracefulShutdown(), timedOut]).finally(() => {
+      if (deadline !== null) clearTimeout(deadline);
+    });
+    return await shutdownPromise;
+  }
+
+  return { shutdown };
+}
+
+export function createShutdownSignalHandler(
+  coordinator: ShutdownCoordinator,
+  onComplete: (result: ShutdownResult) => void,
+): (signal: "SIGINT" | "SIGTERM") => void {
+  let handled = false;
+  return (signal): void => {
+    if (handled) return;
+    handled = true;
+    void coordinator.shutdown(signal).then(onComplete);
+  };
+}