fix: graceful SIGINT/SIGTERM signal handling + 22 tests

packages/squad-cli/src/cli-entry.ts

@@ -74,6 +74,25 @@ try {
   );
 }
 
+// ---------------------------------------------------------------------------
+// Top-level signal handlers — safety net for clean exit on Ctrl+C / SIGTERM.
+// Individual commands (shell, watch, aspire, rc) register their own handlers
+// that run first; these ensure the process never hangs if a command doesn't.
+// ---------------------------------------------------------------------------
+let _exitingOnSignal = false;
+function _handleTopLevelSignal(signal: 'SIGINT' | 'SIGTERM'): void {
+  const code = signal === 'SIGINT' ? 130 : 143;
+  if (_exitingOnSignal) {
+    // Second signal — force exit immediately
+    process.exit(code);
+  }
+  _exitingOnSignal = true;
+  // Allow in-flight cleanup handlers a brief window, then force exit
+  setTimeout(() => process.exit(code), 3_000).unref();
+}
+process.on('SIGINT', () => _handleTopLevelSignal('SIGINT'));
+process.on('SIGTERM', () => _handleTopLevelSignal('SIGTERM'));
+
 import fs from 'node:fs';
 import path from 'node:path';
 import { fatal, SquadError } from './cli/core/errors.js';

packages/squad-cli/src/cli/shell/index.ts

@@ -1158,7 +1158,7 @@ export async function runShell(): Promise<void> {
   // Also ensures we start from a clean viewport before Ink renders.
   process.stdout.write('\x1b[2J\x1b[3J\x1b[H');
 
-  const { waitUntilExit } = render(
+  const { waitUntilExit, unmount } = render(
     React.createElement(ErrorBoundary, null,
       React.createElement(App, {
         registry,
@@ -1233,6 +1233,25 @@ export async function runShell(): Promise<void> {
   // Clear the loading message now that Ink is rendering
   process.stderr.write('\r\x1b[K');
 
+  // Signal handlers for graceful exit — prevents orphaned child processes on Ctrl+C.
+  // Calling unmount() causes waitUntilExit() to resolve, triggering the normal
+  // cleanup path below (session close, client disconnect, telemetry shutdown).
+  let _shellSignalCode: number | undefined;
+  let _shellExiting = false;
+  const handleShellSignal = (signal: 'SIGINT' | 'SIGTERM'): void => {
+    const code = signal === 'SIGINT' ? 130 : 143;
+    if (_shellExiting) {
+      // Second signal — force exit immediately
+      process.exit(code);
+    }
+    _shellExiting = true;
+    _shellSignalCode = code;
+    debugLog(`Received ${signal}, unmounting shell...`);
+    unmount();
+  };
+  process.on('SIGINT', () => handleShellSignal('SIGINT'));
+  process.on('SIGTERM', () => handleShellSignal('SIGTERM'));
+
   await waitUntilExit();
 
   // Record shell session duration before cleanup
@@ -1292,4 +1311,9 @@ export async function runShell(): Promise<void> {
   } else {
     console.log(`${prefix}Squad out.`);
   }
+
+  // If we exited due to a signal, propagate the conventional exit code
+  if (_shellSignalCode !== undefined) {
+    process.exit(_shellSignalCode);
+  }
 }