Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

149 KB
Raw Blame
/**
 * Loopback HTTP 反向代理实现 ——
 *
 * 设计要点 / 性能保证:
 *   1. 监听 127.0.0.1 随机端口,避开 Fetch 禁用端口,纯进程内 loopback,不暴露任何外部接口
 *   2. 响应路径默认字节级 pipe;只有显式协议适配器会进入流式 Transform
 *   3. 请求路径:
 *      - 非 POST / Content-Type 不是 JSON → 整条字节透传
 *      - JSON POST → 缓冲到完整 body,跑 transform 链,re-serialize 后转发
 *      - transform 抛错 / 上游挂 → 退化为透传(透传也失败再给客户端报错)
 *   4. dispose: 立即 destroy 所有 in-flight socket + 等 server.close 回调(~10ms)。
 *      退出场景下客户端 (Claude Code 子进程) 也即将被 SIGTERM, 保留 in-flight 请求无意义;
 *      详见 dispose() 内注释。
 */

import { installResponseGuard } from './response-guard.js';
import { collectRecoverableBody } from './oversized-attachments.js';
import { createHash } from 'node:crypto';
import { createServer, request as httpRequest, type ClientRequest, type IncomingMessage, type RequestOptions, type Server, type ServerResponse } from 'node:http';
import { request as httpsRequest } from 'node:https';
import type { Socket, TcpSocketConnectOpts } from 'node:net';
import { PassThrough, Readable, Transform } from 'node:stream';
import { URL } from 'node:url';
import { brotliDecompressSync, gunzipSync, inflateRawSync, inflateSync } from 'node:zlib';

import { DEFAULT_THREAD_ID_HEADERS, selectedHeaderValue, STABLE_THREAD_ID_HEADERS } from './headers.js';
import {
  formatAuthority,
  formatHostHeader,
  isLoopbackHostname,
  OutboundProxyAgentPool,
  outboundProxyAgentKey,
  parseOutboundProxyUrl,
  redactProxyUrlForLog,
  TunnelingHttpsAgent,
  type OutboundProxyAgent,
  type OutboundProxyTarget,
} from './outbound-proxy.js';
import { Socks5HttpAgent, Socks5HttpsAgent } from './socks5.js';
import { describeUpstreamRequestFailure } from './upstream-failure.js';
import { stripNonAnthropicFields, stripToolUseProviderSpecificFields } from './transform.js';
import {
  collectToolUseIdsForResponseRewrite,
  ToolUseIdDedupeRewriter,
  ToolUseIdRewriteTransform,
} from './tool-use-id-stream-rewrite.js';
import type {
  ForwardLifecycleObserver,
  ForwardLifecycleFailure,
  LocalRequestHandler,
  ProxyHandle,
  ProxyLogger,
  ProxyOptions,
  RecoveryRule,
  RequestTransform,
  RequestTransformCtx,
  OversizedRequestCompactor,
  ResponseObserver,
  ResponseObserverSink,
  ResponseTransform,
  RoutingDecision,
} from './types.js';

// 单条请求最大 body 大小的**默认值** —— Claude Code 请求 body 几 KB 到几百 KB,
// 留 32MB 给极端的长上下文 + 大附件;超出回 413,避免内存被打爆。
// 调用方可用 ProxyOptions.maxRequestBodyBytes 覆盖(codex 全量重发历史的场景需要更大)。
const DEFAULT_MAX_REQUEST_BODY_BYTES = 32 * 1024 * 1024;
// Oversized compaction is intentionally bounded.  A request beyond this
// ingress window is rejected without buffering it into memory.
const MAX_REQUEST_INGRESS_BYTES = 64 * 1024 * 1024;

// 413 响应写回后,等客户端读到响应自行断开的宽限期;超时强制 destroy 防连接悬挂。
const REQUEST_TOO_LARGE_DRAIN_TIMEOUT_MS = 10 * 1000;

// 转发请求的客户端不响应超时(socket 级别);LLM 请求经常 60s+,这里保守给 10 分钟。
const UPSTREAM_SOCKET_TIMEOUT_MS = 10 * 60 * 1000;

// WebSocket 这里只等 HTTP 101 握手,不应沿用允许长时间生成的 10 分钟超时。
// 中间代理静默丢弃 Upgrade 时尽快回 504,让 Codex 把它当临时失败继续原生重试;
// 不能伪装成 426,否则会把当前 Codex session 永久固定到 HTTP transport。
const WEBSOCKET_UPGRADE_TIMEOUT_MS = 15 * 1000;

// 已经由真实上游 101 证明可用的 thread,重连时由 loopback proxy 先接住客户端,随后在
// Cindy 内部回探上游。这样瞬时断网不会把 Codex 的 session 级 transport 固定到 HTTP。
// 回探没有总时限:生命周期由该条客户端 socket / proxy dispose 精确约束;退避上限避免
// 长时间离线时制造高频出网请求。
const WEBSOCKET_RECONNECT_INITIAL_DELAY_MS = 250;
const WEBSOCKET_RECONNECT_MAX_DELAY_MS = 5_000;
const WEBSOCKET_ACCEPT_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';

// Happy Eyeballs 单地址连接尝试超时。Node 20+ 默认开启 autoSelectFamily(双栈并竞),
// 但每个地址的 TCP 握手默认只给 250ms(net.getDefaultAutoSelectFamilyAttemptTimeout());
// 高延迟网络下到 Cloudflare 系上游(chatgpt.com 等)握手经常 >250ms,DNS 解出的所有地址
// 会被逐个砍掉,整个连接直接抛 AggregateError → 客户端收到 502 "upstream unreachable"
// (curl / 浏览器没有这么激进的 per-attempt 超时,所以只有 Node 转发这条路挂,2026-07 实踩)。
// 显式放宽到 2.5s:只拉长新建连接时 v6/v4 地址间的争抢窗口,连接成功后无影响,
// 请求整体超时仍由 UPSTREAM_SOCKET_TIMEOUT_MS 管。
const UPSTREAM_CONNECT_ATTEMPT_TIMEOUT_MS = 2500;

// proxy URL 会交给 Claude/Codex SDK;调用方可能使用 Fetch,因此对外端口必须避开
// Fetch 标准 bad ports。主动从高位私有端口区间选候选,避免依赖 OS 随机分配后再补漏。
const LOOPBACK_BIND_MAX_ATTEMPTS = 32;
const LOOPBACK_CANDIDATE_PORT_MIN = 49152;
const LOOPBACK_CANDIDATE_PORT_MAX = 65535;
const LOOPBACK_CANDIDATE_PORT_COUNT = LOOPBACK_CANDIDATE_PORT_MAX - LOOPBACK_CANDIDATE_PORT_MIN + 1;

const FETCH_BLOCKED_PORTS = new Set<number>([
  0, 1, 7, 9, 11, 13, 15, 17, 19,
  20, 21, 22, 23, 25, 37, 42, 43,
  53, 69, 77, 79, 87, 95, 101, 102,
  103, 104, 109, 110, 111, 113, 115, 117,
  119, 123, 135, 137, 139, 143, 161, 179,
  389, 427, 465, 512, 513, 514, 515, 526,
  530, 531, 532, 540, 548, 554, 556, 563,
  587, 601, 636, 989, 990, 993, 995, 1719,
  1720, 1723, 2049, 3659, 4045, 4190, 5060, 5061,
  6000, 6566, 6665, 6666, 6667, 6668, 6669, 6679, 6697, 10080,
]);

export function isFetchBlockedPort(port: number): boolean {
  return FETCH_BLOCKED_PORTS.has(port);
}

// 请求 dump 的字节上限。入站请求带上下文也很少超 64KB,典型只有几 KB。
// 超出截断后追加 "... (truncated, total N bytes)"。
// 2xx 响应不 dump body —— SSE 一个 turn 几 MB 起步, dump 反而把日志刷爆且没什么排查价值,
// 只记 status / content-type / 字节数。
const DEBUG_REQUEST_DUMP_MAX_BYTES = 64 * 1024;

// 错误响应 (status >= 400) body 的 dump 上限。错误响应通常只是一个 JSON error 对象
// (~几百字节),给 16KB 已经非常宽裕,超出按相同截断策略尾部追加 "... (truncated, total N bytes)"。
const ERROR_RESPONSE_DUMP_MAX_BYTES = 16 * 1024;
/**
 * 流式响应的终态事件:Responses `response.completed|failed|incomplete`、Anthropic
 * `message_stop`、Chat Completions `data: [DONE]`。见 forward() 里 client close 的收口。
 */
const SSE_TERMINAL_EVENT_RE =
  /\nevent:[ \t]*(?:response\.(?:completed|failed|incomplete)|message_stop)[ \t]*(?:\r?\n|\r?$)|"type"[ \t]*:[ \t]*"(?:response\.(?:completed|failed|incomplete)|message_stop)"|\ndata:[ \t]*\[DONE\]/;
const SSE_TERMINAL_SCAN_TAIL_CHARS = 64;
/** SSE 事件结束符:空行。 */
const SSE_EVENT_END_RE = /\r?\n\r?\n/;

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === 'object' && value !== null && !Array.isArray(value);
}

// per-thread 已见 id 缓存的有界上限(Copilot review 防内存 DoS;proxy 只绑
// loopback 不暴露外部,属防御性上限)。
const MAX_CACHED_THREADS = 1024;
const MAX_IDS_PER_THREAD = 8192;

interface ProvenWebSocketHandshake {
  readonly upstreamUrl: string;
  readonly inboundUrl: string;
  readonly requestSignature: string;
  readonly responseProtocol: string;
  readonly responseExtensions: string;
}

function webSocketRequestSignature(headers: Readonly<Record<string, string>>): string {
  return [
    headers['sec-websocket-version'] ?? '',
    headers['sec-websocket-protocol'] ?? '',
    headers['sec-websocket-extensions'] ?? '',
    headers['openai-beta'] ?? '',
  ].join('\n');
}

function createProvenWebSocketHandshake(
  upstreamUrl: string,
  inboundUrl: string,
  requestHeaders: Readonly<Record<string, string>>,
  response: IncomingMessage,
): ProvenWebSocketHandshake {
  return {
    upstreamUrl,
    inboundUrl,
    requestSignature: webSocketRequestSignature(requestHeaders),
    responseProtocol: String(response.headers['sec-websocket-protocol'] ?? ''),
    responseExtensions: String(response.headers['sec-websocket-extensions'] ?? ''),
  };
}

function rememberProvenWebSocketHandshake(
  cache: Map<string, ProvenWebSocketHandshake>,
  threadId: string,
  proof: ProvenWebSocketHandshake,
): void {
  if (!threadId) return;
  cache.delete(threadId);
  cache.set(threadId, proof);
  while (cache.size > MAX_CACHED_THREADS) {
    const oldest = cache.keys().next().value as string | undefined;
    if (oldest === undefined) break;
    cache.delete(oldest);
  }
}

function provenWebSocketHandshakeMatchesRequest(
  proof: ProvenWebSocketHandshake,
  upstreamUrl: string,
  inboundUrl: string,
  headers: Readonly<Record<string, string>>,
): boolean {
  return proof.upstreamUrl === upstreamUrl
    && proof.inboundUrl === inboundUrl
    && proof.requestSignature === webSocketRequestSignature(headers);
}

function provenWebSocketHandshakeMatchesResponse(
  proof: ProvenWebSocketHandshake,
  response: IncomingMessage,
): boolean {
  return proof.responseProtocol === String(response.headers['sec-websocket-protocol'] ?? '')
    && proof.responseExtensions === String(response.headers['sec-websocket-extensions'] ?? '');
}

/**
 * 为已证明可用的 WS thread 生成本地 101。只复用协议/扩展协商结果;Accept 必须按本次
 * Sec-WebSocket-Key 重新计算,不能复用上一条连接的值。
 */
function serializeProvenWebSocketHandshake(
  headers: Readonly<Record<string, string>>,
  proof: ProvenWebSocketHandshake,
): string | null {
  const key = headers['sec-websocket-key']?.trim();
  if (!key) return null;
  const accept = createHash('sha1').update(`${key}${WEBSOCKET_ACCEPT_GUID}`).digest('base64');
  const lines = [
    'HTTP/1.1 101 Switching Protocols',
    'Connection: Upgrade',
    'Upgrade: websocket',
    `Sec-WebSocket-Accept: ${accept}`,
  ];
  if (proof.responseProtocol) {
    lines.push(`Sec-WebSocket-Protocol: ${proof.responseProtocol}`);
  }
  if (proof.responseExtensions) {
    lines.push(`Sec-WebSocket-Extensions: ${proof.responseExtensions}`);
  }
  return `${lines.join('\r\n')}\r\n\r\n`;
}

/**
 * 往 per-thread 已见 id 缓存写入一条(id 去重)。有界:线程数超限 FIFO 淘汰最老
 * (re-insert 到 Map 末尾近似 LRU),单线程 id 超限丢最老(Set 按插入序)。
 */
function addThreadMintedId(
  threadMintedIdCache: Map<string, Set<string>>,
  threadIdKey: string,
  id: string,
): void {
  let set = threadMintedIdCache.get(threadIdKey);
  if (!set) {
    threadMintedIdCache.delete(threadIdKey); // 已存在则触底(近似 LRU)
    threadMintedIdCache.set(threadIdKey, new Set<string>());
    set = threadMintedIdCache.get(threadIdKey);
    while (threadMintedIdCache.size > MAX_CACHED_THREADS) {
      const oldest = threadMintedIdCache.keys().next().value as string | undefined;
      if (oldest === undefined) break;
      threadMintedIdCache.delete(oldest);
    }
  }
  if (set && !set.has(id)) {
    set.add(id);
    if (set.size > MAX_IDS_PER_THREAD) {
      const oldestId = set.keys().next().value as string | undefined;
      if (oldestId !== undefined) set.delete(oldestId);
    }
  }
}

interface UpstreamTarget {
  hostname: string;
  port: number;
  protocol: 'http:' | 'https:';
  basePath: string;  // 上游路径前缀(例 "" 或 "/v1")
  baseQuery: string; // 不含前导 '?'
}

/**
 * 一次请求已解析好的出站代理。在请求处理层(路由决策后)解析一次,透明重试沿用同一份,
 * 保证重试与首发走同一条网络路径。
 */
interface ResolvedOutboundProxy {
  target: OutboundProxyTarget;
  /**
   * 转发要挂的 agent。HTTP 代理:https 上游用 CONNECT 隧道 agent,http 上游走绝对形式
   * 请求不需要 agent(undefined);SOCKS5:两种上游都靠 agent 建隧道,恒有值。
   */
  agent?: OutboundProxyAgent;
}

function parseUpstream(upstream: string): UpstreamTarget {
  const u = new URL(upstream);
  if (u.protocol !== 'http:' && u.protocol !== 'https:') {
    throw new Error(`anthropic-compat-proxy: upstream must be http(s), got ${u.protocol}`);
  }
  return {
    hostname: u.hostname,
    port: u.port ? Number(u.port) : (u.protocol === 'https:' ? 443 : 80),
    protocol: u.protocol,
    basePath: u.pathname.replace(/\/+$/, ''),  // 去末尾斜杠,防止后面拼出双斜杠
    baseQuery: u.search.slice(1),
  };
}

/**
 * 把一个 UpstreamTarget 拼回可读 baseURL(默认端口省略,跟人类阅读习惯一致)——
 * 给 debug 日志用,让人直接看出请求**最终**流向哪个上游。默认上游与 per-request
 * override(routingTransform 的 upstreamOverride,如订阅直连 api.anthropic.com)共用。
 */
function formatUpstreamBase(t: UpstreamTarget): string {
  const defaultPort = t.protocol === 'https:' ? 443 : 80;
  return (
    `${t.protocol}//${t.hostname}` +
    (t.port === defaultPort ? '' : `:${t.port}`) +
    t.basePath +
    (t.baseQuery ? `?${t.baseQuery}` : '')
  );
}

function isRetryableListenError(error: unknown): boolean {
  if (!error || typeof error !== 'object' || !('code' in error)) return false;
  const code = (error as NodeJS.ErrnoException).code;
  return code === 'EADDRINUSE' || code === 'EACCES';
}

function randomLoopbackPort(): number {
  return LOOPBACK_CANDIDATE_PORT_MIN + Math.floor(Math.random() * LOOPBACK_CANDIDATE_PORT_COUNT);
}

async function listenOnLoopbackPort(server: Server, host: string, port: number): Promise<number> {
  return await new Promise<number>((resolve, reject) => {
    const cleanup = (): void => {
      server.removeListener('error', onError);
      server.removeListener('listening', onListening);
    };
    const onError = (error: Error): void => {
      cleanup();
      reject(error);
    };
    const onListening = (): void => {
      cleanup();
      const addr = server.address();
      if (!addr || typeof addr === 'string') {
        const error = new Error('anthropic-compat-proxy: failed to bind loopback port');
        server.close(() => reject(error));
        return;
      }
      resolve(addr.port);
    };

    server.once('error', onError);
    server.once('listening', onListening);
    try {
      server.listen(port, host);
    } catch (error) {
      cleanup();
      reject(error);
    }
  });
}

/** @internal Exported for deterministic port-retry tests; not part of the package entrypoint. */
export async function listenOnFetchSafeLoopbackPort(
  server: Server,
  host: string,
  logger: ProxyLogger,
): Promise<number> {
  const triedPorts = new Set<number>();
  let lastRetryableError: Error | null = null;
  for (let attempt = 1; attempt <= LOOPBACK_BIND_MAX_ATTEMPTS; attempt += 1) {
    // Windows exclusions are contiguous ranges (often hundreds of ports), so
    // retrying adjacent candidates can deterministically exhaust every attempt.
    let port = randomLoopbackPort();
    while (triedPorts.has(port)) {
      port = port === LOOPBACK_CANDIDATE_PORT_MAX ? LOOPBACK_CANDIDATE_PORT_MIN : port + 1;
    }
    triedPorts.add(port);

    if (isFetchBlockedPort(port)) {
      logger.warn?.('anthropic-compat-proxy skipped Fetch-blocked loopback port candidate', {
        port,
        attempt,
      });
      continue;
    }

    try {
      return await listenOnLoopbackPort(server, host, port);
    } catch (error) {
      if (!isRetryableListenError(error)) {
        throw error;
      }
      lastRetryableError = error instanceof Error ? error : new Error(String(error));
      logger.warn?.('anthropic-compat-proxy loopback port candidate unavailable; retrying', {
        port,
        attempt,
        err: String(error),
      });
    }
  }

  throw new Error(
    `anthropic-compat-proxy: failed to bind Fetch-safe loopback port after ${LOOPBACK_BIND_MAX_ATTEMPTS} attempts` +
      (lastRetryableError === null ? '' : `; last error ${lastRetryableError.message}`),
  );
}

/**
 * 把路由解析失败收敛为单请求的结构化错误,不能让 async HTTP handler 的 rejected
 * Promise 漂成 process-level unhandledRejection。错误详情只进日志,响应不回显 URL。
 */
