@gemus/mcp-proxy 0.1.7 → 0.1.9

package/README.md

@@ -1,9 +1,10 @@
 # @gemus/mcp-proxy (Issues #1751, #1756, #1917)
 
 Local stdio↔HTTP MCP proxy that gives **Codex desktop (direct-connect / Mode B)** users canvas
-image write-back. Bundled into the Codex plugin (`.codex-plugin/`), declared as a **command-based**
-MCP server so codex spawns it locally; the proxy owns upstream auth to the remote gemus `/api/mcp`
-(Codex does no OAuth for stdio servers). Full design: `docs/plans/1751-codex-desktop-companion.md`
+image write-back. The Codex plugin declares it as a **default-disabled, command-based** MCP server
+so Codex can spawn it locally after explicit enablement; the proxy owns upstream auth to the remote
+Gemus `/api/mcp` (Codex does no OAuth for stdio servers). Full design:
+`docs/plans/1751-codex-desktop-companion.md`
 and `docs/architecture/agent architecture/codex-desktop-companion.md`.
 
 ## Status: implemented
@@ -14,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.
@@ -27,24 +62,55 @@ server blueprint policy.
 - **(c) turn-end + retrieval** — `Stop` hook fires post-flush carrying `transcript_path` → exact
   rollout; imagegen writes `generated_images/<session>/<sanitized-call-id>.png` (historically `ig_*`,
   currently `call_*`) + rollout `saved_path`+base64.
-- **Session cap** — `KEY_ONLY_SESSION_CAP=3`/user is real; the proxy MUST `DELETE` its upstream
-  session on close (implemented in `shutdown()`) to avoid leaking slots.
+- **Session cap** — the key-only session cap defaults to 10 concurrent sessions per user
+  (`MCP_KEY_ONLY_SESSION_CAP`); the proxy MUST `DELETE` its upstream session on close (implemented
+  in `cleanup()`) to avoid leaking slots.
 
-## Install (Codex desktop)
+## Companion setup and migration (Codex desktop)
 
-The key is supplied as a **literal** in the user's *local* codex config — codex does NOT interpolate
-`${VAR}` in an MCP server's `env`, and a public plugin manifest must never carry a key (Step-0.4
-findings). So the keyed MCP server is registered locally, not via the plugin manifest:
+The plugin owns the non-secret process contract: exact `@gemus/mcp-proxy@0.1.8`,
+`startup_timeout_sec = 60`, `tool_timeout_sec = 300`, and a default-disabled rollout. The user
+environment owns `GEMUS_KEY` and optional `GEMUS_URL`; the public plugin and generated commands
+never contain their values.
 
-```bash
-# 1. Register the proxy as codex's gemus MCP server (writes a literal key into ~/.codex/config.toml).
-codex mcp add gemus --env GEMUS_KEY=mak_<your key> -- npx -y @gemus/mcp-proxy
-#    (get a mak_ key from gemus.ai → Settings → MCP Keys; GEMUS_URL defaults to https://gemus.ai/api/mcp)
-
-# 2. Install the plugin (Stop hook + skills) from the gemus marketplace, then TRUST the hook:
-codex plugin add gemus@<marketplace>
-#    In interactive codex run `/hooks` and trust the gemus Stop hook — REQUIRED for canvas backfill.
-#    Without a trusted hook, images still land on the canvas (orphan node), just not the planned node.
+Environment ownership and lifetime:
+
+- **Windows / PowerShell:** persist the key in the Windows user environment and refresh the current
+  process.
+- **macOS:** If changing login context, sign out and back in first; rerun the `launchctl setenv`
+  setup in the new login session; then fully quit and restart Codex and open a new task.
+- **Linux:** export the key and launch Codex from the same terminal; no universal desktop-session
+  inheritance is assumed.
+
+Companion and direct modes are mutually exclusive. The canonical new-user and legacy migration flow
+is:
+
+1. Set `GEMUS_KEY` in the user environment.
+2. Remove any legacy global server (`codex mcp remove gemus`; not-found is harmless).
+3. Install with `codex plugin marketplace add Gemus-AI/gemus-codex-plugin`, then
+   `codex plugin add gemus@gemus`. Existing users refresh the marketplace snapshot and replace the
+   installed cache:
+
+   ```bash
+   codex plugin marketplace upgrade gemus
+   codex plugin remove gemus@gemus
+   codex plugin add gemus@gemus
+   ```
+4. Explicitly enable the plugin-scoped server:
+
+   ```toml
+   [plugins."gemus@gemus".mcp_servers.gemus]
+   enabled = true
+   ```
+
+5. Restart Codex and open a new task, then use `/hooks` to trust the Stop hook separately.
+
+Intentional direct HTTP/OAuth users keep their global direct server and leave the plugin Companion
+disabled:
+
+```toml
+[plugins."gemus@gemus".mcp_servers.gemus]
+enabled = false
 ```
 
 ## Local dev
@@ -52,7 +118,6 @@ codex plugin add gemus@<marketplace>
 ```bash
 pnpm --filter @gemus/codex-backfill-core build          # proxy imports the built core at runtime
 GEMUS_KEY=mak_... GEMUS_URL=http://localhost:3000/api/mcp PROXY_LOG=/tmp/proxy.log node src/proxy.mjs
