@gemus/mcp-proxy 0.1.7 → 0.1.9

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

@@ -14,8 +14,9 @@
 // Validated end-to-end on 2026-07-06 (codex-cli 0.142.2, real dev /api/mcp): transparent passthrough
 // of all 12 gemus tools; codex spawns one proxy per session; real tool-calls tapped with workflowId
 // (from arguments) + turn/thread identity (from _meta.x-codex-turn-metadata). Step-0.4: plugin-bundled
-// Stop hook fires (needs /hooks trust); codex does NOT interpolate ${VAR} in MCP env → key is a literal
-// in local `codex mcp add --env`. See docs/plans/1751-codex-desktop-companion.md.
+// Stop hook fires after /hooks trust. The plugin-scoped Companion forwards GEMUS_KEY from the user
+// environment, so neither the plugin config nor generated commands contain a literal key.
+// See docs/plans/1751-codex-desktop-companion.md.
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
 import http from 'node:http'
@@ -27,9 +28,51 @@ 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'
 
 const KEY = process.env.GEMUS_KEY || ''
 const GEMUS_URL = process.env.GEMUS_URL || 'https://gemus.ai/api/mcp'
+const LOG = process.env.PROXY_LOG // optional debug log path
+const log = (dir, m) => {
+  if (!LOG) return
+  try {
+    fs.appendFileSync(LOG, `[${new Date().toISOString()}] ${dir} ${typeof m === 'string' ? m : JSON.stringify(m).slice(0, 1000)}\n`)
+  } catch {
+    // Debug logging is optional and must never affect proxy lifecycle.
+  }
+}
+
+const reportFatal = createFatalReporter({
+  secret: KEY,
+  writeStderr: (message) => fs.writeSync(2, message),
+  writeLog: (message) => log('FATAL', message),
+})
+let shutdown
+let shutdownRequested = false
+function terminateFatally(error) {
+  reportFatal(error)
+  shutdownRequested = true
+  if (shutdown) return shutdown(1)
+  process.exit(1)
+}
+process.on('uncaughtException', (error) => { void terminateFatally(error) })
+process.on('unhandledRejection', (reason) => { void terminateFatally(reason) })
+
+try {
+  assertGemusKey(KEY)
+} catch (error) {
+  terminateFatally(error)
+}
+
 const SERVER_ORIGIN = GEMUS_URL.replace(/\/api\/mcp\/?$/, '') // core delivery appends /api/mcp itself
 const CODEX_HOME = process.env.CODEX_HOME || path.join(os.homedir(), '.codex')
 // turn-idle fallback (untrusted-hook path). Default 3min: imagegen alone runs 30-60s with NO MCP tool
@@ -40,11 +83,6 @@ const IDLE_MS = Number(process.env.PROXY_BACKFILL_IDLE_MS) || 180_000
 // （deriveWaitTimeoutMs('gen-image-generation')=180s，见 src/server/generation/waitTimeout.ts），否则
 // proxy 先超时 → 假失败 → orphan 回退 → 同图重复交付。240s = 180s + 余量。别调到 180s 以下。
 const INJECT_TIMEOUT_MS = Number(process.env.PROXY_INJECT_TIMEOUT_MS) || 240_000
-const LOG = process.env.PROXY_LOG // optional debug log path
-const log = (dir, m) => {
-  if (!LOG) return
-  fs.appendFileSync(LOG, `[${new Date().toISOString()}] ${dir} ${typeof m === 'string' ? m : JSON.stringify(m).slice(0, 1000)}\n`)
-}
 
 // ── footprint-0 交付注入（#1756 Layer 1a）─────────────────────────────────────────────────────────
 // 交付/orphan 不再每图新开 key-only session（connect-per-call，抢 KEY_ONLY_SESSION_CAP 槽），而是把
@@ -236,7 +274,10 @@ const hookServer = http.createServer((req, res) => {
       .catch((e) => log('HOOK-BACKFILL-ERR', String(e)))
   })
 })
-hookServer.on('error', (e) => log('HOOK-SERVER-ERR', String(e)))
+hookServer.on('error', (error) => {
+  if (shutdownRequested) return
+  void terminateFatally(error)
+})
 hookServer.listen(0, '127.0.0.1', () => {
   hookPort = hookServer.address().port
   log('HOOK-SERVER', { port: hookPort })
@@ -246,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).
@@ -254,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)))
   },
 })
 
@@ -273,7 +320,22 @@ const upstream = new StreamableHTTPClientTransport(new URL(GEMUS_URL), {
   fetch: failFast.fetch,
 })
 
-stdio.onmessage = (m) => { tapClientToServer(m); log('C->G', m); upstream.send(m).catch((e) => log('ERR-http-send', String(e))) }
+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', { kind: 'transport' })
+  })
+}
 upstream.onmessage = (m) => {
   // footprint-0 (#1756): our injected execute/canvas_edit responses carry a `gemus-bf-*` string id.
   // Self-consume them here (settle the pending injection) and DO NOT forward to Codex — Codex never
@@ -290,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
@@ -310,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() {
@@ -319,10 +383,7 @@ function startHeartbeat() {
   if (typeof heartbeatTimer.unref === 'function') heartbeatTimer.unref() // don't keep the process alive on this alone
 }
 
-let shuttingDown = false
-async function shutdown() {
-  if (shuttingDown) return
-  shuttingDown = true
+async function cleanup() {
   if (heartbeatTimer) clearInterval(heartbeatTimer)
   for (const t of idleTimers.values()) clearTimeout(t)
   idleTimers.clear()
@@ -332,18 +393,48 @@ async function shutdown() {
   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 */ }
-  process.exit(0)
+  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,
+  exit: (code) => process.exit(code),
+})
+function shutdownGracefully() {
+  shutdownRequested = true
+  return shutdown(0)
 }
-stdio.onclose = () => { log('stdio-close', ''); void shutdown() }
+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))
-process.on('SIGTERM', shutdown)
-process.on('SIGINT', shutdown)
+upstream.onerror = () => log('http-err', { kind: 'transport' })
+process.on('SIGTERM', () => { void shutdownGracefully() })
+process.on('SIGINT', () => { void shutdownGracefully() })
 