function respondRoutingFailure(
  res: ServerResponse,
  logger: ProxyLogger,
  reqId: number,
  status: 502 | 503,
  message: string,
  err: unknown,
): void {
  logger.warn?.(message, { reqId, err: String(err) });
  if (!res.headersSent) {
    res.writeHead(status, { 'content-type': 'application/json' });
    res.end(JSON.stringify({ error: { type: 'proxy_error', message } }));
    return;
  }
  res.destroy(err instanceof Error ? err : new Error(String(err)));
}

/**
 * upgrade 阶段失败时写回一个明确的 HTTP 状态行再断开。
 *
 * **不能只 destroy socket**: codex 对裸断开会以 ~1s 间隔持续发 willRetry=true 的 error
 * notification, 而客户端按协议对 willRetry 不收口 —— turn 永不结束、UI 的 generating
 * 永不复位(远端 codex "永卡 generating" 就是这个形态, 见客户端仓 PR #715)。写回状态行
 * 才能让 codex 走它自己的终态路径。
 *
 * 状态码语义(调用方按场景选):
 *  - **426**: 让 codex 优雅退回 HTTP transport。这是它唯一认作降级信号的状态码,
 *    用于宿主主动把某个会话导回 HTTP(见 ProxyOptions.resolveWebSocketUpstream)。
 *  - 500: resolver 配置或本地 upgrade handler 失败。
 *  - 501: 本 proxy 不支持这种 upgrade(非 websocket 协议)。
 *  - 502 / 503 / 504: 上游或本地转发失败。
 */
function writeUpgradeFailure(socket: Socket, status: number, message: string): void {
  // 这些失败有一部分发生在 upgrade handler 安装通用 socket error listener 之前。
  // end() 的写失败是异步 error 事件,try/catch 捕不到;客户端若恰好取消预热或退出,
  // 必须在写入前就收口 EPIPE/ECONNRESET,避免错误冒泡终止 Desktop main 进程。
  socket.once('error', () => socket.destroy());
  try {
    // 先完整刷出状态行再断开。`write()` 后立刻 `destroy()` 在 Windows 上可能让尚未
    // 进入内核发送缓冲的小响应变成 RST,codex 看不到 426 就不会切回 HTTP。
    socket.end(
      `HTTP/1.1 ${status} ${message}\r\nConnection: close\r\n\r\n`,
      () => socket.destroy(),
    );
  } catch {
    // socket 可能已经废了(客户端先断/写入竞态), 此处无可挽回也无需上报。
    socket.destroy();
  }
}

/**
 * 非 101 响应是否更像「这条网络路径不支持 WebSocket」而非模型服务故障。
 *
 * 这些状态在 upgrade 阶段尚未创建模型响应,退回 HTTP 不会重复执行 turn:
 * - 2xx/3xx/大多数 4xx:透明代理/WAF 拦了 upgrade、端点不支持 WS 等,旧 HTTP 可能可用;
 * - 401:凭证本身失效,应保留原错误;
 * - 429:真实限流/容量信号,应交给同版本 Codex;
 * - 5xx:上游服务状态(含 at-capacity)应原样交给 Codex,不能被本地改写。
 */
function shouldFallbackToHttpAfterUpgradeResponse(status: number): boolean {
  return status < 500 && status !== 401 && status !== 429;
}

/**
 * 把上游响应的状态行与 header 序列化回原始 HTTP 报文头。
 *
 * upgrade 路径上客户端拿到的是裸 socket, 没有 ServerResponse 可用, 只能自己拼报文 ——
 * 无论是成功的 101 还是上游拒绝时的普通响应, 都要原样回写状态码与 header。
 */
function serializeResponseHead(
  res: IncomingMessage,
  opts?: {
    /** 要丢弃的 header 名(大小写不敏感)。 */
    readonly dropHeaders?: readonly string[];
    /** 追加/覆盖的 header。 */
    readonly extraHeaders?: Readonly<Record<string, string>>;
  },
): string {
  const dropped = new Set((opts?.dropHeaders ?? []).map((h) => h.toLowerCase()));
  const statusLine = `HTTP/1.1 ${res.statusCode ?? 502} ${res.statusMessage ?? ''}\r\n`;
  const lines = Object.entries(res.headers)
    .flatMap(([key, value]) => {
      if (value == null || dropped.has(key.toLowerCase())) return [];
      return Array.isArray(value) ? value.map((v) => `${key}: ${v}`) : [`${key}: ${value}`];
    });
  for (const [key, value] of Object.entries(opts?.extraHeaders ?? {})) {
    lines.push(`${key}: ${value}`);
  }
  return `${statusLine}${lines.join('\r\n')}\r\n\r\n`;
}

/** 路由层是最后的信任边界;任何调用方给出的路径覆盖都必须保持同源且不可注入 header。 */
function isSafePathOverride(value: unknown): value is string {
  if (typeof value !== 'string') return false;
  const queryIndex = value.indexOf('?');
  const pathname = queryIndex === -1 ? value : value.slice(0, queryIndex);
  const hasEncodedPathSeparator = /%(?:2f|5c)/i.test(pathname);
  const hasDotSegment = pathname
    .split('/')
    .some((segment) => {
      const normalizedDots = segment.replace(/%2e/gi, '.');
      return normalizedDots === '.' || normalizedDots === '..';
    });
  return (
    value.length >= 1
    && value.length <= 2_048
    && value.startsWith('/')
    && !value.startsWith('//')
    && !value.includes('#')
    && !value.includes('\\')
    && !/[^\u0021-\u007e]/.test(value)
    && /^\/[A-Za-z0-9\-._~%!$&()*+,;=:@/?]*$/.test(value)
    && !/%(?![0-9A-Fa-f]{2})/.test(value)
    && !hasEncodedPathSeparator
    && !hasDotSegment
  );
}

function isPromiseLike<T>(value: unknown): value is PromiseLike<T> {
  // 接受 object 与 function 两类 thenable(函数对象也可以合法带 .then,见 Promise/A+)。
  return (
    (typeof value === 'object' || typeof value === 'function') &&
    value !== null &&
    typeof (value as { then?: unknown }).then === 'function'
  );
}

/** Enforce one real start and one terminal callback across transparent retry recursion. */
function guardForwardLifecycleObserver(
  observer: ForwardLifecycleObserver | undefined,
): ForwardLifecycleObserver | null {
  if (!observer) return null;
  let started = false;
  let settled = false;
  return {
    onStart: () => {
      if (started || settled) return;
      started = true;
      observer.onStart?.();
    },
    onComplete: (status) => {
      if (!started || settled) return;
      settled = true;
      observer.onComplete?.(status);
    },
    onFailure: (failure, status) => {
      if (!started || settled) return;
      settled = true;
      observer.onFailure?.(failure, status);
    },
  };
}

/**
 * 执行路由决策命中的本地 handler(见 types.LocalRequestHandler 契约)。
 *
 * 错误语义与 forward 的上游错误一致:
 *   - handler 抛错且未写响应头 → 502 fail-open(客户端得到明确错误,不挂死);
 *   - 已写头(流式中途炸)→ destroy socket;
 *   - handler resolve 但没 end 响应 → 防御性收尾(未写头按 502 算),请求绝不悬挂。
 */
async function runLocalHandler(
  handler: LocalRequestHandler,
  args: { rawBody: Buffer; parsedBody: unknown; ctx: RequestTransformCtx; res: ServerResponse },
  logger: ProxyLogger,
  reqId: number,
): Promise<void> {
  const { res } = args;
  try {
    await handler(args);
    if (!res.writableEnded) {
      logger.warn?.('local handler resolved without ending response; closing defensively', { reqId });
      if (!res.headersSent) {
        res.writeHead(502, { 'content-type': 'application/json' });
        res.end(JSON.stringify({ error: { type: 'proxy_error', message: 'local handler produced no response' } }));
      } else {
        res.end();
      }
    }
  } catch (err) {
    logger.error?.('local handler failed', { reqId, err: err instanceof Error ? err.message : String(err) });
    if (!res.headersSent) {
      res.writeHead(502, { 'content-type': 'application/json' });
      res.end(JSON.stringify({ error: { type: 'proxy_error', message: `local handler failed: ${String(err)}` } }));
    } else {
      res.destroy(err instanceof Error ? err : new Error(String(err)));
    }
  }
}

/**
 * 收集请求 body 到 Buffer。超 maxBytes 时 reject(err.message = 'REQUEST_TOO_LARGE',
 * err.receivedBytes = 已收字节数)让 caller 走 respondRequestTooLarge 回 413。
 * 不解析 JSON —— 解析在 transform 阶段做,先确保拿到完整字节。
 *
 * 超限时**不能**在这里 destroy socket:413 响应还没写回,先斩连接客户端只会看到
 * 含糊的传输层错误(reqwest: "error sending request for url (…)"),且无从排查
 * (2026-07 导入超大 codex 会话实踩)。这里只停止消费,响应与收尾交给调用方。
 */
function collectRequestBody(req: IncomingMessage, maxBytes: number): Promise<Buffer> {
  return new Promise((resolve, reject) => {
    const chunks: Buffer[] = [];
    let total = 0;
    const onEnd = () => resolve(Buffer.concat(chunks));
    const onError = (e: Error) => reject(e);
    const onData = (chunk: Buffer) => {
      total += chunk.length;
      if (total > maxBytes) {
        // 三个监听器一起摘干净 —— 调用方随后 resume drain 剩余 body,end/error
        // 留着虽因 Promise 已 settled 只是 no-op,但没必要挂到 GC。
        req.off('data', onData);
        req.off('end', onEnd);
        req.off('error', onError);
        req.pause();
        const err = new Error('REQUEST_TOO_LARGE') as Error & { receivedBytes?: number };
        err.receivedBytes = total;
        reject(err);
        return;
      }
      chunks.push(chunk);
    };
    req.on('data', onData);
    req.on('end', onEnd);
    req.on('error', onError);
  });
}

/** 丢弃未读完的请求体。early 503 必须先 drain 再结束响应,否则 Node 会 RST 客户端。 */
function drainRequest(req: IncomingMessage): Promise<void> {
  if (req.readableEnded || req.destroyed) return Promise.resolve();
  return new Promise((resolve) => {
    const done = (): void => resolve();
    req.once('end', done);
    req.once('close', done);
    req.once('error', done);
    req.resume();
  });
}

/**
 * 请求 body 超限的统一收尾:先把**完整的 413 响应**写回、再让连接关闭,顺序不能反。
 * 历史实现是先 req.destroy() 再写 413 —— socket 已死,413 永远到不了客户端,
 * codex/reqwest 端只能报 "stream disconnected before completion: error sending
 * request for url (http://127.0.0.1:PORT/responses)" 这种传输层错误;且旧路径
 * 一行日志都没有,线上完全无从定位。现在:
 *   1. warn 日志(threadId + 上限 + 声明/实收字节数),让 main log 可直接 grep 到;
 *   2. 全量写出 413 字节(显式 content-length,客户端边传边读即可完整解析)
 *      + connection: close;
 *   3. resume 丢弃剩余上传字节(无 listener,不占内存),**等请求体 drain 完再
 *      res.end()** —— Node 在"请求未读完就结束响应"时会主动 destroySoon socket,
 *      客户端还没来得及解析 413 就撞上 RST/EPIPE,等 drain 完收尾才是干净的 FIN;
 *   4. 宽限期超时强制收尾兜底,防止不守规矩的客户端把连接挂死。
 */
function respondRequestTooLarge(opts: {
  req: IncomingMessage;
  res: ServerResponse;
  logger: ProxyLogger;
  reqId: number;
  method: string;
  url: string;
  headers: Record<string, string>;
  limitBytes: number;
  /** Content-Length 预检命中时的声明字节数;流式守卫命中时为 null。 */
  declaredBytes: number | null;
  receivedBytes: number;
  reason?: 'request_body_too_large' | 'attachment_recovery_storage_exhausted';
}): void {
  const { req, res, logger } = opts;
  const storageExhausted = opts.reason === 'attachment_recovery_storage_exhausted';
  logger.warn?.(storageExhausted ? 'attachment recovery has insufficient temporary disk space → 507' : '✖ request body exceeds proxy limit → 413', {
    reqId: opts.reqId,
    method: opts.method,
    url: opts.url,
    threadId: selectedHeaderValue(opts.headers, DEFAULT_THREAD_ID_HEADERS) || undefined,
    limitBytes: opts.limitBytes,
    declaredBytes: opts.declaredBytes ?? undefined,
    receivedBytes: opts.receivedBytes,
  });
  const payload = Buffer.from(JSON.stringify({
    error: {
      type: 'proxy_error',
      reason: opts.reason ?? 'request_body_too_large',
      message: storageExhausted ? 'Not enough free disk space to recover this request. Free disk space and retry; the original conversation is unchanged.' : `request body too large: ${opts.declaredBytes ?? `>${opts.receivedBytes}`} bytes exceeds proxy limit of ${opts.limitBytes} bytes`,
    },
  }));
  res.writeHead(storageExhausted ? 507 : 413, {
    'content-type': 'application/json',
    'content-length': String(payload.length),
    connection: 'close',
  });
  res.write(payload);

  let finished = false;
  const finish = () => {
    if (finished) return;
    finished = true;
    clearTimeout(killTimer);
    res.end();
  };
  const killTimer = setTimeout(() => {
    finish();
    req.destroy();
  }, REQUEST_TOO_LARGE_DRAIN_TIMEOUT_MS);
  killTimer.unref?.();

  if (req.readableEnded) {
    finish();
  } else {
    req.once('end', finish);
    req.once('close', finish);
    req.resume();
  }
}

/**
 * 跑 transform 链。transform 默认抛错时跳过;显式标记 reject-request 时中止请求。
 * 所有 transform 都返回 null → 也返回 null(透传)。
 * 至少一个 transform 改了 body → 返回最新的 body。
 *
 * async:transform 可返回 Promise(视觉桥等出网调用)。用 isPromiseLike 统一 await,
 * 同步 transform 返回值原样通过。必须**顺序 await**(禁 Promise.all)——现有 transform
 * 有强顺序依赖(repairToolExchangeAdjacency → dedupeDuplicateToolUseIds),并发会张冠李戴。
 */
async function runTransforms(
  rawBody: Buffer,
  contentType: string,
  transforms: RequestTransform[],
  ctx: RequestTransformCtx,
  logger: ProxyLogger,
  preParsed?: unknown,
): Promise<Buffer | null> {
  if (transforms.length === 0) return null;
  if (!contentType.toLowerCase().startsWith('application/json')) return null;

  let parsed: unknown = preParsed;
  if (preParsed === undefined) {
    try {
      parsed = JSON.parse(rawBody.toString('utf8'));
    } catch (err) {
      logger.warn?.('json parse failed, falling back to passthrough', { err: String(err) });
      return null;
    }
  }

  let current: unknown = parsed;
  let mutated = false;
  for (const t of transforms) {
    try {
      const raw = t(current, ctx);
      const next = isPromiseLike<unknown | null>(raw) ? await raw : raw;
      if (next !== null && next !== undefined) {
        current = next;
        mutated = true;
      }
    } catch (err) {
      if (t.errorMode === 'reject-request') throw err;
      logger.warn?.('transform threw, skipping it', { err: String(err) });
    }
  }

  if (!mutated) return null;
  try {
    return Buffer.from(JSON.stringify(current), 'utf8');
  } catch (err) {
    logger.error?.('re-serialize failed, falling back to passthrough', { err: String(err) });
    return null;
  }
}

/**
 * 把 IncomingMessage.headers 平铺成 Record<string,string>,过滤掉 hop-by-hop headers
 * 和会让上游 / 下游困惑的字段。
 *
 * 删的字段:
 *   - host:           必须由 client lib 自己根据上游 hostname 重算
 *   - connection:     hop-by-hop
 *   - keep-alive:     hop-by-hop
 *   - transfer-encoding: 我们已经把 body 缓冲完整,改回 content-length
 *   - content-length: 由调用方根据 outBody.length 重算
 */
function flattenRequestHeaders(raw: IncomingMessage['headers']): Record<string, string> {
  const out: Record<string, string> = {};
  for (const [k, v] of Object.entries(raw)) {
    const lk = k.toLowerCase();
    if (lk === 'host' || lk === 'connection' || lk === 'keep-alive' || lk === 'transfer-encoding' || lk === 'content-length') continue;
    if (Array.isArray(v)) out[lk] = v.join(', ');
    else if (v != null) out[lk] = String(v);
  }
  return out;
}

function flattenResponseHeaders(raw: IncomingMessage['headers']): Record<string, string> {
  const out: Record<string, string> = {};
  for (const [k, v] of Object.entries(raw)) {
    if (Array.isArray(v)) out[k.toLowerCase()] = v.join(', ');
    else if (v != null) out[k.toLowerCase()] = String(v);
  }
  return out;
}

function extractBodyModel(body: Buffer): string {
  try {
    const parsed: unknown = JSON.parse(body.toString('utf8'));
    if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
      const model = (parsed as Record<string, unknown>).model;
      if (typeof model === 'string') return model;
    }
  } catch { /* not JSON */ }
  return '';
}

/**
 * 把 Buffer 转成 debug 日志友好的字符串 —— UTF-8 解码 + 长度截断 + JSON pretty 尝试。
 *
 * - 优先尝试 JSON.parse + JSON.stringify(2) 输出,可读性高
 * - 解析失败回退原始 utf8 字符串
 * - 超 maxBytes 字节时尾部截断,加 "... (truncated, total N bytes)" 提示
 *
 * 仅在 isDebugEnabled 命中时才会被调用,info/warn 级别开销 0。
 */
/**
 * 从上游错误响应 body 里抽取 `error.type` (低风险字段) 用于 release 默认摘要。
 *
 * Anthropic / OpenAI / litellm 的错误体共享 `{ "error": { "type": "...", ... } }` 形态,
 * 这里只取 type 字符串,不取 message —— message 经常回显请求字段值, 会泄漏 prompt 片段。
 *
 * 任何失败 (非 JSON / content-type 不对 / 字段缺失 / body 截断到一半) 都返回 undefined,
 * 调用方直接省略 errorType 字段, 不影响主路径。
 */
function extractErrorType(buf: Buffer, contentType: string): string | undefined {
  if (!contentType.toLowerCase().startsWith('application/json')) return undefined;
  if (buf.length === 0) return undefined;
  try {
    const parsed: unknown = JSON.parse(buf.toString('utf8'));
    if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
      const err = (parsed as Record<string, unknown>).error;
      if (typeof err === 'object' && err !== null && !Array.isArray(err)) {
        const t = (err as Record<string, unknown>).type;
        if (typeof t === 'string' && t.length > 0) return t;
      }
    }
  } catch { /* not JSON / truncated mid-parse */ }
  return undefined;
}

function dumpBody(buf: Buffer, maxBytes: number): string {
  if (buf.length === 0) return '<empty>';
  const truncated = buf.length > maxBytes;
  const slice = truncated ? buf.subarray(0, maxBytes) : buf;
  let text = slice.toString('utf8');
  // 尝试 pretty: 整 buffer parse 成功才 pretty,截断版本通常 parse 不动直接走 utf8 原文
  if (!truncated) {
    try {
      text = JSON.stringify(JSON.parse(text), null, 2);
    } catch { /* not JSON / corrupted, keep utf8 */ }
  }
  if (truncated) {
    text += `\n... (truncated, total ${buf.length} bytes)`;
  }
  return text;
}

