@gemus/mcp-proxy 0.1.6 → 0.1.8

package/src/failFast.mjs

@@ -0,0 +1,266 @@
+// @gemus/mcp-proxy fail-fast (#2068) — surface upstream stream death to Codex immediately.
+//
+// StreamableHTTPClientTransport.send() resolves as soon as it DISPATCHES the SSE read loop,
+// not when the tool result arrives. When the upstream POST SSE body dies before the result,
+// the SDK only fires a global `onerror` with NO request id, and never reconnects a POST (no
+// priming event). So Codex's pending request never settles → it hangs to its own 300s timeout.
+//
+// The only interception point the SDK offers is the constructor `fetch` option: it receives the
+// exact (url, init) per request, so we parse the JSON-RPC id from `init.body` and wrap the
+// response body. We use a SINGLE-PASS observe-while-forward wrapper (not tee()+grace): the same
+// read loop that forwards bytes to the transport also scans the SSE frames for the tracked id's
+// result/error. "Detect order == forward order" on one reader, so there is NO race between "result
+// delivered" and "stream closed" — no wall-clock grace window (which CLAUDE.md forbids). If the
+// stream reaches done/error while a tracked id was never seen on the wire, that result is lost →
+// inject a JSON-RPC error keyed to that id.
+
+/**
+ * A Codex-originated id is anything the AGENT issued. We exclude our own internal namespaces:
+ *   - `gemus-bf-*`  footprint-0 backfill injections (self-consumed by upstream.onmessage)
+ *   - `gemus-ping-*` liveness heartbeat pongs (self-consumed)
+ * Numeric ids (Codex initialize / tools/list / tools/call) are all tracked.
+ */
+export function isCodexOriginated(id) {
+  if (id === undefined || id === null) return false
+  return !(typeof id === 'string' && (id.startsWith('gemus-bf-') || id.startsWith('gemus-ping-')))
+}
+
+/**
+ * Extract JSON-RPC request ids from a fetch init. Only POST requests with a JSON body carry a
+ * request whose response we must guarantee; GET (standalone SSE) and DELETE (terminateSession)
+ * have no body → []. Never throws — a body we can't parse yields [].
+ */
+export function parseRequestIds(init) {
+  try {
+    const method = (init?.method || 'GET').toUpperCase()
+    if (method !== 'POST' || init.body == null) return []
+    const body = typeof init.body === 'string' ? init.body : String(init.body)
+    const parsed = JSON.parse(body)
+    const msgs = Array.isArray(parsed) ? parsed : [parsed]
+    const ids = []
+    for (const m of msgs) {
+      // A request has both an id and a method; responses/notifications are not our concern here.
+      if (m && m.id !== undefined && m.id !== null && typeof m.method === 'string') ids.push(m.id)
+    }
+    return ids
+  } catch {
+    return []
+  }
+}
+
+/** True for a JSON-RPC RESPONSE (result/error) — has an id and no `method`. A server→client REQUEST
+ * (elicitation/sampling) also has an id but carries a `method`, and its id (the server's own counter)
+ * can COLLIDE with an in-flight Codex tools/call id — settling on it would disarm the fail-fast guard
+ * for the very tool that stream carries. So we settle only on responses, never on relayed requests. */
+export function isJsonRpcResponse(msg) {
+  return !!msg && msg.id !== undefined && msg.id !== null && msg.method === undefined
+}
+
+/**
+ * Minimal SSE frame scanner. Accumulates decoded text, splits on the event boundary, and for each
+ * complete event yields the JSON-RPC id of any `data:` payload that is a RESPONSE (see
+ * isJsonRpcResponse). Comment lines (`:` — including our injected `: keepalive`) are ignored, so
+ * they never count as a delivered result. Half-frames straddling chunk boundaries are buffered until
+ * their terminating blank line arrives (no early/missed detection). CRLF line endings are normalized
+ * to LF so an intermediary that rewrites them can't wedge the scanner.
+ */
+export function createSseIdScanner() {
+  const decoder = new TextDecoder()
+  let buf = ''
+  return {
+    /** Push a chunk; returns the JSON-RPC ids of any RESPONSE frames that crossed the wire in it. */
+    push(chunk) {
+      buf += decoder.decode(chunk, { stream: true }).replace(/\r\n/g, '\n')
+      const ids = []
+      let sep
+      while ((sep = buf.indexOf('\n\n')) !== -1) {
+        const block = buf.slice(0, sep)
+        buf = buf.slice(sep + 2)
+        const dataLines = []
+        for (const line of block.split('\n')) {
+          if (line.startsWith('data:')) dataLines.push(line.slice(5).trimStart())
+        }
+        if (!dataLines.length) continue
+        try {
+          const msg = JSON.parse(dataLines.join('\n'))
+          if (isJsonRpcResponse(msg)) ids.push(msg.id)
+        } catch {
+          /* not JSON-RPC (or partial) — ignore */
+        }
+      }
+      return ids
+    },
+  }
+}
+
+/**
+ * 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 {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.
+ * @param {(dir:string, m:any)=>void} [opts.log]
+ * @param {typeof fetch} [opts.realFetch]  injectable for tests; defaults to global fetch
+ * @returns {{ fetch, settle, touch, forget, dispose, failedIds }}
+ */
+export function createFailFast(opts) {
+  const { onLost, log = () => {} } = opts
+  const idleTimeoutMs = Number(opts.idleTimeoutMs) || 120_000
+  const realFetch = opts.realFetch || fetch
+  const FAILED_IDS_CAP = 512
+
+  /** idStr → { timer } — Codex-originated in-flight requests awaiting a result. */
+  const inFlight = new Map()
+  /** ids already failed by onLost — lets onmessage drop a late real result's forward (still taps it). */
+  const failedIds = new Set()
+
+  function armTimer(entry, id) {
+    entry.timer = setTimeout(() => lose(id, 'proxy idle timeout (no upstream bytes)'), idleTimeoutMs)
+    if (typeof entry.timer.unref === 'function') entry.timer.unref()
+  }
+
+  function register(id) {
+    const key = String(id)
+    if (inFlight.has(key)) return
+    const entry = {}
+    inFlight.set(key, entry)
+    armTimer(entry, id)
+  }
+
+  /** Reset the idle timer on any upstream byte — a healthy stream (heartbeats + data) never trips it. */
+  function touch(id) {
+    const entry = inFlight.get(String(id))
+    if (!entry) return
+    clearTimeout(entry.timer)
+    armTimer(entry, id)
+  }
+
+  function settle(id) {
+    const key = String(id)
+    const entry = inFlight.get(key)
+    if (!entry) return
+    clearTimeout(entry.timer)
+    inFlight.delete(key)
+  }
+
+  /** Drop an id from failedIds once its late result has been handled (bounds the set). */
+  function forget(id) {
+    failedIds.delete(String(id))
+  }
+
+  function lose(id, reason) {
+    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)
+  }
+
+  function observeAndForward(body, codexIds) {
+    const reader = body.getReader()
+    const scanner = createSseIdScanner()
+    let ended = false
+    const onEnd = () => {
+      if (ended) return
+      ended = true
+      for (const id of codexIds) lose(id, 'upstream stream closed before result')
+    }
+    return new ReadableStream({
+      async pull(controller) {
+        let r
+        try {
+          r = await reader.read()
+        } catch (e) {
+          try {
+            controller.error(e)
+          } catch {
+            /* already closed */
+          }
+          onEnd()
+          return
+        }
+        if (r.done) {
+          try {
+            controller.close()
+          } catch {
+            /* already closed */
+          }
+          onEnd()
+          return
+        }
+        try {
+          controller.enqueue(r.value) // forward bytes unchanged to the transport
+        } catch {
+          /* downstream gone */
+        }
+        // Any byte (data OR heartbeat) proves the stream is alive → reset the idle backstop.
+        for (const id of codexIds) touch(id)
+        // Same loop: any tracked id whose RESPONSE crossed the wire is now delivered.
+        for (const id of scanner.push(r.value)) settle(id)
+      },
+      cancel(reason) {
+        reader.cancel(reason).catch(() => {})
+        onEnd()
+      },
+    })
+  }
+
+  async function wrappedFetch(url, init) {
+    // Parse ids + register. Both are internally safe (parseRequestIds never throws), but guard
+    // defensively so a future change can't break the chain — degrade to "no tracking".
+    let codexIds = []
+    try {
+      codexIds = parseRequestIds(init).filter(isCodexOriginated)
+      for (const id of codexIds) register(id)
+    } catch (e) {
+      log('FAILFAST-WRAP-ERR', String(e))
+      codexIds = []
+    }
+
+    // The network call. Its failure MUST propagate to the SDK unchanged — do NOT retry here
+    // (a second fetch could execute the tool server-side after Codex already got the error).
+    let res
+    try {
+      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}`)
+      throw e // preserve the SDK's existing onerror/logging path (no re-fetch)
+    }
+
+    // Response handling + monitoring. On any internal bug, return the response we ALREADY have,
+    // unmonitored — never re-fetch (wrappedFetch sits on 100% of upstream traffic incl. GET
+    // elicitation + DELETE teardown, so it must never break the chain, but also never duplicate).
+    try {
+      if (!codexIds.length) return res // GET / DELETE / notification / internal id → passthrough
+      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}`)
+        return res
+      }
+      const ct = res.headers.get('content-type') || ''
+      if (!ct.includes('text/event-stream') || !res.body) return res // 202 etc. — no id to monitor
+      return new Response(observeAndForward(res.body, codexIds), {
+        status: res.status,
+        statusText: res.statusText,
+        headers: res.headers,
+      })
+    } catch (e) {
+      log('FAILFAST-WRAP-ERR', String(e))
+      return res
+    }
+  }
+
+  function dispose() {
+    for (const { timer } of inFlight.values()) clearTimeout(timer)
+    inFlight.clear()
+  }
+
+  return { fetch: wrappedFetch, settle, touch, forget, dispose, failedIds }
+}

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'
@@ -26,9 +27,49 @@ import { randomBytes } from 'node:crypto'
 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 {
+  assertGemusKey,
+  createFatalReporter,
+  createShutdownCoordinator,
+  safeEndpointLabel,
+  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
@@ -39,11 +80,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 槽），而是把
@@ -235,7 +271,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 })
@@ -244,12 +283,45 @@ hookServer.listen(0, '127.0.0.1', () => {
 if (typeof hookServer.unref === 'function') hookServer.unref()
 
 // ── transparent JSON-RPC passthrough (raw send/onmessage) ──────────────────────────────────────
+const stdio = new StdioServerTransport()
+
+// #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).
+// The custom `fetch` wrapper parses each request's JSON-RPC id and, if the response stream dies
+// before that id's result crosses the wire, injects a JSON-RPC error so Codex fails in <2s instead
+// 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 failFast = createFailFast({
+  idleTimeoutMs: Number(process.env.PROXY_FAILFAST_TIMEOUT_MS) || 120_000,
+  log,
+  onLost: (id, reason) => {
+    const errObj = {
+      jsonrpc: '2.0',
+      id,
+      error: { code: -32000, message: 'Gemus upstream stream disconnected before the tool result was delivered' },
+    }
+    log('FAILFAST-INJECT', { id, reason })
+    stdio.send(errObj).catch((e) => log('ERR-stdio-send', String(e)))
+  },
+})
+
 const upstream = new StreamableHTTPClientTransport(new URL(GEMUS_URL), {
   requestInit: { headers: buildProxyUpstreamHeaders(KEY) },
+  fetch: failFast.fetch,
 })