-# or register against dev:  codex mcp add gemus --env GEMUS_KEY=mak_... GEMUS_URL=http://localhost:3000/api/mcp -- node <abs>/src/proxy.mjs
 ```
 
 Env: `GEMUS_KEY` (required), `GEMUS_URL` (default `https://gemus.ai/api/mcp`), `PROXY_LOG` (optional

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gemus/mcp-proxy",
-  "version": "0.1.7",
+  "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

@@ -0,0 +1,216 @@
+function moduleUrl(source) {
+  return `data:text/javascript,${encodeURIComponent(source)}`
+}
+
+const markerPrelude = `
+  import fs from 'node:fs'
+  function mark(name) {
+    const file = process.env.PROXY_TEST_CONSTRUCTION_LOG
+    if (file) fs.appendFileSync(file, name + '\\n')
+  }
+`
+
+const modules = new Map([
+  ['@gemus/codex-backfill-core', `
+    export const CLIENT_CAPABILITIES = []
+    export const CLIENT_CAPABILITIES_HEADER = 'X-Gemus-Client-Capabilities'
+    export function serializeClientCapabilities(value) { return JSON.stringify(value) }
+    export function unwrapMcpContent(value) { return value }
+  `],
+  ['@modelcontextprotocol/sdk/server/stdio.js', `
+    ${markerPrelude}
+    export class StdioServerTransport {
+      constructor() { mark('stdio-transport') }
+      async start() {
+        if (process.env.PROXY_TEST_STDIO_START_FAILURE === '1') {
+          this.onclose?.()
+          throw new Error(
+            'stdio failed Authorization: Bearer '
+            + process.env.GEMUS_KEY
+            + ' at '
+            + process.env.GEMUS_URL
+          )
+        }
+        if (process.env.PROXY_TEST_FORWARD_STDIN === '1') {
+          let input = ''
+          process.stdin.setEncoding('utf8')
+          process.stdin.on('data', (chunk) => {
+            input += chunk
+            for (;;) {
+              const newline = input.indexOf('\\n')
+              if (newline < 0) break
+              const line = input.slice(0, newline).trim()
+              input = input.slice(newline + 1)
+              if (line) this.onmessage?.(JSON.parse(line))
+            }
+          })
+        }
+        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')
+        }
+      }
+    }
+  `],
+  ['@modelcontextprotocol/sdk/client/streamableHttp.js', `
+    ${markerPrelude}
+    export class StreamableHTTPClientTransport {
+      constructor(url, options) {
+        mark('upstream-transport')
+        this.url = url
+        this.fetch = options.fetch
+      }
+      async start() {}
+      async send(message) {
+        if (
+          process.env.PROXY_TEST_UPSTREAM_INITIALIZE_FAILURE === '1'
+          && message?.method === 'initialize'
+        ) {
+          throw new Error(
+            'initialize fetch failed Authorization: Bearer '
+            + process.env.GEMUS_KEY
+            + ' at '
+            + 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' } },
+        )
+      }
+      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', `
+    ${markerPrelude}
+    function hookError() {
+      return new Error(
+        'hook listen failed Authorization: Bearer '
+        + process.env.GEMUS_KEY
+        + ' at '
+        + process.env.GEMUS_URL
+      )
+    }
+    const http = {
+      createServer() {
+        mark('hook-server')
+        const listeners = new Map()
+        return {
+          on(event, handler) { listeners.set(event, handler); return this },
+          listen(_port, _host, callback) {
+            if (process.env.PROXY_TEST_HOOK_LISTEN_FAILURE === '1') {
+              queueMicrotask(() => listeners.get('error')?.(hookError()))
+            } else {
+              queueMicrotask(callback)
+            }
+            return this
+          },
+          address() { return { port: 43114 } },
+          unref() {},
+          close() {
+            mark('hook-server-close')
+            if (process.env.PROXY_TEST_HOOK_ERROR_AFTER_CLOSE === '1') {
+              queueMicrotask(() => listeners.get('error')?.(hookError()))
+            }
+          },
+        }
+      },
+    }
+    export default http
+  `],
+  ['./backfill.mjs', `
+    ${markerPrelude}
+    export function createBackfiller() {
+      mark('backfiller')
+      return {
+        observeCall() { mark('backfiller-observe-call') },
+        observeResult() { mark('backfiller-observe-result') },
+        async backfillTurn() {},
+      }
+    }
+    export function injectSteering() { return false }
+  `],
+])
+
+export async function resolve(specifier, context, nextResolve) {
+  const source = modules.get(specifier)
+  if (
+    source !== undefined
+    && (specifier !== './backfill.mjs' || context.parentURL?.endsWith('/proxy.mjs'))
+  ) {
+    return { url: moduleUrl(source), shortCircuit: true }
+  }
+  return nextResolve(specifier, context)
+}

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/,
+    )
+  })
+})