-await upstream.start()
-await stdio.start()
-startHeartbeat()
-log('STARTED', { GEMUS_URL, SERVER_ORIGIN, hasKey: Boolean(KEY), pid: process.pid, idleMs: IDLE_MS, heartbeatMs: HEARTBEAT_MS })
+try {
+  await startProxy({
+    key: KEY,
+    upstream,
+    stdio,
+    onStarted: () => {
+      if (shutdownRequested) return
+      startHeartbeat()
+      log('STARTED', {
+        endpoint: safeEndpointLabel(GEMUS_URL),
+        hasKey: Boolean(KEY),
+        pid: process.pid,
+        idleMs: IDLE_MS,
+        heartbeatMs: HEARTBEAT_MS,
+      })
+    },
+  })
+} catch (error) {
+  await terminateFatally(error)
+}

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

@@ -0,0 +1,110 @@
+const REDACTED = '[REDACTED]'
+
+export function assertGemusKey(key) {
+  if (!key) {
+    throw new Error('GEMUS_KEY is required. Set it in your user environment and restart Codex.')
+  }
+}
+
+export function safeEndpointLabel(value) {
+  try {
+    const url = value instanceof URL ? value : new URL(value)
+    return `${url.origin}${url.pathname}`
+  } catch {
+    return '[invalid endpoint]'
+  }
+}
+
+export function sanitizeStartupError(error, { secret }) {
+  const message = error instanceof Error ? error.message : String(error)
+  const exactRedacted = secret ? message.replaceAll(secret, REDACTED) : message
+  const withoutUrlCredentials = exactRedacted.replace(
+    /\b[a-z][a-z0-9+.-]*:\/\/[^\s"'<>]+/gi,
+    (value) => safeEndpointLabel(value),
+  )
+  const withoutQuotedHeaders = withoutUrlCredentials.replace(
+    /((?:(?:Proxy-)?Authorization|X-API-Key|API-Key|X-Gemus-Key|Gemus-Key)["']?\s*[:=]\s*)(["'])(.*?)\2/gi,
+    (_match, prefix, quote, value) => {
+      const scheme = /^(Bearer|Basic|Digest)\s+/i.exec(value)?.[1]
+      return `${prefix}${quote}${scheme ? `${scheme} ` : ''}${REDACTED}${quote}`
+    },
+  )
+  const withoutAuthorizationHeaders = withoutQuotedHeaders.replace(
+    /((?:Proxy-)?Authorization\s*[:=]\s*)(?!["'])(?:(Bearer|Basic|Digest)\s+)?[^\s,;}]+/gi,
+    (_match, prefix, scheme) => `${prefix}${scheme ? `${scheme} ` : ''}${REDACTED}`,
+  )
+  const withoutBearerTokens = withoutAuthorizationHeaders.replace(
+    /Bearer\s+(?!\[REDACTED\])[^\s"',;}]+/gi,
+    `Bearer ${REDACTED}`,
+  )
+  const withoutKeyHeaders = withoutBearerTokens.replace(
+    /((?:X-API-Key|API-Key|X-Gemus-Key|Gemus-Key)\s*[:=]\s*)(?!["'])[^\s,;}]+/gi,
+    `$1${REDACTED}`,
+  )
+  const sanitized = withoutKeyHeaders.replace(
+    /mak_[A-Za-z0-9._~+/=-]+/g,
+    REDACTED,
+  )
+
+  return `Gemus MCP proxy failed to start: ${sanitized}`
+}
+
+export function createFatalReporter({ secret, writeStderr, writeLog = () => {} }) {
+  let reported = false
+
+  return function reportFatal(error) {
+    const message = sanitizeStartupError(error, { secret })
+    if (reported) return message
+    reported = true
+
+    writeStderr(`${message}\n`)
+    try {
+      writeLog(message)
+    } catch {
+      // Optional logging must never replace the guaranteed stderr diagnostic.
+    }
+    return message
+  }
+}
+
+export async function startProxy({ key, upstream, stdio, onStarted }) {
+  assertGemusKey(key)
+  await upstream.start()
+  await stdio.start()
+  onStarted()
+}
+
+export function createShutdownCoordinator({ cleanup, exit }) {
+  let requestedExitCode = 0
+  let cleanupPromise
+
+  return function shutdown(exitCode = 0) {
+    requestedExitCode = Math.max(requestedExitCode, exitCode)
+    if (!cleanupPromise) {
+      cleanupPromise = (async () => {
+        try {
+          await cleanup()
+        } finally {
+          exit(requestedExitCode)
+        }
+      })()
+    }
+    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')
+      },
+    )
+  })
+}