/**
 * 按 content-encoding 解压"日志用"的错误体 buffer。
 *
 * 背景: node:http 的 request 不会自动解压响应体, 上游(litellm / Azure / gateway)
 * 若带 `Content-Encoding: gzip|br|deflate`, errBuf 里就是压缩字节, 直接 toString('utf8')
 * 会得到一坨乱码(典型: 一段被 gzip 的 JSON error 体)。这里仅为让日志可读而解压一次。
 *
 * 不影响响应主路径 —— 给客户端走的是字节级 pipe + content-encoding 头透传, 客户端自己解压。
 *
 * 任何失败(未知编码 / 截断的压缩流 / 非法数据)都返回**原始 buffer 引用**, 调用方据此
 * 判断"是否成功解压"(decoded !== buf 即成功), 失败时日志退回原样, 不抛错、不影响主流程。
 */
function decodeBodyForLog(buf: Buffer, contentEncoding: string | undefined): Buffer {
  if (!contentEncoding || buf.length === 0) return buf;
  const enc = contentEncoding.toLowerCase().trim();
  try {
    if (enc === 'gzip' || enc === 'x-gzip') return gunzipSync(buf);
    if (enc === 'br') return brotliDecompressSync(buf);
    if (enc === 'deflate') {
      // deflate 有两种封装: zlib 头(inflateSync)和裸 deflate(inflateRawSync), 依次尝试。
      try { return inflateSync(buf); } catch { return inflateRawSync(buf); }
    }
  } catch {
    // 截断的压缩流 / 非法数据 → 回退原始字节(日志里仍是乱码但不崩)
  }
  return buf;
}

/**
 * 实际转发到上游 + pipe 响应回客户端。
 *
 * 响应路径关键: res.writeHead + upstreamRes.pipe(res), 全程不读 body 字节,
 * 这是 SSE 流式响应延迟为零的保证。
 *
 * 响应日志只记 status / content-type / 总字节(等 'end' 后),不 dump body —— 一个
 * SSE turn 几 MB 起步, dump 把日志刷爆且没什么排查价值。要看实际响应内容,直接
 * tail cc 子进程的 cc-debug.log。
 *
 * 请求 body 在调用 forward 前已被上层在 debug 级别下 dump 过,这里不重复。
 */
