fix(gateway): detect musl libc and surface real spawn errors

Two related improvements to make the bundled-JRE gateway work in
Alpine-based images (supergateway, node:lts-alpine) and to give a
better error when it doesn't.

- IBGatewayManager.isMuslLibc() (new, static): detects musl by
  checking process.report.getReport().header.glibcVersionRuntime,
  falling back to the presence of /lib/ld-musl-{x86_64,aarch64}.so.1.
  getJavaPath() now appends -musl to the platform key on Linux+musl
  so it picks runtime/linux-x64-musl or runtime/linux-arm64-musl.

- Spawn diagnostics: capture spawn 'error' and non-zero 'exit' events
  plus a 4KB stderr tail, and reject waitForGateway with the actual
  reason (ENOENT on the JRE, exit code, stderr) instead of the
  generic "IB Gateway failed to start within 30 seconds" timeout.
  ENOENT on Linux+musl gets a specific hint about a missing musl
  runtime directory.

Adds test/gateway-manager.test.ts with 6 cases covering isMuslLibc()
across glibc / musl / non-Linux / process.report failure paths.
README updated to mention Alpine support.

Verified end-to-end: rebuilt the npm tarball locally, installed in
supercorp/supergateway, sent an MCP tool call. The previous error
"IB Gateway failed to start within 30 seconds" is now replaced by
"Authentication required" (gateway is up, listening on 5000, running
from runtime/linux-x64-musl/bin/java).

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

Author: NitayRabi

README.md

@@ -45,7 +45,7 @@ your IB account to retrieve market data, check positions, and place trades.
 **No additional installations required!** This package includes:
 
 - Pre-configured IB Gateway for all platforms (Linux, macOS, Windows)
-- Java Runtime Environment (JRE) for IB Gateway
+- Java Runtime Environment (JRE) for IB Gateway, including a musl-libc build for Alpine-based containers (e.g. `node:lts-alpine`, supergateway)
 - All necessary dependencies
 
 You only need:

src/gateway-manager.ts

@@ -1,5 +1,5 @@
 import { spawn, ChildProcess } from 'child_process';
