fix(shutdown): make runCleanup idempotent under concurrent calls (LIB-HIGH-003)

lib/shutdown.ts

@@ -2,6 +2,7 @@ type CleanupFn = () => void | Promise<void>;
 
 const cleanupFunctions: CleanupFn[] = [];
 let shutdownRegistered = false;
+let cleanupPromise: Promise<void> | null = null;
 
 export function registerCleanup(fn: CleanupFn): void {
 	cleanupFunctions.push(fn);
@@ -15,17 +16,27 @@ export function unregisterCleanup(fn: CleanupFn): void {
 	}
 }
 
-export async function runCleanup(): Promise<void> {
-	const fns = [...cleanupFunctions];
-	cleanupFunctions.length = 0;
+export function runCleanup(): Promise<void> {
+	if (cleanupPromise) {
+		return cleanupPromise;
+	}
+
+	cleanupPromise = (async () => {
+		const fns = [...cleanupFunctions];
+		cleanupFunctions.length = 0;
 
-	for (const fn of fns) {
-		try {
-			await fn();
-		} catch {
-			// Ignore cleanup errors during shutdown
+		for (const fn of fns) {
+			try {
+				await fn();
+			} catch {
+				// Ignore cleanup errors during shutdown
+			}
 		}
-	}
+	})().finally(() => {
+		cleanupPromise = null;
+	});
+
+	return cleanupPromise;
 }
 
 function ensureShutdownHandler(): void {

test/shutdown.test.ts

@@ -29,7 +29,7 @@ describe("Graceful shutdown", () => {
 		expect(fn).not.toHaveBeenCalled();
 	});
 
-	it("runs multiple cleanup functions in order", async () => {
+	it("runs multiple cleanup functions in registration order", async () => {
 		const order: number[] = [];
 		registerCleanup(() => { order.push(1); });
 		registerCleanup(() => { order.push(2); });
@@ -65,6 +65,26 @@ describe("Graceful shutdown", () => {
 		expect(getCleanupCount()).toBe(0);
 	});
 
+	it("returns the same promise for concurrent runCleanup calls", async () => {
+		let release!: () => void;
+		const blocker = new Promise<void>((resolve) => {
+			release = resolve;
+		});
+		const cleanupFn = vi.fn(async () => {
+			await blocker;
+		});
+		registerCleanup(cleanupFn);
+
+		const first = runCleanup();
+		const second = runCleanup();
+
+		expect(first).toBe(second);
+		expect(cleanupFn).toHaveBeenCalledTimes(1);
+
+		release();
+		await first;
+	});
+
 	it("unregister is no-op for non-registered function", () => {
 		const fn = vi.fn();
 		unregisterCleanup(fn);