fix(cli): implement signal handlers for graceful shutdown (RR-655)

Rebased onto current develop, dropping changes already merged separately
(redaction regex, CSS comment fix, PageStatus UI, upload math fix).

Only the signal handler work remains:
- SIGINT/SIGTERM handlers with proper exit codes (130/143)
- Double-signal force exit, 5s cleanup timeout
- Idempotent cleanupClient via dedup promise
- isCancelled guards on command actions to prevent exit races
- run()/main() shutdown awareness via awaitShutdown()

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Rod-Christensen

packages/client-typescript/src/cli/rocketride.ts

@@ -801,6 +801,7 @@ export class RocketRideCLI {
 	private connected: boolean = false;
 	private attempt: number = 0;
 	private cancelled: boolean = false;
+	private signalShutdownPromise?: Promise<never>;
 
 	constructor() {
 		this.setupSignalHandlers();
@@ -814,13 +815,53 @@ export class RocketRideCLI {
 		return this.cancelled;
 	}
 
+	isShuttingDown(): boolean {
+		return this.signalShutdownPromise !== undefined;
+	}
+
+	// Resolves only when the signal handler calls process.exit, so any
+	// command/run/main flow that awaits this will stand down and let the
+	// signal handler own the exit code.
+	awaitShutdown(): Promise<never> {
+		return this.signalShutdownPromise ?? new Promise<never>(() => {});
+	}
+
 	private setupSignalHandlers(): void {
-		// TODO: Enable proper signal handling
-		// const signalHandler = () => {
-		// 	this.cancel();
-		// };
-		// process.on('SIGINT', signalHandler);
-		// process.on('SIGTERM', signalHandler);
+		const FORCE_EXIT_TIMEOUT_MS = 5000;
+
+		const signalHandler = async (signal: string) => {
+			const exitCode = 128 + (signal === 'SIGINT' ? 2 : 15);
+
+			if (this.signalShutdownPromise) {
+				// Second signal: force exit immediately
+				process.exit(exitCode);
+			}
+
+			// Park a promise that never resolves; other flows await it to
+			// stand down while the signal handler drives the exit.
+			this.signalShutdownPromise = new Promise<never>(() => {});
+
+			this.cancel();
+
+			// Force exit if cleanup hangs
+			const forceExitTimer = setTimeout(() => {
+				console.error(`\nCleanup timed out after ${FORCE_EXIT_TIMEOUT_MS}ms, forcing exit`);
+				process.exit(exitCode);
+			}, FORCE_EXIT_TIMEOUT_MS);
+
+			try {
+				await this.cleanupClient();
+			} catch {
+				// Ignore cleanup errors during signal handling
+			} finally {
+				clearTimeout(forceExitTimer);
+			}
+
+			process.exit(exitCode);
+		};
+
+		process.on('SIGINT', () => signalHandler('SIGINT'));
+		process.on('SIGTERM', () => signalHandler('SIGTERM'));
 	}
 
 	private createProgram(): Command {
@@ -858,10 +899,14 @@ export class RocketRideCLI {
 
 				try {
 					const exitCode = await this.cmdStart();
-					process.exit(exitCode);
+					if (!this.isCancelled()) {
+						process.exit(exitCode);
+					}
 				} finally {
-					this.cancel();
-					await this.cleanupClient();
+					if (!this.isCancelled()) {
+						this.cancel();
+						await this.cleanupClient();
+					}
 				}
 			});
 
@@ -896,10 +941,14 @@ export class RocketRideCLI {
 
 				try {
 					const exitCode = await this.cmdUpload();
-					process.exit(exitCode);
+					if (!this.isCancelled()) {
+						process.exit(exitCode);
+					}
 				} finally {
-					this.cancel();
-					await this.cleanupClient();
+					if (!this.isCancelled()) {
+						this.cancel();
+						await this.cleanupClient();
+					}
 				}
 			});
 
@@ -925,10 +974,14 @@ export class RocketRideCLI {
 
 				try {
 					const exitCode = await this.cmdStatus();
-					process.exit(exitCode);
+					if (!this.isCancelled()) {
+						process.exit(exitCode);
+					}
 				} finally {
-					this.cancel();
-					await this.cleanupClient();
+					if (!this.isCancelled()) {
+						this.cancel();
+						await this.cleanupClient();
+					}
 				}
 			});
 
@@ -954,10 +1007,14 @@ export class RocketRideCLI {
 
 				try {
 					const exitCode = await this.cmdStop();
-					process.exit(exitCode);
+					if (!this.isCancelled()) {
+						process.exit(exitCode);
+					}
 				} finally {
-					this.cancel();
-					await this.cleanupClient();
+					if (!this.isCancelled()) {
+						this.cancel();
+						await this.cleanupClient();
+					}
 				}
 			});
 
@@ -1188,16 +1245,20 @@ export class RocketRideCLI {
 		}
 	}
 
+	private _cleanupPromise?: Promise<void>;
+
 	private async cleanupClient(): Promise<void> {
-		if (this.client) {
-			try {
-				await this.client.disconnect();
-			} catch {
-				// Ignore cleanup errors
-			} finally {
-				this.client = undefined;
-			}
+		if (this._cleanupPromise) {
+			return this._cleanupPromise;
 		}
+		const client = this.client;
+		if (!client) {
+			return;
+		}
+		this.client = undefined;
+		this._cleanupPromise = client.disconnect().catch(() => {});
+		await this._cleanupPromise;
+		this._cleanupPromise = undefined;
 	}
 
 	private loadPipelineConfig(pipelineFile: string): PipelineConfig {
@@ -1693,8 +1754,15 @@ export class RocketRideCLI {
 		// Parse command line arguments - commander will handle command routing
 		try {
 			await program.parseAsync(process.argv);
+			if (this.isShuttingDown()) {
+				// Signal handler owns the exit; park until it calls process.exit.
+				await this.awaitShutdown();
+			}
 			return 0; // If we get here, a command was executed successfully
 		} catch (error) {
+			if (this.isShuttingDown()) {
+				await this.awaitShutdown();
+			}
 			if (error instanceof Error && error.message.includes('interrupted')) {
 				console.log('\nOperation interrupted by user');
 				return 1;
@@ -1721,11 +1789,18 @@ function formatError(e: Error): string {
 }
 
 export async function main(): Promise<void> {
+	const cli = new RocketRideCLI();
 	try {
-		const cli = new RocketRideCLI();
 		const exitCode = await cli.run();
+		if (cli.isShuttingDown()) {
+			// Signal handler owns the exit code; never race it to process.exit.
+			await cli.awaitShutdown();
+		}
 		process.exit(exitCode);
 	} catch (error) {
+		if (cli.isShuttingDown()) {
+			await cli.awaitShutdown();
+		}
 		if (error instanceof Error && error.message.includes('interrupted')) {
 			console.log('\n\nOperation interrupted by user');
 		} else {