[CLI] Remove process.exit() from library APIs

packages/playground/cli/src/cli.ts

@@ -6,7 +6,33 @@ function runCLI() {
 	// Dynamic import avoids loading run-cli when we're about to respawn.
 	// Do not await — top-level await is not supported in all environments.
 	import('./run-cli').then(({ parseOptionsAndRunCLI }) => {
-		parseOptionsAndRunCLI(args);
+		parseOptionsAndRunCLI(args)
+			.then((result) => {
+				if ('exitCode' in result) {
+					process.exit(result.exitCode);
+					return;
+				}
+
+				// A server is running. Clean up and exit on
+				// SIGINT / SIGTERM.
+				const cleanUpAndExit = (() => {
+					let cleaning: PromiseLike<void>;
+					return async () => {
+						if (!cleaning) {
+							cleaning = result[Symbol.asyncDispose]();
+						}
+						await cleaning;
+						process.exit(0);
+					};
+				})();
+				process.on('SIGINT', cleanUpAndExit);
+				process.on('SIGTERM', cleanUpAndExit);
+			})
+			.catch(() => {
+				// Unexpected error — already logged by
+				// parseOptionsAndRunCLI.
+				process.exit(1);
+			});
 	});
 }
 

packages/playground/cli/src/mounts.ts

@@ -76,10 +76,22 @@ export function parseMountDirArguments(mounts: string[]): Mount[] {
 
 export async function mountResources(php: PHP, mounts: Mount[]) {
 	for (const mount of mounts) {
-		await php.mount(
-			mount.vfsPath,
-			createNodeFsMountHandler(mount.hostPath)
-		);
+		try {
+			await php.mount(
+				mount.vfsPath,
+				createNodeFsMountHandler(mount.hostPath)
+			);
+		} catch (error) {
+			// Wrap the raw mount failure with the offending paths and a
+			// root-cause summary so callers that only read `.message`
+			// (e.g. the boot-failure path) still get an actionable error.
+			const errorSummary =
+				error instanceof Error ? error.message : String(error);
+			throw new Error(
+				`Error mounting path ${mount.hostPath} at ${mount.vfsPath}: ${errorSummary}`,
+				{ cause: error }
+			);
+		}
 	}
 }