-const stdio = new StdioServerTransport()
 
-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)
+  upstream.send(m).catch((error) => {
+    if (m?.method === 'initialize') {
+      void terminateFatally(error)
+      return
+    }
+    log('ERR-http-send', String(error))
+  })
+}
 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
@@ -262,6 +334,18 @@ upstream.onmessage = (m) => {
   // #1756 liveness heartbeat: our own `ping` pongs (gemus-ping-*) are self-consumed — Codex never
   // issued them, so it must never see the responses.
   if (typeof m?.id === 'string' && m.id.startsWith('gemus-ping-')) return
+  // #2068 fail-fast bookkeeping. Gate on RESPONSE only (isJsonRpcResponse) — a server→client request
+  // (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)) {
+    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
+      // do NOT re-forward it to Codex (no double-send). forget() bounds failedIds.
+      tapServerToClient(m); failFast.forget(m.id); log('DROP-AFTER-FAILFAST', m.id); return
+    }
+    failFast.settle(m.id)
+  }
   tapServerToClient(m); steerOnInit(m); log('G->C', m); stdio.send(m).catch((e) => log('ERR-stdio-send', String(e)))
 }
 
@@ -283,30 +367,51 @@ 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()
   // Settle any in-flight footprint-0 injections so a mid-delivery shutdown doesn't hang their awaits.
   for (const p of pendingInjections.values()) p.settle({ ok: false, error: 'proxy shutting down' })
   pendingInjections.clear()
+  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)
 }
-stdio.onclose = () => { log('stdio-close', ''); void shutdown() }
+shutdown = createShutdownCoordinator({
+  cleanup,
+  exit: (code) => process.exit(code),
+})
+function shutdownGracefully() {
+  shutdownRequested = true
+  return shutdown(0)
+}
+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)
+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/startup.mjs

@@ -0,0 +1,94 @@
+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
+  }
+}