mslxdff 0.1.132 → 0.1.133

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mslxdff",
-  "version": "0.1.132",
+  "version": "0.1.133",
   "description": "测试项目，请勿使用。",
   "type": "module",
   "bin": {

package/src/routes/chat/broadband-handler.js

@@ -25,13 +25,15 @@ export async function handleBroadbandRelay({
   res,
   startedAt,
   plugins,
+  deps = {},
 }) {
-  const bb = await tryBroadbandRelay({ groups, token, model, body, hops, bus, logs, reqId: handlerCtx.reqId, evt, res, mark, perf0, stages });
+  const { createPipeline = createRelayPipeline, tryBroadbandRelay: tryRelay = tryBroadbandRelay } = deps;
+  const bb = await tryRelay({ groups, token, model, body, hops, bus, logs, reqId: handlerCtx.reqId, evt, res, mark, perf0, stages });
   if (!bb) {
     evt("relay-miss", { reqId: handlerCtx.reqId, model });
     return { handled: false };
   }
-  const pipeline = createRelayPipeline({
+  const pipeline = createPipeline({
     relay,
     buildFallbackInfo,
     auto,
@@ -46,7 +48,8 @@ export async function handleBroadbandRelay({
   });
   const isResponse = bb.result && typeof bb.result.status === "number" && typeof bb.result.headers?.get === "function";
   if (isResponse) {
-    await pipeline.execute({ res, upRes: bb.result, body, requested, actual: model, lastErr, via: "broadband", lockModel, useAuto, handlerCtx, mark, perf0, stages, startedAt });
+    const r = await pipeline.execute({ res, upRes: bb.result, body, requested, actual: model, lastErr, via: "broadband", lockModel, useAuto, handlerCtx, mark, perf0, stages, startedAt });
+    if (!r.handled) return { handled: false, upRes: null, lastErr: r.lastErr };
     return { handled: true };
   }
   if (bb.result && typeof bb.result.status === "number") {
@@ -59,7 +62,8 @@ export async function handleBroadbandRelay({
       text: async () => str,
       body: isSSE ? (async function* () { yield Buffer.from(str); })() : null,
     };
-    await pipeline.execute({ res, upRes: fakeRes, body, requested, actual: model, lastErr, via: "broadband-local", lockModel, useAuto, handlerCtx, mark, perf0, stages, startedAt });
+    const r = await pipeline.execute({ res, upRes: fakeRes, body, requested, actual: model, lastErr, via: "broadband-local", lockModel, useAuto, handlerCtx, mark, perf0, stages, startedAt });
+    if (!r.handled) return { handled: false, upRes: null, lastErr: r.lastErr };
     return { handled: true };
   }
   evt("relay-miss", { reqId: handlerCtx.reqId, model });

package/src/routes/chat/exhausted-handler.js

@@ -2,18 +2,23 @@ import { relay } from "../stream.js";
 import { json } from "../helpers.js";
 import { performance } from "node:perf_hooks";
 
-export async function handleExhaustedLocal({ res, body, lastErr, order, handlerCtx, evt, logCall, mark, perf0, stages, done, requested, useAuto }) {
+export async function handleExhaustedLocal({ res, body, lastErr, order, handlerCtx, evt, logCall, mark, perf0, stages, done, requested, useAuto, deps = {} }) {
+  const { relay: relayImpl = relay } = deps;
   const model = lastErr?.model ?? handlerCtx.model;
   evt("exhausted-local", { reqId: handlerCtx.reqId, lastModel: lastErr?.model ?? model, lastStatus: lastErr?.status ?? 502, order });
   logCall(lastErr?.model ?? model, lastErr?.status ?? 502);
   if (lastErr?.upstream) {
     evt("relay-start", { reqId: handlerCtx.reqId, model: lastErr.model, via: "local-exhausted", isStream: Boolean(body.stream) });
-    const out = await relay(res, lastErr.upstream, body, {
+    const out = await relayImpl(res, lastErr.upstream, body, {
       onFirstChunk: (d) => mark(`ttf-${lastErr.model}`),
       onDownstreamAbort: () => evt("client-abort", { reqId: handlerCtx.reqId, model: lastErr.model, totalMs: Math.round(performance.now() - perf0), stages: [...stages] }),
     });
     evt("relay-done", { reqId: handlerCtx.reqId, model: lastErr.model, via: "local-exhausted", status: out.status, ttfMs: out.ttfMs, totalMs: out.totalMs, aborted: out.aborted, interrupted: out.interrupted ?? false, detail: out.detail ?? null });
     evt("result", { reqId: handlerCtx.reqId, model: lastErr.model, status: out.status, via: "local", timing: lastErr.upstream._t ?? null, ttfMs: out.ttfMs, totalMs: out.totalMs, detail: out.detail ?? null });
+    // 最后一站：relay 超时路径不写响应（设计留给上层 failover），这里没有上层，必须自己收尾
+    if (out.timedOut) {
+      json(res, 502, { error: out.detail?.upstreamError ? `upstream error: ${out.detail.upstreamError}` : `stream timed out after ${out.totalMs}ms` });
+    }
     return true;
   }
   evt("result", { reqId: handlerCtx.reqId, model, status: lastErr?.status ?? 502, via: "none", timing: null });
@@ -22,17 +27,22 @@ export async function handleExhaustedLocal({ res, body, lastErr, order, handlerC
   return true;
 }
 
-export async function handleExhaustedAll({ res, body, lastErr, order, requested, handlerCtx, evt, logCall, mark, perf0, stages }) {
+export async function handleExhaustedAll({ res, body, lastErr, order, requested, handlerCtx, evt, logCall, mark, perf0, stages, deps = {} }) {
+  const { relay: relayImpl = relay } = deps;
   evt("exhausted-all", { reqId: handlerCtx.reqId, lastModel: lastErr?.model ?? requested, lastStatus: lastErr?.status ?? 502, order });
   logCall(lastErr?.model ?? requested, lastErr?.status ?? 502);
   if (lastErr?.upstream) {
     evt("relay-start", { reqId: handlerCtx.reqId, model: lastErr.model, via: "local-final", isStream: Boolean(body.stream) });
-    const out = await relay(res, lastErr.upstream, body, {
+    const out = await relayImpl(res, lastErr.upstream, body, {
       onFirstChunk: (d) => mark(`ttf-${lastErr.model}`),
       onDownstreamAbort: () => evt("client-abort", { reqId: handlerCtx.reqId, model: lastErr.model, totalMs: Math.round(performance.now() - perf0), stages: [...stages] }),
     });
     evt("relay-done", { reqId: handlerCtx.reqId, model: lastErr.model, via: "local-final", status: out.status, ttfMs: out.ttfMs, totalMs: out.totalMs, aborted: out.aborted, interrupted: out.interrupted ?? false, detail: out.detail ?? null });
     evt("result", { reqId: handlerCtx.reqId, model: lastErr.model, status: out.status, via: "local", timing: lastErr.upstream._t ?? null, ttfMs: out.ttfMs, totalMs: out.totalMs, detail: out.detail ?? null });
+    // 最后一站：relay 超时路径不写响应，这里没有上层 failover，必须自己收尾
+    if (out.timedOut) {
+      json(res, 502, { error: out.detail?.upstreamError ? `upstream error: ${out.detail.upstreamError}` : `stream timed out after ${out.totalMs}ms` });
+    }
     return true;
   }
   evt("result", { reqId: handlerCtx.reqId, model: lastErr?.model ?? requested, status: lastErr?.status ?? 502, via: "none", timing: null });

package/src/routes/chat/hedge-handler.js

@@ -27,14 +27,16 @@ export async function handleHedge({
   plugins,
   res,
   hedgeDelayMs,
+  deps = {},
 }) {
+  const { createPipeline = createRelayPipeline, hedgedFirstChunkRace: race = hedgedFirstChunkRace } = deps;
   const d = hedgeDelayMs;
   try {
-    const hedged = await hedgedFirstChunkRace({ localUpRes: upRes, peers, handlerCtx, hedgeDelayMs: d, evt });
+    const hedged = await race({ localUpRes: upRes, peers, handlerCtx, hedgeDelayMs: d, evt });
     if (hedged && hedged.winner) {
       if (hedged.winner === "local") {
         const bufferedUpRes = { ...upRes, body: hedged.bufferedBody, headers: upRes.headers, status: upRes.status, _t: upRes._t };
-        const pipeline = createRelayPipeline({
+        const pipeline = createPipeline({
           relay,
           buildFallbackInfo,
           auto,
@@ -72,7 +74,7 @@ export async function handleHedge({
         evt("peer-race-win", { reqId: handlerCtx.reqId, model, winPeer: win.peer.url, winTarget: win.target, latencyMs: win.latencyMs, hedged: true, ttfMs: hedged.ttfMs });
         await peers.recordResult(win.peer.url, { ok: true, latencyMs: win.latencyMs, model: win.target });
         const bufferedPeerRes = { ...win.res, body: hedged.bufferedBody, headers: win.res.headers, status: win.res.status, _t: win.res._t };
-        const pipeline = createRelayPipeline({
+        const pipeline = createPipeline({
           relay,
           buildFallbackInfo,
           auto,
@@ -85,7 +87,7 @@ export async function handleHedge({
           startedAt,
           stages,
         });
-        await pipeline.execute({
+        const r = await pipeline.execute({
           res,
           upRes: bufferedPeerRes,
           body,
@@ -101,6 +103,7 @@ export async function handleHedge({
           stages,
           startedAt,
         });
+        if (!r.handled) return { handled: false, upRes: null, lastErr: r.lastErr };
         return { handled: true };
       }
     }

package/src/routes/chat/peer-handler.js

@@ -22,14 +22,16 @@ export async function handlePeerRelay({
   startedAt,
   plugins,
   res,
+  deps = {},
 }) {
+  const { createPipeline = createRelayPipeline, racePeerCandidates: race = racePeerCandidates } = deps;
   evt("peer-race-start", { reqId: handlerCtx.reqId, model, peers: peers.ordered().length });
   const peerErrors = [];
   const pctx = { ...handlerCtx, peerErrors };
   const win =
-    (await racePeerCandidates(peers.ordered(), pctx)) ||
-    (await racePeerCandidates(peers.orderedByLastError(), pctx)) ||
-    (await racePeerCandidates(peers.coolingByLastError(), pctx));
+    (await race(peers.ordered(), pctx)) ||
+    (await race(peers.orderedByLastError(), pctx)) ||
+    (await race(peers.coolingByLastError(), pctx));
   if (!win) {
     evt("peer-race-lose", { reqId: handlerCtx.reqId, model });
     // 组员全失败：把每个组员的真实返回汇总给调用者（否则只剩一个无信息的 429/502）
@@ -42,7 +44,7 @@ export async function handlePeerRelay({
   evt("peer-race-win", { reqId: handlerCtx.reqId, model, winPeer: win.peer.url, winTarget: win.target, latencyMs: win.latencyMs });
   await peers.recordResult(win.peer.url, { ok: true, latencyMs: win.latencyMs, model: win.target });
 
-  const pipeline = createRelayPipeline({
+  const pipeline = createPipeline({
     relay,
     buildFallbackInfo,
     auto,
@@ -55,7 +57,7 @@ export async function handlePeerRelay({
     startedAt,
     stages,
   });
-  await pipeline.execute({
+  const r = await pipeline.execute({
     res,
     upRes: win.res,
     body,
@@ -71,5 +73,7 @@ export async function handlePeerRelay({
     stages,
     startedAt,
   });
+  // Note: 超时/失败必须把 handled:false 交回上层换候选（丢弃 → 响应永不 end）— 见 .agents/notes/implemented/bug-fix/2026-09-17-relay-first-chunk-gate-real-cancel.md
+  if (!r.handled) return { handled: false, upRes: null, lastErr: r.lastErr };
   return { handled: true };
-}
+}

package/src/routes/chat/relay-pipeline.js

@@ -5,7 +5,7 @@ import { computeMetrics } from "../../metrics.js";
 
 // 唯一/最后候选没有 failover 去向：首块闸门退化为纯"防连接泄漏"，放宽避免误杀慢模型
 // （参考 opencode：zen 通道不设超时；openai responses 硬编码 300s headerTimeout）
-const LAST_CANDIDATE_TIMEOUT_MS = (() => {
+export const LAST_CANDIDATE_TIMEOUT_MS = (() => {
   const n = Number(process.env.MSLXDFF_LAST_CANDIDATE_TIMEOUT_MS);
   return Number.isInteger(n) && n >= 0 ? n : 120_000;
 })();
@@ -60,6 +60,7 @@ export function createRelayPipeline({
     perf0,
     stages: s2,
     startedAt: sa2,
+    streamTimeoutMs: ctxStreamTimeoutMs,
   } = {}) {
     const markFn = m2 || _mark;
     const curStartedAt = sa2 ?? defaultStartedAt ?? Date.now();
@@ -79,13 +80,15 @@ export function createRelayPipeline({
     }
     _evt("relay-start", { reqId, model: actual, via, isStream: Boolean(body?.stream), fallback });
 
-    // 3. relay（唯一/最后候选：无 failover 去向 → 闸门放宽到防泄漏级别）
+    // 3. relay（唯一/最后候选：无 failover 去向 → 闸门放宽到防泄漏级别；显式 streamTimeoutMs 优先）
     const orderLen = handlerCtx?.orderLen;
     const curIdx = handlerCtx?.idx;
     const isLastCandidate =
       Number.isInteger(orderLen) && orderLen > 0 &&
       (orderLen === 1 || (Number.isInteger(curIdx) && curIdx >= orderLen - 1));
-    const streamTimeoutMs = isLastCandidate ? LAST_CANDIDATE_TIMEOUT_MS : C.STREAM_TIMEOUT_MS;
+    const streamTimeoutMs = Number.isInteger(ctxStreamTimeoutMs) && ctxStreamTimeoutMs >= 0
+      ? ctxStreamTimeoutMs
+      : (isLastCandidate ? LAST_CANDIDATE_TIMEOUT_MS : C.STREAM_TIMEOUT_MS);
     const out = await _relay(res, upRes, body, {
       fallback,
       streamTimeoutMs,
@@ -115,11 +118,12 @@ export function createRelayPipeline({
 
     // 5a. 首块超时未写字节 → 回退（显式 timedOut 字段，status 只是 HTTP 语义展示）
     if (out.timedOut === true) {
+      const why = out.detail?.upstreamError ? ` (upstream read error: ${out.detail.upstreamError})` : "";
       if (auto) try { await auto.recordError(actual, { status: 502, slow: true, note: `stream timeout ${streamTimeoutMs}ms` }); } catch {}
-      try { _logError(actual, 502, `stream timeout ${streamTimeoutMs}ms`); } catch {}
+      try { _logError(actual, 502, `stream timeout ${streamTimeoutMs}ms${why}`); } catch {}
       _evt("upstream-error", { reqId, model: actual, status: 502, message: "stream timeout", timing: null });
       _evt("fallback", { reqId, from: actual, to: null, reason: "stream timeout" });
-      return { handled: false, upRes: null, lastErr: { model: actual, upstream: null, status: 502, message: `stream timed out after ${streamTimeoutMs}ms` } };
+      return { handled: false, upRes: null, lastErr: { model: actual, upstream: null, status: 502, message: `stream timed out after ${streamTimeoutMs}ms${why}` } };
     }
 
     // 5b. 中断（stall 超时 / max 流时长）

package/src/routes/chat/via-route-handler.js

@@ -1,4 +1,4 @@
-import { createRelayPipeline } from "./relay-pipeline.js";
+import { createRelayPipeline, LAST_CANDIDATE_TIMEOUT_MS } from "./relay-pipeline.js";
 import { relay, SLOW_TOTAL_MS, STREAM_TIMEOUT_MS, STALL_TIMEOUT_MS, SCORE_STALL_MS } from "../stream.js";
 import { buildFallbackInfo } from "../fallback.js";
 import { getViaRoute } from "../../bench/via-routes.js";
@@ -121,7 +121,7 @@ export async function handleViaRoute({
     startedAt,
     stages,
   });
-  await pipeline.execute({
+  const r = await pipeline.execute({
     res,
     upRes,
     body,
@@ -136,6 +136,9 @@ export async function handleViaRoute({
     perf0,
     stages,
     startedAt,
+    // 借道单路径无第二候选可比：按末位耐心档（默认 120s，MSLXDFF_LAST_CANDIDATE_TIMEOUT_MS 可调/0=不限）
+    streamTimeoutMs: LAST_CANDIDATE_TIMEOUT_MS,
   });
+  if (!r.handled) return { handled: false, upRes: null, lastErr: r.lastErr };
   return { handled: true };
 }

package/src/routes/helpers.js

@@ -19,7 +19,8 @@ export function authorized(req, token) {
 
 export function json(res, status, body) {
   res.statusCode = status;
-  res.setHeader("Content-Type", "application/json");
+  // 已发 headers（如 failover 时前一个候选写过 SSE 注释帧）不可再设，否则抛 ERR_HTTP_HEADERS_SENT
+  try { if (!res.headersSent) res.setHeader("Content-Type", "application/json"); } catch { /* ignore */ }
   res.end(JSON.stringify(body));
 }
 

package/src/routes/stream.js

@@ -20,6 +20,29 @@ function cancelBody(body) {
   } catch { /* ignore */ }
 }
 
+// 注释帧（": keepalive" 等）不是模型输出：不算首块、不解除闸门、不触发超时救回，但照常透传
+function hasPayload(text) {
+  for (const line of String(text).split("\n")) {
+    const t = line.trim();
+    if (!t || t.startsWith(":")) continue;
+    return true;
+  }
+  return false;
+}
+
+// 自持 reader 优先：for-await 会锁定 ReadableStream，使 body.cancel() 必 reject（真流上等于空操作），
+// 超时/断下游要真能掐上游必须走 reader.cancel()
+async function* bodyChunks(body, reader) {
+  if (reader) {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) return;
+      yield value;
+    }
+  }
+  for await (const c of body) yield c;
+}
+
 export const SLOW_TOTAL_MS = (() => {
   const n = Number(process.env.MSLXDFF_SLOW_TOTAL_MS);
   return Number.isInteger(n) && n > 0 ? n : 20_000;
@@ -94,16 +117,26 @@ export async function relay(res, upRes, body, { onFirstChunk, onDownstreamAbort,
     recoveries: 0,
   };
   let prevChunkAt = t0;
+  // 断下游即掐上游：流式分支装配真实取消，非流式保持 no-op
+  let cancelUpstream = () => {};
   const onClose = () => {
     detail.downstreamClosed = true;
-    if (!finishedNormally && onDownstreamAbort) onDownstreamAbort();
+    if (!finishedNormally) {
+      cancelUpstream();
+      if (onDownstreamAbort) onDownstreamAbort();
+    }
   };
   res.on("close", onClose);
 
   if (isStream) {
-    res.setHeader("Content-Type", "text/event-stream");
-    res.setHeader("Cache-Control", "no-cache");
-    res.setHeader("Connection", "keep-alive");
+    // failover 重入时 headers 可能已发（前一个候选只发过 keepalive 注释帧就被掐）——已发则不可再设
+    if (!res.headersSent) {
+      try {
+        res.setHeader("Content-Type", "text/event-stream");
+        res.setHeader("Cache-Control", "no-cache");
+        res.setHeader("Connection", "keep-alive");
+      } catch { /* ignore */ }
+    }
     if (fallback?.fallback) {
       try {
         res.write(`: mslxdff fallback ${fallback.requested_model} -> ${fallback.actual_model} (${fallback.reason})\n`);
@@ -113,10 +146,21 @@ export async function relay(res, upRes, body, { onFirstChunk, onDownstreamAbort,
     if (upRes.body) {
       let first = true;
       let wroteAny = false;
+      let wrotePayload = false; // 真实数据帧（注释帧不算）：决定能否安全 failover
       let timedOut = false;
       let stalled = false;
       let tooLong = false;
       let stallTimer = null;
+      // 自持 reader：超时/断下游时 reader.cancel() 才真的掐得断上游
+      // Note: 闸门真取消 + 注释帧不算首块 + wrotePayload 判据 — 见 .agents/notes/implemented/bug-fix/2026-09-17-relay-first-chunk-gate-real-cancel.md
+      const reader = typeof upRes.body.getReader === "function" ? upRes.body.getReader() : null;
+      let cancelled = false;
+      cancelUpstream = () => {
+        if (cancelled) return;
+        cancelled = true;
+        if (reader) { try { reader.cancel().catch(() => {}); } catch { /* ignore */ } }
+        else cancelBody(upRes.body);
+      };
       let pingTimer = keepaliveMs > 0
         ? setInterval(() => {
             if (wroteAny) return;
@@ -129,7 +173,7 @@ export async function relay(res, upRes, body, { onFirstChunk, onDownstreamAbort,
           ? setTimeout(() => {
               stalled = true;
               detail.exitReason = "stall";
-              cancelBody(upRes.body);
+              cancelUpstream();
             }, STALL_TIMEOUT_MS)
           : null;
       };
@@ -137,18 +181,18 @@ export async function relay(res, upRes, body, { onFirstChunk, onDownstreamAbort,
         ? setTimeout(() => {
             timedOut = true;
             detail.exitReason = "first-timeout";
-            cancelBody(upRes.body);
+            cancelUpstream();
           }, streamTimeoutMs)
         : null;
       const maxTimer = MAX_STREAM_MS
         ? setTimeout(() => {
             tooLong = true;
             detail.exitReason = "max";
-            cancelBody(upRes.body);
+            cancelUpstream();
           }, MAX_STREAM_MS)
         : null;
       try {
-        for await (const chunk of upRes.body) {
+        for await (const chunk of bodyChunks(upRes.body, reader)) {
           const now = performance.now();
           detail.receivedChunks += 1;
           const len = chunk?.length ?? chunk?.byteLength ?? 0;
@@ -159,8 +203,9 @@ export async function relay(res, upRes, body, { onFirstChunk, onDownstreamAbort,
           if (gap > detail.maxGapMs) detail.maxGapMs = gap;
           if (gap > SCORE_STALL_MS) detail.stallHits += 1;
           prevChunkAt = now;
+          const txt = chunkText(chunk);
+          const isPayload = hasPayload(txt);
           try {
-            const txt = chunkText(chunk);
             if (txt.includes("[DONE]")) detail.sawDone = true;
             const m = txt.match(/"finish_reason"\s*:\s*"([^"]+)"/);
             if (m) detail.sawFinishReason = m[1];
@@ -196,9 +241,10 @@ export async function relay(res, upRes, body, { onFirstChunk, onDownstreamAbort,
               } catch {}
             }
           } catch { /* ignore */ }
-          // 首块/空闲超时后上游仍吐出了数据 → 只是慢，不是死：撤销超时判定，照常转发
-          //（cancel 是协作式的，缓冲数据仍会到达；丢掉已到达的数据是纯损失）
-          if (timedOut || stalled) {
+          // 首块/空闲超时后上游仍吐出了真实数据 → 只是慢，不是死：撤销超时判定，照常转发
+          //（cancel 是异步的，竞态窗口内已到达的数据是纯收益；丢掉是纯损失）
+          // 注释帧（keepalive）不算：否则对端只要在发心跳，闸门就永远解除
+          if (isPayload && (timedOut || stalled)) {
             timedOut = false;
             stalled = false;
             detail.recoveries = (detail.recoveries || 0) + 1;
@@ -206,14 +252,14 @@ export async function relay(res, upRes, body, { onFirstChunk, onDownstreamAbort,
             if (firstTimer) { clearTimeout(firstTimer); firstTimer = null; }
           }
           if (timedOut || stalled || tooLong) break;
-          if (first) {
+          if (isPayload && first) {
             first = false;
             ttf = Math.round(now - t0);
             onFirstChunk?.(ttf);
             if (firstTimer) { clearTimeout(firstTimer); firstTimer = null; }
           }
           let outChunk = chunk;
-          if (first === false && fallback?.fallback && wroteAny === false) {
+          if (first === false && fallback?.fallback && wrotePayload === false) {
             try {
               let txt = "";
               if (Buffer.isBuffer(chunk)) txt = chunk.toString("utf8");
@@ -226,16 +272,17 @@ export async function relay(res, upRes, body, { onFirstChunk, onDownstreamAbort,
             } catch {}
           }
           wroteAny = true;
+          if (isPayload) wrotePayload = true;
           detail.wroteChunks += 1;
           detail.wroteBytes += Buffer.isBuffer(outChunk) ? outChunk.length : (outChunk?.length ?? len);
-          res.write(outChunk);
+          try { res.write(outChunk); } catch { /* 下游已断开：onClose 已掐上游 */ }
           armStall();
         }
-        if (!detail.exitReason) detail.exitReason = "normal";
+        if (!detail.exitReason) detail.exitReason = detail.downstreamClosed ? "downstream-closed" : "normal";
       } catch (err) {
         detail.upstreamError = String(err?.message || err).slice(0, 300);
         detail.exitReason = "upstream-error";
-        if (!wroteAny) timedOut = true;
+        if (!wrotePayload) timedOut = true;
         else stalled = true;
       } finally {
         if (firstTimer) clearTimeout(firstTimer);
@@ -243,12 +290,13 @@ export async function relay(res, upRes, body, { onFirstChunk, onDownstreamAbort,
         if (stallTimer) clearTimeout(stallTimer);
         if (pingTimer) clearInterval(pingTimer);
       }
-      if (timedOut && !wroteAny) {
+      // 任一闸门到点且未写出真实数据 → 可安全 failover（注释帧对客户端无意义，不算已响应）
+      if ((timedOut || stalled || tooLong) && !wrotePayload) {
         res.removeListener("close", onClose);
         // Note: 超时是显式字段（timedOut），别再用 status 数值当信号 — 见 .agents/notes/implemented/architecture/2026-09-17-relay-timedout-explicit-and-metrics-seam.md
         return { status: 504, timedOut: true, ttfMs: null, totalMs: Math.round(performance.now() - t0), aborted: true, interrupted: false, detail };
       }
-      if ((stalled || tooLong) && wroteAny) {
+      if ((stalled || tooLong) && wrotePayload) {
         interrupted = true;
         detail.exitReason = detail.exitReason || (stalled ? "stall" : "max");
         res.removeListener("close", onClose);