fix(interrupt): flush the signal message synchronously before exit

A signal handler calls process.exit() immediately after writing the interrupt
hint. When stderr is a pipe, an async process.stderr.write() may not flush
before the process terminates, so the hint could be lost. The default stderr
writer now uses fs.writeSync (best-effort, guarded against EPIPE) so the hint is
reliably emitted. Added a test mocking fs.writeSync to assert the synchronous
write on the default path.

Author: Andy00L

src/lib/interrupt.test.ts

@@ -1,4 +1,5 @@
 import { EventEmitter } from 'node:events';
+import { writeSync } from 'node:fs';
 import { describe, expect, it, vi } from 'vitest';
 import {
   SIGINT_EXIT_CODE,
@@ -8,6 +9,13 @@ import {
   installSignalHandlers,
 } from './interrupt.js';
 
+// installSignalHandlers' default stderr writes via fs.writeSync (synchronous, so
+// the hint survives a piped stderr before exit); mock it to assert on that path.
+vi.mock('node:fs', async importOriginal => {
+  const actual = (await importOriginal()) as Record<string, unknown>;
+  return { ...actual, writeSync: vi.fn() };
+});
+
 describe('formatInterruptMessage', () => {
   it('defaults to SIGINT and explains the run continues server-side', () => {
     const message = formatInterruptMessage();
@@ -52,6 +60,24 @@ describe('installSignalHandlers', () => {
     expect(TERMINATION_EXIT_CODES.SIGTERM).toBe(143);
     expect(TERMINATION_EXIT_CODES.SIGHUP).toBe(129);
   });
+
+  it('writes the hint synchronously via writeSync before exit (survives a piped stderr)', () => {
+    vi.mocked(writeSync).mockClear();
+    const handlers = new Map<string, () => void>();
+    const exit = vi.fn();
+    // No stderr dep: exercise the synchronous default path.
+    installSignalHandlers({
+      on: (signal, handler) => handlers.set(signal, handler),
+      exit,
+    });
+    handlers.get('SIGINT')!();
+    expect(exit).toHaveBeenCalledWith(130);
+    const written = vi
+      .mocked(writeSync)
+      .mock.calls.map(call => String(call[1]))
+      .join('');
+    expect(written).toContain('Interrupted (SIGINT)');
+  });
 });
 
 describe('installBrokenPipeGuard', () => {

src/lib/interrupt.ts

@@ -19,6 +19,8 @@
  * without spawning a subprocess or sending a real signal.
  */
 
+import { writeSync } from 'node:fs';
+
 /**
  * Termination signals handled, mapped to their conventional `128 + signum`
  * exit code. sourceRef: POSIX signal numbers (SIGHUP=1, SIGINT=2, SIGTERM=15).
@@ -60,7 +62,18 @@ export function installSignalHandlers(deps: InterruptDeps = {}): void {
     ((signal: TerminationSignal, handler: () => void) => {
       process.on(signal, handler);
     });
-  const stderr = deps.stderr ?? ((line: string) => process.stderr.write(`${line}\n`));
+  const stderr =
+    deps.stderr ??
+    ((line: string) => {
+      // A signal handler calls process.exit() right after writing, which can
+      // truncate an async process.stderr.write() when stderr is a pipe. Write
+      // synchronously so the interrupt hint is flushed before the process exits.
+      try {
+        writeSync(process.stderr.fd, `${line}\n`);
+      } catch {
+        // Best-effort: if stderr is already gone (EPIPE), still exit cleanly.
+      }
+    });
   const exit = deps.exit ?? ((code: number) => process.exit(code));
 
   for (const signal of Object.keys(TERMINATION_EXIT_CODES) as TerminationSignal[]) {