react-on-rails-pro-node-renderer 16.6.0-rc.0 → 16.6.0

package/tests/masterStartupFailure.test.ts

@@ -0,0 +1,295 @@
+import { WORKER_STARTUP_FAILURE, type WorkerStartupFailureMessage } from '../src/shared/workerMessages';
+
+type MockWorker = {
+  id: number;
+  isScheduledRestart?: boolean;
+  process: { exitCode: number | null };
+};
+
+type ClusterHandlers = {
+  message: (worker: MockWorker, message: unknown) => void;
+  exit: (worker: MockWorker) => void;
+};
+
+type MockCluster = {
+  on: jest.Mock<MockCluster, [event: string, handler: (...args: unknown[]) => void]>;
+  fork: jest.Mock<unknown, []>;
+  disconnect: jest.Mock<void, [callback?: () => void]>;
+};
+
+function buildStartupFailureMessage(
+  overrides: Partial<WorkerStartupFailureMessage> = {},
+): WorkerStartupFailureMessage {
+  return {
+    type: WORKER_STARTUP_FAILURE,
+    stage: 'listen',
+    code: 'EADDRINUSE',
+    errno: -48,
+    syscall: 'listen',
+    host: 'localhost',
+    port: 3800,
+    message: 'listen EADDRINUSE: address already in use :::3800',
+    ...overrides,
+  };
+}
+
+function setupMasterRunHarness() {
+  const operations: string[] = [];
+  const clusterHandlers: Partial<ClusterHandlers> = {};
+  const mockFork = jest.fn(() => {
+    operations.push('fork');
+    return {};
+  });
+  const mockCluster = {} as MockCluster;
+  mockCluster.disconnect = jest.fn((callback?: () => void) => {
+    if (callback) callback();
+  });
+  mockCluster.on = jest.fn((event: string, handler: (...args: unknown[]) => void) => {
+    operations.push(`on:${event}`);
+    if (event === 'message') {
+      clusterHandlers.message = handler as ClusterHandlers['message'];
+    } else if (event === 'exit') {
+      clusterHandlers.exit = handler as ClusterHandlers['exit'];
+    }
+    return mockCluster;
+  });
+  mockCluster.fork = mockFork;
+  const mockErrorReporterMessage = jest.fn();
+  const mockLog = {
+    info: jest.fn(),
+    warn: jest.fn(),
+    error: jest.fn(),
+    fatal: jest.fn(),
+  };
+  const mockBuildConfig = jest.fn(() => ({
+    workersCount: 2,
+    allWorkersRestartInterval: undefined,
+    delayBetweenIndividualWorkerRestarts: undefined,
+    gracefulWorkerRestartTimeout: 0,
+    serverBundleCachePath: '/tmp/react-on-rails-pro-node-renderer-bundles',
+  }));
+  const mockLogSanitizedConfig = jest.fn();
+  const mockGetLicenseStatus = jest.fn(() => 'valid');
+  const setIntervalSpy = jest.spyOn(global, 'setInterval').mockReturnValue(0 as unknown as NodeJS.Timeout);
+  const setTimeoutSpy = jest
+    .spyOn(global, 'setTimeout')
+    .mockReturnValue({ unref: jest.fn() } as unknown as NodeJS.Timeout);
+  const processExitSpy = jest.spyOn(process, 'exit').mockImplementation(((code?: number) => {
+    throw new Error(`process.exit:${code}`);
+  }) as typeof process.exit);
+
+  jest.doMock('cluster', () => ({
+    __esModule: true,
+    default: mockCluster,
+  }));
+  jest.doMock('../src/shared/log', () => ({
+    __esModule: true,
+    default: mockLog,
+  }));
+  jest.doMock('../src/shared/errorReporter', () => ({
+    __esModule: true,
+    message: mockErrorReporterMessage,
+    error: jest.fn(),
+    addMessageNotifier: jest.fn(),
+    addErrorNotifier: jest.fn(),
+    addNotifier: jest.fn(),
+  }));
+  jest.doMock('../src/shared/configBuilder', () => ({
+    __esModule: true,
+    buildConfig: mockBuildConfig,
+    logSanitizedConfig: mockLogSanitizedConfig,
+  }));
+  jest.doMock('../src/shared/licenseValidator', () => ({
+    __esModule: true,
+    getLicenseStatus: mockGetLicenseStatus,
+  }));
+  jest.doMock('../src/master/restartWorkers', () => ({
+    __esModule: true,
+    default: jest.fn(),
+  }));
+
+  let masterRun: typeof import('../src/master').default | undefined;
+  jest.isolateModules(() => {
+    // eslint-disable-next-line global-require
+    masterRun = require('../src/master').default as typeof import('../src/master').default;
+  });
+
+  if (!masterRun) {
+    throw new Error('Failed to load masterRun');
+  }
+
+  masterRun();
+
+  if (!clusterHandlers.message || !clusterHandlers.exit) {
+    throw new Error('Failed to register cluster handlers');
+  }
+
+  return {
+    operations,
+    clusterHandlers: clusterHandlers as ClusterHandlers,
+    mockFork,
+    mockCluster,
+    mockErrorReporterMessage,
+    setIntervalSpy,
+    setTimeoutSpy,
+    processExitSpy,
+  };
+}
+
+async function waitForSetImmediate() {
+  await new Promise<void>((resolve) => {
+    setImmediate(resolve);
+  });
+}
+
+describe('master startup failure handling via masterRun wiring', () => {
+  afterEach(() => {
+    jest.restoreAllMocks();
+    jest.resetModules();
+  });
+
+  it.each([
+    {
+      testName: 'EADDRINUSE startup failure',
+      failureWorker: { id: 1, process: { exitCode: 1 } },
+      exitingWorker: { id: 1, process: { exitCode: 1 } },
+      failure: buildStartupFailureMessage(),
+      expectedMessage: 'Node renderer startup failed: localhost:3800 is already in use',
+    },
+    {
+      testName: 'generic startup failure from one worker while another exits first',
+      failureWorker: { id: 2, process: { exitCode: 1 } },
+      exitingWorker: { id: 1, process: { exitCode: 1 } },
+      failure: buildStartupFailureMessage({
+        code: 'EACCES',
+        message: 'listen EACCES: permission denied 0.0.0.0:80',
+      }),
+      expectedMessage:
+        'Node renderer startup failed in worker 2: listen EACCES: permission denied 0.0.0.0:80',
+    },
+  ])('registers listeners before forking and aborts without reforking on $testName', (scenario) => {
+    const harness = setupMasterRunHarness();
+
+    expect(harness.operations).toEqual(['on:message', 'fork', 'fork', 'on:exit']);
+    expect(harness.mockFork).toHaveBeenCalledTimes(2);
+    expect(harness.setIntervalSpy).toHaveBeenCalledTimes(1);
+
+    harness.clusterHandlers.message(scenario.failureWorker, scenario.failure);
+
+    expect(() => harness.clusterHandlers.exit(scenario.exitingWorker)).toThrow('process.exit:1');
+    expect(harness.mockErrorReporterMessage).toHaveBeenCalledWith(scenario.expectedMessage);
+    expect(harness.mockCluster.disconnect).toHaveBeenCalledTimes(1);
+    expect(harness.processExitSpy).toHaveBeenCalledWith(1);
+    expect(harness.mockFork).toHaveBeenCalledTimes(2);
+  });
+
+  it('keeps the first startup-failure details when multiple workers report failures', () => {
+    const harness = setupMasterRunHarness();
+    const firstFailure = buildStartupFailureMessage({
+      code: 'EACCES',
+      message: 'listen EACCES: permission denied 0.0.0.0:80',
+    });
+    const secondFailure = buildStartupFailureMessage({
+      code: 'ECONNREFUSED',
+      message: 'listen ECONNREFUSED: connection refused 127.0.0.1:3800',
+    });
+
+    harness.clusterHandlers.message({ id: 1, process: { exitCode: 1 } }, firstFailure);
+    harness.clusterHandlers.message({ id: 2, process: { exitCode: 1 } }, secondFailure);
+
+    expect(() => harness.clusterHandlers.exit({ id: 2, process: { exitCode: 1 } })).toThrow('process.exit:1');
+    expect(harness.mockErrorReporterMessage).toHaveBeenCalledWith(
+      'Node renderer startup failed in worker 1: listen EACCES: permission denied 0.0.0.0:80',
+    );
+  });
+
+  it('reports error only once when multiple workers exit during abort', () => {
+    const harness = setupMasterRunHarness();
+    // Use a disconnect mock that does NOT invoke the callback, so process.exit
+    // is not called and subsequent exit events can be observed.
+    harness.mockCluster.disconnect.mockImplementation(() => {});
+
+    harness.clusterHandlers.message({ id: 1, process: { exitCode: 1 } }, buildStartupFailureMessage());
+
+    // First exit triggers the error report and disconnect.
+    harness.clusterHandlers.exit({ id: 1, process: { exitCode: 1 } });
+    expect(harness.mockErrorReporterMessage).toHaveBeenCalledTimes(1);
+    expect(harness.mockCluster.disconnect).toHaveBeenCalledTimes(1);
+
+    // Second worker exit during abort — no duplicate report, no refork.
+    harness.clusterHandlers.exit({ id: 2, process: { exitCode: 1 } });
+    expect(harness.mockErrorReporterMessage).toHaveBeenCalledTimes(1);
+    expect(harness.mockCluster.disconnect).toHaveBeenCalledTimes(1);
+    expect(harness.mockFork).toHaveBeenCalledTimes(2);
+  });
+
+  it('does not refork a scheduled-restart worker when aborting for startup failure', () => {
+    const harness = setupMasterRunHarness();
+
+    harness.clusterHandlers.message({ id: 1, process: { exitCode: 1 } }, buildStartupFailureMessage());
+
+    // A scheduled-restart worker exiting during abort should NOT be reforked.
+    expect(() =>
+      harness.clusterHandlers.exit({ id: 2, isScheduledRestart: true, process: { exitCode: 0 } }),
+    ).toThrow('process.exit:1');
+    expect(harness.mockFork).toHaveBeenCalledTimes(2);
+    expect(harness.mockErrorReporterMessage).toHaveBeenCalledTimes(1);
+  });
+
+  it('restarts scheduled-restart workers without reporting an error', () => {
+    const harness = setupMasterRunHarness();
+    const worker: MockWorker = { id: 1, isScheduledRestart: true, process: { exitCode: 0 } };
+
+    harness.clusterHandlers.exit(worker);
+
+    expect(harness.mockFork).toHaveBeenCalledTimes(3);
+    expect(harness.mockErrorReporterMessage).not.toHaveBeenCalled();
+    expect(harness.processExitSpy).not.toHaveBeenCalled();
+  });
+
+  it('waits one tick for startup-failure IPC before classifying an unexpected crash', async () => {
+    const harness = setupMasterRunHarness();
+    harness.mockCluster.disconnect.mockImplementation(() => {});
+    const worker = { id: 1, process: { exitCode: 1 } };
+
+    // Exit arrives first.
+    harness.clusterHandlers.exit(worker);
+    // Startup-failure message arrives before the deferred crash classification runs.
+    harness.clusterHandlers.message(worker, buildStartupFailureMessage());
+    await waitForSetImmediate();
+
+    expect(harness.mockErrorReporterMessage).toHaveBeenCalledWith(
+      'Node renderer startup failed: localhost:3800 is already in use',
+    );
+    expect(harness.mockCluster.disconnect).toHaveBeenCalledTimes(1);
+    expect(harness.mockFork).toHaveBeenCalledTimes(2);
+    expect(harness.processExitSpy).not.toHaveBeenCalled();
+  });
+
+  it('reforks on unexpected runtime crash when no startup failure was received', async () => {
+    const harness = setupMasterRunHarness();
+
+    harness.clusterHandlers.exit({ id: 3, process: { exitCode: 1 } });
+    await waitForSetImmediate();
+
+    expect(harness.mockErrorReporterMessage).toHaveBeenCalledWith(
+      'Worker 3 died UNEXPECTEDLY :(, restarting',
+    );
+    expect(harness.mockFork).toHaveBeenCalledTimes(3);
+    expect(harness.processExitSpy).not.toHaveBeenCalled();
+  });
+
+  it('ignores malformed startup-failure messages and treats exit as runtime crash', async () => {
+    const harness = setupMasterRunHarness();
+
+    harness.clusterHandlers.message({ id: 1, process: { exitCode: 1 } }, { type: WORKER_STARTUP_FAILURE });
+    harness.clusterHandlers.exit({ id: 1, process: { exitCode: 1 } });
+    await waitForSetImmediate();
+
+    expect(harness.mockErrorReporterMessage).toHaveBeenCalledWith(
+      'Worker 1 died UNEXPECTEDLY :(, restarting',
+    );
+    expect(harness.mockFork).toHaveBeenCalledTimes(3);
+    expect(harness.processExitSpy).not.toHaveBeenCalled();
+  });
+});

