@gemus/mcp-proxy 0.1.5 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gemus/mcp-proxy",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Local stdio<->HTTP MCP proxy for Codex desktop: transparent passthrough + execute tap + imagegen backfill (Issue #1751, P1).",
   "type": "module",
   "bin": {

package/src/__tests__/failFast.test.ts

@@ -0,0 +1,254 @@
+/**
+ * @gemus/mcp-proxy fail-fast (#2068) — single-pass upstream-disconnect correlation.
+ *
+ * Pure logic; the socket is an injected `realFetch` returning controllable `Response`s. Cases that
+ * involve the final-safety timer use fake timers with advanceTimersByTimeAsync (lesson: fake timers
+ * + real reader.read() promises need the async advance to flush continuations).
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { parseRequestIds, isCodexOriginated, createSseIdScanner, createFailFast, isJsonRpcResponse } from '../failFast.mjs'
+
+const enc = new TextEncoder()
+
+/** A response body that emits the given SSE frames then closes. */
+function bodyOf(...frames: string[]): ReadableStream<Uint8Array> {
+  return new ReadableStream<Uint8Array>({
+    start(c) {
+      for (const f of frames) c.enqueue(enc.encode(f))
+      c.close()
+    },
+  })
+}
+/** A response body that never emits and never closes (zombie stream). */
+function neverBody(): ReadableStream<Uint8Array> {
+  return new ReadableStream<Uint8Array>({ start() {} })
+}
+function sseRes(body: ReadableStream<Uint8Array> | null, init?: { status?: number; contentType?: string }) {
+  const status = init?.status ?? 200
+  return new Response(body, { status, headers: { 'content-type': init?.contentType ?? 'text/event-stream' } })
+}
+function resultFrame(id: number | string): string {
+  return `event: message\ndata: ${JSON.stringify({ jsonrpc: '2.0', id, result: { ok: true } })}\n\n`
+}
+function post(id: number | string, method = 'tools/call') {
+  return { method: 'POST', body: JSON.stringify({ jsonrpc: '2.0', id, method, params: {} }) }
+}
+async function drain(res: Response): Promise<void> {
+  const r = res.body!.getReader()
+  for (;;) { const { done } = await r.read(); if (done) break }
+}
+
+describe('parseRequestIds', () => {
+  it('extracts the id from a POST JSON-RPC request', () => {
+    expect(parseRequestIds(post(42))).toEqual([42])
+  })
+  it('extracts all ids from a batch', () => {
+    const body = JSON.stringify([
+      { jsonrpc: '2.0', id: 1, method: 'a' },
+      { jsonrpc: '2.0', id: 2, method: 'b' },
+    ])
+    expect(parseRequestIds({ method: 'POST', body })).toEqual([1, 2])
+  })
+  it('returns [] for GET / DELETE / bodyless requests', () => {
+    expect(parseRequestIds({ method: 'GET' })).toEqual([])
+    expect(parseRequestIds({ method: 'DELETE' })).toEqual([])
+    expect(parseRequestIds({ method: 'POST' })).toEqual([])
+  })
+  it('returns [] for non-JSON body and for notifications (no id)', () => {
+    expect(parseRequestIds({ method: 'POST', body: 'not json' })).toEqual([])
+    expect(parseRequestIds({ method: 'POST', body: JSON.stringify({ jsonrpc: '2.0', method: 'x' }) })).toEqual([])
+  })
+})
+
+describe('isCodexOriginated', () => {
+  it.each([
+    [42, true],
+    ['abc', true],
+    ['gemus-bf-3', false],
+    ['gemus-ping-9', false],
+    [null, false],
+    [undefined, false],
+  ])('id=%s → %s', (id, expected) => {
+    expect(isCodexOriginated(id as never)).toBe(expected)
+  })
+})
+
+describe('isJsonRpcResponse', () => {
+  it('is true for a result/error response, false for a request or notification', () => {
+    expect(isJsonRpcResponse({ id: 1, result: {} })).toBe(true)
+    expect(isJsonRpcResponse({ id: 1, error: {} })).toBe(true)
+    expect(isJsonRpcResponse({ id: 1, method: 'elicitation/create', params: {} })).toBe(false) // server→client request
+    expect(isJsonRpcResponse({ method: 'notifications/x' })).toBe(false)
+    expect(isJsonRpcResponse(null)).toBe(false)
+  })
+})
+
+describe('createSseIdScanner', () => {
+  it('yields the id of a complete RESPONSE frame; ignores comment lines', () => {
+    const s = createSseIdScanner()
+    expect(s.push(enc.encode(': keepalive\n\n'))).toEqual([])
+    expect(s.push(enc.encode(resultFrame(7)))).toEqual([7])
+  })
+  it('does NOT yield a server→client REQUEST id (has a method) — avoids id-collision premature settle', () => {
+    const s = createSseIdScanner()
+    const reqFrame = `event: message\ndata: ${JSON.stringify({ jsonrpc: '2.0', id: 3, method: 'elicitation/create', params: {} })}\n\n`
+    expect(s.push(enc.encode(reqFrame))).toEqual([])
+  })
+  it('buffers a half-frame split across chunks until its boundary arrives', () => {
+    const s = createSseIdScanner()
+    const frame = resultFrame(5)
+    const mid = Math.floor(frame.length / 2)
+    expect(s.push(enc.encode(frame.slice(0, mid)))).toEqual([])
+    expect(s.push(enc.encode(frame.slice(mid)))).toEqual([5])
+  })
+  it('handles CRLF line endings (normalizes to LF)', () => {
+    const s = createSseIdScanner()
+    const crlf = `event: message\r\ndata: ${JSON.stringify({ jsonrpc: '2.0', id: 8, result: {} })}\r\n\r\n`
+    expect(s.push(enc.encode(crlf))).toEqual([8])
+  })
+  it('ignores non-JSON data payloads', () => {
+    const s = createSseIdScanner()
+    expect(s.push(enc.encode('data: not-json\n\n'))).toEqual([])
+  })
+})
+
+describe('createFailFast.fetch', () => {
+  it('injects a JSON-RPC error when the stream closes before the result', async () => {
+    const onLost = vi.fn()
+    const realFetch = vi.fn(async () => sseRes(bodyOf(': keepalive\n\n'))) // no result frame → lost
+    const ff = createFailFast({ onLost, realFetch })
+
+    const res = await ff.fetch('u', post(42))
+    await drain(res)
+
+    expect(onLost).toHaveBeenCalledTimes(1)
+    expect(onLost.mock.calls[0][0]).toBe(42)
+    expect(ff.failedIds.has('42')).toBe(true)
+  })
+
+  it('does NOT inject an error when the result crosses the wire before close', async () => {
+    const onLost = vi.fn()
+    const realFetch = vi.fn(async () => sseRes(bodyOf(resultFrame(42))))
+    const ff = createFailFast({ onLost, realFetch })
+
+    const res = await ff.fetch('u', post(42))
+    await drain(res)
+
+    expect(onLost).not.toHaveBeenCalled()
+    expect(ff.failedIds.has('42')).toBe(false)
+  })
+
+  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 ff = createFailFast({ onLost, realFetch })
+
+    await expect(ff.fetch('u', post(7))).rejects.toThrow('ECONNRESET')
+    expect(onLost).toHaveBeenCalledWith(7, expect.stringContaining('upstream fetch failed'))
+    expect(realFetch).toHaveBeenCalledTimes(1) // must NOT retry — a 2nd fetch could execute the tool
+  })
+
+  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')
+  })
+
+  it('passes GET and DELETE through untouched (no body → no monitoring, no onLost)', async () => {
+    const onLost = vi.fn()
+    const getRes = sseRes(bodyOf())
+    const realFetch = vi.fn(async () => getRes)
+    const ff = createFailFast({ onLost, realFetch })
+
+    const g = await ff.fetch('u', { method: 'GET' })
+    const d = await ff.fetch('u', { method: 'DELETE' })
+    expect(g).toBe(getRes)
+    expect(d).toBe(getRes)
+    expect(onLost).not.toHaveBeenCalled()
+  })
+
+  it('does not track internal gemus-bf-* / gemus-ping-* ids', async () => {
+    const onLost = vi.fn()
+    const realFetch = vi.fn(async () => sseRes(bodyOf(': keepalive\n\n'))) // closes with no result
+    const ff = createFailFast({ onLost, realFetch })
+
+    await drain(await ff.fetch('u', post('gemus-bf-1')))
+    await drain(await ff.fetch('u', post('gemus-ping-2')))
+    expect(onLost).not.toHaveBeenCalled()
+  })
+
+  it('degrades to plain passthrough if internal logic throws', async () => {
+    const onLost = vi.fn()
+    const badRes = { ok: true, status: 200, headers: { get() { throw new Error('boom') } }, body: null } as unknown as Response
+    const realFetch = vi.fn(async () => badRes)
+    const ff = createFailFast({ onLost, realFetch })
+
+    const res = await ff.fetch('u', post(1))
+    expect(res).toBe(badRes)              // returns the response we ALREADY have — no re-fetch
+    expect(realFetch).toHaveBeenCalledTimes(1)
+    expect(onLost).not.toHaveBeenCalled()
+    ff.dispose()
+  })
+
+  it('isolates concurrent requests — disconnecting one does not affect the other', async () => {
+    const onLost = vi.fn()
+    const realFetch = vi
+      .fn()
+      .mockResolvedValueOnce(sseRes(bodyOf(': keepalive\n\n')))   // id 1 → dies with no result
+      .mockResolvedValueOnce(sseRes(bodyOf(resultFrame(2))))      // id 2 → delivers
+    const ff = createFailFast({ onLost, realFetch })
+
+    await drain(await ff.fetch('u', post(1)))
+    await drain(await ff.fetch('u', post(2)))
+
+    expect(onLost).toHaveBeenCalledTimes(1)
+    expect(onLost.mock.calls[0][0]).toBe(1)
+  })
+
+  describe('idle safety timeout', () => {
+    beforeEach(() => vi.useFakeTimers())
+    afterEach(() => vi.useRealTimers())
+
+    it('injects an error for a zombie connection that never emits a byte', async () => {
+      const onLost = vi.fn()
+      const realFetch = vi.fn(async () => sseRes(neverBody()))
+      const ff = createFailFast({ onLost, realFetch, idleTimeoutMs: 120_000 })
+
+      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'))
+      ff.dispose()
+    })
+
+    it('does NOT kill a healthy-but-slow stream — heartbeat bytes reset the idle timer', async () => {
+      const onLost = vi.fn()
+      let ctl!: ReadableStreamDefaultController<Uint8Array>
+      const body = new ReadableStream<Uint8Array>({ start(c) { ctl = c } })
+      const realFetch = vi.fn(async () => sseRes(body))
+      const ff = createFailFast({ onLost, realFetch, idleTimeoutMs: 100 })
+
+      const res = await ff.fetch('u', post(1))
+      const reader = res.body!.getReader()
+
+      // Keepalive every 60ms (< 100ms idle) for 300ms total — each read touches → never fires.
+      for (let i = 0; i < 5; i++) {
+        ctl.enqueue(enc.encode(': keepalive\n\n'))
+        await reader.read()
+        await vi.advanceTimersByTimeAsync(60)
+      }
+      expect(onLost).not.toHaveBeenCalled() // survived 300ms > idleTimeout because bytes kept flowing
+
+      // Now the result arrives and the stream closes → still no fail-fast.
+      ctl.enqueue(enc.encode(resultFrame(1)))
+      await reader.read()
+      ctl.close()
+      await reader.read()
+      expect(onLost).not.toHaveBeenCalled()
+      ff.dispose()
+    })
+  })
+})

