fix(mcp): Add shutdown timeout headroom

Add explicit outer-step headroom for bulk cleanup so one-item and multi-item\nsteps are less likely to report false timeouts at the boundary.\n\nIncrease debugger dispose-all shutdown budget based on active session\ncount to align with debugger manager detach/dispose behavior.\n\nAdd regression coverage for one-item bulk headroom and debugger\ndispose-all timeout budgeting.

Co-Authored-By: OpenAI Codex <noreply@openai.com>

Author: cameroncooke

src/server/__tests__/mcp-shutdown.test.ts

@@ -106,7 +106,44 @@ describe('runMcpShutdown', () => {
     expect(mocks.stopAllTrackedProcesses).toHaveBeenCalledTimes(1);
   });
 
-  it('uses an expanded timeout budget for sequential bulk cleanup steps', async () => {
+  it('adds outer timeout headroom for one-item bulk cleanup', async () => {
+    mocks.stopAllLogCaptures.mockImplementationOnce(async () => {
+      await wait(1050);
+      return { stoppedSessionCount: 1, errorCount: 0, errors: [] };
+    });
+
+    const result = await runMcpShutdown({
+      reason: 'sigterm',
+      snapshot: {
+        pid: 1,
+        ppid: 1,
+        orphaned: false,
+        phase: 'running',
+        shutdownReason: 'sigterm',
+        uptimeMs: 100,
+        rssBytes: 1,
+        heapUsedBytes: 1,
+        watcherRunning: false,
+        watchedPath: null,
+        activeOperationCount: 0,
+        activeOperationByCategory: {},
+        debuggerSessionCount: 0,
+        simulatorLogSessionCount: 1,
+        deviceLogSessionCount: 0,
+        videoCaptureSessionCount: 0,
+        swiftPackageProcessCount: 0,
+        matchingMcpProcessCount: 0,
+        matchingMcpPeerSummary: [],
+        anomalies: [],
+      },
+      server: { close: async () => undefined },
+    });
+
+    const simulatorLogsStep = result.steps.find((step) => step.name === 'simulator-logs.stop-all');
+    expect(simulatorLogsStep?.status).toBe('completed');
+  });
+
+  it('uses an expanded timeout budget for sequential multi-item bulk cleanup steps', async () => {
     mocks.stopAllLogCaptures.mockImplementationOnce(async () => {
       await wait(1100);
       return { stoppedSessionCount: 2, errorCount: 0, errors: [] };
@@ -142,4 +179,40 @@ describe('runMcpShutdown', () => {
     const simulatorLogsStep = result.steps.find((step) => step.name === 'simulator-logs.stop-all');
     expect(simulatorLogsStep?.status).toBe('completed');
   });
+
+  it('uses a larger timeout budget for debugger dispose-all', async () => {
+    mocks.disposeAll.mockImplementationOnce(async () => {
+      await wait(1500);
+    });
+
+    const result = await runMcpShutdown({
+      reason: 'sigterm',
+      snapshot: {
+        pid: 1,
+        ppid: 1,
+        orphaned: false,
+        phase: 'running',
+        shutdownReason: 'sigterm',
+        uptimeMs: 100,
+        rssBytes: 1,
+        heapUsedBytes: 1,
+        watcherRunning: false,
+        watchedPath: null,
+        activeOperationCount: 0,
+        activeOperationByCategory: {},
+        debuggerSessionCount: 1,
+        simulatorLogSessionCount: 0,
+        deviceLogSessionCount: 0,
+        videoCaptureSessionCount: 0,
+        swiftPackageProcessCount: 0,
+        matchingMcpProcessCount: 0,
+        matchingMcpPeerSummary: [],
+        anomalies: [],
+      },
+      server: { close: async () => undefined },
+    });
+
+    const debuggerStep = result.steps.find((step) => step.name === 'debugger.dispose-all');
+    expect(debuggerStep?.status).toBe('completed');
+  });
 });

src/server/mcp-shutdown.ts

@@ -18,6 +18,8 @@ import { isTransportDisconnectReason } from './mcp-lifecycle.ts';
 const DISCONNECT_SERVER_CLOSE_TIMEOUT_MS = 150;
 const DEFAULT_SERVER_CLOSE_TIMEOUT_MS = 1000;
 const STEP_TIMEOUT_MS = 1000;
+const STEP_TIMEOUT_HEADROOM_MS = 100;
+const DEBUGGER_STEP_BASE_TIMEOUT_MS = 2200;
 const DISCONNECT_FLUSH_TIMEOUT_MS = 250;
 const DEFAULT_FLUSH_TIMEOUT_MS = 1500;
 
@@ -166,7 +168,19 @@ export async function runMcpShutdown(input: {
 
   const perItemTimeoutMs = STEP_TIMEOUT_MS;
   const bulkStepTimeoutMs = (itemCount: number): number => {
-    return Math.max(STEP_TIMEOUT_MS, itemCount * perItemTimeoutMs);
+    const boundedCount = Math.max(1, itemCount);
+    return Math.max(
+      STEP_TIMEOUT_MS + STEP_TIMEOUT_HEADROOM_MS,
+      boundedCount * perItemTimeoutMs + STEP_TIMEOUT_HEADROOM_MS,
+    );
+  };
+
+  const debuggerStepTimeoutMs = (debuggerSessionCount: number): number => {
+    const boundedCount = Math.max(1, debuggerSessionCount);
+    return Math.max(
+      DEBUGGER_STEP_BASE_TIMEOUT_MS,
+      boundedCount * STEP_TIMEOUT_MS + STEP_TIMEOUT_HEADROOM_MS,
+    );
   };
 
   const cleanupSteps: Array<{
@@ -182,7 +196,7 @@ export async function runMcpShutdown(input: {
     },
     {
       name: 'debugger.dispose-all',
-      timeoutMs: STEP_TIMEOUT_MS,
+      timeoutMs: debuggerStepTimeoutMs(input.snapshot.debuggerSessionCount),
       operation: () => getDefaultDebuggerManager().disposeAll(),
     },
     {