package/tests/worker.test.ts

@@ -101,6 +101,154 @@ describe('worker', () => {
     expect(fs.existsSync(assetPathOther(testName, String(SECONDARY_BUNDLE_TIMESTAMP)))).toBe(true);
   });
 
+  test('POST /bundles/:bundleTimestamp/render/:renderRequestDigest returns actionable error when renderingRequest is missing', async () => {
+    const app = worker({
+      serverBundleCachePath: serverBundleCachePathForTest(),
+    });
+
+    const res = await app
+      .inject()
+      .post(`/bundles/${BUNDLE_TIMESTAMP}/render/d41d8cd98f00b204e9800998ecf8427e`)
+      .payload({
+        gemVersion,
+        protocolVersion,
+        railsEnv,
+      })
+      .end();
+
+    expect(res.statusCode).toBe(400);
+    expect(res.payload).toContain('Invalid "renderingRequest" field in render request.');
+    expect(res.payload).toContain('Received type: undefined.');
+    expect(res.payload).toContain('Likely causes: request body truncation');
+  });
+
+  test('POST /bundles/:bundleTimestamp/render/:renderRequestDigest does not notify errorReporter for malformed renderingRequest', async () => {
+    const reportMessageSpy = jest.spyOn(errorReporter, 'message').mockImplementation(jest.fn());
+
+    try {
+      const app = worker({
+        serverBundleCachePath: serverBundleCachePathForTest(),
+      });
+
+      const res = await app
+        .inject()
+        .post(`/bundles/${BUNDLE_TIMESTAMP}/render/d41d8cd98f00b204e9800998ecf8427e`)
+        .payload({
+          gemVersion,
+          protocolVersion,
+          railsEnv,
+        })
+        .end();
+
+      expect(res.statusCode).toBe(400);
+      expect(reportMessageSpy).not.toHaveBeenCalled();
+    } finally {
+      reportMessageSpy.mockRestore();
+    }
+  });
+
+  test('POST /bundles/:bundleTimestamp/render/:renderRequestDigest returns actionable error when renderingRequest is null', async () => {
+    const app = worker({
+      serverBundleCachePath: serverBundleCachePathForTest(),
+    });
+
+    const res = await app
+      .inject()
+      .post(`/bundles/${BUNDLE_TIMESTAMP}/render/d41d8cd98f00b204e9800998ecf8427e`)
+      .payload({
+        gemVersion,
+        protocolVersion,
+        railsEnv,
+        renderingRequest: null,
+      })
+      .end();
+
+    expect(res.statusCode).toBe(400);
+    expect(res.payload).toContain('Invalid "renderingRequest" field in render request.');
+    expect(res.payload).toContain('Received type: null.');
+    expect(res.payload).toContain('Likely causes: request body truncation');
+  });
+
+  test('POST /bundles/:bundleTimestamp/render/:renderRequestDigest returns actionable error when renderingRequest is empty string', async () => {
+    const app = worker({
+      serverBundleCachePath: serverBundleCachePathForTest(),
+    });
+
+    const res = await app
+      .inject()
+      .post(`/bundles/${BUNDLE_TIMESTAMP}/render/d41d8cd98f00b204e9800998ecf8427e`)
+      .payload({
+        gemVersion,
+        protocolVersion,
+        railsEnv,
+        renderingRequest: '',
+      })
+      .end();
+
+    expect(res.statusCode).toBe(400);
+    expect(res.payload).toContain('Invalid "renderingRequest" field in render request.');
+    expect(res.payload).toContain('Received type: empty string.');
+    expect(res.payload).toContain('Likely causes: request body truncation');
+  });
+
+  test('POST /bundles/:bundleTimestamp/render/:renderRequestDigest returns actionable error when renderingRequest is an array', async () => {
+    const app = worker({
+      serverBundleCachePath: serverBundleCachePathForTest(),
+    });
+
+    const res = await app
+      .inject()
+      .post(`/bundles/${BUNDLE_TIMESTAMP}/render/d41d8cd98f00b204e9800998ecf8427e`)
+      .payload({
+        gemVersion,
+        protocolVersion,
+        railsEnv,
+        renderingRequest: ['a', 'b'],
+      })
+      .end();
+
+    expect(res.statusCode).toBe(400);
+    expect(res.payload).toContain('Invalid "renderingRequest" field in render request.');
+    expect(res.payload).toContain('Received type: array.');
+    expect(res.payload).not.toMatch(/Received body keys:.*renderingRequest/);
+    expect(res.payload).toContain('Likely causes: request body truncation');
+  });
+
+  test('POST /bundles/:bundleTimestamp/render/:renderRequestDigest filters sensitive body keys case-insensitively in invalid renderingRequest diagnostics', async () => {
+    const app = worker({
+      serverBundleCachePath: serverBundleCachePathForTest(),
+    });
+
+    const res = await app
+      .inject()
+      .post(`/bundles/${BUNDLE_TIMESTAMP}/render/d41d8cd98f00b204e9800998ecf8427e`)
+      .payload({
+        gemVersion,
+        protocolVersion,
+        railsEnv,
+        Password: 'super-secret',
+        apiKey: 'token',
+        Authorization: 'Bearer abc',
+        AUTH_TOKEN: 'auth',
+        accessToken: 'access',
+        authToken: 'auth-camel',
+        Credentials: 'creds-secret',
+        safeField: 'safe',
+      })
+      .end();
+
+    expect(res.statusCode).toBe(400);
+    expect(res.payload).toContain('Received body keys:');
+    expect(res.payload).not.toContain('Password');
+    expect(res.payload).not.toContain('apiKey');
+    expect(res.payload).not.toContain('Authorization');
+    expect(res.payload).not.toContain('AUTH_TOKEN');
+    expect(res.payload).not.toContain('accessToken');
+    expect(res.payload).not.toContain('authToken');
+    expect(res.payload).not.toContain('Credentials');
+    expect(res.payload).toContain('safeField');
+  });
+
   test('POST /bundles/:bundleTimestamp/render/:renderRequestDigest reports unexpected handleRenderRequest failures once', async () => {
     const buildVMSpy = jest.spyOn(vm, 'buildVM').mockRejectedValueOnce(new Error('Injected buildVM failure'));
     const reportMessageSpy = jest.spyOn(errorReporter, 'message').mockImplementation(jest.fn());

package/tests/workerStartupFailure.test.ts

@@ -0,0 +1,250 @@
+import {
+  WORKER_STARTUP_FAILURE,
+  isWorkerStartupFailureMessage,
+  type WorkerStartupFailureMessage,
+} from '../src/shared/workerMessages';
+import { handleStartupListenError } from '../src/worker/startupErrorHandler';
+
+describe('isWorkerStartupFailureMessage', () => {
+  it('returns true for a valid startup failure message', () => {
+    const msg: WorkerStartupFailureMessage = {
+      type: WORKER_STARTUP_FAILURE,
+      stage: 'listen',
+      code: 'EADDRINUSE',
+      errno: -48,
+      syscall: 'listen',
+      host: 'localhost',
+      port: 3800,
+      message: 'listen EADDRINUSE: address already in use :::3800',
+    };
+    expect(isWorkerStartupFailureMessage(msg)).toBe(true);
+  });
+
+  it('returns false for null', () => {
+    expect(isWorkerStartupFailureMessage(null)).toBe(false);
+  });
+
+  it('returns false for a string', () => {
+    expect(isWorkerStartupFailureMessage('hello')).toBe(false);
+  });
+
+  it('returns false for an object with a different type', () => {
+    expect(isWorkerStartupFailureMessage({ type: 'OTHER' })).toBe(false);
+  });
+
+  it('returns false for an object without type', () => {
+    expect(isWorkerStartupFailureMessage({ stage: 'listen' })).toBe(false);
+  });
+
+  it('returns false for a non-integer port', () => {
+    expect(
+      isWorkerStartupFailureMessage({
+        type: WORKER_STARTUP_FAILURE,
+        stage: 'listen',
+        host: 'localhost',
+        port: 3800.5,
+        message: 'some error',
+      }),
+    ).toBe(false);
+  });
+
+  it('returns false for an out-of-range port', () => {
+    expect(
+      isWorkerStartupFailureMessage({
+        type: WORKER_STARTUP_FAILURE,
+        stage: 'listen',
+        host: 'localhost',
+        port: 70000,
+        message: 'some error',
+      }),
+    ).toBe(false);
+  });
+
+  it('returns false for a negative port', () => {
+    expect(
+      isWorkerStartupFailureMessage({
+        type: WORKER_STARTUP_FAILURE,
+        stage: 'listen',
+        host: 'localhost',
+        port: -1,
+        message: 'some error',
+      }),
+    ).toBe(false);
+  });
+});
+
+describe('worker startup listen error handling', () => {
+  const buildListenError = () =>
+    Object.assign(new Error('listen EADDRINUSE: address already in use :::3800'), {
+      code: 'EADDRINUSE',
+      errno: -48,
+      syscall: 'listen',
+    });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('sends WORKER_STARTUP_FAILURE message in clustered mode via the production handler', () => {
+    const sentMessages: unknown[] = [];
+    const exitCalls: number[] = [];
+    const send = ((msg: unknown, _handle?: unknown, _options?: unknown, callback?: () => void) => {
+      sentMessages.push(msg);
+      callback?.();
+      return true;
+    }) as NodeJS.Process['send'];
+    const exit = ((code?: number) => {
+      exitCalls.push(code ?? 0);
+    }) as NodeJS.Process['exit'];
+
+    handleStartupListenError({
+      err: buildListenError(),
+      host: 'localhost',
+      port: 3800,
+      isWorker: true,
+      send,
+      exit,
+    });
+
+    expect(sentMessages).toHaveLength(1);
+    expect(isWorkerStartupFailureMessage(sentMessages[0])).toBe(true);
+    expect(sentMessages[0]).toMatchObject({
+      type: WORKER_STARTUP_FAILURE,
+      stage: 'listen',
+      host: 'localhost',
+      port: 3800,
+      code: 'EADDRINUSE',
+    });
+    expect(exitCalls).toEqual([1]);
+  });
+
+  it('exits without IPC in single-process mode via the production handler', () => {
+    const send = jest.fn();
+    const exitCalls: number[] = [];
+    const exit = ((code?: number) => {
+      exitCalls.push(code ?? 0);
+    }) as NodeJS.Process['exit'];
+
+    handleStartupListenError({
+      err: buildListenError(),
+      host: 'localhost',
+      port: 3800,
+      isWorker: false,
+      send: send as unknown as NodeJS.Process['send'],
+      exit,
+    });
+
+    expect(send).not.toHaveBeenCalled();
+    expect(exitCalls).toEqual([1]);
+  });
+
+  it('logs a warning and exits when cluster worker has no IPC channel', () => {
+    // Temporarily remove process.send so the fallback `send ?? process.send?.bind(process)`
+    // resolves to undefined, simulating a worker whose IPC channel has been destroyed.
+    const originalSend = process.send;
+    delete (process as { send?: typeof process.send }).send;
+
+    const exitCalls: number[] = [];
+    const exit = ((code?: number) => {
+      exitCalls.push(code ?? 0);
+    }) as NodeJS.Process['exit'];
+
+    try {
+      handleStartupListenError({
+        err: buildListenError(),
+        host: 'localhost',
+        port: 3800,
+        isWorker: true,
+        send: undefined,
+        exit,
+      });
+
+      expect(exitCalls).toEqual([1]);
+    } finally {
+      process.send = originalSend;
+    }
+  });
+
+  it('exits when process.send throws synchronously', () => {
+    const send = (() => {
+      throw new Error('ERR_IPC_CHANNEL_CLOSED');
+    }) as NodeJS.Process['send'];
+    const exitCalls: number[] = [];
+    const exit = ((code?: number) => {
+      exitCalls.push(code ?? 0);
+    }) as NodeJS.Process['exit'];
+
+    handleStartupListenError({
+      err: buildListenError(),
+      host: 'localhost',
+      port: 3800,
+      isWorker: true,
+      send,
+      exit,
+    });
+
+    expect(exitCalls).toEqual([1]);
+  });
+
+  it('exits via timeout fallback when IPC callback is never invoked', () => {
+    jest.useFakeTimers();
+    const exitCalls: number[] = [];
+    // send accepts the message but never invokes the callback, simulating a
+    // half-broken IPC channel.
+    const send = ((_msg: unknown, _handle?: unknown, _options?: unknown, _callback?: () => void) =>
+      true) as NodeJS.Process['send'];
+    const exit = ((code?: number) => {
+      exitCalls.push(code ?? 0);
+    }) as NodeJS.Process['exit'];
+
+    handleStartupListenError({
+      err: buildListenError(),
+      host: 'localhost',
+      port: 3800,
+      isWorker: true,
+      send,
+      exit,
+    });
+
+    // Callback was never invoked, so exit hasn't been called yet.
+    expect(exitCalls).toEqual([]);
+
+    // Advance past the IPC_SEND_TIMEOUT_MS (2000ms) fallback timer.
+    jest.advanceTimersByTime(2000);
+    expect(exitCalls).toEqual([1]);
+
+    jest.useRealTimers();
+  });
+
+  it('does not exit twice when callback fires after timeout', () => {
+    jest.useFakeTimers();
+    const exitCalls: number[] = [];
+    let savedCallback: (() => void) | undefined;
+    const send = ((_msg: unknown, _handle?: unknown, _options?: unknown, callback?: () => void) => {
+      savedCallback = callback;
+      return true;
+    }) as NodeJS.Process['send'];
+    const exit = ((code?: number) => {
+      exitCalls.push(code ?? 0);
+    }) as NodeJS.Process['exit'];
+
+    handleStartupListenError({
+      err: buildListenError(),
+      host: 'localhost',
+      port: 3800,
+      isWorker: true,
+      send,
+      exit,
+    });
+
+    // Timeout fires first.
+    jest.advanceTimersByTime(2000);
+    expect(exitCalls).toEqual([1]);
+
+    // Late callback — should be a no-op.
+    savedCallback?.();
+    expect(exitCalls).toEqual([1]);
+
+    jest.useRealTimers();
+  });
+});