test(e2e): narrow address-in-use retries

Author: ihor-sokoliuk

__tests__/e2e/helpers/spawn-server.ts

@@ -81,6 +81,16 @@ interface HttpCliAttempt {
   close: () => Promise<void>;
 }
 
+class HttpCliStartupError extends Error {
+  readonly code?: string;
+
+  constructor(message: string, readonly startupStderr: string, code?: string) {
+    super(message);
+    this.name = 'HttpCliStartupError';
+    this.code = code;
+  }
+}
+
 const MAX_HTTP_CLI_START_ATTEMPTS = 2;
 const MAX_CAPTURED_OUTPUT_CHARS = 64 * 1024;
 const MAX_HEALTH_RESPONSE_CHARS = 16 * 1024;
@@ -251,21 +261,32 @@ async function captureCleanupFailure(close: () => Promise<void>): Promise<string
   }
 }
 
+function getErrorCode(error: Error): string | undefined {
+  const code = (error as Error & { code?: unknown }).code;
+  return typeof code === 'string' ? code : undefined;
+}
+
 async function startHttpCliAttempt(port: number, config: HttpCliConfig): Promise<SpawnedHttpCli> {
   const attempt = createHttpCliAttempt(port, config);
   try {
     const health = await waitForHealth(attempt.child, port, attempt.output, config.readyTimeoutMs);
     return { url: attempt.url, health, close: attempt.close };
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
+    const code = error instanceof Error ? getErrorCode(error) : undefined;
     const cleanupFailure = await captureCleanupFailure(attempt.close);
     const cleanupError = cleanupFailure ? `; cleanupFailure=${JSON.stringify(cleanupFailure)}` : '';
-    throw new Error(`${message}; cleanup=${diagnostics(attempt.child, attempt.output)}${cleanupError}`);
+    throw new HttpCliStartupError(
+      `${message}; cleanup=${diagnostics(attempt.child, attempt.output)}${cleanupError}`,
+      attempt.output.stderr,
+      code,
+    );
   }
 }
 
 function isAddressInUse(error: Error): boolean {
-  return error.message.includes('EADDRINUSE');
+  return getErrorCode(error) === 'EADDRINUSE'
+    || error instanceof HttpCliStartupError && error.startupStderr.includes('EADDRINUSE');
 }
 
 /** Starts the built CLI on an isolated loopback port and waits for /health. */

__tests__/e2e/http-transport.e2e.ts

@@ -86,7 +86,7 @@ async function runTests() {
       server = await spawnHttpCli({
         reservePort: async () => {
           reserveCalls++;
-          if (reserveCalls === 1) throw new Error('EADDRINUSE deterministic test collision');
+          if (reserveCalls === 1) throw Object.assign(new Error('deterministic test collision'), { code: 'EADDRINUSE' });
           return await reserveTestPort();
         },
       });
@@ -96,6 +96,26 @@ async function runTests() {
     }
   }, results);
 
+  await testFunction('HTTP CLI does not retry when only stdout mentions EADDRINUSE', async () => {
+    let reserveCalls = 0;
+    await assert.rejects(
+      () => spawnHttpCli({
+        args: ['-e', "process.stdout.write('EADDRINUSE in child stdout only'); process.exit(7);"],
+        reservePort: async () => {
+          reserveCalls++;
+          return await reserveTestPort();
+        },
+      }),
+      (error: unknown) => {
+        const message = error instanceof Error ? error.message : String(error);
+        assert.match(message, /HTTP CLI exited before health became ready/);
+        assert.match(message, /EADDRINUSE in child stdout only/);
+        return true;
+      },
+    );
+    assert.equal(reserveCalls, 1);
+  }, results);
+
   await testFunction('HTTP CLI readiness timeout includes diagnostics and reaps the child', async () => {
     await assert.rejects(
       () => spawnHttpCli({