package/src/__tests__/mcpHeaders.test.ts

@@ -1,11 +1,32 @@
 import { describe, expect, it } from 'vitest'
+import { CLIENT_CAPABILITIES } from '@gemus/codex-backfill-core'
 import { buildProxyUpstreamHeaders } from '../mcpHeaders.mjs'
 
 describe('buildProxyUpstreamHeaders', () => {
-  it('advertises the canonical Codex MCP capabilities alongside bearer authentication', () => {
+  it('advertises only the capabilities the proxy can actually fulfil', () => {
     expect(buildProxyUpstreamHeaders('mak_test123')).toEqual({
       Authorization: 'Bearer mak_test123',
       'X-Gemus-Client-Capabilities': 'agent-authored-prompts,codex-imagen',
     })
   })
+
+  it('never advertises codex-instant-delivery — the proxy has no ImageScheduler to renew the lease (#2049)', () => {
+    // 该能力门控服务端的 AWAITING_CLIENT execute 分支，要求客户端有 scheduler 每 60s renewLease。
+    // 只有 bridge 有（且 probe 门控，见 bridge/src/cli.ts）。proxy 没有 —— 发了它就等于承诺一个
+    // 永不到来的续租 → 5min 后 CLIENT_LEASE_EXPIRED → 图 orphan 成孤立 image-upload 节点。
+    // absent → 服务端回退经典两阶段 client-delivered 协议，proxy 完全支持（backfill.mjs）。
+    const header = buildProxyUpstreamHeaders('mak_test123')['X-Gemus-Client-Capabilities']
+    expect(header).not.toContain('codex-instant-delivery')
+  })
+
+  it('stays a strict subset of the shared allowlist — a new capability must not auto-inherit (#2049)', () => {
+    // 回归门：本 bug 的成因正是 proxy 发「整个 CLIENT_CAPABILITIES 数组」—— #1969 往数组里加了
+    // codex-instant-delivery，proxy 就自动继承了一个它做不到的承诺，而 #1990 把红掉的断言改成
+    // 迎合它。此断言让「加能力」与「proxy 声称支持它」变成两个独立决策，不再自动传染。
+    const advertised = buildProxyUpstreamHeaders('mak_test123')['X-Gemus-Client-Capabilities'].split(',')
+    for (const capability of advertised) {
+      expect(CLIENT_CAPABILITIES).toContain(capability)
+    }
+    expect(advertised.length).toBeLessThan(CLIENT_CAPABILITIES.length)
+  })
 })

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/mcpHeaders.mjs

@@ -4,9 +4,36 @@ import {
   serializeClientCapabilities,
 } from '@gemus/codex-backfill-core'
 
+/**
+ * #2049：proxy 只 advertise **它自己能履行**的能力 —— 不是 `CLIENT_CAPABILITIES` 全集。
+ *
+ * `CLIENT_CAPABILITIES` 是**所有已知能力的 allowlist**（共享 SSOT），不是「每个客户端都支持」的清单。
+ * 各客户端各自声明自己能兑现的子集：bridge 见 `bridge/src/cli.ts`（`imageScheduler` 与
+ * `activeCapabilities` **成对注入** —— 有 scheduler 才发 capability，且 probe 门控）。
+ *
+ * **`codex-instant-delivery` 必须排除**：它门控服务端的 AWAITING_CLIENT execute 分支，
+ * 要求客户端有 ImageScheduler 每 60s `renewLease`。**proxy 没有 scheduler**（本包与
+ * `@gemus/codex-backfill-core` 里 `renew`/`lease` 零命中）。发了它 = 承诺一个永不到来的续租：
+ *   execute 建 AWAITING_CLIENT job（lease=+5min）→ 无人续 → `CLIENT_LEASE_EXPIRED` → 节点 FAILED
+ *   → Codex 的图回来时目标已死 → `backfill.mjs` orphan 兜底 → 孤立 `image-upload` 节点。
+ * 真机实测见 #2049。
+ * **不发它 → 服务端回退经典两阶段 client-delivered 协议，proxy 完全支持**（`backfill.mjs`
+ * tap execute + 注入交付）—— 这正是 `codex-backfill-core/src/mcp.ts` 那条注释写的
+ * "absent → the classic dryRun/Phase-2 two-phase client-delivered protocol is used unchanged"。
+ *
+ * ⚠️ **往 `CLIENT_CAPABILITIES` 加新能力时**：默认**不会**、也**不该**自动出现在这里。先问
+ * 「proxy 拿什么兑现它？」—— 本 bug 的成因正是「发全集」让新能力自动传染（#1969 加，proxy 白捡，
+ * #1990 把红掉的断言改成迎合）。`__tests__/mcpHeaders.test.ts` 有严格子集断言守着这条。
+ */
+const PROXY_UNSUPPORTED_CAPABILITIES = new Set(['codex-instant-delivery'])
+
+const PROXY_CAPABILITIES = Object.freeze(
+  CLIENT_CAPABILITIES.filter((capability) => !PROXY_UNSUPPORTED_CAPABILITIES.has(capability)),
+)
+
 export function buildProxyUpstreamHeaders(apiKey) {
   return {
     Authorization: `Bearer ${apiKey}`,
-    [CLIENT_CAPABILITIES_HEADER]: serializeClientCapabilities(CLIENT_CAPABILITIES),
+    [CLIENT_CAPABILITIES_HEADER]: serializeClientCapabilities(PROXY_CAPABILITIES),
   }
 }

package/src/proxy.mjs

@@ -26,6 +26,7 @@ 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'
 
 const KEY = process.env.GEMUS_KEY || ''
 const GEMUS_URL = process.env.GEMUS_URL || 'https://gemus.ai/api/mcp'
@@ -244,10 +245,33 @@ 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))) }
 upstream.onmessage = (m) => {
@@ -262,6 +286,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)))
 }
 
@@ -293,6 +329,7 @@ async function shutdown() {
   // 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 */ }