fix: handle transient child-process I/O errors (read EIO) gracefully

Add global uncaughtException handler that suppresses transient I/O
errors (EIO, EPIPE, ECONNRESET, ERR_STREAM_DESTROYED) from dying
child processes instead of crashing the entire visor process.

Three layers of defense:
- Global handler in child-process-error-handler.ts (imported early)
- Worktree manager skips process.exit(1) for transient I/O errors
- Stream-level error handlers on MCP transport stderr pipes

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

Author: buger

src/cli-main.ts

@@ -1,5 +1,10 @@
 #!/usr/bin/env node
 
+// Register global handler for transient child-process I/O errors (EIO, EPIPE)
+// before any other code runs so broken pipes from MCP servers etc. don't crash
+// the process.
+import './utils/child-process-error-handler';
+
 // Load environment variables from .env file (override existing to allow .env to take precedence)
 import * as dotenv from 'dotenv';
 dotenv.config({ override: true, quiet: true });

src/index.ts

@@ -2,6 +2,11 @@
 // GitHub event objects have complex dynamic structures that are difficult to fully type
 // Using 'any' for these objects is acceptable as they come from external GitHub webhooks
 
+// Register global handler for transient child-process I/O errors (EIO, EPIPE)
+// before any other code runs so broken pipes from MCP servers etc. don't crash
+// the process.
+import './utils/child-process-error-handler';
+
 // Load environment variables from .env file (override existing to allow .env to take precedence)
 import * as dotenv from 'dotenv';
 dotenv.config({ override: true, quiet: true });

src/providers/mcp-check-provider.ts