-import { promises as fs } from 'fs';
+import { promises as fs, existsSync as fsExistsSync } from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import { createRequire } from 'module';
@@ -20,6 +20,8 @@ export class IBGatewayManager {
   private cleanupHandlersRegistered = false;
   private currentPort: number = 5000;
   private backgroundStartupPromise: Promise<void> | null = null;
+  private spawnFailure: { reason: string; details?: string } | null = null;
+  private static readonly STDERR_TAIL_BYTES = 4096;
 
   constructor() {
     this.gatewayDir = path.join(__dirname, '../ib-gateway');
@@ -134,19 +136,44 @@ export class IBGatewayManager {
   // Removed forceKillGateway - we never kill gateway processes anymore
 
   private getJavaPath(): string {
-    const platform = `${process.platform}-${process.arch}`;
     const isWindows = process.platform === 'win32';
     const javaExecutable = isWindows ? 'java.exe' : 'java';
-    
+
+    let platform = `${process.platform}-${process.arch}`;
+    if (process.platform === 'linux' && IBGatewayManager.isMuslLibc()) {
+      platform = `${platform}-musl`;
+    }
+
     const runtimePath = path.join(this.jreDir, platform, 'bin', javaExecutable);
-    
-    if (!require('fs').existsSync(runtimePath)) {
+
+    if (!fsExistsSync(runtimePath)) {
       throw new Error(`Custom runtime not found for platform: ${platform}. Expected at: ${runtimePath}`);
     }
-    
+
     return runtimePath;
   }
 
+  // Detect whether the current Linux system uses musl libc (Alpine, etc.) rather than glibc.
+  // The bundled glibc JRE cannot exec on musl — its ELF interpreter /lib64/ld-linux-x86-64.so.2
+  // does not exist there, producing an opaque ENOENT at spawn time.
+  static isMuslLibc(): boolean {
+    if (process.platform !== 'linux') {
+      return false;
+    }
+    // process.report.getReport() exposes glibcVersionRuntime when glibc is present.
+    try {
+      const report = (process as { report?: { getReport: () => { header?: { glibcVersionRuntime?: string } } } }).report;
+      const glibcRuntime = report?.getReport?.().header?.glibcVersionRuntime;
+      if (typeof glibcRuntime === 'string' && glibcRuntime.length > 0) {
+        return false;
+      }
+    } catch {
+      // Fall through to filesystem check.
+    }
+    // Fallback: presence of the musl loader in its standard path.
+    return fsExistsSync('/lib/ld-musl-x86_64.so.1') || fsExistsSync('/lib/ld-musl-aarch64.so.1');
+  }
+
   async ensureGatewayExists(): Promise<void> {
     const gatewayPath = path.join(this.gatewayDir, 'clientportal.gw');
     const runScript = path.join(gatewayPath, 'bin/run.sh');
@@ -251,7 +278,8 @@ export class IBGatewayManager {
     }
 
     this.isStarting = true;
-    
+    this.spawnFailure = null;
+
     try {
       await this.ensureGatewayExists();
 
@@ -319,6 +347,10 @@ export class IBGatewayManager {
         stdio: ['ignore', 'pipe', 'pipe']
       });
 
+      // Buffer the tail of stderr so we can include it in a failure reason if the process
+      // dies before the gateway's HTTP port comes up.
+      let stderrTail = '';
+
       this.gatewayProcess.stdout?.on('data', (data) => {
         const output = data.toString().trim();
         if (output) {
@@ -332,20 +364,32 @@ export class IBGatewayManager {
       });
 
       this.gatewayProcess.stderr?.on('data', (data) => {
-        const output = data.toString().trim();
-        if (output && !output.includes('WARNING')) {
-          Logger.error(`[Gateway Error] ${output}`);
+        const chunk = data.toString();
+        stderrTail = (stderrTail + chunk).slice(-IBGatewayManager.STDERR_TAIL_BYTES);
+        const trimmed = chunk.trim();
+        if (trimmed && !trimmed.includes('WARNING')) {
+          Logger.error(`[Gateway Error] ${trimmed}`);
         }
       });
 
       this.gatewayProcess.on('error', (error) => {
         Logger.error('❌ Gateway process error:', error.message);
+        this.spawnFailure = {
+          reason: this.diagnoseSpawnError(error, bundledJavaPath),
+          details: error.message,
+        };
         this.isStarting = false;
         this.isReady = false;
       });
 
       this.gatewayProcess.on('exit', (code, signal) => {
         this.log(`🛑 Gateway process exited with code ${code}, signal ${signal}`);
+        if (!this.isReady && code !== 0 && code !== null) {
+          this.spawnFailure = {
+            reason: `IB Gateway process exited with code ${code} before becoming ready`,
+            details: stderrTail.trim() || `(no stderr captured; signal=${signal ?? 'none'})`,
+          };
+        }
         this.gatewayProcess = null;
         this.isStarting = false;
         this.isReady = false;
@@ -371,6 +415,11 @@ export class IBGatewayManager {
     let attempts = 0;
 
     while (attempts < maxAttempts) {
+      // Bail out early if the child process already failed — no point polling for 30s.
+      if (this.spawnFailure) {
+        throw this.buildSpawnFailureError();
+      }
+
       try {
         // Try to connect to the gateway port
         const response = await this.checkGatewayHealth();
@@ -384,15 +433,40 @@ export class IBGatewayManager {
 
       attempts++;
       await new Promise(resolve => setTimeout(resolve, 1000));
-      
+
       if (attempts % 5 === 0) {
         this.log(`⏳ Still waiting for gateway... (${attempts}/${maxAttempts})`);
       }
     }
 
+    if (this.spawnFailure) {
+      throw this.buildSpawnFailureError();
+    }
     throw new Error('IB Gateway failed to start within 30 seconds');
   }
 
+  private buildSpawnFailureError(): Error {
+    const failure = this.spawnFailure!;
+    const detail = failure.details ? `\nDetails: ${failure.details}` : '';
+    return new Error(`${failure.reason}${detail}`);
+  }
+
+  private diagnoseSpawnError(error: NodeJS.ErrnoException, javaPath: string): string {
+    if (error.code === 'ENOENT' && process.platform === 'linux' && IBGatewayManager.isMuslLibc()) {
+      // Defensive: getJavaPath should have already routed to runtime/linux-*-musl. If we still hit
+      // ENOENT on musl it's almost certainly a missing musl runtime directory in this build.
+      return `Failed to spawn bundled JRE at ${javaPath}: musl libc detected but the musl JRE was not found. ` +
+        `If you built this package locally, ensure runtime/linux-x64-musl and runtime/linux-arm64-musl are present.`;
+    }
+    if (error.code === 'ENOENT') {
+      return `Failed to spawn bundled JRE at ${javaPath}: file not found or its dynamic loader is missing on this system.`;
+    }
+    if (error.code === 'EACCES') {
+      return `Failed to spawn bundled JRE at ${javaPath}: permission denied (the file may not be executable).`;
+    }
+    return `Failed to spawn IB Gateway: ${error.message}`;
+  }
+
   private async checkGatewayHealth(): Promise<boolean> {
     // Import https dynamically to avoid issues with module resolution
     const https = await import('https');

test/gateway-manager.test.ts

@@ -0,0 +1,85 @@
+// test/gateway-manager.test.ts
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import * as fs from 'fs';
+import { IBGatewayManager } from '../src/gateway-manager.js';
+
+vi.mock('fs', async () => {
+  const actual = await vi.importActual<typeof fs>('fs');
+  return {
+    ...actual,
+    existsSync: vi.fn(actual.existsSync),
+  };
+});
+
+describe('IBGatewayManager.isMuslLibc', () => {
+  const originalPlatform = process.platform;
+  const originalReport = (process as unknown as { report?: unknown }).report;
+
+  afterEach(() => {
+    Object.defineProperty(process, 'platform', { value: originalPlatform });
+    Object.defineProperty(process, 'report', { configurable: true, value: originalReport });
+    vi.mocked(fs.existsSync).mockReset();
+    vi.mocked(fs.existsSync).mockImplementation((p: fs.PathLike) => {
+      // Default: nothing exists unless a test opts in.
+      return false;
+    });
+  });
+
+  it('returns false on non-Linux platforms without consulting libc', () => {
+    Object.defineProperty(process, 'platform', { value: 'darwin' });
+    vi.mocked(fs.existsSync).mockReturnValue(true); // would lie if consulted
+    expect(IBGatewayManager.isMuslLibc()).toBe(false);
+  });
+
+  it('returns false on Linux when process.report exposes a glibc runtime version', () => {
+    Object.defineProperty(process, 'platform', { value: 'linux' });
+    Object.defineProperty(process, 'report', { configurable: true, value: {
+      getReport: () => ({ header: { glibcVersionRuntime: '2.36' } }),
+    } });
+    expect(IBGatewayManager.isMuslLibc()).toBe(false);
+  });
+
+  it('returns true on Linux when glibcVersionRuntime is missing and the musl loader is on disk', () => {
+    Object.defineProperty(process, 'platform', { value: 'linux' });
+    Object.defineProperty(process, 'report', { configurable: true, value: {
+      getReport: () => ({ header: {} }),
+    } });
+    vi.mocked(fs.existsSync).mockImplementation(
+      (p: fs.PathLike) => p === '/lib/ld-musl-x86_64.so.1',
+    );
+    expect(IBGatewayManager.isMuslLibc()).toBe(true);
+  });
+
+  it('returns true when only the aarch64 musl loader is present', () => {
+    Object.defineProperty(process, 'platform', { value: 'linux' });
+    Object.defineProperty(process, 'report', { configurable: true, value: {
+      getReport: () => ({ header: {} }),
+    } });
+    vi.mocked(fs.existsSync).mockImplementation(
+      (p: fs.PathLike) => p === '/lib/ld-musl-aarch64.so.1',
+    );
+    expect(IBGatewayManager.isMuslLibc()).toBe(true);
+  });
+
+  it('returns false when neither glibc nor a musl loader is detectable', () => {
+    Object.defineProperty(process, 'platform', { value: 'linux' });
+    Object.defineProperty(process, 'report', { configurable: true, value: {
+      getReport: () => ({ header: {} }),
+    } });
+    vi.mocked(fs.existsSync).mockReturnValue(false);
+    expect(IBGatewayManager.isMuslLibc()).toBe(false);
+  });
+
+  it('falls back to the filesystem check if process.report.getReport throws', () => {
+    Object.defineProperty(process, 'platform', { value: 'linux' });
+    Object.defineProperty(process, 'report', { configurable: true, value: {
+      getReport: () => {
+        throw new Error('not available');
+      },
+    } });
+    vi.mocked(fs.existsSync).mockImplementation(
+      (p: fs.PathLike) => p === '/lib/ld-musl-x86_64.so.1',
+    );
+    expect(IBGatewayManager.isMuslLibc()).toBe(true);
+  });
+});