function forward(
  target: UpstreamTarget,
  method: string,
  path: string,
  headers: Record<string, string>,
  body: Buffer,
  clientRes: ServerResponse,
  logger: ProxyLogger,
  recoveryRules: readonly RecoveryRule[],
  reqId: number,
  // false → 本次是某条 recovery rule 的透明重试结果, 不再二次重试 (防循环)。
  canRetry = true,
  // per-request 路由 override:覆盖上游目标 / 合并额外 header(典型: 换 authorization)。
  // 省略 → 用默认 target + 原 headers(与扩展前字节级一致)。
  overrideTarget?: UpstreamTarget,
  headerOverride?: Record<string, string>,
  // 转发前从 outbound headers 删除的字段(大小写不敏感)。在 headerOverride 合并之后应用。
  headerDelete?: readonly string[],
  responseObserver?: ResponseObserver,
  transformResponse?: ResponseTransform,
  // 原始客户端 model id。provider transform 可能在出站前去掉命名空间;recovery
  // controller 必须记原值,才能和下一轮主动 strip 看到的入站 model 对上。
  clientModel = '',
  // 请求处理层解析好的出站代理;undefined = 直连(与扩展前字节级一致)。
  outboundProxy?: ResolvedOutboundProxy,
  // 精确推理路径覆盖;省略时沿用客户端原始 path。
  pathOverride?: string,
  // 请求历史里「铸造形态」的 tool_use id 集合(moonshot/kimi 的 ${name}_${index}
  // id);非空时响应 SSE 流经过撞车改名,防 CLI 把重复 id 写进转录后被
  // ensureToolResultPairing 整段丢弃(运行中会话的空消息腐蚀,见
  // tool-use-id-stream-rewrite.ts 头注)。null/undefined → 响应字节透传。
  responseToolUseIds?: Set<string> | null,
  // per-thread 已见 id 缓存:改名产物(_dupN)落缓存,防「请求体缺席历史 id 但
  // 同底再铸」的自激循环(codex-connector review P1)。由 createAnthropicCompatProxy
  // 注入,forward 是模块级函数取不到闭包作用域。
  threadMintedIdCache?: Map<string, Set<string>> | null,
  // 请求体显式声明 `"stream": true`(请求处理层解析一次后传入,不二次 parse)。
  // 为 true 时启用 2xx 成功响应的流式有效性门(#2242):空 2xx / 非 SSE 2xx /
  // 零事件 SSE 不再原样透传给客户端,转成结构化 502。false 保持字节级透传。
  requestDeclaredStream = false,
  // 透明重试前再跑同一条 dispatch gate。返回 false = 已改道(典型 503),
  // 不得带着旧 headerOverride 再发一次。省略 = 与扩展前一样直接重发。
  beforeRetry?: () => Promise<boolean>,
  // Optional request-local operational observer. It never receives raw request/response data.
  forwardLifecycle?: ForwardLifecycleObserver | null,
  recoverUpstreamOversized?: (body: Buffer, signal: AbortSignal) => Promise<Buffer>,
): void {
  // Diagnostics are a strict side channel: callback failures must never change forwarding.
  const notifyForwardLifecycle = (notify: () => void): void => {
    try {
      notify();
    } catch {
      // Diagnostic callback: deliberately ignored.
    }
  };
  // 客户端已断开(典型:400 缓冲期间断开后走到透明重试)——'close' 已经发过,
  // 下面挂的中断传播 listener 永远不会触发,直接不发起上游请求。
  if (clientRes.destroyed) {
    if (forwardLifecycle?.onFailure) {
      notifyForwardLifecycle(() => forwardLifecycle.onFailure?.('client-aborted'));
    }
    logger.info?.('client already disconnected — skipping upstream forward', { reqId, method, path });
    return;
  }
  const actualTarget = overrideTarget ?? target;
  let actualHeaders = headerOverride ? { ...headers, ...headerOverride } : headers;
  if (headerDelete && headerDelete.length > 0) {
    // clone if we haven't already —— 不能就地改 `headers`(透明重试会复用同一份原始 headers)。
    if (actualHeaders === headers) actualHeaders = { ...headers };
    const toDelete = new Set(headerDelete.map((h) => h.toLowerCase()));
    for (const key of Object.keys(actualHeaders)) {
      if (toDelete.has(key.toLowerCase())) delete actualHeaders[key];
    }
  }
  const reqFn = actualTarget.protocol === 'https:' ? httpsRequest : httpRequest;
  const routedPath = pathOverride ?? path;
  const queryIndex = routedPath.indexOf('?');
  const routedPathname = queryIndex === -1 ? routedPath : routedPath.slice(0, queryIndex);
  const routedQuery = queryIndex === -1 ? '' : routedPath.slice(queryIndex + 1);
  const upstreamPathname =
    `${actualTarget.basePath}${routedPathname.startsWith('/') ? routedPathname : '/' + routedPathname}`;
  const upstreamQuery = [actualTarget.baseQuery, routedQuery].filter(Boolean).join('&');
  const upstreamPath = upstreamQuery ? `${upstreamPathname}?${upstreamQuery}` : upstreamPathname;

  // http.request 会把 options 原样透传给 agent.createConnection → net.connect,
  // 所以 socket 级 connect 选项运行时有效;但 @types/node 的 RequestOptions 没收录
  // autoSelectFamilyAttemptTimeout,用交叉类型显式补上。
  const upstreamOptions: RequestOptions & Pick<TcpSocketConnectOpts, 'autoSelectFamilyAttemptTimeout'> = {
    hostname: actualTarget.hostname,
    port: actualTarget.port,
    method,
    path: upstreamPath,
    headers: {
      ...actualHeaders,
      host: actualTarget.hostname,
      'content-length': String(body.length),
    },
    timeout: UPSTREAM_SOCKET_TIMEOUT_MS,
    autoSelectFamilyAttemptTimeout: UPSTREAM_CONNECT_ATTEMPT_TIMEOUT_MS,
  };
  if (outboundProxy) {
    if (outboundProxy.target.kind === 'socks5') {
      // SOCKS5 是 L4 隧道:握手由 agent 完成,请求本身照常发给真实上游 ——
      // hostname / port / path / Host 头一律不动(没有绝对形式请求这回事),
      // 目标域名也不在本地解析,交给代理端(见 socks5.ts 文件头)。
      upstreamOptions.agent = outboundProxy.agent;
    } else if (actualTarget.protocol === 'https:') {
      // https 上游:经 CONNECT 隧道 agent 转发(TLS 端到端,代理只见密文)。
      upstreamOptions.agent = outboundProxy.agent;
    } else {
      // http 上游:按 HTTP 代理惯例改发绝对形式请求给代理;Host 头指向真实上游。
      // socket 连的是代理,Host 头只能显式设置 —— 按 RFC 9110 带非默认端口 / IPv6 方括号。
      upstreamOptions.hostname = outboundProxy.target.hostname;
      upstreamOptions.port = outboundProxy.target.port;
      upstreamOptions.path = `http://${formatAuthority(actualTarget.hostname, actualTarget.port)}${upstreamPath}`;
      (upstreamOptions.headers as Record<string, string>).host =
        formatHostHeader(actualTarget.hostname, actualTarget.port, actualTarget.protocol);
      if (outboundProxy.target.authHeader) {
        (upstreamOptions.headers as Record<string, string>)['proxy-authorization'] = outboundProxy.target.authHeader;
      }
    }
  }
  const upstreamReq = reqFn(upstreamOptions);
  if (forwardLifecycle?.onStart) {
    notifyForwardLifecycle(() => forwardLifecycle.onStart?.());
  }

  // ── 客户端中断传播 ────────────────────────────────────────────────────────
  // CC 掐流(stall 检测 / 用户 Stop / watchdog interrupt)时只会断开与本代理的
  // 连接;若不把中断传给上游,上游会把整段生成跑完并按全量输出计费(大上下文
  // 会话单笔可达数美元的费用泄漏),socket 也会悬挂到响应自然结束。这里在客户端
  // 连接于响应完成前关闭时,同步 destroy 上游请求(连带掐掉响应流)。
  // writableEnded 守卫:正常完成后的 'close'(end() 已调用)不触发。
  // 透明重试复用同一 clientRes,每次 forward 各挂一个 listener 指向自己的
  // upstreamReq —— 旧请求早已完成,destroy 是 no-op,不影响重试语义。
  let clientAborted = false;
  // 代理自己 destroy clientRes(上游故障回收客户端连接)也会触发 'close' 且
  // writableEnded 为 false —— 那不是客户端断开,不该打断开日志/置 clientAborted,
  // 否则排查上游故障时日志会把因果指向客户端。destroy 前置位此标记跳过。
  let proxyDestroyedClient = false;
  // 一个请求可能同时收到 upstream response 的 `aborted` + `error`(或 `close`),
  // 也可能在 response error 之后再收到 upstreamReq error。所有这些事件都只
  // 能把 clientRes 收口一次;否则第二个事件会重复 destroy / 重复刷错误日志。
  let upstreamFailureHandled = false;
  // `end` 与 `close` 的事件顺序由 Node stream 决定,不能用 clientRes.writableEnded
  // 判断上游是否正常结束:上游 `end` listener 执行时 pipe 尚未调用 clientRes.end()。
  // 这个状态还用于屏蔽 error/aborted 在正常 end 后的迟到事件。
  let upstreamResponseTerminal: 'end' | 'error' | 'aborted' | 'close' | 'client-aborted' | null = null;
  // response 已经开始后,同一个 socket 故障在不同 Node/平台上可能先落到
  // upstreamReq.error 或 upstreamRes.error。request 侧通过这个回调汇入当前
  // response 的终态处理,保证 observer 与下游收口语义不受事件先后影响。
  let failActiveResponse: ((err: unknown) => void) | null = null;
  // 2xx SSE 已把终态事件(response.completed / message_stop / [DONE] 等)转给客户端后,
  // 客户端随即断开是正常收尾(Codex CLI 收到 response.completed 就关连接,上游 body 往往
  // 还没 end)。流式路径在这里挂一个收口函数:返回 true 表示已按正常完成处理。
  let completeAfterTerminalSseEvent: (() => boolean) | null = null;
  // upstreamRes emits `end` before a request-scoped response Transform finishes
  // its _flush. Keep those downstream transforms pending so an async flush
  // error can still fail the client instead of being mistaken for a harmless
  // post-end event.
  const pendingResponseTransforms = new Set<Transform>();

  const finishClientAfterUpstreamFailure = (
    err: Error,
    message = `upstream stream error: ${String(err)}`,
    code?: string,
  ): boolean => {
    if (
      clientAborted ||
      proxyDestroyedClient ||
      upstreamFailureHandled ||
      clientRes.destroyed ||
      clientRes.writableEnded
    ) {
      return false;
    }
    upstreamFailureHandled = true;
    // `destroy()` / `end()` 都会触发 clientRes.close;先标记来源,避免 close listener
    // 把代理自己收口的故障误报成“client disconnected”。
    proxyDestroyedClient = true;
    if (!clientRes.headersSent) {
      clientRes.writeHead(502, { 'content-type': 'application/json' });
      clientRes.end(JSON.stringify({
        error: { type: 'proxy_error', ...(code ? { code } : {}), message },
      }));
    } else {
      // 已经把上游的部分响应发给客户端时,不能 end 一个看似完整的 SSE。
      // destroy 让 Claude/SDK 明确收到截断连接并立即失败,而不是把半截流当成功。
      clientRes.destroy(err);
    }
    return true;
  };

  clientRes.on('close', () => {
    // 透明重试的上一笔 forward 也保留着 close listener;它的上游已经 end,
    // 后一笔若因上游故障 destroy clientRes,不能被旧 listener 误报成客户端断开。
    if (proxyDestroyedClient || upstreamResponseTerminal === 'end' || clientRes.writableEnded) return;
    if (completeAfterTerminalSseEvent?.()) {
      // 生成已经结束,不存在计费泄漏;仍释放上游 socket,不让它悬挂到 body 自然结束。
      upstreamReq.destroy();
      return;
    }
    clientAborted = true;
    if (upstreamResponseTerminal === null) upstreamResponseTerminal = 'client-aborted';
    if (forwardLifecycle?.onFailure) {
      notifyForwardLifecycle(() => forwardLifecycle.onFailure?.('client-aborted'));
    }
    logger.info?.('client disconnected mid-response — aborting upstream request', {
      reqId,
      method,
      path: upstreamPathname,
    });
    upstreamReq.destroy(new Error('client aborted before response completed'));
  });

  upstreamReq.on('response', (upstreamRes) => {
    // 请求已经因客户端断开或另一条 upstream error 路径收口时,不要再向同一个
    // ServerResponse 写 header/pipe;恢复上游读取以释放 socket。
    if (clientAborted || upstreamFailureHandled || clientRes.destroyed || upstreamResponseTerminal === 'client-aborted') {
      upstreamRes.resume();
      return;
    }

    // status + headers 透传(过滤掉 transfer-encoding 让 Node 自己处理 chunked)
    const respHeaders: Record<string, string | string[]> = {};
    for (const [k, v] of Object.entries(upstreamRes.headers)) {
      if (k.toLowerCase() === 'transfer-encoding') continue;
      if (v !== undefined) respHeaders[k] = v;
    }
    const status = upstreamRes.statusCode ?? 502;

    // ── 上游 400/422 的透明重试 ──────────────────────────────────────────────
    // 只对启用恢复规则的客户端错误(400/422)缓冲判定:
    // 先把(很小的) 错误体完整缓冲下来, 在 'end' 找第一条 match 命中且 strip 出东西的规则,
    // 剥字段重发最多一次, 对客户端透明;重试后只分类不可恢复的错误,不再重发。
    // xAI 对不可反序列化 / 解不开的 encrypted_content 可能回 422 invalid-argument, 不能只认 400。
    // 2xx 流式响应 / 其它 4xx5xx / 无适用规则走下面原有的 writeHead + pipe, 零额外延迟。
    const activeRules = (status === 400 || status === 422)
      ? recoveryRules.filter((r) => r.enabled() && (canRetry || r.unrecoverableCode))
      : [];
    const recover413 = status === 413 && canRetry && recoverUpstreamOversized;
    if (activeRules.length > 0 || recover413) {
      const chunks: Buffer[] = [];
      const failBufferedResponse = (
        reason: 'error' | 'aborted' | 'close',
        rawError?: unknown,
      ): void => {
        if (upstreamResponseTerminal !== null) return;
        upstreamResponseTerminal = reason;
        if (clientAborted || clientRes.destroyed) return;
        const err = rawError instanceof Error
          ? rawError
          : new Error(rawError === undefined
            ? `upstream response ${reason} before completion`
            : String(rawError));
        if (forwardLifecycle?.onFailure) {
          const failure: ForwardLifecycleFailure =
            reason === 'close' ? 'response-closed' : `response-${reason}`;
          notifyForwardLifecycle(() =>
            forwardLifecycle.onFailure?.(failure, status),
          );
        }
        logger.error?.('upstream response stream error (during 400 buffering)', {
          reqId,
          err: String(err),
          reason,
          status,
          bytes: chunks.reduce((sum, chunk) => sum + chunk.length, 0),
        });
        // 400/422 buffering never creates a responseObserver sink; only the
        // streaming path below owns observer start/data/end/error callbacks.
        finishClientAfterUpstreamFailure(err);
      };
      failActiveResponse = (err) => failBufferedResponse('error', err);

      upstreamRes.on('data', (chunk: Buffer) => {
        if (upstreamResponseTerminal !== null) return;
        chunks.push(chunk);
      });
      upstreamRes.on('end', async () => {
        if (upstreamResponseTerminal !== null) return;
        upstreamResponseTerminal = 'end';
        if (clientAborted || clientRes.destroyed || upstreamFailureHandled) return;
        const errBody = Buffer.concat(chunks);
        // 先按 content-encoding 解压一次 —— 规则 matches / errorType / body dump 都吃解压后的字节。
        // node:http 不自动解压; 上游若 gzip/br 压缩, 直接对压缩字节跑 regex 会漏判, 透明重试就不触发。
        // (回客户端仍是原始 errBody + content-encoding 头透传, 客户端自己解压, 见下方 clientRes.end)
        const decodedErrBody = decodeBodyForLog(errBody, String(upstreamRes.headers['content-encoding'] ?? ''));
        const decodedText = decodedErrBody.toString('utf8');
        if (recover413) {
          const recoveryAbort = new AbortController();
          const abortRecovery = (): void => recoveryAbort.abort();
          clientRes.once('close', abortRecovery);
          let recovered: Buffer | undefined;
          try {
            recovered = await recover413(body, recoveryAbort.signal);
          } catch {
            // Storage failure, unsupported content and cancellation must never
            // replace the original 413 with an unrelated recovery error.
            logger.info?.('upstream 413 attachment recovery unavailable', { reqId });
          } finally {
            clientRes.off('close', abortRecovery);
          }
          if (clientRes.destroyed || clientRes.writableEnded) return;
          if (recovered && recovered.length < body.length) {
            try {
              if (beforeRetry && !(await beforeRetry())) return;
            } catch {
              recovered = undefined;
            }
            if (clientRes.destroyed || clientRes.writableEnded) return;
            if (recovered) {
              logger.info?.('upstream 413 attachment recovery retry', {
                reqId, originalBytes: body.length, recoveredBytes: recovered.length,
              });
              forward(
                target, method, path, headers, recovered, clientRes, logger,
                recoveryRules, reqId, false, overrideTarget, headerOverride,
                headerDelete, responseObserver, transformResponse, clientModel,
                outboundProxy, pathOverride, responseToolUseIds, threadMintedIdCache,
                requestDeclaredStream, beforeRetry, forwardLifecycle,
              );
              return;
            }
          }
        }
        // 取第一条 match 命中且 strip 出东西的规则;命中错误文案但没东西可删 → 试下一条。
        for (const [matchedIndex, rule] of activeRules.entries()) {
          if (!canRetry) break;
          if (!rule.matches(decodedText)) continue;
          const stripped = rule.strip(body);
          if (!stripped) continue;
          let retryBody = stripped;
          const appliedRules: RecoveryRule[] = [rule];
          // 透明重试只有一次。若同一历史里同时存在多类已知坏 payload,在这一次 retry
          // 前把其它安全 strip 也顺手应用掉,避免第一类 400 恢复后立刻撞第二类 400。
          // applyOnUnmatchedRetry === false 的规则只在自己 matches 时跑,不能叠到
          // 别人的 400 上(xAI ModelInput 清洗会改写 OpenAI collab 历史)。
          // allowExtraRules === false 的主匹配禁止整轮叠洗(ModelInput 422 叠
          // encrypted-content 会删掉 xAI 本可回放的 reasoning blob)。
          if (rule.allowExtraRules !== false) {
            for (const [extraIndex, extraRule] of activeRules.entries()) {
              if (extraIndex === matchedIndex) continue;
              if (extraRule.applyOnUnmatchedRetry === false) continue;
              const extraStripped = extraRule.strip(retryBody);
              if (!extraStripped) continue;
              retryBody = extraStripped;
              appliedRules.push(extraRule);
            }
          }
          logger.info?.(`◀ upstream ${status} [${rule.id}] → 透明重试 (strip + 重发)`, {
            reqId,
            ruleId: rule.id,
            appliedRuleIds: appliedRules.map((r) => r.id),
            originalBytes: body.length,
            strippedBytes: retryBody.length,
          });
          const threadId = selectedHeaderValue(headers, rule.threadIdHeaders ?? DEFAULT_THREAD_ID_HEADERS);
          if (threadId) {
            for (const appliedRule of appliedRules) {
              const model = appliedRule.useUpstreamModel
                ? extractBodyModel(body)
                : clientModel || extractBodyModel(body);
              if (model) appliedRule.onRetry?.(threadId, model);
            }
          }
          const retry = (): void => {
            forward(
              target,
              method,
              path,
              headers,
              retryBody,
              clientRes,
              logger,
              recoveryRules,
              reqId,
              false,
              overrideTarget,
              headerOverride,
              headerDelete,
              responseObserver,
              transformResponse,
              clientModel,
              outboundProxy,
              pathOverride,
              responseToolUseIds,
              threadMintedIdCache,
              requestDeclaredStream,
              beforeRetry,
              forwardLifecycle,
            );
          };
          if (!beforeRetry) {
            retry();
            return;
          }
          const onRetryClientClose = (): void => {
            if (clientRes.writableEnded) return;
            if (forwardLifecycle?.onFailure) {
              notifyForwardLifecycle(() => forwardLifecycle.onFailure?.('client-aborted'));
            }
          };
          clientRes.once('close', onRetryClientClose);
          void beforeRetry().then((proceed) => {
            clientRes.off('close', onRetryClientClose);
            if (!proceed) {
              if (forwardLifecycle?.onFailure) {
                notifyForwardLifecycle(() => forwardLifecycle.onFailure?.('retry-rejected'));
              }
              return;
            }
            if (clientRes.destroyed) {
              if (forwardLifecycle?.onFailure) {
                notifyForwardLifecycle(() => forwardLifecycle.onFailure?.('client-aborted'));
              }
              return;
            }
            retry();
          }).catch(() => {
            clientRes.off('close', onRetryClientClose);
            if (forwardLifecycle?.onFailure) {
              notifyForwardLifecycle(() => forwardLifecycle.onFailure?.(
                clientRes.destroyed && !clientRes.writableEnded ? 'client-aborted' : 'retry-error',
              ));
            }
            logger.error?.('retry dispatch gate failed', { reqId });
            if (clientRes.destroyed || clientRes.headersSent) return;
            clientRes.writeHead(503, {
              'content-type': 'application/json',
              'cache-control': 'no-store',
              'retry-after': '1',
            });
            clientRes.end(JSON.stringify({
              error: { type: 'proxy_error', message: 'dispatch revalidation failed' },
            }));
          });
          return;
        }
        // 无规则命中: 把这条 400 原样回给客户端 + 记 warn 日志 (与下方非 2xx 分支同语义)。
        // responseObserver 在此分支同样要喂到:这条 400 是客户端真实收到的失败,不喂会让
        // 「带 enabled recovery rule 的 400」(如 MODEL_NOT_FOUND) 静默绕过上游错误观察。
        // (规则命中并透明重试的那次 400 刻意不喂——客户端从未见到它,重试结果会正常过观察器。)
        if (responseObserver) {
          try {
            const sink = responseObserver({
              reqId,
              method,
              url: path,
              upstreamBase: formatUpstreamBase(actualTarget),
              status,
              requestHeaders: headers,
              outboundHeaders: actualHeaders,
              responseHeaders: flattenResponseHeaders(upstreamRes.headers),
              requestBody: body,
            }) ?? null;
            // 与流式路径同口径喂原始字节(观察器自己按 content-encoding 解码)。
            sink?.onData?.(errBody);
            sink?.onEnd?.();
          } catch (err) {
            logger.warn?.('responseObserver threw on buffered 400', { reqId, err: String(err) });
          }
        }
        const errorType = extractErrorType(decodedErrBody, String(upstreamRes.headers['content-type'] ?? ''));
        const baseCtx: Record<string, unknown> = {
          reqId,
          status,
          contentType: upstreamRes.headers['content-type'],
          bytes: errBody.length,  // 始终记上游回传的原始(可能压缩后)字节数
        };
        if (errorType) baseCtx.errorType = errorType;
        if (logger.isDebugEnabled?.()) baseCtx.body = dumpBody(decodedErrBody, ERROR_RESPONSE_DUMP_MAX_BYTES);
        logger.warn?.('◀ upstream response (non-2xx)', baseCtx);
        if (forwardLifecycle?.onComplete) {
          notifyForwardLifecycle(() => forwardLifecycle.onComplete?.(status));
        }
        const recoveryCode = activeRules
          .filter((rule) => rule.matches(decodedText))
          .map((rule) => rule.unrecoverableCode?.(body))
          .find((code) => !!code);
        if (recoveryCode) {
          // The vendor rejected the preserved compaction blob. Return a stable
          // machine-readable error; never delete the blob or silently lose history.
          delete respHeaders['content-encoding'];
          delete respHeaders['content-length'];
          respHeaders['content-type'] = 'application/json';
          clientRes.writeHead(status, upstreamRes.statusMessage, respHeaders);
          clientRes.end(JSON.stringify({ error: { code: recoveryCode, message: recoveryCode } }));
          return;
        }
        if (!clientRes.headersSent) {
          clientRes.writeHead(status, upstreamRes.statusMessage, respHeaders);
        }
        clientRes.end(errBody);
      });
      upstreamRes.on('error', (err) => failBufferedResponse('error', err));
      // IncomingMessage 在连接被对端提前掐断时可能只发 `aborted`,不一定随后发
      // `error`;两条事件都接入同一个幂等收口。
      upstreamRes.on('aborted', () => failBufferedResponse('aborted'));
      upstreamRes.on('close', () => {
        if (upstreamResponseTerminal !== null || upstreamRes.complete) return;
        failBufferedResponse('close');
      });
      return;
    }

    let observerSink: ResponseObserverSink | null = null;
    if (responseObserver) {
      try {
        observerSink = responseObserver({
          reqId,
          method,
          url: path,
          upstreamBase: formatUpstreamBase(actualTarget),
          status,
          requestHeaders: headers,
          outboundHeaders: actualHeaders,
          responseHeaders: flattenResponseHeaders(upstreamRes.headers),
          requestBody: body,
        }) ?? null;
      } catch (err) {
        observerSink = null;
        logger.warn?.('responseObserver threw on response start', { reqId, err: String(err) });
      }
    }
    const observerData = (chunk: Buffer) => {
      if (!observerSink?.onData) return;
      try {
        observerSink.onData(chunk);
      } catch (err) {
        observerSink = null;
        logger.warn?.('responseObserver threw on data', { reqId, err: String(err) });
      }
    };
    const observerEnd = () => {
      const sink = observerSink;
      observerSink = null;
      if (!sink?.onEnd) return;
      try {
        sink.onEnd();
      } catch (err) {
        logger.warn?.('responseObserver threw on end', { reqId, err: String(err) });
      }
    };
    const observerError = (err: Error) => {
      const sink = observerSink;
      observerSink = null;
      if (!sink?.onError) return;
      try {
        sink.onError(err);
      } catch (observerErr) {
        logger.warn?.('responseObserver threw on error', { reqId, err: String(observerErr) });
      }
    };

    let lastChunkBytes = 0;
    let lastChunkAt: number | null = null;
    const failStreamingResponse = (
      reason: 'error' | 'aborted' | 'close',
      rawError?: unknown,
    ): void => {
      const isPendingTransformFailure =
        upstreamResponseTerminal === 'end' && pendingResponseTransforms.size > 0;
      if (upstreamResponseTerminal !== null && !isPendingTransformFailure) return;
      if (isPendingTransformFailure) pendingResponseTransforms.clear();
      upstreamResponseTerminal = reason;
      // 客户端主动停止是预期的取消路径,不应再通知 observer 为上游故障。
      if (clientAborted || clientRes.destroyed) return;
      const err = rawError instanceof Error
        ? rawError
        : new Error(rawError === undefined
          ? `upstream response ${reason} before completion`
          : String(rawError));
      if (forwardLifecycle?.onFailure) {
        const failure: ForwardLifecycleFailure =
          reason === 'close' ? 'response-closed' : `response-${reason}`;
        notifyForwardLifecycle(() =>
          forwardLifecycle.onFailure?.(failure, status),
        );
      }
      observerError(err);
      logger.error?.('upstream response stream error', {
        reqId,
        method,
        // query 可能携带供应商签名或 token;生命周期日志只保留 pathname。
        path: upstreamPathname,
        status,
        err: String(err),
        reason,
        bytes: totalBytes,
        lastChunkBytes,
        lastChunkAt,
      });
      finishClientAfterUpstreamFailure(err);
    };
    failActiveResponse = (err) => failStreamingResponse('error', err);

    // kimi 撞车 id 的响应流改名(仅当请求历史带铸造形态 id 且响应是 SSE 才接管;
    // 否则保持字节级 pipe,与扩展前一致)。observer 仍吃上游原始字节(计数/错误体
    // 收集语义不变),CLI 客户端拿到的是改名后的流。
    // 必须在 writeHead 前判定:改名会改变 body 长度,上游 content-length 必须删掉,
    // 否则客户端按旧值读取 → 截断(GPT-5.5 review 第 5 轮 P1,本地 fake upstream
    // 复现确认)。
    // 压缩 SSE(gzip/br)不接管:改写器按明文换行切行,压缩字节会漏改甚至误改;
    // 压缩流下保持字节透传(不删 content-length,客户端自行解压),与扩展前一致
    // (Greptile review)。identity 是合法的「不压缩」编码,不视为压缩(Greptile
    // review P1,否则明文 SSE 被误跳过改写)。
    const contentType = String(upstreamRes.headers['content-type'] ?? '').trim().toLowerCase();
    const isSse = contentType.startsWith('text/event-stream');
    const contentEncoding = String(upstreamRes.headers['content-encoding'] ?? '')
      .trim()
      .toLowerCase();
    const isCompressed = contentEncoding !== '' && contentEncoding !== 'identity';
    // Codex subscription HTTP fallback can omit Content-Type on a valid SSE response.
    // Infer only an absent type, after a complete data event; never override an explicit MIME type.
    const canInferSse = requestDeclaredStream && contentType === '' && !isCompressed;
    let toolUseIdRewrite: ToolUseIdRewriteTransform | null = null;
    if (responseToolUseIds && (isSse || canInferSse) && !isCompressed) {
      // 压缩 SSE(gzip/br)不改写: 字节按明文换行切分会漏改/误改, 保持透传
      // (Greptile 指出此路径撞车 id 不设防; 但 LLM 流式响应不 gzip, 实测链路
      // 均明文 SSE, 属理论场景)。为压缩流做解压-改写-重压收益趋零、风险高,
      // 不做; 压缩透传的撞车 id 不会污染明文转录, 下一轮明文请求仍由缓存拦截)。
      delete respHeaders['content-length'];
      // 响应流改写涉及线程缓存读(onObserved 写 / sharedSeen 读),二者必须用同一
      // thread id,否则并发流 A 写入的 id 流 B 读不到,共享缓存检查形同虚设。
      const streamThreadId = selectedHeaderValue(headers, STABLE_THREAD_ID_HEADERS) ?? '';
      const rewriter = new ToolUseIdDedupeRewriter(
        responseToolUseIds,
        (from, to) => {
          logger.info?.('⇄ renamed duplicate tool_use id in response stream (kimi mint collision)', {
            reqId,
            from,
            to,
          });
        },
        // 每个 streamed id(含 fresh 非碰撞路径)都进线程缓存:rewind/中断让下一
        // 请求体不含该 id 时,缓存仍能拦截重铸。只记录 rename 产物会漏掉
        // fresh id 首次出现即被 rewind 的场景(codex-connector review:
        // Persist every streamed tool ID in the thread cache)。
        (observed) => {
          if (streamThreadId && threadMintedIdCache) {
            addThreadMintedId(threadMintedIdCache, streamThreadId, observed);
          }
        },
        // 共享缓存实时检查:同一 thread 的并发响应流(如同步 subagent)各自持有本
        // rewriter, 都从请求开始快照构建 —— 若快照都空, 流 A 放行并缓存 Bash_210
        // 后, 流 B 仍当 fresh 放行, CLI 追加重复 id 重新引入腐蚀。resolve 时实时查
        // 线程缓存: 别处已见 → 按碰撞改名(codex-connector P1: Check the live cache
        // before accepting fresh IDs)。JS 单线程事件循环保证同 tick 内 check-then-
        // add 原子; 跨 tick 的并发流由共享缓存拦截。
        (id) => (streamThreadId && threadMintedIdCache
          ? (threadMintedIdCache.get(streamThreadId)?.has(id) ?? false)
          : false),
      );
      toolUseIdRewrite = new ToolUseIdRewriteTransform(rewriter);
      toolUseIdRewrite.on('error', (err) => failStreamingResponse('error', err));
    }

    // ── 流式请求的成功响应有效性门(#2242)──────────────────────────────
    // 请求显式声明 stream:true 时,2xx 响应不再「先 writeHead 再 pipe」:上游或
    // 网关产生的**正常结束的空 2xx / 非 SSE 2xx / 零事件 SSE** 会被客户端(Claude
    // Code)当成 "empty or malformed response (HTTP 200)" 而无法分类重试。此时把
    // writeHead 延迟到确认合法流才提交 —— 明文 SSE 扫到首个 event:/data: 行提交,
    // 压缩 SSE 无法扫行、收到首字节即提交(空 2xx 仍被 end 分支拦);上游干净结束
    // 仍未提交 → 结构化 502(proxy_error + code)。已提交后的截断继续走既有连接
    // 失败语义(finishClientAfterUpstreamFailure → destroy),不补成正常结束。
    // 只约束显式流式请求:非流式 JSON 响应照旧字节透传,零行为变化。
    const gateStreamValidity = requestDeclaredStream && status >= 200 && status < 300;
    // 合法 Anthropic SSE 的首个事件必然远早于此(首行即 event: message_start);
    // 上限只为封顶「持续输出无事件垃圾」时的内存与延迟。缺 MIME 的 Responses
    // 回退流必须等到完整事件才能确认,response.created 会回显长 instructions,
    // 所以仅在已确认 SSE 前缀后使用独立且仍有界的首事件预算。
    const STREAM_GATE_PENDING_CAP_BYTES = 64 * 1024;
    const STREAM_GATE_INFERRED_EVENT_CAP_BYTES = 8 * 1024 * 1024;
    const SSE_EVENT_MARKER_RE = /(^|\r?\n)(event|data):/;
    const SSE_PREFIX_RE = /^\uFEFF?(?:(?:|:[^\r\n]*)\r?\n)*(?:event|data):/;
    const SSE_DATA_FIELD_RE = /(?:^\uFEFF?|\r?\n)data:/;
    let streamGateCommitted = false;
    const pendingChunks: Buffer[] = [];
    let pendingBytes = 0;
    let pendingText = '';
    let inferredSseEventStart = 0;
    let inferredSseBoundarySearchOffset = 0;
    const commitStreamResponse = (): void => {
      if (streamGateCommitted || upstreamFailureHandled || clientAborted || clientRes.destroyed) return;
      // Resolve the final MIME before constructing an adapter, and construct it
      // before committing 200. Invalid or cancelled streams never reach adapters.
      let responseBodyTransform: Transform | null = null;
      if (transformResponse && status >= 200 && status < 300) {
        try {
          responseBodyTransform = transformResponse({
            reqId,
            method,
            url: path,
            upstreamBase: formatUpstreamBase(actualTarget),
            status,
            requestHeaders: headers,
            outboundHeaders: actualHeaders,
            responseHeaders: flattenResponseHeaders(respHeaders),
            requestBody: body,
          }) ?? null;
        } catch (err) {
          upstreamResponseTerminal = 'error';
          const responseError = err instanceof Error ? err : new Error(String(err));
          observerError(responseError);
          upstreamRes.resume();
          finishClientAfterUpstreamFailure(
            responseError,
            `upstream response cannot be adapted safely: ${String(err)}`,
            'response_transform_unavailable',
          );
          return;
        }
      }
      if (responseBodyTransform) {
        delete respHeaders['content-length'];
        responseBodyTransform.on('error', (err) => failStreamingResponse('error', err));
      }
      streamGateCommitted = true;
      clientRes.writeHead(status, upstreamRes.statusMessage, respHeaders);
      const responseTransforms = [responseBodyTransform, toolUseIdRewrite]
        .filter((value): value is Transform => value !== null);
      for (const transform of responseTransforms) {
        pendingResponseTransforms.add(transform);
        const settle = () => pendingResponseTransforms.delete(transform);
        transform.once('end', settle);
      }
      const dest = responseTransforms[0] ?? clientRes;
      // 门控期间积累的待发字节(非门控路径恒为空)先写出,再切回字节级 pipe ——
      // pipe 是 SSE 零延迟的命脉('data' 监听只做计数+错误体收集,不影响流)。
      for (const chunk of pendingChunks) dest.write(chunk);
      pendingChunks.length = 0;
      pendingText = '';
      if (responseTransforms.length > 0) {
        // 客户端断开 / 上游故障收口时把 transform 一并拆掉,避免上游继续灌进无消费者的流。
        clientRes.on('close', () => responseTransforms.forEach((transform) => transform.destroy()));
        upstreamRes.pipe(responseTransforms[0]);
        for (let index = 0; index < responseTransforms.length; index += 1) {
          responseTransforms[index].pipe(responseTransforms[index + 1] ?? clientRes);
        }
      } else {
        upstreamRes.pipe(clientRes);
      }
    };
    if (!gateStreamValidity) {
      commitStreamResponse();
      if (upstreamFailureHandled) return;
    }

    /** 未提交状态下把无效流转成结构化 502(观察器按上游真实终态另行收口)。 */
    const rejectInvalidStreamResponse = (code: string, detail: Record<string, unknown>): void => {
      logger.warn?.('◀ invalid success response to a streaming request → 502', {
        reqId,
        method,
        path: upstreamPathname,
        status,
        code,
        contentType: upstreamRes.headers['content-type'],
        contentEncoding: upstreamRes.headers['content-encoding'],
        ...detail,
      });
      finishClientAfterUpstreamFailure(
        new Error(`invalid streaming response (${code})`),
        `upstream returned an invalid success response to a streaming request (${code})`,
        code,
      );
    };

    // 收 body: 总字节始终累加;status >= 400 时额外收集前 ERROR_RESPONSE_DUMP_MAX_BYTES
    // 字节做 dump 用。2xx 路径只做计数, 无内存压力。
    // 错误响应的 status 在 'response' 事件就拿到了,这里直接判断要不要开收集器。
    // 终态 SSE 事件探测:仅明文 2xx SSE(压缩流无法按行扫描,保持原有断开即失败语义)。
    // 匹配 `event: <终态>` 行或 data JSON 的顶层 `"type":"<终态>"`(JSON 字符串内的引号
    // 必然被转义,正文内容不会误命中);保留上一 chunk 的尾巴以覆盖跨 chunk 截断。
    const scanTerminalSseEvent = (isSse || canInferSse) && !isCompressed && status >= 200 && status < 300;
    // terminalSseEventSeen 仅在终态事件完整经过(其后出现空行结束符)后为真:
    // 事件被拆成两段发送时,第一段命中标记不代表事件已转发完,此时取消仍按断开处理。
    let terminalSseEventSeen = false;
    let terminalSseMarkerSeen = false;
    // 以换行起头:首个 chunk 开头即视为行首。
    let terminalSseScanTail = '\n';
    const scanChunkForTerminalSseEvent = (chunk: Buffer): void => {
      if (!scanTerminalSseEvent || terminalSseEventSeen) return;
      const text = terminalSseScanTail + chunk.toString('latin1');
      let rest = text;
      if (!terminalSseMarkerSeen) {
        const match = SSE_TERMINAL_EVENT_RE.exec(text);
        if (!match) {
          terminalSseScanTail = text.slice(-SSE_TERMINAL_SCAN_TAIL_CHARS);
          return;
        }
        terminalSseMarkerSeen = true;
        rest = text.slice(match.index + match[0].length);
      }
      if (SSE_EVENT_END_RE.test(rest)) {
        terminalSseEventSeen = true;
        terminalSseScanTail = '';
        return;
      }
      // 空行结束符可能跨 chunk,保留最后 3 个字符。
      terminalSseScanTail = rest.slice(-3);
    };
    completeAfterTerminalSseEvent = () => {
      if (!terminalSseEventSeen || !streamGateCommitted || upstreamResponseTerminal !== null) return false;
      upstreamResponseTerminal = 'end';
      // transform 随 clientRes close 一起被 destroy,不会再 emit 'end';清掉挂起集合,
      // 让随后 upstream 的 aborted/error 被视为已收口后的迟到事件。
      pendingResponseTransforms.clear();
      observerEnd();
      logger.debug?.('client closed after terminal SSE event — releasing upstream', {
        reqId,
        method,
        path: upstreamPathname,
        status,
        bytes: totalBytes,
      });
      if (forwardLifecycle?.onComplete) {
        notifyForwardLifecycle(() => forwardLifecycle.onComplete?.(status));
      }
      return true;
    };

    const collectErrBody = status >= 400;
    let totalBytes = 0;
    const errBuf: Buffer[] = [];
    let errBufBytes = 0;
    upstreamRes.on('data', (chunk: Buffer) => {
      if (upstreamResponseTerminal !== null) return;
      totalBytes += chunk.length;
      lastChunkBytes = chunk.length;
      lastChunkAt = Date.now();
      observerData(chunk);
      scanChunkForTerminalSseEvent(chunk);
      if (collectErrBody && errBufBytes < ERROR_RESPONSE_DUMP_MAX_BYTES) {
        const remain = ERROR_RESPONSE_DUMP_MAX_BYTES - errBufBytes;
        errBuf.push(chunk.length <= remain ? chunk : chunk.subarray(0, remain));
        errBufBytes += Math.min(chunk.length, remain);
      }
      if (!streamGateCommitted) {
        // 门控中(未提交):积累待发字节并判定是否可提交。
        // 无条件入缓冲:曾用 `pendingBytes < CAP` 做入队条件, 累计恰好落在 CAP
        // (64KiB, 回环读的常见块大小)时, 后续 chunk 只计数不入队 —— 一旦事件
        // 标记在这些 chunk 里到达并提交, 这些字节被永久跳过, 客户端收到中间
        // 有缺口的 200 SSE。任何把 pendingBytes 推过上限的 chunk 都会在该
        // chunk 内提交或按 502 拒收, 缓冲仍有界(至多 CAP + 单 chunk 溢出)。
        pendingChunks.push(chunk);
        pendingBytes += chunk.length;
        if (!isSse) {
          if (canInferSse) {
            pendingText += chunk.toString('utf8');
            // Fast-path the common first field. SSE_PREFIX_RE also admits BOM and
            // comment preambles before that field.
            const hasSsePrefix = pendingText.startsWith('event:')
              || pendingText.startsWith('data:')
              || SSE_PREFIX_RE.test(pendingText);
            // A field prefix alone cannot dispatch an event: wait for a
            // data-containing block to end in a blank line, including across
            // chunks. Scan only newly appended text so a large valid first
            // event cannot turn into repeated whole-buffer work.
            if (hasSsePrefix) {
              while (true) {
                const boundary = [
                  { value: '\n\n', offset: pendingText.indexOf('\n\n', inferredSseBoundarySearchOffset) },
                  { value: '\n\r\n', offset: pendingText.indexOf('\n\r\n', inferredSseBoundarySearchOffset) },
                  { value: '\r\n\n', offset: pendingText.indexOf('\r\n\n', inferredSseBoundarySearchOffset) },
                  { value: '\r\n\r\n', offset: pendingText.indexOf('\r\n\r\n', inferredSseBoundarySearchOffset) },
                ].filter((candidate) => candidate.offset !== -1)
                  .sort((left, right) => left.offset - right.offset)[0];
                if (!boundary) {
                  // Retain three trailing characters to catch a delimiter
                  // split across chunks (\n\n or \r\n\r\n).
                  inferredSseBoundarySearchOffset = Math.max(
                    inferredSseEventStart,
                    pendingText.length - 3,
                  );
                  break;
                }
                const completeEvent = pendingText.slice(inferredSseEventStart, boundary.offset);
                inferredSseEventStart = boundary.offset + boundary.value.length;
                inferredSseBoundarySearchOffset = inferredSseEventStart;
                if (SSE_DATA_FIELD_RE.test(completeEvent)) {
                  respHeaders['content-type'] = 'text/event-stream';
                  commitStreamResponse();
                  return;
                }
              }
            }
            const pendingCap = hasSsePrefix
              ? STREAM_GATE_INFERRED_EVENT_CAP_BYTES
              : STREAM_GATE_PENDING_CAP_BYTES;
            if (pendingBytes > pendingCap) {
              const code = hasSsePrefix
                ? 'sse_inference_limit_exceeded'
                : 'non_sse_stream_response';
              upstreamResponseTerminal = 'error';
              observerError(new Error(`invalid streaming response (${code})`));
              rejectInvalidStreamResponse(code, { bytes: totalBytes });
              upstreamReq.destroy(new Error(`invalid streaming response (${code})`));
              return;
            }
            // A valid prefix is waiting only for the terminator of its first data
            // event; do not also apply the generic non-SSE 64 KiB limit below.
            if (hasSsePrefix) return;
          }
          // 非 SSE 2xx:留在门控里等 end 统一转 502(有界缓冲做 errorType 诊断);
          // 超上限说明上游在持续输出非流式字节,立刻转 502 并切断上游。
          if (pendingBytes > STREAM_GATE_PENDING_CAP_BYTES) {
            upstreamResponseTerminal = 'error';
            observerError(new Error('invalid streaming response (non_sse_stream_response)'));
            rejectInvalidStreamResponse('non_sse_stream_response', { bytes: totalBytes });
            upstreamReq.destroy(new Error('invalid streaming response (non_sse_stream_response)'));
          }
          return;
        }
        if (isCompressed) {
          // 压缩 SSE 无法按明文扫事件行:首字节即提交(与改写器同款不解压原则);
          // 空 2xx 仍由 end 分支拦截。
          commitStreamResponse();
          return;
        }
        // 事件标记均为 ASCII,UTF-8 多字节字符被 chunk 边界截断不影响判定。
        pendingText += chunk.toString('utf8');
        if (SSE_EVENT_MARKER_RE.test(pendingText)) {
          commitStreamResponse();
        } else if (pendingBytes > STREAM_GATE_PENDING_CAP_BYTES) {
          upstreamResponseTerminal = 'error';
          observerError(new Error('invalid streaming response (sse_without_events)'));
          rejectInvalidStreamResponse('sse_without_events', { bytes: totalBytes });
          upstreamReq.destroy(new Error('invalid streaming response (sse_without_events)'));
        }
      }
    });
    upstreamRes.on('end', () => {
      if (upstreamResponseTerminal !== null) return;
      upstreamResponseTerminal = 'end';
      if (clientAborted || clientRes.destroyed || upstreamFailureHandled) return;
      if (!streamGateCommitted) {
        // 上游对流式请求「正常结束」却始终没有产生合法流:空 2xx / 非 SSE 2xx /
        // 零事件 SSE。观察器按上游真实终态收口(end),客户端收结构化 502。
        observerEnd();
        const detail: Record<string, unknown> = { bytes: totalBytes };
        let code: string;
        if (totalBytes === 0) {
          code = 'empty_stream_response';
        } else if (isSse) {
          code = 'sse_without_events';
        } else {
          code = 'non_sse_stream_response';
          const merged = Buffer.concat(pendingChunks);
          const decoded = decodeBodyForLog(merged, String(upstreamRes.headers['content-encoding'] ?? ''));
          const errorType = extractErrorType(decoded, String(upstreamRes.headers['content-type'] ?? ''));
          if (errorType) detail.errorType = errorType;
        }
        rejectInvalidStreamResponse(code, detail);
        if (forwardLifecycle?.onComplete) {
          notifyForwardLifecycle(() => forwardLifecycle.onComplete?.(status));
        }
        return;
      }
      // 4xx/5xx 用 warn 级别冒泡, 默认只记低风险摘要 (status / content-type / bytes / errorType),
      // 完整 body 只在 debug 级别下才进日志 —— 避免 release 把上游错误体里可能回显的请求字段
      // 静默落盘到用户磁盘。debug 关时 isDebugEnabled 提前返 false, 不付 dump 字符串构造开销。
      // grep `cc-proxy.log` 配合 reqId 直接拉出完整往返。
      const baseCtx: Record<string, unknown> = {
        reqId,
        status,
        contentType: upstreamRes.headers['content-type'],
        bytes: totalBytes,
      };
      if (collectErrBody) {
        const merged = Buffer.concat(errBuf);
        // 先按 content-encoding 解压(失败 / 截断会返回 merged 原引用), errorType 与 body dump 共用。
        // 注意: errBuf 最多收 16KB 压缩字节, 截断的 gzip/br 解不开 → decoded === merged → 走原始字节分支。
        const decoded = decodeBodyForLog(merged, String(upstreamRes.headers['content-encoding'] ?? ''));
        const errorType = extractErrorType(decoded, String(upstreamRes.headers['content-type'] ?? ''));
        if (errorType) baseCtx.errorType = errorType;
        if (logger.isDebugEnabled?.()) {
          if (decoded !== merged) {
            // 解压成功 —— 只在拿到完整压缩流时才会成功(截断的 gzip/br 会解压失败回退),
            // 所以这里 decoded 一定是完整错误体, 无需再加 truncated 提示。
            baseCtx.body = dumpBody(decoded, ERROR_RESPONSE_DUMP_MAX_BYTES);
          } else {
            // 未压缩 / 解压失败: 保留原始字节 + (若收集时被 16KB 截断过) 截断提示。
            baseCtx.body = totalBytes > errBufBytes
              ? merged.toString('utf8') + `\n... (truncated, total ${totalBytes} bytes)`
              : dumpBody(merged, ERROR_RESPONSE_DUMP_MAX_BYTES);
          }
        }
        logger.warn?.('◀ upstream response (non-2xx)', baseCtx);
      } else {
        logger.debug?.('◀ upstream response', baseCtx);
      }
      observerEnd();
      if (forwardLifecycle?.onComplete) {
        notifyForwardLifecycle(() => forwardLifecycle.onComplete?.(status));
      }
    });
    upstreamRes.on('error', (err) => failStreamingResponse('error', err));
    upstreamRes.on('aborted', () => failStreamingResponse('aborted'));
    upstreamRes.on('close', () => {
      if (upstreamResponseTerminal !== null || upstreamRes.complete) return;
      failStreamingResponse('close');
    });

  });

  let requestTimedOut = false;
  upstreamReq.on('error', (err) => {
    // 客户端主动断开触发的 destroy 是预期路径:客户端已不在,不写 502、不按
    // 上游故障记 error(上面 'close' 处已记过 info)。
    if (
      clientAborted ||
      upstreamFailureHandled ||
      upstreamResponseTerminal === 'end' ||
      clientRes.destroyed ||
      clientRes.writableEnded
    ) return;
    if (failActiveResponse && upstreamResponseTerminal === null) {
      failActiveResponse(err);
      return;
    }
    if (forwardLifecycle?.onFailure) {
      notifyForwardLifecycle(() =>
        forwardLifecycle.onFailure?.(
          requestTimedOut ? 'request-timeout' : 'request-error',
        ),
      );
    }
    logger.error?.('upstream request failed', {
      reqId,
      err: String(err),
      method,
      path: upstreamPathname,
      ...(outboundProxy ? { viaProxy: outboundProxy.target.url } : {}),
    });
    if (upstreamResponseTerminal === null) upstreamResponseTerminal = 'error';
    const upstreamError = err instanceof Error ? err : new Error(String(err));
    // 回环端口 ECONNREFUSED 单独措辞(本机没监听 ≠ 远端服务故障,#4100);其余逐字不变。
    const failure = describeUpstreamRequestFailure(err, { viaOutboundProxy: Boolean(outboundProxy) });
    finishClientAfterUpstreamFailure(upstreamError, failure.message, failure.code);
  });

  upstreamReq.on('timeout', () => {
    requestTimedOut = true;
    upstreamReq.destroy(new Error('upstream socket timeout'));
  });

  upstreamReq.end(body);
}

