refactor(scripts): replace process.exit() with ExitError + runMain handler (#739) (#740)

Part 1 of 2 of the n/no-process-exit cleanup (umbrella #738): convert every
process.exit() call in standalone scripts/** CLIs to the rule-compliant pattern.

- New shared helper scripts/lib/cli-exit.cjs: ExitError(code,message) + runMain()
  which translates a thrown ExitError / returned number into process.exitCode
  (never process.exit()), flushing output and still firing process.on('exit').
- main()-based entrypoints: throw new ExitError(code) for errors, return <code>
  for verdicts; invoked via runMain(main). Child exit codes preserved via return.
- top-level-only scripts: imperative body extracted into main() so mid-flow
  aborts (throw ExitError) actually halt; pure consts/helpers stay at module scope.
- diff-touches-shipped-paths.cjs: stdin event handling restructured to an async
  read so the whole flow runs under runMain; uncaughtException/unhandledRejection
  nets replaced by an in-band catch that preserves EXIT_ERROR=2.

Exit codes verified unchanged for every converted script (success/error/help and
the 0/1/2 semantic codes in diff-touches). Rule stays warn here; flipped to error
in part 2 (#738) once gsd-core/bin/** is also clean.

Refs #739

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

scripts/gen-research-agents.cjs

@@ -24,6 +24,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const { PROFILES } = require('./research-profiles.cjs');
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
 
 const ROOT = path.resolve(__dirname, '..');
 const AGENTS_DIR = path.join(ROOT, 'agents');
@@ -225,8 +226,7 @@ function runWrite() {
   for (const profile of PROFILES) {
     const agentPath = path.join(AGENTS_DIR, profile.name + '.md');
     if (!fs.existsSync(agentPath)) {
-      process.stderr.write('ERROR: agent file not found: ' + agentPath + '\n');
-      process.exit(1);
+      throw new ExitError(1, 'ERROR: agent file not found: ' + agentPath);
     }
     writeAgent(profile);
     process.stdout.write('  wrote  ' + profile.name + '.md\n');
@@ -241,7 +241,7 @@ module.exports = { PROFILES, checkAgent, runCheck, parseAgentFile };
 
 // ─── CLI entry point ──────────────────────────────────────────────────────────
 
-if (require.main === module) {
+function main() {
   const flag = process.argv[2] || '--check';
 
   if (flag === '--write') {
@@ -251,7 +251,7 @@ if (require.main === module) {
     const ok = runCheck();
     if (!ok) {
       process.stderr.write('\nERROR: --check failed after --write. Fix serialization.\n');
-      process.exit(1);
+      throw new ExitError(1);
     }
     process.stdout.write('\nAll agents match their profiles.\n');
   } else if (flag === '--check') {
@@ -263,12 +263,14 @@ if (require.main === module) {
         '\nTo regenerate frontmatter from profiles:\n' +
         '  node scripts/gen-research-agents.cjs --write\n',
       );
-      process.exit(1);
+      throw new ExitError(1);
     }
     process.stdout.write('\nAll 7 agents match their profiles.\n');
   } else {
-    process.stderr.write('Unknown flag: ' + flag + '\n');
-    process.stderr.write('Usage: node scripts/gen-research-agents.cjs [--check|--write]\n');
-    process.exit(1);
+    throw new ExitError(1, 'Unknown flag: ' + flag + '\nUsage: node scripts/gen-research-agents.cjs [--check|--write]');
   }
 }
+
+if (require.main === module) {
+  runMain(main);
+}