@@ -597,6 +597,18 @@ export class McpCheckProvider extends CheckProvider {
 
       const transport = createTransport();
 
+      // Attach error handler on the transport's stderr stream (if piped) so
+      // that EIO / EPIPE errors from a dying child process don't become
+      // uncaught exceptions that crash the whole visor process.
+      if ('stderr' in transport && transport.stderr) {
+        const stderrStream = transport.stderr as any;
+        if (typeof stderrStream.on === 'function') {
+          stderrStream.on('error', (err: Error) => {
+            logger.debug(`MCP transport stderr error (${transportName}): ${err.message}`);
+          });
+        }
+      }
+
       try {
         // Connect with timeout
         let timeoutId: NodeJS.Timeout | undefined;

src/providers/script-check-provider.ts

@@ -382,6 +382,12 @@ export class ScriptCheckProvider extends CheckProvider {
             env,
             stderr: 'pipe',
           });
+          // Prevent EIO errors on the stderr pipe from crashing the process
+          if (transport.stderr) {
+            transport.stderr.on('error', (err: Error) => {
+              logger.debug(`MCP transport stderr error: ${err.message}`);
+            });
+          }
           await Promise.race([
             client.connect(transport),
             new Promise((_, reject) =>

src/slack/markdown.ts

@@ -135,6 +135,9 @@ export async function renderMermaidToPng(mermaidCode: string): Promise<Buffer |
       proc.stderr?.on('data', data => {
         stderr += data.toString();
       });
+      // Prevent EIO errors on stderr from becoming uncaught exceptions
+      proc.stderr?.on('error', () => {});
+      proc.stdout?.on('error', () => {});
 
       proc.on('close', code => {
         if (code === 0) {

src/utils/child-process-error-handler.ts

@@ -0,0 +1,53 @@
+/**
+ * Global handler for transient child-process I/O errors.
+ *
+ * When a child process (MCP server, probe agent, sandbox command, etc.) dies
+ * unexpectedly, its stdio streams may emit `read EIO`, `write EPIPE`, or
+ * similar errors.  If no listener is attached to the stream's `error` event
+ * the error bubbles up as an uncaught exception and crashes the entire visor
+ * process.
+ *
+ * Importing this module installs a single, idempotent `uncaughtException`
+ * handler that recognises these transient I/O errors, logs a warning, and
+ * swallows them so the rest of the process can continue.
+ *
+ * Usage: import once, as early as possible in every entry point.
+ *
+ *   import './utils/child-process-error-handler';
+ */
+
+import { logger } from '../logger';
+
+const TRANSIENT_IO_CODES = new Set(['EIO', 'EPIPE', 'ECONNRESET']);
+
+export function isChildProcessIOError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  const errno = (error as NodeJS.ErrnoException).code;
+  if (errno && TRANSIENT_IO_CODES.has(errno)) return true;
+  const msg = error.message;
+  if (msg.includes('read EIO') || msg.includes('write EPIPE')) return true;
+  if (msg.includes('ERR_STREAM_DESTROYED')) return true;
+  return false;
+}
+
+// Guard: register at most once per process, even if the module is loaded
+// multiple times (ESM + CJS dual-instance, or re-imported).
+const GUARD = Symbol.for('visor.childProcessErrorHandler');
+if (!(globalThis as any)[GUARD]) {
+  (globalThis as any)[GUARD] = true;
+
+  process.on('uncaughtException', (error: Error, origin: string) => {
+    if (isChildProcessIOError(error)) {
+      // Log but do NOT crash.  The broken pipe is from a child process that
+      // already exited; crashing here would be collateral damage.
+      logger.warn(
+        `[child-process-error-handler] Suppressed transient I/O error (${origin}): ${error.message}`
+      );
+      return;
+    }
+    // Not our error — let other handlers (or the default behaviour) deal with it.
+    // Note: Node.js invokes all registered handlers; if none of them call
+    // process.exit() the process will continue.  The worktree-manager handler
+    // already calls process.exit(1) for non-IO errors.
+  });
+}

src/utils/worktree-manager.ts

@@ -10,6 +10,7 @@ import * as fsp from 'fs/promises';
 import * as path from 'path';
 import * as crypto from 'crypto';
 import { commandExecutor } from './command-executor';
+import { isChildProcessIOError } from './child-process-error-handler';
 import { logger } from '../logger';
 import type {
   WorktreeMetadata,
@@ -1041,6 +1042,12 @@ export class WorktreeManager {
 
       // Cleanup on uncaught exception
       process.on('uncaughtException', async error => {
+        // EIO errors from child process stdio streams (e.g. MCP servers dying)
+        // are transient and should not crash the entire process.
+        if (isChildProcessIOError(error)) {
+          logger.warn(`Ignoring transient child-process I/O error: ${error.message}`);
+          return;
+        }
         logger.error(`Uncaught exception, cleaning up worktrees: ${error}`);
         await this.cleanupProcessWorktrees();
         process.exit(1);

tests/unit/child-process-error-handler.test.ts

@@ -0,0 +1,101 @@
+/**
+ * Tests for the global child-process I/O error handler.
+ *
+ * The handler suppresses transient EIO / EPIPE errors that originate from
+ * broken child-process stdio pipes so the visor process doesn't crash.
+ */
+
+// Helper to emit uncaughtException without TS overload complaints
+function emitUncaughtException(err: Error): void {
+  (process as any).emit('uncaughtException', err, 'uncaughtException');
+}
+
+describe('child-process-error-handler', () => {
+  let originalListeners: NodeJS.UncaughtExceptionListener[];
+
+  beforeAll(() => {
+    // Capture pre-existing uncaughtException listeners so we can restore later
+    originalListeners = process.listeners(
+      'uncaughtException'
+    ) as NodeJS.UncaughtExceptionListener[];
+  });
+
+  afterAll(() => {
+    // Remove any listeners our import added and restore originals
+    process.removeAllListeners('uncaughtException');
+    for (const fn of originalListeners) {
+      process.on('uncaughtException', fn);
+    }
+  });
+
+  beforeEach(() => {
+    // Clear the guard so the module re-registers on each test
+    delete (globalThis as any)[Symbol.for('visor.childProcessErrorHandler')];
+  });
+
+  it('should register an uncaughtException listener', () => {
+    const before = process.listenerCount('uncaughtException');
+    jest.isolateModules(() => {
+      require('../../src/utils/child-process-error-handler');
+    });
+    const after = process.listenerCount('uncaughtException');
+    expect(after).toBeGreaterThan(before);
+  });
+
+  it('should suppress EIO errors without crashing', () => {
+    jest.isolateModules(() => {
+      require('../../src/utils/child-process-error-handler');
+    });
+
+    const err = Object.assign(new Error('read EIO'), { code: 'EIO' });
+    expect(() => emitUncaughtException(err)).not.toThrow();
+  });
+
+  it('should suppress EPIPE errors without crashing', () => {
+    jest.isolateModules(() => {
+      require('../../src/utils/child-process-error-handler');
+    });
+
+    const err = Object.assign(new Error('write EPIPE'), { code: 'EPIPE' });
+    expect(() => emitUncaughtException(err)).not.toThrow();
+  });
+
+  it('should suppress ECONNRESET errors without crashing', () => {
+    jest.isolateModules(() => {
+      require('../../src/utils/child-process-error-handler');
+    });
+
+    const err = Object.assign(new Error('read ECONNRESET'), { code: 'ECONNRESET' });
+    expect(() => emitUncaughtException(err)).not.toThrow();
+  });
+
+  it('should suppress ERR_STREAM_DESTROYED errors without crashing', () => {
+    jest.isolateModules(() => {
+      require('../../src/utils/child-process-error-handler');
+    });
+
+    const err = new Error('ERR_STREAM_DESTROYED');
+    expect(() => emitUncaughtException(err)).not.toThrow();
+  });
+
+  it('should NOT suppress unrelated errors', () => {
+    jest.isolateModules(() => {
+      require('../../src/utils/child-process-error-handler');
+    });
+
+    const err = new Error('Something completely different');
+    expect(() => emitUncaughtException(err)).not.toThrow();
+  });
+
+  it('should only register once even when imported twice', () => {
+    jest.isolateModules(() => {
+      require('../../src/utils/child-process-error-handler');
+    });
+    const afterFirst = process.listenerCount('uncaughtException');
+    jest.isolateModules(() => {
+      require('../../src/utils/child-process-error-handler');
+    });
+    const afterSecond = process.listenerCount('uncaughtException');
+    expect(afterSecond).toBe(afterFirst);
+  });
+});