@gemus/mcp-proxy 0.1.8 → 0.1.9

package/README.md

@@ -15,6 +15,40 @@ then delivers an unambiguous image to its planned node or conservatively creates
 `image-upload`. MCP initialization advertises the shared Codex capability contract used by the
 server blueprint policy.
 
+## Upstream connection reliability (#2328)
+
+The proxy uses one owned Undici `Agent` for all upstream MCP traffic. By default its TCP
+address-family racing policy sets `autoSelectFamily: true` with a
+`PROXY_CONNECT_ATTEMPT_TIMEOUT_MS=1000` per-address-family attempt window. An operator may set a
+positive numeric override; invalid, empty, and non-positive values fall back to `1000`, while
+values below `10` ms clamp to `10` ms. The transport's request method, body, and auth headers are
+preserved; the proxy adds only that owned dispatcher.
+
+This is a connection-attempt policy, not an MCP retry policy. For a post-start request, a rejected
+`POST` before response headers produces one request only: the affected JSON-RPC id receives `-32000`
+with `Gemus upstream connection failed before a response was received`. The raw network reason is
+never returned to Codex. During `initialize`, the same classification writes one sanitized fatal
+diagnostic and exits non-zero. Once an SSE response has started, a body that ends before its result
+remains the distinct #2068 failure:
+`Gemus upstream stream disconnected before the tool result was delivered`.
+
+On graceful or fatal shutdown, the proxy bounds session `DELETE`, then transport close, before it
+closes the owned Agent. Each stage has a 2-second bound; an Agent that does not close in its bound
+has its retained per-origin dispatchers force-destroyed before the Agent is destroyed. Repeated
+shutdown signals share the same cleanup. See the [transport reliability
+runbook](../../docs/operations/mcp-transport-reliability.md) for the network boundaries and the
+[Companion architecture](../../docs/architecture/agent%20architecture/codex-desktop-companion.md)
+for the request path.
+
+## Release gate (#2330)
+
+This package is prepared as `@gemus/mcp-proxy@0.1.9`; it is not published by this change. Release
+Issue [#2330](https://github.com/Gemus-AI/Gemus/issues/2330) owns the post-merge gate: publish and
+verify the npm package, then in a follow-up change pin the plugin to exact `0.1.9`, forward
+`PROXY_CONNECT_ATTEMPT_TIMEOUT_MS`, bump and sync the plugin, refresh the installed Codex plugin
+cache, and run fresh ESA and direct-domain smoke tests. Until that gate completes, the plugin
+contract stays byte-for-byte at exact `@gemus/mcp-proxy@0.1.8`.
+
 ## What was validated end-to-end (2026-07-06, codex-cli 0.142.2 → local dev `/api/mcp`)
 
 - **Transparent passthrough** — initialize + tools/list relay all **12 gemus tools** (incl.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gemus/mcp-proxy",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Local stdio<->HTTP MCP proxy for Codex desktop: transparent passthrough + execute tap + imagegen backfill (Issue #1751, P1).",
   "type": "module",
   "bin": {
@@ -25,10 +25,11 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "undici": "^6.28.0",
     "@gemus/codex-backfill-core": "0.1.3"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=18.17"
   },
   "files": [
     "src/",

package/src/__tests__/failFast.test.ts

@@ -122,7 +122,7 @@ describe('createFailFast.fetch', () => {
     await drain(res)
 
     expect(onLost).toHaveBeenCalledTimes(1)
-    expect(onLost.mock.calls[0][0]).toBe(42)
+    expect(onLost).toHaveBeenCalledWith(42, { kind: 'stream' })
     expect(ff.failedIds.has('42')).toBe(true)
   })
 
@@ -140,21 +140,90 @@ describe('createFailFast.fetch', () => {
 
   it('fails fast immediately when realFetch throws before any response', async () => {
     const onLost = vi.fn()
-    const realFetch = vi.fn(async () => { throw new Error('ECONNRESET') })
+    const realFetch = vi.fn(async () => {
+      throw new Error('socket reset', { cause: Object.assign(new Error('inner socket failure'), { code: 'ECONNRESET' }) })
+    })
     const ff = createFailFast({ onLost, realFetch })
 
-    await expect(ff.fetch('u', post(7))).rejects.toThrow('ECONNRESET')
-    expect(onLost).toHaveBeenCalledWith(7, expect.stringContaining('upstream fetch failed'))
+    await expect(ff.fetch('u', post(7))).rejects.toThrow('socket reset')
+    expect(onLost).toHaveBeenCalledWith(7, { kind: 'connection', code: 'ECONNRESET' })
     expect(realFetch).toHaveBeenCalledTimes(1) // must NOT retry — a 2nd fetch could execute the tool
   })
 
+  it('allowlists a nested connection code without exposing hostile raw diagnostics or retrying', async () => {
+    const hostile =
+      'Authorization: Bearer arbitrary-secret at '
+      + 'https://alice:password@example.test/api/mcp?token=query-secret '
+      + 'via 203.0.113.1,2001:db8::1'
+    const onLost = vi.fn()
+    const log = vi.fn()
+    const rejection = new Error(`outer ${hostile}`, {
+      cause: new Error(`middle ${hostile}`, {
+        cause: Object.assign(new Error(`inner ${hostile}`), {
+          code: 'UND_ERR_CONNECT_TIMEOUT',
+        }),
+      }),
+    })
+    const realFetch = vi.fn(async () => { throw rejection })
+    const ff = createFailFast({ onLost, log, realFetch })
+
+    await expect(ff.fetch('u', post(71))).rejects.toBe(rejection)
+
+    expect(realFetch).toHaveBeenCalledTimes(1)
+    expect(onLost).toHaveBeenCalledTimes(1)
+    expect(onLost).toHaveBeenCalledWith(71, {
+      kind: 'connection',
+      code: 'UND_ERR_CONNECT_TIMEOUT',
+    })
+    const diagnostics = JSON.stringify(log.mock.calls)
+    expect(diagnostics).not.toMatch(
+      /arbitrary-secret|alice|password|query-secret|203\.0\.113\.1|2001:db8/,
+    )
+  })
+
+  it('classifies an established SSE reader error before its result as a stream failure', async () => {
+    const readerError = new Error('established stream failed')
+    let pulls = 0
+    const body = new ReadableStream<Uint8Array>({
+      pull(controller) {
+        if (pulls++ === 0) {
+          controller.enqueue(enc.encode(': established\n\n'))
+        } else {
+          controller.error(readerError)
+        }
+      },
+    })
+    const onLost = vi.fn()
+    const realFetch = vi.fn(async () => sseRes(body))
+    const ff = createFailFast({ onLost, realFetch })
+
+    const res = await ff.fetch('u', post(72))
+    await expect(drain(res)).rejects.toBe(readerError)
+
+    expect(onLost).toHaveBeenCalledTimes(1)
+    expect(onLost).toHaveBeenCalledWith(72, { kind: 'stream' })
+  })
+
+  it('classifies downstream cancellation before its result as a stream failure', async () => {
+    const onLost = vi.fn()
+    const realFetch = vi.fn(async () => sseRes(neverBody()))
+    const ff = createFailFast({ onLost, realFetch })
+    const res = await ff.fetch('u', post(73))
+    const reader = res.body!.getReader()
+
+    await reader.cancel('downstream closed')
+
+    expect(onLost).toHaveBeenCalledTimes(1)
+    expect(onLost).toHaveBeenCalledWith(73, { kind: 'stream' })
+  })
+
   it('fails fast on a non-ok HTTP response', async () => {
     const onLost = vi.fn()
     const realFetch = vi.fn(async () => sseRes(null, { status: 404, contentType: 'application/json' }))
     const ff = createFailFast({ onLost, realFetch })
 
     await ff.fetch('u', post(7))
-    expect(onLost).toHaveBeenCalledWith(7, 'upstream HTTP 404')
+    expect(onLost).toHaveBeenCalledWith(7, { kind: 'http', status: 404 })
   })
 
   it('passes GET and DELETE through untouched (no body → no monitoring, no onLost)', async () => {
@@ -208,6 +277,39 @@ describe('createFailFast.fetch', () => {
     expect(onLost.mock.calls[0][0]).toBe(1)
   })
 
+  it('does not settle a healthy concurrent request when another connection rejects before response', async () => {
+    let healthyController!: ReadableStreamDefaultController<Uint8Array>
+    const healthyBody = new ReadableStream<Uint8Array>({
+      start(controller) { healthyController = controller },
+    })
+    const connectionError = Object.assign(new Error('connection rejected'), {
+      code: 'ECONNREFUSED',
+    })
+    const onLost = vi.fn()
+    const realFetch = vi.fn(async (_url: unknown, init: { body?: unknown }) => {
+      const [{ id }] = [JSON.parse(String(init.body))]
+      if (id === 74) throw connectionError
+      return sseRes(healthyBody)
+    })
+    const ff = createFailFast({ onLost, realFetch })
+
+    const rejecting = ff.fetch('u', post(74))
+    const healthy = ff.fetch('u', post(75))
+    await expect(rejecting).rejects.toBe(connectionError)
+    const healthyResponse = await healthy
+
+    expect(onLost).toHaveBeenCalledTimes(1)
+    expect(onLost).toHaveBeenCalledWith(74, {
+      kind: 'connection',
+      code: 'ECONNREFUSED',
+    })
+    healthyController.enqueue(enc.encode(resultFrame(75)))
+    healthyController.close()
+    await drain(healthyResponse)
+    expect(onLost).toHaveBeenCalledTimes(1)
+    expect(ff.failedIds.has('75')).toBe(false)
+  })
+
   describe('idle safety timeout', () => {
     beforeEach(() => vi.useFakeTimers())
     afterEach(() => vi.useRealTimers())
@@ -220,7 +322,7 @@ describe('createFailFast.fetch', () => {
       await ff.fetch('u', post(99)) // never emits → idle timer is never reset
       expect(onLost).not.toHaveBeenCalled()
       await vi.advanceTimersByTimeAsync(120_000)
-      expect(onLost).toHaveBeenCalledWith(99, expect.stringContaining('idle'))
+      expect(onLost).toHaveBeenCalledWith(99, { kind: 'idle' })
       ff.dispose()
     })
 

package/src/__tests__/fixtures/proxy-runtime-loader.mjs

@@ -47,14 +47,31 @@ const modules = new Map([
         }
         process.stdin.resume()
         process.stdin.once('end', () => this.onclose?.())
+        if (process.env.PROXY_TEST_SIGNAL_AFTER_START === 'SIGTERM') {
+          setTimeout(() => {
+            if (process.platform === 'win32') {
+              process.emit('SIGTERM')
+            } else {
+              process.kill(process.pid, 'SIGTERM')
+            }
+          }, 0)
+        }
+      }
+      async send(message) {
+        if (process.env.PROXY_TEST_STDIO_CAPTURE_SEND === '1') {
+          process.stdout.write(JSON.stringify(message) + '\\n')
+        }
       }
-      async send() {}
     }
   `],
   ['@modelcontextprotocol/sdk/client/streamableHttp.js', `
     ${markerPrelude}
     export class StreamableHTTPClientTransport {
-      constructor() { mark('upstream-transport') }
+      constructor(url, options) {
+        mark('upstream-transport')
+        this.url = url
+        this.fetch = options.fetch
+      }
       async start() {}
       async send(message) {
         if (
@@ -68,9 +85,72 @@ const modules = new Map([
             + process.env.GEMUS_URL
           )
         }
+        if (
+          process.env.PROXY_TEST_UPSTREAM_INITIALIZE_FETCH_FAILURE === '1'
+          && message?.method === 'initialize'
+        ) {
+          await this.fetch(this.url, {
+            method: 'POST',
+            headers: { Authorization: 'Bearer ' + process.env.GEMUS_KEY },
+            body: JSON.stringify(message),
+          })
+        }
+        if (
+          process.env.PROXY_TEST_LATE_RESULT === '1'
+          && message?.method === 'tools/call'
+        ) {
+          await this.fetch(this.url, {
+            method: 'POST',
+            body: JSON.stringify(message),
+          })
+          setTimeout(() => {
+            this.onmessage?.({
+              jsonrpc: '2.0',
+              id: message.id,
+              result: { content: [{ type: 'text', text: 'late-real-result' }] },
+            })
+          }, 80)
+        }
+      }
+      async terminateSession() {
+        mark('upstream-terminate-session')
+        if (process.env.PROXY_TEST_TERMINATE_SESSION_HANG === '1') {
+          return await new Promise(() => {})
+        }
+        if (process.env.PROXY_TEST_TERMINATE_SESSION_REJECT === '1') {
+          throw new Error('terminate session rejected')
+        }
+      }
+      async close() { mark('upstream-transport-close') }
+    }
+  `],
+  ['undici', `
+    ${markerPrelude}
+    export class Agent {
+      constructor() { mark('upstream-http-agent') }
+      async close() { mark('upstream-http-shutdown') }
+      destroy() { mark('upstream-http-destroy') }
+    }
+    export class Pool {
+      destroy() { mark('upstream-origin-destroy') }
+    }
+    export async function fetch() {
+      mark('undici-fetch')
+      if (process.env.PROXY_TEST_LATE_RESULT === '1') {
+        return new Response(
+          new ReadableStream({ start() {} }),
+          { headers: { 'content-type': 'text/event-stream' } },
+        )
       }
-      async terminateSession() {}
-      async close() {}
+      const error = new Error(
+        'connect failed Authorization: Bearer '
+        + process.env.GEMUS_KEY
+        + ' at '
+        + process.env.GEMUS_URL
+        + ' via 203.0.113.1,2001:db8::1'
+      )
+      error.cause = { code: 'UND_ERR_CONNECT_TIMEOUT' }
+      throw error
     }
   `],
   ['node:http', `
@@ -115,8 +195,8 @@ const modules = new Map([
     export function createBackfiller() {
       mark('backfiller')
       return {
-        observeCall() {},
-        observeResult() {},
+        observeCall() { mark('backfiller-observe-call') },
+        observeResult() { mark('backfiller-observe-result') },
         async backfillTurn() {},
       }
     }

package/src/__tests__/proxyMessages.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from 'vitest'
+import { createProxyFailure, publicMessageForFailure } from '../proxyMessages.mjs'
+
+describe('publicMessageForFailure', () => {
+  it.each([
+    [
+      { kind: 'connection', code: 'UND_ERR_CONNECT_TIMEOUT' },
+      'Gemus upstream connection failed before a response was received',
+    ],
+    [
+      { kind: 'http', status: 503 },
+      'Gemus upstream returned an HTTP error before the tool result was delivered',
+    ],
+    [
+      { kind: 'stream' },
+      'Gemus upstream stream disconnected before the tool result was delivered',
+    ],
+    [
+      { kind: 'idle' },
+      'Gemus upstream stream became unresponsive before the tool result was delivered',
+    ],
+  ])('maps $kind to its delivery-stage message', (failure, expected) => {
+    expect(publicMessageForFailure(failure)).toBe(expected)
+  })
+
+  it('fails closed for an unknown failure kind', () => {
+    expect(publicMessageForFailure({ kind: 'hostile-secret-kind' })).toBe(
+      'Gemus upstream failed before the tool result was delivered',
+    )
+  })
+
+  it.each(['toString', 'constructor', '__proto__'])(
+    'fails closed for the Object.prototype property name %s',
+    (kind) => {
+      expect(publicMessageForFailure({ kind })).toBe(
+        'Gemus upstream failed before the tool result was delivered',
+      )
+    },
+  )
+})
+
+describe('createProxyFailure', () => {
+  it('preserves the original JSON-RPC id in the public error envelope', () => {
+    expect(createProxyFailure('request-17', { kind: 'stream' }).response).toEqual({
+      jsonrpc: '2.0',
+      id: 'request-17',
+      error: {
+        code: -32000,
+        message: 'Gemus upstream stream disconnected before the tool result was delivered',
+      },
+    })
+  })
+
+  it.each([
+    [
+      {
+        kind: 'connection',
+        code: 'UND_ERR_CONNECT_TIMEOUT',
+        reason: 'Authorization: Bearer secret at https://alice:password@example.test/api/mcp?token=secret',
+        addresses: ['203.0.113.1', '2001:db8::1'],
+      },
+      { id: 41, kind: 'connection', code: 'UND_ERR_CONNECT_TIMEOUT' },
+    ],
+    [
+      {
+        kind: 'http',
+        status: 503,
+        reason: 'https://alice:password@example.test/api/mcp?token=secret',
+      },
+      { id: 41, kind: 'http', status: 503 },
+    ],
+  ])('keeps only safe diagnostic fields for $kind failures', (failure, expected) => {
+    const result = createProxyFailure(41, failure)
+    const serialized = JSON.stringify(result)
+
+    expect(result.diagnostic).toEqual(expected)
+    expect(serialized).not.toMatch(
+      /Authorization|Bearer|secret|alice|password|example\.test|203\.0\.113\.1|2001:db8/,
+    )
+  })
+})

package/src/__tests__/startup.test.ts

@@ -37,7 +37,7 @@ async function runProxy(
     closeStdinAfterMs = 600,
     input,
   }: {
-    closeStdinAfterMs?: number
+    closeStdinAfterMs?: number | null
     input?: Record<string, unknown>
   } = {},
 ) {
@@ -69,10 +69,12 @@ async function runProxy(
     child.on('error', reject)
     if (input) child.stdin.write(`${JSON.stringify(input)}\n`)
 
-    const closeTimer = setTimeout(() => child.stdin.end(), closeStdinAfterMs)
+    const closeTimer = closeStdinAfterMs === null
+      ? undefined
+      : setTimeout(() => child.stdin.end(), closeStdinAfterMs)
     const killTimer = setTimeout(() => child.kill(), 5_000)
     child.on('close', (code, signal) => {
-      clearTimeout(closeTimer)
+      if (closeTimer) clearTimeout(closeTimer)
       clearTimeout(killTimer)
       resolve({ code, signal, stdout, stderr })
     })
@@ -337,6 +339,142 @@ describe('proxy process startup', () => {
     }
   })
 
+  it('shuts down the upstream transport before closing its HTTP adapter exactly once', async () => {
+    const tempRoot = await mkdtemp(path.join(tmpdir(), 'gemus-proxy-cleanup-'))
+    const constructionLogPath = path.join(tempRoot, 'construction.log')
+    try {
+      const result = await runProxy({
+        GEMUS_KEY: 'configured-key',
+        PROXY_LOG: undefined,
+        PROXY_TEST_CONSTRUCTION_LOG: constructionLogPath,
+      })
+      const events = (await readFile(constructionLogPath, 'utf8')).trim().split(/\r?\n/)
+
+      expect(result.code).toBe(0)
+      expect(result.signal).toBeNull()
+      expect(events.filter((event) => event === 'upstream-http-agent')).toHaveLength(1)
+      expect(events.filter((event) => event === 'upstream-http-shutdown')).toHaveLength(1)
+      expect(events.indexOf('upstream-terminate-session')).toBeLessThan(
+        events.indexOf('upstream-transport-close'),
+      )
+      expect(events.indexOf('upstream-transport-close')).toBeLessThan(
+        events.indexOf('upstream-http-shutdown'),
+      )
+    } finally {
+      await rm(tempRoot, { recursive: true, force: true })
+    }
+  })
+
+  it('bounds a stuck session DELETE before transport, adapter, and process shutdown', async () => {
+    const tempRoot = await mkdtemp(path.join(tmpdir(), 'gemus-proxy-bounded-cleanup-'))
+    const constructionLogPath = path.join(tempRoot, 'construction.log')
+    try {
+      const result = await runProxy({
+        GEMUS_KEY: 'configured-key',
+        PROXY_LOG: undefined,
+        PROXY_TEST_CONSTRUCTION_LOG: constructionLogPath,
+        PROXY_TEST_TERMINATE_SESSION_HANG: '1',
+      })
+      const events = (await readFile(constructionLogPath, 'utf8')).trim().split(/\r?\n/)
+
+      expect(result.code).toBe(0)
+      expect(result.signal).toBeNull()
+      expect(events.indexOf('upstream-terminate-session')).toBeLessThan(
+        events.indexOf('upstream-transport-close'),
+      )
+      expect(events.indexOf('upstream-transport-close')).toBeLessThan(
+        events.indexOf('upstream-http-shutdown'),
+      )
+      expect(events.filter((event) => event === 'upstream-http-shutdown')).toHaveLength(1)
+    } finally {
+      await rm(tempRoot, { recursive: true, force: true })
+    }
+  }, 10_000)
+
+  it('taps and drops a late real result without forwarding a second stdio response', async () => {
+    const tempRoot = await mkdtemp(path.join(tmpdir(), 'gemus-proxy-late-result-'))
+    const logPath = path.join(tempRoot, 'proxy.log')
+    const constructionLogPath = path.join(tempRoot, 'construction.log')
+    try {
+      const result = await runProxy(
+        {
+          GEMUS_KEY: 'configured-key',
+          PROXY_LOG: logPath,
+          PROXY_FAILFAST_TIMEOUT_MS: '25',
+          PROXY_TEST_CONSTRUCTION_LOG: constructionLogPath,
+          PROXY_TEST_FORWARD_STDIN: '1',
+          PROXY_TEST_LATE_RESULT: '1',
+          PROXY_TEST_STDIO_CAPTURE_SEND: '1',
+        },
+        {
+          input: {
+            jsonrpc: '2.0',
+            id: 76,
+            method: 'tools/call',
+            params: { name: 'execute', arguments: {} },
+          },
+        },
+      )
+      const log = await readFile(logPath, 'utf8')
+      const events = (await readFile(constructionLogPath, 'utf8')).trim().split(/\r?\n/)
+      const stdoutMessages = result.stdout.trim().split(/\r?\n/).map((line) => JSON.parse(line))
+
+      expect(result.code).toBe(0)
+      expect(result.signal).toBeNull()
+      expect(stdoutMessages).toEqual([
+        {
+          jsonrpc: '2.0',
+          id: 76,
+          error: {
+            code: -32000,
+            message: 'Gemus upstream stream became unresponsive before the tool result was delivered',
+          },
+        },
+      ])
+      expect(events.filter((event) => event === 'backfiller-observe-call')).toHaveLength(1)
+      expect(events.filter((event) => event === 'backfiller-observe-result')).toHaveLength(1)
+      expect(log.match(/DROP-AFTER-FAILFAST/g)).toHaveLength(1)
+      expect(log).not.toContain('late-real-result')
+    } finally {
+      await rm(tempRoot, { recursive: true, force: true })
+    }
+  })
+
+  it('continues transport and adapter shutdown after terminateSession rejects on SIGTERM', async () => {
+    const tempRoot = await mkdtemp(path.join(tmpdir(), 'gemus-proxy-signal-cleanup-'))
+    const constructionLogPath = path.join(tempRoot, 'construction.log')
+    try {
+      const result = await runProxy(
+        {
+          GEMUS_KEY: 'configured-key',
+          PROXY_LOG: undefined,
+          PROXY_TEST_CONSTRUCTION_LOG: constructionLogPath,
+          PROXY_TEST_SIGNAL_AFTER_START: 'SIGTERM',
+          PROXY_TEST_TERMINATE_SESSION_REJECT: '1',
+        },
+        {
+          closeStdinAfterMs: null,
+        },
+      )
+      const events = (await readFile(constructionLogPath, 'utf8')).trim().split(/\r?\n/)
+
+      expect(result.code).toBe(0)
+      expect(result.signal).toBeNull()
+      expect(result.stderr).toBe('')
+      expect(events.filter((event) => event === 'upstream-terminate-session')).toHaveLength(1)
+      expect(events.filter((event) => event === 'upstream-transport-close')).toHaveLength(1)
+      expect(events.filter((event) => event === 'upstream-http-shutdown')).toHaveLength(1)
+      expect(events.indexOf('upstream-terminate-session')).toBeLessThan(
+        events.indexOf('upstream-transport-close'),
+      )
+      expect(events.indexOf('upstream-transport-close')).toBeLessThan(
+        events.indexOf('upstream-http-shutdown'),
+      )
+    } finally {
+      await rm(tempRoot, { recursive: true, force: true })
+    }
+  })
+
   it('keeps exit code 1 when stdio onclose races with a startup error', async () => {
     const secret = 'arbitrary-secret'
     const result = await runProxy({
@@ -390,6 +528,62 @@ describe('proxy process startup', () => {
     )
   })
 
+  it('classifies an initialize fetch rejection without exposing its raw network error', async () => {
+    const tempRoot = await mkdtemp(path.join(tmpdir(), 'gemus-proxy-initialize-fetch-'))
+    const logPath = path.join(tempRoot, 'proxy.log')
+    const constructionLogPath = path.join(tempRoot, 'construction.log')
+    const secret = 'arbitrary-secret'
+    const endpoint =
+      'https://alice:password@example.test/api/mcp?token=query-secret#fragment-secret'
+    try {
+      const result = await runProxy(
+        {
+          GEMUS_KEY: secret,
+          GEMUS_URL: endpoint,
+          PROXY_LOG: logPath,
+          PROXY_TEST_CONSTRUCTION_LOG: constructionLogPath,
+          PROXY_TEST_FORWARD_STDIN: '1',
+          PROXY_TEST_UPSTREAM_INITIALIZE_FETCH_FAILURE: '1',
+        },
+        {
+          input: {
+            jsonrpc: '2.0',
+            id: 29,
+            method: 'initialize',
+            params: {
+              protocolVersion: '2025-06-18',
+              capabilities: {},
+              clientInfo: { name: 'startup-test', version: '1.0.0' },
+            },
+          },
+        },
+      )
+      const log = await readFileOrEmpty(logPath)
+      const events = (await readFile(constructionLogPath, 'utf8')).trim().split(/\r?\n/)
+      const fatalLines = log.split(/\r?\n/).filter((line) => line.includes(' FATAL '))
+
+      expect(result.code).toBe(1)
+      expect(result.signal).toBeNull()
+      expect(result.stderr).toBe(
+        'Gemus MCP proxy failed to start: Gemus upstream connection failed before a response was received\n',
+      )
+      expect(result.stderr.trim().split(/\r?\n/)).toHaveLength(1)
+      expect(events.filter((event) => event === 'upstream-http-agent')).toHaveLength(1)
+      expect(events.filter((event) => event === 'undici-fetch')).toHaveLength(1)
+      expect(events.filter((event) => event === 'upstream-http-shutdown')).toHaveLength(1)
+      expect(log).toContain('"kind":"connection","code":"UND_ERR_CONNECT_TIMEOUT"')
+      expect(fatalLines).toHaveLength(1)
+      for (const output of [result.stderr, log]) {
+        expect(output).not.toContain(endpoint)
+        expect(output).not.toMatch(
+          /arbitrary-secret|alice|password|query-secret|fragment-secret|203\.0\.113\.1|2001:db8/,
+        )
+      }
+    } finally {
+      await rm(tempRoot, { recursive: true, force: true })
+    }
+  })
+
   it.each(['ftp', 'ws'])(
     'sanitizes a credential-bearing %s endpoint in a real initialize failure',
     async (scheme) => {

package/src/__tests__/upstreamHttp.real.test.ts

@@ -0,0 +1,37 @@
+import { createServer, type Server } from 'node:http'
+import type { Socket } from 'node:net'
+import { afterEach, describe, expect, it } from 'vitest'
+import { createUpstreamHttp } from '../upstreamHttp.mjs'
+
+let server: Server | undefined
+
+afterEach(async () => {
+  server?.closeAllConnections()
+  if (server?.listening) {
+    await new Promise<void>((resolve) => server?.close(() => resolve()))
+  }
+  server = undefined
+})
+
+describe('createUpstreamHttp with real Undici dispatchers', () => {
+  it('force-closes an established hanging response after the graceful budget expires', async () => {
+    let activeSocket!: Socket
+    server = createServer((request, response) => {
+      activeSocket = request.socket
+      response.writeHead(200, { 'content-type': 'text/event-stream' })
+      response.write(': heartbeat\n\n')
+    })
+    await new Promise<void>((resolve) => server?.listen(0, '127.0.0.1', resolve))
+    const address = server.address()
+    if (!address || typeof address === 'string') throw new Error('expected a TCP listener')
+
+    const upstream = createUpstreamHttp()
+    const response = await upstream.fetch(`http://127.0.0.1:${address.port}/api/mcp`)
+    expect(response.ok).toBe(true)
+    expect(activeSocket.destroyed).toBe(false)
+
+    await upstream.shutdown()
+
+    await expect.poll(() => activeSocket.destroyed, { timeout: 500 }).toBe(true)
+  }, 5000)
+})

package/src/__tests__/upstreamHttp.test.ts

@@ -0,0 +1,151 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const undiciFetch = vi.fn()
+const agents: Array<{ options: unknown; close: ReturnType<typeof vi.fn>; destroy: ReturnType<typeof vi.fn> }> = []
+const pools: Array<{ origin: unknown; options: unknown; destroy: ReturnType<typeof vi.fn> }> = []
+
+const Agent = vi.fn(function Agent(options) {
+  const agent = {
+    options,
+    close: vi.fn(() => Promise.resolve()),
+    destroy: vi.fn(),
+  }
+  agents.push(agent)
+  return agent
+})
+
+const Pool = vi.fn(function Pool(origin, options) {
+  const pool = {
+    origin,
+    options,
+    destroy: vi.fn(() => Promise.resolve()),
+  }
+  pools.push(pool)
+  return pool
+})
+
+vi.mock('undici', () => ({ Agent, Pool, fetch: undiciFetch }))
+
+async function createAdapter() {
+  return (await import('../upstreamHttp.mjs')).createUpstreamHttp()
+}
+
+beforeEach(() => {
+  agents.length = 0
+  pools.length = 0
+  Agent.mockClear()
+  Pool.mockClear()
+  undiciFetch.mockReset()
+  delete process.env.PROXY_CONNECT_ATTEMPT_TIMEOUT_MS
+})
+
+afterEach(() => {
+  vi.useRealTimers()
+  delete process.env.PROXY_CONNECT_ATTEMPT_TIMEOUT_MS
+})
+
+describe('createUpstreamHttp', () => {
+  it('creates one Agent with the 1000ms address-family attempt window by default', async () => {
+    const upstream = await createAdapter()
+
+    expect(upstream.attemptTimeoutMs).toBe(1000)
+    expect(Agent).toHaveBeenCalledTimes(1)
+    expect(agents[0].options).toEqual({
+      factory: expect.any(Function),
+      connect: {
+        autoSelectFamily: true,
+        autoSelectFamilyAttemptTimeout: 1000,
+      },
+    })
+  })
+
+  it.each([
+    ['', 1000],
+    ['not-a-number', 1000],
+    ['Infinity', 1000],
+    ['0', 1000],
+    ['-1', 1000],
+    ['9.9', 10],
+    ['10.9', 10],
+    ['251.9', 251],
+  ])('normalizes PROXY_CONNECT_ATTEMPT_TIMEOUT_MS=%j to %i milliseconds', async (value, expected) => {
+    process.env.PROXY_CONNECT_ATTEMPT_TIMEOUT_MS = value
+
+    const upstream = await createAdapter()
+
+    expect(upstream.attemptTimeoutMs).toBe(expected)
+    expect(agents[0].options).toEqual({
+      factory: expect.any(Function),
+      connect: {
+        autoSelectFamily: true,
+        autoSelectFamilyAttemptTimeout: expected,
+      },
+    })
+  })
+
+  it('preserves transport request init while injecting its dispatcher', async () => {
+    const upstream = await createAdapter()
+    const signal = new AbortController().signal
+    const init = {
+      method: 'POST',
+      headers: { authorization: 'Bearer example', accept: 'text/event-stream' },
+      body: '{"jsonrpc":"2.0","id":7}',
+      signal,
+      cache: 'no-store' as RequestCache,
+      redirect: 'manual' as RequestRedirect,
+    }
+    undiciFetch.mockResolvedValue(new Response('ok'))
+
+    await upstream.fetch('https://example.test/api/mcp', init)
+
+    expect(undiciFetch).toHaveBeenCalledTimes(1)
+    expect(undiciFetch).toHaveBeenCalledWith('https://example.test/api/mcp', {
+      ...init,
+      dispatcher: agents[0],
+    })
+    expect(init).not.toHaveProperty('dispatcher')
+  })
+
+  it('propagates a failed request after one fetch attempt', async () => {
+    const upstream = await createAdapter()
+    undiciFetch.mockRejectedValue(new Error('connect failed'))
+
+    await expect(upstream.fetch('https://example.test/api/mcp', { method: 'POST', body: 'side-effecting' })).rejects.toThrow('connect failed')
+
+    expect(undiciFetch).toHaveBeenCalledTimes(1)
+  })
+
+  it('shares one graceful shutdown across repeated calls', async () => {
+    const upstream = await createAdapter()
+    let finishClose!: () => void
+    agents[0].close.mockImplementation(() => new Promise<void>((resolve) => { finishClose = resolve }))
+
+    const first = upstream.shutdown()
+    const second = upstream.shutdown()
+    expect(second).toBe(first)
+    expect(agents[0].close).toHaveBeenCalledTimes(1)
+
+    finishClose()
+    await first
+    await upstream.shutdown()
+    expect(agents[0].close).toHaveBeenCalledTimes(1)
+    expect(agents[0].destroy).not.toHaveBeenCalled()
+  })
+
+  it('destroys retained origin dispatchers and the Agent when graceful close exceeds 2000ms', async () => {
+    vi.useFakeTimers()
+    const upstream = await createAdapter()
+    agents[0].close.mockImplementation(() => new Promise<void>(() => {}))
+    const factory = (agents[0].options as { factory: (origin: string, options: object) => unknown }).factory
+    factory('https://example.test', { connections: 2 })
+
+    const shutdown = upstream.shutdown()
+    await vi.advanceTimersByTimeAsync(2000)
+    await shutdown
+
+    expect(agents[0].close).toHaveBeenCalledTimes(1)
+    expect(agents[0].destroy).toHaveBeenCalledTimes(1)
+    expect(pools[0].destroy).toHaveBeenCalledTimes(1)
+    expect(upstream.shutdown()).toBe(shutdown)
+  })
+})

package/src/failFast.mjs

@@ -93,11 +93,24 @@ export function createSseIdScanner() {
   }
 }
 
+/** Extract an allowlisted network error code without exposing the raw error text. */
+function failureCode(error) {
+  let current = error
+  for (let depth = 0; depth < 8 && current && typeof current === 'object'; depth++) {
+    if (typeof current.code === 'string') {
+      const code = current.code.toUpperCase()
+      if (/^[A-Z0-9_]{1,64}$/.test(code)) return code
+    }
+    current = current.cause
+  }
+  return 'UNKNOWN'
+}
+
 /**
  * Build the fail-fast fetch wrapper + settle/dispose controls.
  *
  * @param {object} opts
- * @param {(id:any, reason:string)=>void} opts.onLost  called once per lost id (must be idempotent-safe on caller side)
+ * @param {(id:any, failure:{kind:string, code?:string, status?:number})=>void} opts.onLost  called once per lost id (must be idempotent-safe on caller side)
  * @param {number} [opts.idleTimeoutMs]  IDLE backstop reset on every upstream byte (incl. server
  *   heartbeats every ~12s), so it trips ONLY on a genuinely silent/zombie connection — never on a
  *   healthy-but-slow tool. Must be < Codex 300s; default 120_000.
@@ -117,7 +130,7 @@ export function createFailFast(opts) {
   const failedIds = new Set()
 
   function armTimer(entry, id) {
-    entry.timer = setTimeout(() => lose(id, 'proxy idle timeout (no upstream bytes)'), idleTimeoutMs)
+    entry.timer = setTimeout(() => lose(id, { kind: 'idle' }), idleTimeoutMs)
     if (typeof entry.timer.unref === 'function') entry.timer.unref()
   }
 
@@ -150,15 +163,15 @@ export function createFailFast(opts) {
     failedIds.delete(String(id))
   }
 
-  function lose(id, reason) {
+  function lose(id, failure) {
     const key = String(id)
     if (!inFlight.has(key)) return // already settled or already lost
     settle(id)
     failedIds.add(key)
     // Bound the set: disconnect-case entries never see a late result to forget(), so cap FIFO.
     if (failedIds.size > FAILED_IDS_CAP) failedIds.delete(failedIds.values().next().value)
-    log('FAILFAST', { id, reason })
-    onLost(id, reason)
+    log('FAILFAST', { id, ...failure })
+    onLost(id, failure)
   }
 
   function observeAndForward(body, codexIds) {
@@ -168,7 +181,7 @@ export function createFailFast(opts) {
     const onEnd = () => {
       if (ended) return
       ended = true
-      for (const id of codexIds) lose(id, 'upstream stream closed before result')
+      for (const id of codexIds) lose(id, { kind: 'stream' })
     }
     return new ReadableStream({
       async pull(controller) {
@@ -218,7 +231,7 @@ export function createFailFast(opts) {
       codexIds = parseRequestIds(init).filter(isCodexOriginated)
       for (const id of codexIds) register(id)
     } catch (e) {
-      log('FAILFAST-WRAP-ERR', String(e))
+      log('FAILFAST-WRAP-ERR', { code: failureCode(e) })
       codexIds = []
     }
 
@@ -229,7 +242,7 @@ export function createFailFast(opts) {
       res = await realFetch(url, init)
     } catch (e) {
       // Connection failed before any response (DNS / TLS / RST) — fail fast, don't wait 270s.
-      for (const id of codexIds) lose(id, `upstream fetch failed: ${e}`)
+      for (const id of codexIds) lose(id, { kind: 'connection', code: failureCode(e) })
       throw e // preserve the SDK's existing onerror/logging path (no re-fetch)
     }
 
@@ -241,7 +254,7 @@ export function createFailFast(opts) {
       if (!res.ok) {
         // Non-SSE HTTP error (404 session-gone / 403 / 429 / …). send() throws before onmessage,
         // and that rejection is swallowed by upstream.send().catch — so nothing ever settles the id.
-        for (const id of codexIds) lose(id, `upstream HTTP ${res.status}`)
+        for (const id of codexIds) lose(id, { kind: 'http', status: res.status })
         return res
       }
       const ct = res.headers.get('content-type') || ''
@@ -252,7 +265,7 @@ export function createFailFast(opts) {
         headers: res.headers,
       })
     } catch (e) {
-      log('FAILFAST-WRAP-ERR', String(e))
+      log('FAILFAST-WRAP-ERR', { code: failureCode(e) })
       return res
     }
   }

package/src/proxy.mjs

@@ -28,11 +28,14 @@ import { createBackfiller, injectSteering } from './backfill.mjs'
 import { unwrapMcpContent } from '@gemus/codex-backfill-core'
 import { buildProxyUpstreamHeaders } from './mcpHeaders.mjs'
 import { createFailFast, isJsonRpcResponse } from './failFast.mjs'
+import { createProxyFailure } from './proxyMessages.mjs'
+import { createUpstreamHttp } from './upstreamHttp.mjs'
 import {
   assertGemusKey,
   createFatalReporter,
   createShutdownCoordinator,
   safeEndpointLabel,
+  settleWithin,
   startProxy,
 } from './startup.mjs'
 
@@ -284,6 +287,8 @@ if (typeof hookServer.unref === 'function') hookServer.unref()
 
 // ── transparent JSON-RPC passthrough (raw send/onmessage) ──────────────────────────────────────
 const stdio = new StdioServerTransport()
+const initializingIds = new Set()
+const classifiedInitializeFailures = new Set()
 
 // #2068 fail-fast: StreamableHTTPClientTransport.send() resolves before the upstream SSE result
 // arrives and only surfaces a stream death via a global, id-less `onerror` (no reconnect for POST).
@@ -292,17 +297,21 @@ const stdio = new StdioServerTransport()
 // of hanging to its 300s timeout. onLost only injects to stdio — it does NOT tap: tapping here would
 // delete the proxy's `inflight` entry, so the DROP-AFTER-FAILFAST branch below could no longer let
 // backfill observe a late real result (env delivery on the still-open, idle-timed-out case).
+const upstreamHttp = createUpstreamHttp()
 const failFast = createFailFast({
   idleTimeoutMs: Number(process.env.PROXY_FAILFAST_TIMEOUT_MS) || 120_000,
+  realFetch: upstreamHttp.fetch,
   log,
-  onLost: (id, reason) => {
-    const errObj = {
-      jsonrpc: '2.0',
-      id,
-      error: { code: -32000, message: 'Gemus upstream stream disconnected before the tool result was delivered' },
+  onLost: (id, failure) => {
+    const { response, diagnostic } = createProxyFailure(id, failure)
+    const key = String(id)
+    log('FAILFAST-INJECT', diagnostic)
+    if (initializingIds.has(key)) {
+      classifiedInitializeFailures.add(key)
+      void terminateFatally(new Error(response.error.message))
+      return
     }
-    log('FAILFAST-INJECT', { id, reason })
-    stdio.send(errObj).catch((e) => log('ERR-stdio-send', String(e)))
+    stdio.send(response).catch((e) => log('ERR-stdio-send', String(e)))
   },
 })
 
@@ -314,12 +323,17 @@ const upstream = new StreamableHTTPClientTransport(new URL(GEMUS_URL), {
 stdio.onmessage = (m) => {
   tapClientToServer(m)
   log('C->G', m)
+  const key = String(m?.id)
+  if (m?.method === 'initialize') initializingIds.add(key)
   upstream.send(m).catch((error) => {
+    const classified = classifiedInitializeFailures.delete(key)
+    initializingIds.delete(key)
     if (m?.method === 'initialize') {
+      if (classified) return
       void terminateFatally(error)
       return
     }
-    log('ERR-http-send', String(error))
+    log('ERR-http-send', { kind: 'transport' })
   })
 }
 upstream.onmessage = (m) => {
@@ -338,6 +352,7 @@ upstream.onmessage = (m) => {
   // (elicitation/sampling) also carries an id that can collide with an in-flight tools/call id, and
   // must be forwarded to Codex untouched, never settled/dropped.
   if (isJsonRpcResponse(m)) {
+    initializingIds.delete(String(m.id))
     if (failFast.failedIds.has(String(m.id))) {
       // Already fail-fasted (idle timeout on a still-open stream) → Codex got the error. Still tap so
       // backfill (#1751) observes the late real result (inflight survives — onLost didn't tap), but
@@ -358,6 +373,7 @@ upstream.onmessage = (m) => {
 // **independent of Codex tool activity**, so a proxy mid-imagegen (silent to Codex for minutes) still
 // proves liveness → the platform reclaims only genuinely-dead sessions (short floor), never a live one.
 const HEARTBEAT_MS = Number(process.env.PROXY_HEARTBEAT_MS) || 30_000
+const SHUTDOWN_STEP_TIMEOUT_MS = 2000
 let pingSeq = 0
 let heartbeatTimer
 function startHeartbeat() {
@@ -377,8 +393,15 @@ async function cleanup() {
   failFast.dispose() // #2068: clear fail-fast final-safety timers
   try { hookServer.close() } catch { /* ignore */ }
   if (discoveryFile) { try { fs.unlinkSync(discoveryFile) } catch { /* ignore */ } }
-  try { await upstream.terminateSession() } catch { /* ignore */ }
-  try { await upstream.close() } catch { /* ignore */ }
+  await settleWithin(
+    Promise.resolve().then(() => upstream.terminateSession()),
+    SHUTDOWN_STEP_TIMEOUT_MS,
+  )
+  await settleWithin(
+    Promise.resolve().then(() => upstream.close()),
+    SHUTDOWN_STEP_TIMEOUT_MS,
+  )
+  try { await upstreamHttp.shutdown() } catch { /* ignore */ }
 }
 shutdown = createShutdownCoordinator({
   cleanup,
@@ -391,7 +414,7 @@ function shutdownGracefully() {
 stdio.onclose = () => { log('stdio-close', ''); void shutdownGracefully() }
 upstream.onclose = () => { log('http-close', '') }
 stdio.onerror = (e) => log('stdio-err', String(e))
-upstream.onerror = (e) => log('http-err', String(e))
+upstream.onerror = () => log('http-err', { kind: 'transport' })
 process.on('SIGTERM', () => { void shutdownGracefully() })
 process.on('SIGINT', () => { void shutdownGracefully() })
 

package/src/proxyMessages.mjs

@@ -0,0 +1,38 @@
+const PUBLIC_MESSAGES = {
+  connection: 'Gemus upstream connection failed before a response was received',
+  http: 'Gemus upstream returned an HTTP error before the tool result was delivered',
+  stream: 'Gemus upstream stream disconnected before the tool result was delivered',
+  idle: 'Gemus upstream stream became unresponsive before the tool result was delivered',
+}
+
+const FALLBACK_MESSAGE = 'Gemus upstream failed before the tool result was delivered'
+const SAFE_CODE = /^[A-Z0-9_]{1,64}$/
+
+export function publicMessageForFailure(failure) {
+  return Object.hasOwn(PUBLIC_MESSAGES, failure?.kind)
+    ? PUBLIC_MESSAGES[failure.kind]
+    : FALLBACK_MESSAGE
+}
+
+export function createProxyFailure(id, failure) {
+  const knownKind = Object.hasOwn(PUBLIC_MESSAGES, failure?.kind)
+  const kind = knownKind ? failure.kind : 'unknown'
+  const diagnostic = { id, kind }
+
+  if (kind === 'connection') {
+    diagnostic.code = typeof failure.code === 'string' && SAFE_CODE.test(failure.code)
+      ? failure.code
+      : 'UNKNOWN'
+  } else if (kind === 'http' && Number.isInteger(failure.status)) {
+    diagnostic.status = failure.status
+  }
+
+  return {
+    response: {
+      jsonrpc: '2.0',
+      id,
+      error: { code: -32000, message: publicMessageForFailure(failure) },
+    },
+    diagnostic,
+  }
+}

package/src/startup.mjs

@@ -92,3 +92,19 @@ export function createShutdownCoordinator({ cleanup, exit }) {
     return cleanupPromise
   }
 }
+
+export function settleWithin(promise, timeoutMs) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => resolve('timed_out'), timeoutMs)
+    Promise.resolve(promise).then(
+      () => {
+        clearTimeout(timer)
+        resolve('settled')
+      },
+      () => {
+        clearTimeout(timer)
+        resolve('settled')
+      },
+    )
+  })
+}

package/src/upstreamHttp.mjs

@@ -0,0 +1,69 @@
+import { Agent, Pool, fetch as undiciFetch } from 'undici'
+
+const DEFAULT_ATTEMPT_TIMEOUT_MS = 1000
+const MIN_ATTEMPT_TIMEOUT_MS = 10
+const SHUTDOWN_TIMEOUT_MS = 2000
+
+function attemptTimeoutFromEnvironment(value) {
+  const parsed = Number(value)
+  if (!value || !Number.isFinite(parsed) || parsed <= 0) return DEFAULT_ATTEMPT_TIMEOUT_MS
+  return Math.max(MIN_ATTEMPT_TIMEOUT_MS, Math.trunc(parsed))
+}
+
+function settleClose(closePromise) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => resolve('timed_out'), SHUTDOWN_TIMEOUT_MS)
+    Promise.resolve(closePromise).then(
+      () => {
+        clearTimeout(timer)
+        resolve('settled')
+      },
+      () => {
+        clearTimeout(timer)
+        resolve('rejected')
+      },
+    )
+  })
+}
+
+/** Owns the MCP upstream dispatcher and its bounded shutdown. */
+export function createUpstreamHttp() {
+  const attemptTimeoutMs = attemptTimeoutFromEnvironment(process.env.PROXY_CONNECT_ATTEMPT_TIMEOUT_MS)
+  const originDispatchers = new Set()
+  const dispatcher = new Agent({
+    factory(origin, options) {
+      const originDispatcher = new Pool(origin, options)
+      originDispatchers.add(originDispatcher)
+      return originDispatcher
+    },
+    connect: {
+      autoSelectFamily: true,
+      autoSelectFamilyAttemptTimeout: attemptTimeoutMs,
+    },
+  })
+  let shutdownPromise
+
+  function upstreamFetch(input, init) {
+    return undiciFetch(input, { ...init, dispatcher })
+  }
+
+  function shutdown() {
+    if (!shutdownPromise) {
+      shutdownPromise = (async () => {
+        const closePromise = dispatcher.close()
+        const outcome = await settleClose(closePromise)
+        if (outcome !== 'settled') {
+          const error = new Error('MCP upstream dispatcher shutdown timed out')
+          await Promise.allSettled([
+            dispatcher.destroy(error),
+            ...Array.from(originDispatchers, (originDispatcher) => originDispatcher.destroy(error)),
+          ])
+        }
+        originDispatchers.clear()
+      })()
+    }
+    return shutdownPromise
+  }
+
+  return { fetch: upstreamFetch, shutdown, attemptTimeoutMs }
+}