/**
 * 启动代理。返回 ProxyHandle —— url 给 host 用作 ANTHROPIC_BASE_URL。
 */
export async function createAnthropicCompatProxy(opts: ProxyOptions): Promise<ProxyHandle> {
  // 默认上游支持函数形态:宿主的网关 endpoint 运行期可变(如登录后由服务端下发),
  // 只在路由没有给出 upstreamOverride / localHandler 时现取。有效值按原文 memoize,
  // endpoint 未变化时零重复 parse;显式供应商路由完全不碰默认上游(热路径,规则 10)。
  const resolveTarget = ((): (() => UpstreamTarget) => {
    const raw = opts.upstream;
    const readRaw = typeof raw === 'function' ? raw : () => raw;
    let cachedRaw: string | null = null;
    let cachedTarget: UpstreamTarget | null = null;
    return () => {
      const current = readRaw()?.trim() ?? '';
      if (!current) throw new Error('default upstream is not configured');
      if (cachedTarget === null || current !== cachedRaw) {
        cachedTarget = parseUpstream(current);
        cachedRaw = current;
      }
      return cachedTarget;
    };
  })();
  const transforms = opts.transformRequest ?? [stripToolUseProviderSpecificFields, stripNonAnthropicFields];
  const logger = opts.logger ?? {};
  const host = opts.host ?? '127.0.0.1';
  const maxBodyBytes = opts.maxRequestBodyBytes ?? DEFAULT_MAX_REQUEST_BODY_BYTES;
  const oversizedRequestCompactor: OversizedRequestCompactor | undefined = opts.oversizedRequestCompactor;
  // Treat a malformed ingress override as unset.  Letting NaN reach the
  // stream guard would make `total > NaN` false forever and turn the bounded
  // ingress into an unbounded read.
  const configuredOversizedIngressBytes = opts.oversizedRequestIngressBytes;
  const oversizedIngressOverride =
    typeof configuredOversizedIngressBytes === 'number'
      && Number.isFinite(configuredOversizedIngressBytes)
      && configuredOversizedIngressBytes > 0
      ? configuredOversizedIngressBytes
      : undefined;
  const oversizedIngressBytes = oversizedRequestCompactor
    ? maxBodyBytes >= MAX_REQUEST_INGRESS_BYTES
      ? maxBodyBytes
      : Math.max(
        maxBodyBytes,
        Math.min(
          MAX_REQUEST_INGRESS_BYTES,
          oversizedIngressOverride ?? maxBodyBytes * 2,
        ),
      )
    : maxBodyBytes;
  // 入站请求 body dump 默认关(仅显式诊断时开):高并发下 64KiB×每请求的日志
  // 构造/落盘/终端镜像会占满宿主 main event loop,详见 ProxyOptions 注释。
  const dumpRequestBody = opts.debugDumpRequestBody === true;

  /**
   * 路由优先级的唯一落点:显式 override 胜出时绝不读取默认上游;只有 decision
   * 没选目标(含仅换 header 的 gateway-key 路由)时才解析默认 endpoint。
   */
  const resolveForwardRoute = (
    decision: RoutingDecision | null,
    res: ServerResponse,
    reqId: number,
  ): {
    target: UpstreamTarget;
    overrideTarget?: UpstreamTarget;
    headerOverride?: Record<string, string>;
    headerDelete?: readonly string[];
    pathOverride?: string;
  } | null => {
    const pathOverride = decision?.pathOverride;
    if (pathOverride !== undefined && !isSafePathOverride(pathOverride)) {
      respondRoutingFailure(
        res,
        logger,
        reqId,
        502,
        'selected request path invalid',
        new Error('routingTransform returned an unsafe pathOverride'),
      );
      return null;
    }
    let overrideTarget: UpstreamTarget | undefined;
    try {
      overrideTarget = decision?.upstreamOverride
        ? parseUpstream(decision.upstreamOverride)
        : undefined;
    } catch (err) {
      respondRoutingFailure(res, logger, reqId, 502, 'selected upstream invalid', err);
      return null;
    }
    let target = overrideTarget;
    try {
      target ??= resolveTarget();
    } catch (err) {
      respondRoutingFailure(res, logger, reqId, 503, 'default upstream unavailable', err);
      return null;
    }
    return {
      target,
      overrideTarget,
      headerOverride: decision?.headerOverride,
      headerDelete: decision?.headerDelete,
      pathOverride,
    };
  };

  /**
   * 凭证出站前的同步门。请求开始(读 body 前)盖章,routing 后、异步 transform /
   * outbound 后、透明重试前再看一眼 owner-boundary:返回 localHandler 则改道本地
   * 响应,不再 forward。hook 抛错也 fail-closed,避免把决策时选中的 headerOverride /
   * 占位 key 打出去。
   */
  const rejectDispatchGeneration = (message: string): RoutingDecision => ({
    localHandler: async ({ res }) => {
      if (res.headersSent || res.destroyed) return;
      res.writeHead(503, {
        'content-type': 'application/json',
        'cache-control': 'no-store',
        'retry-after': '1',
      });
      await new Promise<void>((resolve) => {
        res.end(JSON.stringify({ error: { type: 'proxy_error', message } }), resolve);
      });
    },
  });
  const applyDispatchGate = (
    decision: RoutingDecision | null,
    reqId: number,
    ctx: RequestTransformCtx,
    propagateErrors = false,
  ): RoutingDecision | null => {
    if (decision?.dispatchGenerationValid) {
      try {
        if (!decision.dispatchGenerationValid()) {
          return rejectDispatchGeneration('dispatch generation changed');
        }
      } catch {
        if (propagateErrors) throw new Error('dispatch generation validation failed');
        return rejectDispatchGeneration('dispatch generation validation failed');
      }
    }
    const hook = opts.revalidateBeforeDispatch;
    if (!hook) return decision;
    try {
      return hook(decision, ctx) ?? decision;
    } catch (err) {
      if (propagateErrors) throw err;
      logger.warn?.('revalidateBeforeDispatch threw; refusing dispatch', {
        reqId,
        err: err instanceof Error ? err.message : String(err),
      });
      return {
        localHandler: async ({ res }) => {
          if (res.headersSent) return;
          res.writeHead(503, {
            'content-type': 'application/json',
            'cache-control': 'no-store',
            'retry-after': '1',
          });
          res.end(JSON.stringify({
            error: { type: 'proxy_error', message: 'dispatch revalidation failed' },
          }));
        },
      };
    }
  };

  // 出站代理:CONNECT 隧道 agent 按代理地址缓存(keep-alive 连接池),随 dispose 销毁。
  const outboundAgentPool = new OutboundProxyAgentPool();

  /**
   * per-request 解析本次转发的出站代理。任何一步失败(resolver 抛错 / 返回不支持的
   * 代理形态)都回落直连 —— 代理解析问题绝不能比今天的裸直连更糟。loopback 上游
   * (本机 bridge / gateway / 测试桩)恒直连,不打扰 resolver。
   */
  const resolveOutboundForTarget = async (
    target: UpstreamTarget,
    reqId: number,
  ): Promise<ResolvedOutboundProxy | undefined> => {
    const resolver = opts.resolveOutboundProxy;
    if (!resolver) return undefined;
    if (isLoopbackHostname(target.hostname)) return undefined;
    // IPv6 字面量上游要按 [addr]:port 拼 origin,否则 resolver 拿到非法 URL。
    const upstreamOrigin = `${target.protocol}//${formatAuthority(target.hostname, target.port)}`;
    let raw: string | null | undefined;
    try {
      raw = await resolver(upstreamOrigin);
    } catch (err) {
      logger.warn?.('outbound proxy resolver threw — using direct connection', { reqId, err: String(err) });
      return undefined;
    }
    if (!raw) return undefined;
    const parsed = parseOutboundProxyUrl(raw);
    if (!parsed) {
      // raw 可能带凭证,只记脱敏形态。
      logger.warn?.('unsupported outbound proxy url — using direct connection', {
        reqId,
        proxy: redactProxyUrlForLog(String(raw)),
      });
      return undefined;
    }
    logger.debug?.('using outbound proxy for upstream', {
      reqId,
      proxy: parsed.url,
      upstream: upstreamOrigin,
    });
    const agentKey = outboundProxyAgentKey(parsed, target.protocol);
    if (parsed.kind === 'socks5') {
      // SOCKS5 两种上游都要 agent:https 在隧道上做 TLS,http 直接用隧道当连接。
      return {
        target: parsed,
        agent: outboundAgentPool.get(agentKey, () => (target.protocol === 'https:'
          ? new Socks5HttpsAgent(parsed)
          : new Socks5HttpAgent(parsed))),
      };
    }
    return {
      target: parsed,
      agent: target.protocol === 'https:'
        ? outboundAgentPool.get(agentKey, () => new TunnelingHttpsAgent(parsed))
        : undefined,
    };
  };

  // in-flight 请求计数 —— dispose 时等清零或 2s 超时
  let inflight = 0;
  const inflightSockets = new Set<Socket>();

  // 单调递增 reqId, 用来在 cc-proxy.log 里把"▶ forward / ◀ response / error" 三条
  // 日志归到同一笔请求,grep `reqId=N` 就能拉出完整往返。整数 wrap 后(非常远的未来)
  // 重复也无所谓,只用于读日志的人眼对齐。
  let reqIdSeq = 0;

  const server: Server = createServer(async (req, res) => {
    inflight++;
    const reqId = ++reqIdSeq;
    let responseSettled = false;
    let transformsCompleted = false;
    let transformSettlementNotified = false;
    const notifyTransformSettlement = (): void => {
      if (!responseSettled || !transformsCompleted || transformSettlementNotified) return;
      transformSettlementNotified = true;
      for (const transform of transforms) {
        try {
          transform.onRequestSettled?.(reqId);
        } catch (err) {
          logger.warn?.('request transform settlement hook threw', { reqId, err: String(err) });
        }
      }
    };
    const markResponseSettled = (): void => {
      responseSettled = true;
      notifyTransformSettlement();
    };
    res.once('finish', markResponseSettled);
    res.once('close', () => {
      inflight--;
      markResponseSettled();
    });

    const method = req.method ?? 'GET';
    const url = req.url ?? '/';
    const headers = flattenRequestHeaders(req.headers);
    const requestCtx: RequestTransformCtx = { reqId, method, url, headers };
    const threadId = selectedHeaderValue(headers, STABLE_THREAD_ID_HEADERS) ?? '';
    const contentType = headers['content-type'] ?? '';
    let recoverOversized: ReturnType<NonNullable<ProxyOptions['oversizedRequestRecovery']>> = null;
    // Capture the owner before receiving bytes. Compressed/opaque bodies retain
    // their existing behavior; recovery must never interpret compressed JSON.
    if (contentType.toLowerCase().startsWith('application/json') && !req.headers['content-encoding']) {
      try { recoverOversized = opts.oversizedRequestRecovery?.(requestCtx) ?? null; }
      catch { /* No stable owner: retain the existing bounded request path. */ }
    }
    let requestGuard: ReturnType<NonNullable<ProxyOptions['requestGuard']>>;
    try {
      requestGuard = opts.requestGuard?.(requestCtx) ?? null;
      if (requestGuard) {
        headers['accept-encoding'] = 'identity';
        installResponseGuard(res, () => res.statusCode >= 400
          ? new PassThrough() // Native clients treat HTTP failures as errors, never executable output.
          : requestGuard!.response(res.getHeaders()), error => {
          logger.warn?.('response guard rejected upstream payload', { reqId, err: String(error) });
        });
      }
    } catch {
      res.writeHead(403); res.end(); req.resume(); return;
    }

    // The compactor only understands JSON request histories.  Keep the normal
    // hard limit for other media types so enabling it cannot accidentally make
    // binary/form uploads consume the larger ingress window.
    const requestIngressBytes =
      oversizedRequestCompactor && contentType.toLowerCase().startsWith('application/json')
        ? oversizedIngressBytes
        : maxBodyBytes;

    // 请求一开始就盖章:collectRequestBody 是第一段 await,拖到 routingTransform
    // 会把 body 上传期间完成的 owner 切换当成「起始」scope。
    let decision: RoutingDecision | null = applyDispatchGate(null, reqId, requestCtx);
    const beforeRetry = async (): Promise<boolean> => {
      const gated = applyDispatchGate(decision, reqId, requestCtx, true);
      if (gated?.localHandler) {
        await runLocalHandler(
          gated.localHandler,
          { rawBody: Buffer.alloc(0), parsedBody: undefined, ctx: requestCtx, res },
          logger,
          reqId,
        );
        return false;
      }
      return true;
    };
    if (decision?.localHandler) {
      if (method === 'POST' || method === 'PUT' || method === 'PATCH') {
        await drainRequest(req);
      }
      await runLocalHandler(
        decision.localHandler,
        { rawBody: Buffer.alloc(0), parsedBody: undefined, ctx: requestCtx, res },
        logger,
        reqId,
      );
      return;
    }

    // 非 POST / 没 body(GET / HEAD / DELETE 等)→ 不收集 stream,但仍跑一次路由决策:
    // 这类请求没有 body,routingTransform 以 `undefined` body 调用,可据 method/url/headers 路由
    // 控制面请求(典型: codex models-manager 的 `GET /models` 轮询)。transform 对 undefined body
    // 应自行短路返回 null(= 默认上游 + 透传 headers,向后兼容)。
    if (method !== 'POST' && method !== 'PUT' && method !== 'PATCH') {
      if (opts.routingTransform) {
        try {
          const maybeDecision = opts.routingTransform(undefined, requestCtx);
          decision = isPromiseLike<RoutingDecision | null>(maybeDecision)
            ? await maybeDecision
            : maybeDecision;
        } catch (err) {
          logger.warn?.('routingTransform threw, using default upstream', { reqId, err: String(err) });
        }
      }
      decision = applyDispatchGate(decision, reqId, requestCtx);
      // 本地 handler 命中:不转发上游,由 handler 直接写回响应(见 LocalRequestHandler 契约)。
      if (decision?.localHandler) {
        logger.debug?.('▶ inbound request from client', { reqId, method, upstreamBase: 'local-handler', url, bytes: 0 });
        await runLocalHandler(
          decision.localHandler,
          { rawBody: Buffer.alloc(0), parsedBody: undefined, ctx: requestCtx, res },
          logger,
          reqId,
        );
        return;
      }
      const route = resolveForwardRoute(decision, res, reqId);
      if (!route) return;
      if (logger.isDebugEnabled?.()) {
        logger.debug?.('▶ inbound request from client', {
          reqId,
          method,
          upstreamBase: formatUpstreamBase(route.target),
          url,
          bytes: 0,
        });
      }
      const outbound = await resolveOutboundForTarget(route.target, reqId);
      decision = applyDispatchGate(decision, reqId, requestCtx);
      if (decision?.localHandler) {
        await runLocalHandler(
          decision.localHandler,
          { rawBody: Buffer.alloc(0), parsedBody: undefined, ctx: requestCtx, res },
          logger,
          reqId,
        );
        return;
      }
      forward(
        route.target,
        method,
        url,
        headers,
        Buffer.alloc(0),
        res,
        logger,
        opts.recoveryRules ?? [],
        reqId,
        true,
        route.overrideTarget,
        route.headerOverride,
        route.headerDelete,
        opts.responseObserver,
        opts.transformResponse,
        '',
        outbound,
        route.pathOverride,
        undefined,
        undefined,
        false,
        beforeRetry,
        guardForwardLifecycleObserver(decision?.forwardLifecycle),
      );
      return;
    }

    // Content-Length 预检: 声明就超限的直接 413,不让客户端白传几十 MB 后再失败
    // (reqwest/hyper 对缓冲 body 必带 content-length,codex 正常都命中这条快路径;
    // 只有 chunked 上传才落到 collectRequestBody 的流式守卫)。
    // 注意读原始 req.headers —— flattenRequestHeaders 会剥掉 content-length(转发时重算)。
    const declaredBytes = Number(req.headers['content-length'] ?? '');
    if (!recoverOversized && Number.isFinite(declaredBytes) && declaredBytes > requestIngressBytes) {
      respondRequestTooLarge({
        req, res, logger, reqId, method, url, headers,
        limitBytes: maxBodyBytes,
        declaredBytes,
        receivedBytes: 0,
      });
      return;
    }

    let rawBody: Buffer;
    const recoveryAbort = new AbortController();
    const abortRecovery = () => recoveryAbort.abort();
    res.once('close', abortRecovery);
    try {
      rawBody = recoverOversized
        ? await collectRecoverableBody(req, maxBodyBytes, async body => {
            try {
              const recovered = await recoverOversized!(body, maxBodyBytes);
              if (recovered) logger.info?.('oversized attachments preserved outside request', {
                reqId, originalBytes: body.bytes, recoveredBytes: recovered.length,
              });
              return recovered;
            } catch (error) {
              if (error instanceof Error && error.message === 'RECOVERY_STORAGE_EXHAUSTED') throw error;
              // Do not leak paths, payloads or credentials in recovery errors.
              logger.warn?.('oversized attachment recovery failed', { reqId });
              return null;
            }
          }, recoveryAbort.signal)
        : await collectRequestBody(req, requestIngressBytes);
    } catch (err) {
      const msg = err instanceof Error ? err.message : String(err);
      if (msg === 'REQUEST_TOO_LARGE' || msg === 'RECOVERY_STORAGE_EXHAUSTED') {
        respondRequestTooLarge({
          req, res, logger, reqId, method, url, headers,
          limitBytes: maxBodyBytes,
          reason: msg === 'RECOVERY_STORAGE_EXHAUSTED' ? 'attachment_recovery_storage_exhausted' : 'request_body_too_large',
          declaredBytes: null,
          receivedBytes: (err as { receivedBytes?: number }).receivedBytes ?? 0,
        });
        return;
      }
      logger.warn?.('failed to read request body', { reqId, err: msg });
      res.writeHead(400);
      res.end();
      return;
    } finally {
      res.off('close', abortRecovery);
    }

    if (requestGuard) {
      try { rawBody = requestGuard.transformBody(rawBody); headers['content-length'] = String(rawBody.length); }
      catch { res.destroy(); return; }
    }

    // 路由决策: 基于**原始** body(transform 链改写前)判路由 —— 能看到上游看不到的原始字段
    // (例: 去前缀前的 codex/ model id)。decision 的 override 传给 forward, 默认不 override。
    // 提前到 ▶ inbound 日志**之前**计算: 路由只依赖 rawBody / headers / contentType,与下方
    // runTransforms 的输出无关,提前是安全的; 这样 inbound 日志能直接打出本请求**最终**发往的
    // upstream(订阅直连 api.anthropic.com / 走网关 endpoint),而非静态默认上游。
    let rawParsed: unknown = undefined;
    const jsonRequest = contentType.toLowerCase().startsWith('application/json');
    const routeOpaqueRequest = !jsonRequest && opts.routeOpaqueRequestBody?.(requestCtx) === true;
    if (opts.routingTransform && (jsonRequest || routeOpaqueRequest)) {
      try {
        if (jsonRequest) rawParsed = JSON.parse(rawBody.toString('utf8'));
      } catch {
        // Some native clients (notably PI's ChatGPT adapter) send compressed
        // JSON while keeping content-type=application/json. Header/path based
        // routing must still run; the selected local handler receives rawBody
        // and can forward it byte-for-byte without parsing.
      }
      try {
        const maybeDecision = opts.routingTransform(rawParsed, requestCtx);
        decision = isPromiseLike<RoutingDecision | null>(maybeDecision)
          ? await maybeDecision
          : maybeDecision;
      } catch (err) {
        logger.warn?.('routingTransform threw, using default upstream', { reqId, err: String(err) });
      }
    }
    decision = applyDispatchGate(decision, reqId, requestCtx);

    // 本地 handler 命中:不转发上游、不跑 transform 链,由 handler 直接消费(协议翻译场景)。
    // parsedBody 复用路由阶段的解析结果,不二次 parse。
    if (decision?.localHandler) {
      // PI native subscription handlers also receive provider-native JSON and
      // can carry the same accumulated vision history as forwarded requests.
      // Apply the bounded compactor before the local-handler hard-limit check;
      // non-JSON or unparseable bodies still retain the historical 413 path.
      let localRawBody = rawBody;
      let localParsedBody = rawParsed;
      if (rawBody.length > maxBodyBytes && oversizedRequestCompactor) {
        const originalLocalBodyBytes = rawBody.length;
        const compactStartedAt = Date.now();
        let oversizedParsed: unknown = rawParsed;
        if (oversizedParsed === undefined && jsonRequest) {
          try {
            oversizedParsed = JSON.parse(rawBody.toString('utf8'));
          } catch {
            oversizedParsed = undefined;
          }
        }
        if (oversizedParsed !== undefined) {
          try {
            const compacted = oversizedRequestCompactor(oversizedParsed, requestCtx, maxBodyBytes);
            const compactedBody = isPromiseLike<unknown | null>(compacted)
              ? await compacted
              : compacted;
            if (compactedBody !== null && compactedBody !== undefined) {
              const serialized = JSON.stringify(compactedBody);
              if (typeof serialized !== 'string') throw new Error('compactor returned a non-serializable body');
              localRawBody = Buffer.from(serialized, 'utf8');
              // Do not retain the original oversized Buffer through local
              // handler execution; compaction already produced the bytes the
              // handler will consume.
              rawBody = localRawBody;
              localParsedBody = compactedBody;
              logger.info?.('oversized request body compacted before local dispatch', {
                reqId,
                originalBytes: originalLocalBodyBytes,
                compactedBytes: localRawBody.length,
                compactionMs: Date.now() - compactStartedAt,
              });
            }
          } catch (err) {
            logger.warn?.('oversized request compactor failed; enforcing hard limit', {
              reqId,
              originalBytes: originalLocalBodyBytes,
              compactionMs: Date.now() - compactStartedAt,
              err: String(err),
            });
          }
        }
      }
      if (localRawBody.length > maxBodyBytes) {
        respondRequestTooLarge({
          req, res, logger, reqId, method, url, headers,
          limitBytes: maxBodyBytes,
          declaredBytes: Number.isFinite(declaredBytes) ? declaredBytes : null,
          receivedBytes: localRawBody.length,
        });
        return;
      }
      if (logger.isDebugEnabled?.()) {
        logger.debug?.('▶ inbound request from client', {
          reqId,
          method,
          upstreamBase: 'local-handler',
          url,
          bytes: localRawBody.length,
          ...(dumpRequestBody ? { body: dumpBody(localRawBody, DEBUG_REQUEST_DUMP_MAX_BYTES) } : {}),
        });
      }
      await runLocalHandler(
        decision.localHandler,
        { rawBody: localRawBody, parsedBody: localParsedBody, ctx: requestCtx, res },
        logger,
        reqId,
      );
      return;
    }
    const route = resolveForwardRoute(decision, res, reqId);
    if (!route) return;

    const debugOn = logger.isDebugEnabled?.() ?? false;
    if (debugOn) {
      logger.debug?.('▶ inbound request from client', {
        reqId,
        method,
        // 本请求**最终**发往的 upstream(per-request override 后), 不是静态默认上游 ——
        // = api.anthropic.com 即走订阅直连; = 网关 endpoint 即走网关。
        upstreamBase: formatUpstreamBase(route.target),
        url,
        bytes: rawBody.length,
        ...(dumpRequestBody ? { body: dumpBody(rawBody, DEBUG_REQUEST_DUMP_MAX_BYTES) } : {}),
      });
    }

    // transform 链的 ctx 附带最终上游(override 已生效):按目标上游做兼容改写的
    // transform 据此判断去向,不必在 host 侧复刻路由逻辑。
    const transformCtx: RequestTransformCtx = {
      ...requestCtx,
      upstreamBase: formatUpstreamBase(route.target),
    };
    const originalRawBodyBytes = rawBody.length;
    let bodyForTransforms = rawBody;
    let parsedForTransforms: unknown = undefined;
    if (rawBody.length > maxBodyBytes && oversizedRequestCompactor) {
      const compactStartedAt = Date.now();
      let oversizedParsed: unknown = rawParsed;
      if (oversizedParsed === undefined && jsonRequest) {
        try {
          oversizedParsed = JSON.parse(rawBody.toString('utf8'));
        } catch {
          oversizedParsed = undefined;
        }
      }
      if (oversizedParsed !== undefined) {
        // Reuse the parsed object even when the image compactor is a no-op;
        // this avoids a second JSON.parse for the regular transform chain.
        parsedForTransforms = oversizedParsed;
        try {
          const compacted = oversizedRequestCompactor(oversizedParsed, transformCtx, maxBodyBytes);
          const compactedBody = isPromiseLike<unknown | null>(compacted)
            ? await compacted
            : compacted;
          if (compactedBody !== null && compactedBody !== undefined) {
            const serialized = JSON.stringify(compactedBody);
            if (typeof serialized !== 'string') throw new Error('compactor returned a non-serializable body');
            bodyForTransforms = Buffer.from(serialized, 'utf8');
            parsedForTransforms = compactedBody;
            // No later stage needs the pre-compaction bytes. Releasing that
            // reference avoids retaining two large Buffers through forwarding.
            rawBody = bodyForTransforms;
            logger.info?.('oversized request body compacted before forwarding', {
              reqId,
              originalBytes: originalRawBodyBytes,
              compactedBytes: bodyForTransforms.length,
              compactionMs: Date.now() - compactStartedAt,
            });
          }
        } catch (err) {
          logger.warn?.('oversized request compactor failed; enforcing hard limit', {
            reqId,
            originalBytes: originalRawBodyBytes,
            compactionMs: Date.now() - compactStartedAt,
            err: String(err),
          });
        }
      }
    }
    let transformed: Buffer | null;
    try {
      const bypassTransforms =
        opts.bypassRequestTransforms?.(rawParsed ?? parsedForTransforms, transformCtx) === true;
      transformed = bypassTransforms
        ? null
        : await runTransforms(
            bodyForTransforms,
            contentType,
            transforms,
            transformCtx,
            logger,
            parsedForTransforms,
          );
      if (decision?.transformRequestBody) {
        const rewritten = await decision.transformRequestBody(
          transformed ?? bodyForTransforms,
          transformCtx,
        );
        transformed = rewritten.body;
        if (rewritten.contentType) {
          route.headerOverride = { ...route.headerOverride, 'content-type': rewritten.contentType };
        }
      }
    } catch (err) {
      transformsCompleted = true;
      notifyTransformSettlement();
      logger.warn?.('request transform rejected request', { reqId, err: String(err) });
      res.writeHead(502, { 'content-type': 'application/json' });
      res.end(JSON.stringify({
        error: {
          type: 'proxy_error',
          message: 'request could not be transformed safely',
        },
      }));
      return;
    }
    transformsCompleted = true;
    notifyTransformSettlement();
    let outBody = transformed ?? bodyForTransforms;
    if (requestGuard) {
      // Compatibility transforms may reintroduce provider-hosted tools. Apply
      // the same frozen policy at the final outbound boundary as well.
      try { outBody = requestGuard.transformBody(outBody, transformCtx); }
      catch { res.destroy(); return; }
    }
    if (outBody.length > maxBodyBytes) {
      respondRequestTooLarge({
        req, res, logger, reqId, method, url, headers,
        limitBytes: maxBodyBytes,
        declaredBytes: Number.isFinite(declaredBytes) ? declaredBytes : null,
        receivedBytes: outBody.length,
      });
      return;
    }

    let parsedForRewrite: unknown = rawParsed ?? parsedForTransforms;
    if (parsedForRewrite === undefined && jsonRequest) {
      try {
        parsedForRewrite = JSON.parse(rawBody.toString('utf8'));
      } catch {
        parsedForRewrite = undefined;
      }
    }
    // 请求是否显式声明流式(#2242 有效性门的启用判据)。复用上方解析结果,
    // 非 JSON / 未声明 → false,响应路径保持字节级透传不变。
    const requestDeclaredStream =
      isRecord(parsedForRewrite) && parsedForRewrite.stream === true;
    const requestedIds = collectToolUseIdsForResponseRewrite(parsedForRewrite);
    // 全新/刚归一化的 kimi 会话,请求体可能还没有任何铸造形态 id(历史缺席),
    // 但模型仍会铸 minted id —— 用请求体 model 判定 kimi,确保首 fresh id 也
    // 被接管记录(codex-connector review: Cache first streamed Kimi tool IDs)。
    // Coding Plan 的 k3 / k3.1-pro 等 ID 不带 kimi 前缀,小数版本也必须命中。
    const isKimiRequest =
      decision?.compatibilityProfiles !== undefined
        ? decision.compatibilityProfiles.includes('kimi-tool-ids-v1')
        : isRecord(parsedForRewrite) && typeof parsedForRewrite.model === 'string'
        ? /(^|[/_-])(kimi|k3(?:\.\d+)?)([/_-]|$)/i.test(parsedForRewrite.model)
        : false;

    // per-thread 已见 id 缓存(跨请求并入 usedIds):rewind / 中断 / CLI 压缩会让
    // 历史撞车 id 缺席于某个请求体,若只从请求体建 usedIds,该 id 重铸时 proxy
    // 认作「新 id」放行,转录出现重复 → 下轮 ensureToolResultPairing 丢弃 → 请求
    // 体更缺 → 自激循环(codex-connector review P1)。缓存让本线程内见过的 minted
    // 形态 id 持续设防。副作用:rewind 后 kimi 本可安全复用的旧号被改名(无害,
    // _dupN 后缀不影响语义)。
    //
    // 注意:缓存读取**不能**依赖 requestedIds 非空 —— rewind 后请求体恰恰
    // 可能不含任何铸造 id(历史缺席),而缓存里留有上次见过的撞车 id,这正
    // 是缓存存在的意义。请求体无铸造 id 但缓存非空时,用缓存建 usedIds 设防。
    let responseToolUseIds: Set<string> | null = null;
    if (threadId) {
      const cache = threadMintedIdCache.get(threadId);
      if (requestedIds) {
        responseToolUseIds = requestedIds;
        // 缓存里本线程见过但缺席当前请求体的撞车 id 也必须并入 —— rewind 后
        // 请求体可能只含部分铸造 id,漏掉这些会让 kimi 重铸同号时被当新 id
        // 放行(codex-connector review: Merge cached tool IDs into rewrite seeds)。
        if (cache && cache.size > 0) {
          for (const id of cache) responseToolUseIds.add(id);
        }
        for (const id of requestedIds) addThreadMintedId(threadMintedIdCache, threadId, id);
      } else if (cache && cache.size > 0) {
        responseToolUseIds = new Set(cache);
      } else if (isKimiRequest) {
        // 全新 kimi 会话:空种子集接管响应流,onObserved 记录首个 streamed id。
        responseToolUseIds = new Set<string>();
      }
    } else {
      responseToolUseIds = requestedIds;
    }

    if (transformed) {
      logger.debug?.('⇄ transformed request body', {
        reqId,
        method,
        url,
        originalBytes: originalRawBodyBytes,
        outBytes: outBody.length,
      });
    }

    const outbound = await resolveOutboundForTarget(route.target, reqId);
    decision = applyDispatchGate(decision, reqId, requestCtx);
    if (decision?.localHandler) {
      await runLocalHandler(
        decision.localHandler,
        { rawBody, parsedBody: rawParsed, ctx: requestCtx, res },
        logger,
        reqId,
      );
      return;
    }

    const forwardLifecycle = guardForwardLifecycleObserver(decision?.forwardLifecycle);

    forward(
      route.target,
      method,
      url,
      headers,
      outBody,
      res,
      logger,
      opts.recoveryRules ?? [],
      reqId,
      true,
      route.overrideTarget,
      route.headerOverride,
      route.headerDelete,
      opts.responseObserver,
      opts.transformResponse,
      extractBodyModel(rawBody),
      outbound,
      route.pathOverride,
      responseToolUseIds,
      threadMintedIdCache,
      requestDeclaredStream,
      beforeRetry,
      forwardLifecycle,
      recoverOversized
        ? (body, signal) => collectRecoverableBody(
            Readable.from([body]),
            body.length - 1,
            (spooled) => recoverOversized!({ ...spooled, upstreamRejected: true }, body.length - 1),
            signal,
          )
        : undefined,
    );
  });

  // 同时占用的 WS 数(正在握手 + 已建立),仅用于日志观测,不参与拒绝策略。
  // 容量控制属于 Codex / 上游职责;proxy 自设上限会凭空制造本地 503,让 Cindy 的
  // at-capacity 体验反而劣于同版本 Codex。刻意不并入 inflight —— WS 是长连接,
  // 计入会让 dispose 的清零等待永不满足。
  // per-thread 已见 tool_use id 缓存(跨请求),供响应流撞车改名的 usedIds 并入。
  // 有界见 addThreadMintedId(Copilot review 防内存 DoS)。
  const threadMintedIdCache = new Map<string, Set<string>>();

  let liveWebSockets = 0;
  interface LiveWebSocket {
    readonly threadId: string;
    readonly clientSocket: Socket;
    upstreamSocket: Socket | null;
    closeForHostFallback(): void;
  }
  const liveWebSocketConnections = new Set<LiveWebSocket>();
  const provenWebSocketHandshakes = new Map<string, ProvenWebSocketHandshake>();

  /**
   * WebSocket upgrade 透传。
   *
   * **为什么需要**: bundled codex 的 Responses transport 自己负责 startup prewarm、
   * 连接复用、重试与 HTTP fallback。proxy 不支持 upgrade 时只能给 provider 设
   * supports_websockets=false,Cindy 就无法使用与同版本 Codex 相同的原生传输。
   * 正常路径只做透明隧道,不解释或改写 at-capacity;宿主显式开启时,仅对已有真实 101
   * 证明的单 thread 重连在本地保活并回探同一上游,避免瞬时断网被误判成 HTTP fallback。
   *
   * **刻意只做 socket 级透传, 不解析 WS 帧**: requestTransform / routingTransform 的
   * body 改写、recoveryRules、responseObserver 全部依赖读写一次性请求体, 而 WS 帧里
   * 没有这个东西。需要那些能力的会话应由宿主在 resolveWebSocketUpstream 返回 null,
   * 走 426 退回 HTTP(见 types.ts 该字段注释), 而不是在这里半解析。
   *
   * inflight 计数刻意不加: WS 是长连接, 计入会让 dispose 的清零等待永不满足。socket
   * 本身由下面的 'connection' 监听收录进 inflightSockets, dispose 时统一 destroy。
   */
  server.on('upgrade', (req, clientSocket: Socket, head: Buffer) => {
    const reqId = ++reqIdSeq;
    const headers = flattenRequestHeaders(req.headers);
    const url = req.url ?? '/';
    const resolveWsUpstream = opts.resolveWebSocketUpstream;

    // 不配 resolver = 本 proxy 不接 upgrade(Claude Code 侧就是这样, 行为与扩展前一致)。
    if (!resolveWsUpstream) {
      logger.debug?.('upgrade rejected — resolveWebSocketUpstream not configured', { reqId, url });
      writeUpgradeFailure(clientSocket, 501, 'Not Implemented');
      return;
    }
    // 只接 websocket; 其它 upgrade 协议(h2c 等)不猜语义。
    if ((headers.upgrade ?? '').toLowerCase() !== 'websocket') {
      logger.debug?.('upgrade rejected — not a websocket upgrade', {
        reqId, url, upgrade: headers.upgrade ?? '',
      });
      writeUpgradeFailure(clientSocket, 501, 'Not Implemented');
      return;
    }
    let upstreamUrl: string | null;
    try {
      upstreamUrl = resolveWsUpstream({ url, headers });
    } catch (err) {
      logger.error?.('resolveWebSocketUpstream threw', {
        reqId,
        url,
        err: String(err),
      });
      writeUpgradeFailure(clientSocket, 500, 'Internal Server Error');
      return;
    }
    if (!upstreamUrl) {
      // **426 而不是 501**: 这是 codex 唯一认作"退回 HTTP transport"的状态码, 且它的
      // 降级是 session 级(一次即稳定)。宿主返回 null 的语义是"这个会话走 HTTP 更合适"
      // (需要 recoveryRules / responseObserver), 不是拒绝服务 —— 用 501 会让 codex
      // 直接报错而不是降级。
      logger.debug?.('upgrade declined by host — signalling 426 to fall back to HTTP', { reqId, url });
      writeUpgradeFailure(clientSocket, 426, 'Upgrade Required');
      return;
    }
    if (opts.webSocketTransforms) delete headers['sec-websocket-extensions'];
    const resolvedWebSocketUpstream = upstreamUrl;

    let target: UpstreamTarget;
    try {
      target = parseUpstream(resolvedWebSocketUpstream);
    } catch (err) {
      logger.error?.('resolveWebSocketUpstream returned an unusable url', {
        reqId,
        err: String(err),
      });
      writeUpgradeFailure(clientSocket, 500, 'Internal Server Error');
      return;
    }

    // 异步出网前开始计数,让日志同时覆盖 pending 与 established。
    liveWebSockets += 1;

    let established = false;
    let settled = false;
    let upstreamReqForEarlyClose: ClientRequest | null = null;
    let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
    let handshakeTimer: ReturnType<typeof setTimeout> | null = null;
    const clearHandshakeTimer = (): void => {
      if (handshakeTimer === null) return;
      clearTimeout(handshakeTimer);
      handshakeTimer = null;
    };
    let upstreamAttempt = 0;
    let removeAuthorizationListener: (() => void) | undefined;
    let authorizeWebSocket: (() => boolean) | undefined;
    let preparedTransforms: (() => { outbound: Transform; inbound: Transform }) | undefined;
    let onUpgradeFailure: ((status: number, body: string) => Promise<void>) | undefined;
    // bundled Codex 0.145.0 的 startup-prewarm / reconnect 都带稳定 thread-id。
    // 真正无 scope 的非 Codex / 通用 socket 仍保留空值隔离;不能把泛用的
    // x-client-request-id 当作稳定 recovery key,误逐出其它 thread 的连接。
    const threadId = selectedHeaderValue(headers, STABLE_THREAD_ID_HEADERS);
    const provenHandshake = opts.retryProvenWebSocketUpgrades && threadId
      ? provenWebSocketHandshakes.get(threadId)
      : undefined;
    const localHandshake = provenHandshake
      && provenWebSocketHandshakeMatchesRequest(
        provenHandshake,
        resolvedWebSocketUpstream,
        url,
        headers,
      )
      ? serializeProvenWebSocketHandshake(headers, provenHandshake)
      : null;
    const locallyAcceptedForReconnect = localHandshake !== null;
    const connection: LiveWebSocket = {
      threadId,
      clientSocket,
      upstreamSocket: null,
      closeForHostFallback: () => {
        settle('host-http-fallback');
        connection.upstreamSocket?.destroy();
        clientSocket.destroy();
        if (!established) upstreamReqForEarlyClose?.destroy();
      },
    };
    const settle = (why: string, err?: Error): void => {
      if (settled) return;
      settled = true;
      clearHandshakeTimer();
      removeAuthorizationListener?.();
      if (reconnectTimer !== null) {
        clearTimeout(reconnectTimer);
        reconnectTimer = null;
      }
      liveWebSockets -= 1;
      liveWebSocketConnections.delete(connection);
      logger.info?.('◀ websocket closed', {
        reqId,
        threadId: threadId || undefined,
        why,
        live: liveWebSockets,
        err: err ? String(err) : undefined,
      });
    };
    liveWebSocketConnections.add(connection);

    // client 可能在 resolveOutboundForTarget 尚未返回时就离开。close 必须立即归还预占
    // 槽位;若上游请求已经创建,同时终止它,避免无人接收的握手继续占网络资源。
    // Before 101 there is no pipe to propagate FIN. An abandoned handshake
    // can otherwise stay half-open until its upstream eventually responds.
    clientSocket.on('end', () => {
      if (established || settled) return;
      settle('client-end-before-upgrade');
      upstreamReqForEarlyClose?.destroy();
      clientSocket.end();
    });
    clientSocket.on('close', () => {
      settle('client-close');
      if (!established) {
        upstreamReqForEarlyClose?.destroy();
        return;
      }
      // 正常 FIN 会先触发 end/readableEnded,pipe 负责把写侧冲完并结束上游;
      // destroy/RST 则只有 close,Node 不会把 source close 传播成 destination end。
      // 后一种必须显式拆上游,否则 dispose 或客户端崩溃会留下远端 WS 与事件循环。
      if (!clientSocket.readableEnded) connection.upstreamSocket?.destroy();
    });
    // resolver / PAC 解析本身是异步的。error listener 必须在 await 之前安装,否则
    // Windows 代理切换、网络瞬断等事件若恰好落在这个窗口,Socket 的未监听 error
    // 可能上抛到进程级。upstream request 尚未创建时只记账;创建后同时终止它。
    clientSocket.on('error', (err) => {
      if (established) return;
      logger.debug?.('client socket error before upgrade established', { reqId, err: String(err) });
      settle('client-error', err);
      upstreamReqForEarlyClose?.destroy();
    });

    if (locallyAcceptedForReconnect) {
      // 暂停读取会把客户端后续 WS 帧留在有界的 socket/TCP 缓冲中;上游恢复并完成真实 101
      // 后再 resume。不能让用户态数组无限积累离线期间的数据。
      clientSocket.pause();
      try {
        clientSocket.write(localHandshake);
        logger.info?.('websocket reconnect held by local proxy', {
          reqId,
          threadId,
        });
      } catch (err) {
        settle('local-reconnect-handshake-error', err instanceof Error ? err : undefined);
        clientSocket.destroy();
        return;
      }
    }

    const scheduleReconnectAttempt = (why: string, err?: Error): void => {
      if (!locallyAcceptedForReconnect || settled || clientSocket.destroyed) return;
      clearHandshakeTimer();
      upstreamReqForEarlyClose = null;
      const exponent = Math.max(0, Math.min(upstreamAttempt - 1, 8));
      const delayMs = Math.min(
        WEBSOCKET_RECONNECT_INITIAL_DELAY_MS * (2 ** exponent),
        WEBSOCKET_RECONNECT_MAX_DELAY_MS,
      );
      logger.warn?.('websocket reconnect upstream unavailable; retrying in proxy', {
        reqId,
        threadId,
        attempt: upstreamAttempt,
        delayMs,
        why,
        err: err ? String(err) : undefined,
      });
      reconnectTimer = setTimeout(() => {
        reconnectTimer = null;
        startUpstreamAttempt();
      }, delayMs);
      reconnectTimer.unref?.();
    };

    function startUpstreamAttempt(): void {
      upstreamAttempt += 1;
      void (async () => {
        const outbound = await resolveOutboundForTarget(target, reqId);
        if (settled || clientSocket.destroyed) return;
        let outboundHeaders = headers;
        if (opts.prepareWebSocketRequest) {
          const prepared = await opts.prepareWebSocketRequest({ url, headers });
          if (settled || clientSocket.destroyed) return;
          const revoke = (): void => {
            settle('host-authorization-revoked');
            upstreamReqForEarlyClose?.destroy();
            connection.upstreamSocket?.destroy();
            clientSocket.destroy();
          };
          if (prepared.signal.aborted) { revoke(); return; }
          removeAuthorizationListener?.();
          prepared.signal.addEventListener('abort', revoke, { once: true });
          removeAuthorizationListener = () => prepared.signal.removeEventListener('abort', revoke);
          outboundHeaders = prepared.headers;
          authorizeWebSocket = prepared.authorize;
          onUpgradeFailure = prepared.onUpgradeFailure;
          if (prepared.transforms && !opts.webSocketTransforms) throw new Error('WEBSOCKET_TRANSFORMS_REQUIRE_UNCOMPRESSED_NEGOTIATION');
          preparedTransforms = prepared.transforms;
        }
        let attemptSettled = false;

      // codex 构造 WS URL 的规则是 `base_url + "/responses"`。宿主给 codex 的 base_url
      // 常带 `/v1` 前缀(OpenAI 兼容风格), 而真上游(如 chatgpt.com/backend-api/codex)
      // 下**没有这一段** —— 带上去直接 403, 且上游对 path 严格、不会降级(2026-07-30
      // 实测: .../codex/responses 拿到 101, .../codex/v1/responses 拿到 403)。所以这里
      // 剥掉入站 path 的 /v1, 再拼上游自己的 basePath。
      const inboundPath = url.replace(/^\/v1(?=\/|$)/, '') || '/';
      const upstreamPath =
        `${target.basePath}${inboundPath.startsWith('/') ? inboundPath : `/${inboundPath}`}`;
      const reqFn = target.protocol === 'https:' ? httpsRequest : httpRequest;

      // WS 是低频事件(一个 session 通常只建一两条长连接), 用 info 让它落盘 ——
      // 这条链路出问题时"有没有建连 / 谁先关的 / 关在哪一步"是唯一有用的线索,
      // debug 级别在打包版里拿不到。
      logger.info?.('▶ upgrade to upstream', {
        reqId,
        upstreamBase: formatUpstreamBase(target),
        path: upstreamPath,
        viaProxy: outbound ? outbound.target.url : 'direct',
      });

      // flattenRequestHeaders 刻意剥掉 hop-by-hop header(connection / keep-alive /
      // transfer-encoding …), 对普通转发是对的 —— 但 **WebSocket 握手必须带
      // `Connection: Upgrade`**(RFC 6455), 缺了上游不会回 101。所以这里显式补回
      // 握手必需的两个头; Sec-WebSocket-* 不属于 hop-by-hop, 已在 headers 里。
      const upstreamReq = reqFn({
        hostname: target.hostname,
        port: target.port,
        method: req.method ?? 'GET',
        path: upstreamPath,
        headers: {
          ...outboundHeaders,
          host: formatHostHeader(target.hostname, target.port, target.protocol),
          connection: 'Upgrade',
          upgrade: 'websocket',
        },
        ...(outbound ? { agent: outbound.agent } : {}),
      });
      upstreamReqForEarlyClose = upstreamReq;

      const failTransientAttempt = (
        why: 'handshake-timeout' | 'upstream-error',
        status: 502 | 504,
        message: 'Bad Gateway' | 'Gateway Timeout',
        err?: Error,
      ): void => {
        if (attemptSettled || established || settled) return;
        attemptSettled = true;
        clearHandshakeTimer();
        if (locallyAcceptedForReconnect) {
          scheduleReconnectAttempt(why, err);
          return;
        }
        settle(why, err);
        writeUpgradeFailure(clientSocket, status, message);
      };

      // Request/socket idle timeouts start after connection and reset on traffic.
      // Bound the entire network handshake, including DNS/TCP/TLS, instead.
      // This deadline is removed on 101; it never limits model inference.
      handshakeTimer = setTimeout(() => {
        if (attemptSettled || established || settled) return;
        logger.warn?.('upgrade handshake timed out', { reqId, path: upstreamPath });
        failTransientAttempt('handshake-timeout', 504, 'Gateway Timeout');
        upstreamReq.destroy();
      }, WEBSOCKET_UPGRADE_TIMEOUT_MS);
      handshakeTimer.unref?.();

      upstreamReq.on('upgrade', (upstreamRes, upstreamSocket: Socket, upstreamHead: Buffer) => {
        if (attemptSettled) {
          upstreamSocket.destroy();
          return;
        }
        attemptSettled = true;
        clearHandshakeTimer();
        upstreamReqForEarlyClose = null;
        // 解除握手超时(长连接不能被它杀掉)。
        upstreamReq.setTimeout(0);
        upstreamSocket.setTimeout(0);

        // 客户端可能恰好在上游 101 到达前断开。此时 close listener 已经 settle,
        // 或 socket 已 destroy 但 close 事件尚未派发;都不能再把上游连接接入隧道。
        if (settled || clientSocket.destroyed || upstreamSocket.destroyed) {
          settle('upgrade-raced-with-close');
          upstreamSocket.destroy();
          clientSocket.destroy();
          return;
        }

        if (
          locallyAcceptedForReconnect
          && provenHandshake
          && !provenWebSocketHandshakeMatchesResponse(provenHandshake, upstreamRes)
        ) {
          // 本地已经按旧协商结果回复过 101,真实上游若给出不同子协议/扩展,继续裸 pipe 会
          // 破坏帧语义。清掉证明并断开;Codex 下一次连接回到完整透明握手。
          provenWebSocketHandshakes.delete(threadId);
          settle('reconnect-negotiation-changed');
          upstreamSocket.destroy();
          clientSocket.destroy();
          return;
        }

        if (opts.webSocketTransforms && upstreamRes.headers['sec-websocket-extensions']) {
          settle('unexpected-websocket-extension'); upstreamSocket.destroy(); clientSocket.destroy(); return;
        }
        established = true;
        connection.upstreamSocket = upstreamSocket;
        if (opts.retryProvenWebSocketUpgrades) {
          rememberProvenWebSocketHandshake(
            provenWebSocketHandshakes,
            threadId,
            createProvenWebSocketHandshake(
              resolvedWebSocketUpstream,
              url,
              headers,
              upstreamRes,
            ),
          );
        }

        // **正常关闭只记账, 绝不 destroy 对端**。
        // pipe 的默认 end:true 已经负责把 FIN 传下去, 并且会先冲完缓冲里未写出的数据;
        // 在 close 里主动 destroy 另一端会**立即丢弃这些缓冲** —— 实测表现为上游发完
        // 最后一帧就 close 时, `response.completed` 被截掉: 模型文本已经完整输出
        // (response.output_text.done 到了), 但 turn 永不收口, UI 卡在「正在生成」。
        upstreamSocket.on('close', () => {
          settle('upstream-close');
          // 与下游同理:正常 FIN 交给 pipe 冲完;只有无 end 的异常销毁才强拆对端。
          if (!upstreamSocket.readableEnded) clientSocket.destroy();
        });

        // 只有出错才强拆两端 —— 那时缓冲里的数据已经没有意义。
        const abort = (why: string) => (err?: Error): void => {
          settle(why, err);
          upstreamSocket.destroy();
          clientSocket.destroy();
        };
        clientSocket.on('error', abort('client-error'));
        upstreamSocket.on('error', abort('upstream-error'));

        let guarded: ReturnType<NonNullable<ProxyOptions['webSocketTransforms']>> | undefined;
        try { guarded = preparedTransforms?.() ?? opts.webSocketTransforms?.({ url, headers }); }
        catch { abort('websocket-guard-failed')(); return; }
        if (guarded) {
          guarded.outbound.on('error', abort('websocket-outbound-rejected'));
          guarded.inbound.on('error', abort('websocket-inbound-rejected'));
          clientSocket.once('close', () => { guarded?.outbound.destroy(); guarded?.inbound.destroy(); });
          guarded.outbound.pipe(upstreamSocket);
          guarded.inbound.pipe(clientSocket);
        }
        // Check the live host route even on a reused socket. This gate preserves
        // compressed/fragmented bytes and does not buffer model context.
        const authorizationGate = authorizeWebSocket ? new Transform({
          transform(chunk, _encoding, callback) {
            try {
              if (!authorizeWebSocket!()) { callback(new Error('WEBSOCKET_AUTHORIZATION_CHANGED')); return; }
              callback(null, chunk);
            } catch (error) {
              callback(error instanceof Error ? error : new Error('WEBSOCKET_AUTHORIZATION_CHANGED'));
            }
          },
        }) : undefined;
        if (authorizationGate) {
          authorizationGate.on('error', abort('host-authorization-changed'));
          clientSocket.once('close', () => authorizationGate.destroy());
          authorizationGate.pipe(guarded?.outbound ?? upstreamSocket);
        }
        const outboundStream = authorizationGate ?? guarded?.outbound ?? upstreamSocket;
        try {
          if (!locallyAcceptedForReconnect) {
            clientSocket.write(serializeResponseHead(upstreamRes));
          }
          // 双向把握手时已缓冲的首包补上, 再对接。
          if (upstreamHead?.length) (guarded?.inbound ?? clientSocket).write(upstreamHead);
          if (head?.length) outboundStream.write(head);

          clientSocket.setNoDelay(true);
          upstreamSocket.setNoDelay(true);
        } catch (err) {
          abort('handshake-forward-error')(
            err instanceof Error ? err : new Error(String(err)),
          );
          return;
        }

        upstreamSocket.pipe(guarded?.inbound ?? clientSocket);
        clientSocket.pipe(outboundStream);
        if (locallyAcceptedForReconnect) clientSocket.resume();
        logger.info?.('◀ websocket established', {
          reqId, status: upstreamRes.statusCode, live: liveWebSockets,
          upstreamHeadBytes: upstreamHead?.length ?? 0,
          clientHeadBytes: head?.length ?? 0,
        });
      });

      // 上游没给 101 而是普通响应(403 / 426 / 503 等): **连 body 一起原样回写**。
      // 只写状态行会丢掉 body 里的错误详情, 排查时无从下手; 而 426 更必须准确透传 ——
      // 它是 codex 退回 HTTP transport 的信号。
      upstreamReq.on('response', (upstreamRes) => {
        if (attemptSettled) {
          upstreamRes.resume();
          return;
        }
        attemptSettled = true;
        clearHandshakeTimer();
        upstreamReqForEarlyClose = null;
        settle('upstream-refused');
        const status = upstreamRes.statusCode ?? 502;
        if (onUpgradeFailure && (status === 401 || status === 403)) {
          const observe = onUpgradeFailure;
          const chunks: Buffer[] = [];
          let bytes = 0;
          upstreamRes.on('data', (chunk: Buffer) => {
            bytes += chunk.length;
            if (bytes <= 64 * 1024) chunks.push(Buffer.from(chunk));
          });
          upstreamRes.once('end', () => {
            if (bytes <= 64 * 1024) void observe(status, Buffer.concat(chunks).toString('utf8')).catch(() => {});
          });
        }
        logger.warn?.('upstream refused websocket upgrade', {
          reqId,
          status,
          path: upstreamPath,
        });
        upstreamReq.setTimeout(0);
        if (locallyAcceptedForReconnect) {
          // 真实 HTTP 状态不是瞬时建连错误。由于本地已经回复 101,当前 socket 无法再补写
          // HTTP 状态;撤销该 thread 的握手证明并断开,下一次重连走透明路径并保留原状态。
          provenWebSocketHandshakes.delete(threadId);
          upstreamRes.once('error', () => {});
          upstreamRes.resume();
          clientSocket.destroy();
          return;
        }
        if (shouldFallbackToHttpAfterUpgradeResponse(status)) {
          logger.info?.('websocket upgrade unsupported on current path — falling back to HTTP', {
            reqId,
            status,
            path: upstreamPath,
          });
          // 客户端已经只需要 426,仍要消费上游 body 才能复用/释放连接;但 resume
          // 不会吞掉源流 error。代理/WAF 若在 403 body 中途断开,监听并记日志,
          // 避免 IncomingMessage error 上升成进程级未处理异常。
          upstreamRes.once('error', (err) => {
            logger.warn?.('websocket fallback response body failed', {
              reqId,
              status,
              path: upstreamPath,
              err: String(err),
            });
          });
          upstreamRes.resume();
          writeUpgradeFailure(clientSocket, 426, 'Upgrade Required');
          return;
        }
        try {
          // 裸 socket 上**不能沿用上游的 framing 头**: upstreamRes 是 Node 已解码的流
          // (chunked 已经解掉), 原样带 transfer-encoding: chunked 会让客户端拿一段
          // 已解码的数据去解 chunk。改成 connection: close, 由 EOF 定界。
          clientSocket.write(serializeResponseHead(upstreamRes, {
            dropHeaders: ['transfer-encoding', 'content-length', 'connection', 'keep-alive'],
            extraHeaders: { Connection: 'close' },
          }));
        } catch {
          // socket 可能已废; body pipe 下面照常尝试, 失败由 socket 自己的 error 收口。
        }
        // pipe 不会把源流 error 自动传播给目标 socket。上游若在 401/429/5xx body
        // 中途断开,必须自己结束客户端写侧;否则 Codex 会一直等 EOF,未监听的
        // IncomingMessage error 还可能升级为进程级异常。用 end 而不是立即 destroy,
        // 先尽量刷出已经收到的状态行和错误详情。
        let refusalBodyTerminal = false;
        const failRefusalBody = (
          reason: 'error' | 'aborted' | 'close',
          err?: Error,
        ): void => {
          if (refusalBodyTerminal) return;
          refusalBodyTerminal = true;
          logger.warn?.('websocket refusal response body failed', {
            reqId,
            status,
            path: upstreamPath,
            reason,
            err: err ? String(err) : undefined,
          });
          if (!clientSocket.destroyed) {
            clientSocket.end(() => clientSocket.destroy());
          }
        };
        upstreamRes.once('end', () => {
          refusalBodyTerminal = true;
        });
        upstreamRes.once('error', (err) => failRefusalBody('error', err));
        // IncomingMessage 对提前断流的事件形态取决于 Node/代理/平台:可能有 error,
        // 也可能只有 aborted 或 incomplete close。三路必须汇入同一个幂等收口,
        // 否则裸 socket 没有 EOF,Codex 会一直等拒绝响应结束。
        upstreamRes.once('aborted', () => failRefusalBody('aborted'));
        upstreamRes.once('close', () => {
          if (refusalBodyTerminal || upstreamRes.complete) return;
          failRefusalBody('close');
        });
        upstreamRes.pipe(clientSocket);
      });

      upstreamReq.on('error', (err) => {
        logger.warn?.('upgrade upstream request failed', {
          reqId,
          err: String(err),
        });
        failTransientAttempt('upstream-error', 502, 'Bad Gateway', err);
      });

      upstreamReq.end();
      })().catch((err: unknown) => {
        // 与 respondRoutingFailure 同款理由: 不让 async handler 的 rejection 漂成
        // process-level unhandledRejection。
        logger.error?.('websocket upgrade handler threw', { reqId, err: String(err) });
        if (established || settled) return;
        const error = err instanceof Error ? err : new Error(String(err));
        if (locallyAcceptedForReconnect) {
          scheduleReconnectAttempt('handler-error', error);
          return;
        }
        settle('handler-error', error);
        writeUpgradeFailure(clientSocket, 500, 'Internal Server Error');
      });
    }
    startUpstreamAttempt();
  });

  // 跟踪所有底层 socket,dispose 时强制 destroy
  server.on('connection', (socket) => {
    inflightSockets.add(socket);
    socket.on('close', () => inflightSockets.delete(socket));
  });

  const port = await listenOnFetchSafeLoopbackPort(server, host, logger);
  const hostInUrl = host.includes(':') ? `[${host}]` : host;
  const url = `http://${hostInUrl}:${port}`;

  logger.debug?.('anthropic-compat-proxy listening', { url, upstream: opts.upstream });

  const disconnectWebSocketsForThread = (threadId: string): number => {
    const normalized = threadId.trim();
    if (!normalized) return 0;
    const matches = Array.from(liveWebSocketConnections)
      .filter((connection) => connection.threadId === normalized);
    for (const connection of matches) connection.closeForHostFallback();
    return matches.length;
  };

  return {
    url,
    disconnectWebSocketsForThread(threadId) {
      return disconnectWebSocketsForThread(threadId);
    },
    forgetWebSocketStateForThread(threadId) {
      const normalized = threadId.trim();
      if (!normalized) return 0;
      provenWebSocketHandshakes.delete(normalized);
      return disconnectWebSocketsForThread(normalized);
    },
    hasProvenWebSocketForThread(threadId) {
      const normalized = threadId.trim();
      return normalized !== '' && provenWebSocketHandshakes.has(normalized);
    },
    async dispose() {
      logger.debug?.('anthropic-compat-proxy disposing', { inflight });
      // 退出场景: 客户端(Claude Code 子进程)也即将被 SIGTERM, in-flight 请求保留无意义。
      // 立即 destroy 所有 socket → server.close 的 keep-alive 等待立刻满足 → callback
      // 立即触发, 整个 dispose 从 ~2s grace 降到 ~10ms。
      //
      // 副作用: in-flight 请求那一侧 (Claude Code 子进程) 会收 ECONNRESET。bootstrap-electron
      // 注释 (onQuit 'anthropic-compat-proxy' 段) 已显式接受此语义: "session 本来就在 close
      // 路径上, 这种 error 直接被吞, 影响可接受"。
      // 已建立的 WS 上游不属于 server 的入站 socket 集;先显式关闭隧道两端,
      // 避免只 destroy 下游后把远端连接留在事件循环里。
      for (const connection of Array.from(liveWebSocketConnections)) {
        connection.closeForHostFallback();
      }
      for (const s of inflightSockets) {
        try { s.destroy(); } catch { /* no-op */ }
      }
      // 出站代理的 keep-alive 隧道池一并断开,不留空闲 CONNECT 连接。
      outboundAgentPool.destroy();
      await new Promise<void>((resolve) => server.close(() => resolve()));
    },
  };
}