pi-freeflow 1.32.0 → 1.32.2

package/src/relay.ts

@@ -4,6 +4,7 @@
 
 import { randomUUID } from "node:crypto";
 import { Buffer } from "node:buffer";
+import { Agent } from "undici";
 import { UPSTREAM_HEADER_TIMEOUT_MS } from "./config.ts";
 import { isDebugEnabled, log } from "./logger.ts";
 import {
@@ -23,6 +24,44 @@ import {
 // one warning instead of a wall of identical toasts.
 let lastRollNotify = 0;
 const ROLL_NOTIFY_MS = 5 * 60 * 1_000;
+/********************************************************
+ * Warm client-to-relay dispatcher: one shared undici Agent
+ * with long keep-alive so repeat relay attempts reuse
+ * CONNECT/TLS across hot turns instead of paying a fresh handshake
+ * per attempt. Relay leg only - the direct-to-upstream
+ * fallback keeps the built-in global dispatcher. headersTimeout
+ * reaps wedged tunnels, bodyTimeout 0 disables per-chunk kill
+ * (the 300s total backstop still bounds a turn), connections 50
+ * caps burst spray.
+ *
+ * Compat: an npm undici Agent is rejected as a `dispatcher`
+ * by an older-major global fetch bundled in Node
+ * (`invalid onRequestStart method`, cf. commit 7cbbb37), so
+ * the custom dispatcher attaches only when the bundled
+ * undici major covers the npm major (both 7 here); older
+ * Node keeps the built-in global dispatcher, which already
+ * pools keep-alive.
+ ********************************************************/
+let relayAgent: Agent | null = null;
+/** True when the bundled undici accepts the npm undici 7.x Agent as dispatcher. */
+export const canUseRelayDispatcher =
+	Number((process.versions.undici ?? "0").split(".")[0]) >= 7;
+function getRelayAgent(): Agent {
+	if (!relayAgent) {
+		relayAgent = new Agent({ keepAliveTimeout: 60_000, connectTimeout: 10_000, headersTimeout: 60_000, bodyTimeout: 0, connections: 50 });
+	}
+	return relayAgent;
+}
+/** Extra fetch init for relay-leg attempts; empty when the custom dispatcher is unavailable. */
+function relayLegInit(): { dispatcher?: Agent } {
+	return canUseRelayDispatcher ? { dispatcher: getRelayAgent() } : {};
+}
+/** Test-only: close the shared relay Agent so its sockets never leak across tests. */
+export async function _closeRelayDispatcherForTest(): Promise<void> {
+	const agent = relayAgent;
+	relayAgent = null;
+	if (agent) await agent.close().catch(() => {});
+}
 /********************************************************
  * Hedged failover grace: an attempt with no response headers
  * within this window fires the NEXT candidate in parallel.
@@ -120,6 +159,8 @@ export async function relayFetch(
 	let lastResponseRelay: string | null = null;
 	/** Relay URLs that returned a gated 402 DEPLOYMENT_DISABLED this request. */
 	const disabledRelays: string[] = [];
+	/** Bare-500 roll-once cap: one extra attempt per relayFetch turn. */
+	let sawBare500 = false;
 	const u = new URL(url);
 	const relayTarget = `${u.protocol}//${u.host}`;
 	const relayPath = `${u.pathname}${u.search}`;
@@ -220,14 +261,14 @@ export async function relayFetch(
 			if (!canHedge) {
 				const soloCtl = new AbortController();
 				const solo = buildAttempt(targetUrl, soloCtl);
-				res = await fetch(targetUrl, { ...opts, headers: solo.headers, signal: solo.signal } as unknown as RequestInit);
+				res = await fetch(targetUrl, { ...opts, headers: solo.headers, signal: solo.signal, ...relayLegInit() } as unknown as RequestInit);
 			} else {
 				const primaryUrl = targetUrl;
 				const nextUrl = candidates[i + 1];
 				const nextCheck = validateRelayUrl(nextUrl);
 				const hedgeCtlA = new AbortController();
 				const first = buildAttempt(primaryUrl, hedgeCtlA);
-				const fetchA = fetch(primaryUrl, { ...opts, headers: first.headers, signal: first.signal } as unknown as RequestInit);
+				const fetchA = fetch(primaryUrl, { ...opts, headers: first.headers, signal: first.signal, ...relayLegInit() } as unknown as RequestInit);
 				const stalled = await new Promise<boolean>((resolve) => {
 					const graceTimer = setTimeout(() => resolve(true), HEDGE_GRACE_MS);
 					fetchA.then(
@@ -242,7 +283,7 @@ export async function relayFetch(
 					const hedgeCtlB = new AbortController();
 					const second = buildAttempt(nextUrl, hedgeCtlB);
 					const hedgeStart = Date.now();
-					const fetchB = fetch(nextUrl, { ...opts, headers: second.headers, signal: second.signal } as unknown as RequestInit);
+					const fetchB = fetch(nextUrl, { ...opts, headers: second.headers, signal: second.signal, ...relayLegInit() } as unknown as RequestInit);
 					// Swallow the loser path so the deliberate abort never
 					// surfaces as an unhandled rejection or a direct fallback.
 					fetchA.catch(() => {});
@@ -430,6 +471,23 @@ export async function relayFetch(
 				continue;
 			}
 
+			// Bounded bare-500 roll-once: a transient model-side 500 carries no
+			// relay-fault signal (413 precedent: roll without health penalty), so
+			// retry once on the next candidate instead of surfacing. A second
+			// consecutive 500 falls through to the terminal passthrough below.
+			if (res.status === 500 && !sawBare500) {
+				sawBare500 = true;
+				lastResponse?.body?.cancel().catch(() => {});
+				lastResponse = res;
+				lastResponseRelay = targetUrl;
+				log(
+					"warn",
+					`relay ${targetUrl} returned HTTP 500 in ${elapsed}s — rolling once to next relay`,
+					{ upstream: url, status: 500 },
+					rid,
+				);
+				continue;
+			}
 			markRelaySuccess(targetUrl, Date.now() - attemptStart);
 
 			// SUCCESS or non-retriable client error (e.g. 200, 404):

package/src/stream-pipe.ts

@@ -25,10 +25,79 @@ import { restoreToolNameForCaller } from "./tool-translation.ts";
  */
 export const SUBSTANTIAL_MIN_CHUNKS = 50;
 export const SUBSTANTIAL_MIN_BYTES = 100 * 1024;
+// Wire markers proving the forwarded bytes already contain a tool call the
+// host may execute (responses + chat shapes). A re-fired turn would
+// regenerate those calls, so their presence vetoes the silent resume and
+// the turn keeps the synthetic-terminal behavior. Text/reasoning turns are
+// safe to resume: nothing was executed yet.
+const TOOL_CALL_MARKERS = [
+ '"type":"function_call"',
+ '"type":"custom_tool_call"',
+ '"type":"tool_use"',
+ "function_call_arguments",
+ "custom_tool_call_input",
+ '"tool_calls"',
+];
 
 export function isSubstantial(chunks: number, bytes: number): boolean {
  return chunks > SUBSTANTIAL_MIN_CHUNKS && bytes > SUBSTANTIAL_MIN_BYTES;
 }
+// Markers identifying an upstream-issued mid-stream model failure worth one
+// silent resume on a sibling relay (transient model flake, not a caller or
+// upstream verdict). Kept narrow on purpose: anything shaped like a request,
+// auth, quota, or reasoning-reference problem stays terminal and is
+// forwarded untouched.
+const TRANSIENT_MODEL_FAILURE_MARKERS = [
+ "server_error",
+ "failed to generate",
+ "overloaded",
+];
+// Deterministic verdicts that must NEVER resume: retrying would replay the
+// same refusal while masking a quota/auth/gate problem as relay trouble.
+const DETERMINISTIC_FAILURE_MARKERS = [
+ "invalid_request",
+ "invalid_response",
+ "invalid_reasoning",
+ "previous_response",
+ "FreeTierError",
+ "rate_limit",
+ "quota",
+ "billing",
+ "authentication",
+ "invalid_api_key",
+ "permission",
+ "moderation",
+];
+
+/**
+ * True when scanned SSE text carries an upstream-issued response.failed frame
+ * for a TRANSIENT model fault (server_error class). Text-only turns holding
+ * such a frame may offer one silent re-fire; anything else (clean terminals,
+ * deterministic verdicts, chat shapes) keeps existing behavior.
+ */
+export function isTransientModelFailureFrame(s: string): boolean {
+ if (!s.includes("response.failed") && !s.includes('"status":"failed"')) return false;
+ for (const m of DETERMINISTIC_FAILURE_MARKERS) if (s.includes(m)) return false;
+ for (const m of TRANSIENT_MODEL_FAILURE_MARKERS) if (s.includes(m)) return true;
+ return false;
+}
+
+// Mid-stream fault split (observability only, never routing): upstream-issued
+// model-fault frames vs relay-fault truncations. Relay-health marks stay the
+// rotation mechanism; these counters attribute blame for status/logs.
+let midStreamModelFaults = 0;
+let midStreamRelayTruncations = 0;
+
+/** Current mid-stream fault split. */
+export function getMidStreamFaultStats(): { modelFaults: number; relayTruncations: number } {
+ return { modelFaults: midStreamModelFaults, relayTruncations: midStreamRelayTruncations };
+}
+
+/** Test-only: reset the mid-stream fault split. */
+export function _resetMidStreamFaultStatsForTest(): void {
+ midStreamModelFaults = 0;
+ midStreamRelayTruncations = 0;
+}
 
 /**
  * Failed-SSE rolling window (client watchdog input).
@@ -492,6 +561,22 @@ export function rewriteSseBlock(
  if (cloak.pathname.endsWith("/messages")) return rewriteMessagesBlock(block, state, cloak);
  return rewriteChatBlock(block, state, cloak);
 }
+/**
+ * Options for pipeUpstreamStream.
+ */
+export interface StreamPipeOptions {
+ /**
+  * Mid-stream resume hook. Invoked at most once per turn, only when the
+  * upstream truncates (clean FIN without a terminal marker, premature
+  * socket close, or a genuine stream error) while the client is still
+  * attached. Return a replacement upstream readable to continue THIS turn
+  * on it — no synthetic terminal is injected and the client response stays
+  * open. Return null (or throw) to keep the existing terminate behavior:
+  * a synthetic response.incomplete/failed plus relay-health accounting.
+  * Client aborts and clean terminal markers never reach this hook.
+  */
+ refire?: () => Promise<Readable | null>;
+}
 /**
  * Pipes an upstream readable stream to a client HTTP response.
  *
@@ -501,6 +586,9 @@ export function rewriteSseBlock(
  * - Cleans up resources and destroys upstream stream on client disconnect/abort.
  * - Optional per-request `cloak`: rewrites SSE events inline (placeholder
  *   strip + caller-name restore); bypassed streams flow byte-identical.
+ * - Optional `opts.refire`: one silent mid-stream resume on upstream
+ *   truncation (see StreamPipeOptions); without it the turn ends with a
+ *   synthetic terminal event exactly as before.
  */
 export function pipeUpstreamStream(
  nodeStream: Readable,
@@ -509,6 +597,7 @@ export function pipeUpstreamStream(
  reqId?: string,
  relayUrl?: string,
  cloak?: StreamCloakOptions,
+ opts?: StreamPipeOptions,
 ): void {
  const rid = reqId || randomUUID().slice(0, 8);
  let totalChunks = 0;
@@ -523,11 +612,19 @@ export function pipeUpstreamStream(
  // relay health. Client disconnects and clean upstream ends must not.
  let upstreamEnded = false;
  let clientAborted = false;
+ // Set once forwarded bytes carry a tool call (see TOOL_CALL_MARKERS): a
+ // resumed turn would regenerate — and the host would re-execute — those
+ // calls, so tryRefire refuses while this is set.
+ let sawToolCall = false;
  // Terminal-marker scan carry: holds the tail of the previously scanned
  // view so a marker split across adjacent chunks ("[DO" | "NE]") is still
  // recognized. Longest marker is "response.completed" (18 bytes); 32
  // gives comfortable headroom.
  let terminalScanCarry = Buffer.alloc(0);
+ // True while a replacement stream is being fetched: the stalled close of the
+ // truncated stream must not inject a terminal or end res mid-rescue (its
+ // `end` already ran; `close` always trails it on a later tick).
+ let refirePending = false;
  // Streaming cloak: per-stream rewrite state (null = byte-identical passthrough).
  const cloakState = cloak && !shouldBypassStreamCloak(cloak) ? createSseStreamCloakState() : null;
  // Holds the trailing incomplete SSE block across chunks; complete blocks are
@@ -543,6 +640,8 @@ export function pipeUpstreamStream(
   outcomeRecorded = true;
   recordSseOutcome(failed);
  };
+ // One-shot resume guard: the refire hook below fires at most once per turn.
+ let refireUsed = false;
 
  const sniffThinking = (chunk: Buffer | string): boolean => {
   const s =
@@ -568,6 +667,92 @@ export function pipeUpstreamStream(
    s.includes("[DONE]")
   );
  };
+ // Held transient model-failure frame (raw chunk or rewritten block text):
+ // withheld from the client while one silent resume is attempted. Dropped on
+ // success, forwarded verbatim (as the genuine upstream verdict) when the
+ // resume is vetoed, unavailable, or fails. Null outside a hold.
+ let heldFailureChunk: string | Buffer | null = null;
+ /**
+  * Hold an upstream-issued transient model-failure frame for one silent
+  * resume on a sibling relay. Returns true when held (caller must NOT
+  * forward the frame); false keeps the existing terminate behavior. Tool
+  * turns always veto: a regenerated turn would re-execute forwarded calls.
+  */
+ const holdModelFailureForRefire = (chunk: string | Buffer): boolean => {
+  if (refirePending || heldFailureChunk !== null || sawToolCall) return false;
+  if (clientAborted || refireUsed || !opts?.refire || res.writableEnded || res.destroyed) return false;
+  refireUsed = true;
+  refirePending = true;
+  heldFailureChunk = chunk;
+  midStreamModelFaults += 1;
+  log(
+   "warn",
+   "upstream model failed this turn mid-stream (model fault) — retrying once on the next relay",
+   { totalChunks, totalBytes },
+   rid,
+  );
+  void rescueHeldModelFailure();
+  return true;
+ };
+ /**
+  * Deliver a held failure frame after the resume failed: the same
+  * scan/mark/forward as a normal chunk, minus any further hold (the
+  * one-resume budget is spent). Never penalizes relay health — the failure
+  * is an upstream model verdict, not a relay fault.
+  */
+ const releaseHeldFailure = (): void => {
+  const held = heldFailureChunk;
+  heldFailureChunk = null;
+  if (held === null || res.writableEnded) return;
+  const buf = typeof held === "string" ? Buffer.from(held, "utf8") : held;
+  const scanBuf =
+   terminalScanCarry.length > 0
+    ? Buffer.concat([terminalScanCarry, buf])
+    : buf;
+  const scanned = scanBuf.toString("utf8");
+  if (!hasTerminalEvent && checkTerminalEvent(scanned)) hasTerminalEvent = true;
+  if (!sawToolCall && TOOL_CALL_MARKERS.some((m) => scanned.includes(m))) sawToolCall = true;
+  terminalScanCarry = Buffer.from(scanBuf.subarray(Math.max(0, scanBuf.length - 32)));
+  try {
+   res.write(held);
+   const maybeFlush = res as unknown as { flush?: () => void };
+   if (typeof maybeFlush.flush === "function") maybeFlush.flush();
+  } catch { }
+ };
+ /**
+  * Resume a held model-failure turn on the replacement stream from
+  * opts.refire (rotation marking lives there, shared with the truncation
+  * path). Success drops the held frame; the stale cut stream's later
+  * events are neutered by the generation check in watch().
+  */
+ const rescueHeldModelFailure = async (): Promise<void> => {
+  const refire = opts?.refire;
+  let next: Readable | null = null;
+  try {
+   next = refire ? await refire() : null;
+  } catch {
+   next = null;
+  }
+  refirePending = false;
+  if (!next || next.destroyed || clientAborted || res.writableEnded || res.destroyed) {
+   try {
+    next?.destroy();
+   } catch { }
+   releaseHeldFailure();
+   return;
+  }
+  heldFailureChunk = null;
+  const cut = nodeStream;
+  upstreamEnded = false;
+  nodeStream = next;
+  sseBuffer = "";
+  terminalScanCarry = Buffer.alloc(0);
+  watch(next);
+  try {
+   if (!cut.destroyed) cut.destroy();
+  } catch { }
+  log("debug", "mid-stream model-fault refire: continuing turn on replacement stream", { totalChunks, totalBytes }, rid);
+ };
  /**
   * Forward one rewritten SSE block: terminal-marker scan plus the shared
   * backpressure/flush handling, so cloaked streams keep the raw path's
@@ -579,7 +764,13 @@ export function pipeUpstreamStream(
    terminalScanCarry.length > 0
     ? Buffer.concat([terminalScanCarry, buf])
     : buf;
-  if (!hasTerminalEvent && checkTerminalEvent(scanBuf.toString("utf8"))) {
+  const scanned = scanBuf.toString("utf8");
+  if (!sawToolCall && TOOL_CALL_MARKERS.some((m) => scanned.includes(m))) sawToolCall = true;
+  if (!hasTerminalEvent && checkTerminalEvent(scanned)) {
+   // Upstream-issued transient model failure on a text-only turn: hold the
+   // frame for one silent resume instead of terminating (tool turns veto
+   // inside holdModelFailureForRefire and keep the terminal below).
+   if (isTransientModelFailureFrame(scanned) && holdModelFailureForRefire(text)) return;
    hasTerminalEvent = true;
   }
   terminalScanCarry = Buffer.from(scanBuf.subarray(Math.max(0, scanBuf.length - 32)));
@@ -608,17 +799,19 @@ export function pipeUpstreamStream(
   // Only genuine upstream-side truncation penalizes relay health.
   // Client disconnects and clean upstream ends leave it untouched.
   if (penalizeRelay && relayUrl && relayUrl !== "direct") {
+   // Relay-fault side of the mid-stream split (model faults never reach here).
+   midStreamRelayTruncations += 1;
    markRelayFailure(relayUrl, 0, errorMsg || "stream truncated prematurely");
   }
   if (isResponsesApi && totalChunks > 0) {
    try {
     if (isError) {
      res.write(
-      `\nevent: response.failed\ndata: {"type":"response.failed","response":{"status":"failed","error":{"code":"stream_error","message":${JSON.stringify(errorMsg || "Upstream stream disconnected unexpectedly")}}}}\n\n`,
+      `\n\nevent: response.failed\ndata: {"type":"response.failed","response":{"status":"failed","error":{"code":"stream_error","message":${JSON.stringify(errorMsg || "Upstream stream disconnected unexpectedly")}}}}\n\n`,
      );
     } else {
      res.write(
-      `\nevent: response.incomplete\ndata: {"type":"response.incomplete","response":{"status":"incomplete","incomplete_details":{"reason":"cancelled"}}}\n\n`,
+      `\n\nevent: response.incomplete\ndata: {"type":"response.incomplete","response":{"status":"incomplete","incomplete_details":{"reason":"cancelled"}}}\n\n`,
      );
     }
     hasTerminalEvent = true;
@@ -631,19 +824,61 @@ export function pipeUpstreamStream(
    } catch { }
   } else if (!isResponsesApi && totalChunks > 0) {
    try {
-    res.write("\ndata: [DONE]\n\n");
+    res.write("\n\ndata: [DONE]\n\n");
     hasTerminalEvent = true;
    } catch { }
   }
  };
+ /**
+  * One silent mid-stream resume. When the upstream truncates with the client
+  * still attached, asks the proxy (via opts.refire) for a replacement stream
+  * and continues THIS turn on it — no synthetic terminal, res stays open.
+  * Returns true when the turn continues; false keeps the existing
+  * terminate-with-synthetic-terminal behavior at the call site. At most one
+  * resume per turn; the proxy additionally budgets re-fires, so a dying pool
+  * degrades to one synthetic terminal instead of a retry storm.
+  */
+ const tryRefire = async (): Promise<boolean> => {
+  if (clientAborted || refireUsed || !opts?.refire) return false;
+  if (sawToolCall) {
+   log("debug", "mid-stream refire skipped: turn already forwarded tool calls", { totalChunks, totalBytes }, rid);
+   return false;
+  }
+  if (res.writableEnded || res.destroyed) return false;
+  refireUsed = true;
+  refirePending = true;
+  let next: Readable | null = null;
+  try {
+   next = await opts.refire();
+  } catch {
+   next = null;
+  }
+  refirePending = false;
+  if (!next || next.destroyed || clientAborted || res.writableEnded || res.destroyed) {
+   try {
+    next?.destroy();
+   } catch { }
+   return false;
+  }
+  upstreamEnded = false;
+  nodeStream = next;
+  sseBuffer = "";
+  terminalScanCarry = Buffer.alloc(0);
+  watch(next);
+  log("debug", "mid-stream refire: continuing turn on replacement stream", { totalChunks, totalBytes }, rid);
+  return true;
+ };
 
  try {
   if (typeof res.flushHeaders === "function") {
    res.flushHeaders();
   }
  } catch { }
- nodeStream.on("data", (chunk: Buffer | string) => {
+ const onData = (chunk: Buffer | string): void => {
   try {
+   // While a replacement stream is being fetched the cut stream is stale:
+   // its late frames must not interleave with the rescued turn.
+   if (refirePending) return;
    if (firstChunkAt === null) {
     firstChunkAt = Date.now();
     const ttfb = firstChunkAt - startAt;
@@ -671,58 +906,30 @@ export function pipeUpstreamStream(
      );
     }
    }
-   if (cloakState && cloak) {
-    // Cloaked stream: buffer across chunks so event names split mid-chunk
-    // still match, rewrite complete SSE blocks, and drop injected calls.
-    sseBuffer += typeof chunk === "string" ? chunk : chunk.toString("utf8");
-    let boundary = sseBoundary.exec(sseBuffer);
-    while (boundary) {
-     const block = sseBuffer.slice(0, boundary.index);
-     sseBuffer = sseBuffer.slice(boundary.index + boundary[0].length);
+   // Buffer across chunks into complete SSE blocks delimited by double-newline.
+   // Forwarding only complete blocks guarantees that network chunk boundaries
+   // never split JSON strings on the wire or leave unterminated syntax when
+   // mid-stream refire or truncation occurs.
+   sseBuffer += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+   let boundary = sseBoundary.exec(sseBuffer);
+   while (boundary) {
+    const block = sseBuffer.slice(0, boundary.index);
+    sseBuffer = sseBuffer.slice(boundary.index + boundary[0].length);
+    if (cloakState && cloak) {
      const rewritten = rewriteSseBlock(block, cloakState, cloak);
      if (rewritten !== null) forwardText(`${rewritten}\n\n`);
-     boundary = sseBoundary.exec(sseBuffer);
+    } else {
+     forwardText(`${block}\n\n`);
     }
-    return;
-   }
-   // Always scan the FULL chunk plus the small carry from the previous
-   // view. SSE chunks are KBs at most, so includes() over everything
-   // is negligible against correctness — the removed head/tail windows
-   // are exactly what let markers buried mid-chunk or split across
-   // adjacent chunks escape and cause duplicate synthetic terminals.
-   const buf =
-    typeof chunk === "string" ? Buffer.from(chunk, "utf8") : chunk;
-   const scanBuf =
-    terminalScanCarry.length > 0
-     ? Buffer.concat([terminalScanCarry, buf])
-     : buf;
-   if (!hasTerminalEvent && checkTerminalEvent(scanBuf.toString("utf8"))) {
-    hasTerminalEvent = true;
-   }
-   terminalScanCarry = Buffer.from(scanBuf.subarray(Math.max(0, scanBuf.length - 32)));
-
-   const canContinue = res.write(chunk);
-   if (canContinue === false && !nodeStream.destroyed) {
-    // Backpressure: pause the upstream source until the client
-    // socket drains, instead of buffering an unbounded amount into
-    // the response. 'drain' might never fire if the client closes —
-    // the close handlers below destroy the stream regardless of
-    // its paused state.
-    nodeStream.pause();
-    const onDrain = () => {
-     res.off("drain", onDrain);
-     if (!nodeStream.destroyed) nodeStream.resume();
-    };
-    res.once("drain", onDrain);
-   }
-   const maybeFlush = res as unknown as { flush?: () => void };
-   if (typeof maybeFlush.flush === "function") {
-    maybeFlush.flush();
+    boundary = sseBoundary.exec(sseBuffer);
    }
   } catch { }
- });
+ };
 
- nodeStream.on("error", (e: unknown) => {
+ const onError = async (e: unknown): Promise<void> => {
+  // A rescue is already in flight (its outcome decides the turn): a late
+  // error from the cut stream must not inject a terminal mid-rescue.
+  if (refirePending) return;
   const errorMsg = (e as Error)?.message || String(e);
   // An abort (client disconnect or a proxy-internal header timeout marked
   // FF_INTERNAL_ABORT) is not a relay fault — never penalize relay health,
@@ -745,29 +952,48 @@ export function pipeUpstreamStream(
     res.writeHead(502, { "content-type": "application/json" });
    } else if (isInternalAbort) {
     clientAborted = true;
+    sseBuffer = "";
+    terminalScanCarry = Buffer.alloc(0);
     ensureTerminalEvent(false, errorMsg || "stream interrupted", false);
    } else {
+    if (await tryRefire()) return;
+    sseBuffer = "";
+    terminalScanCarry = Buffer.alloc(0);
     ensureTerminalEvent(!isSubstantial(totalChunks, totalBytes), errorMsg, true);
    }
    if (!res.writableEnded) {
     res.end();
    }
   } catch { }
- });
+ };
 
- nodeStream.on("end", () => {
+ const onEnd = async (): Promise<void> => {
+  // A rescue is in flight (its outcome owns the turn): the cut stream's FIN
+  // must neither inject a terminal nor end res mid-rescue.
+  if (refirePending) return;
   upstreamEnded = true;
   // Cloaked streams hold the trailing incomplete block: flush it (rewritten)
   // ahead of the terminal-marker check so a coalesced final event still counts.
-  if (cloakState && cloak && sseBuffer.trim() !== "") {
+  if (sseBuffer.trim() !== "") {
    const tail = sseBuffer;
    sseBuffer = "";
-   const rewritten = rewriteSseBlock(tail, cloakState, cloak);
-   if (rewritten !== null) forwardText(`${rewritten}\n\n`);
+   if (checkTerminalEvent(tail)) {
+    if (cloakState && cloak) {
+     const rewritten = rewriteSseBlock(tail, cloakState, cloak);
+     if (rewritten !== null) forwardText(`${rewritten}\n\n`);
+    } else {
+     forwardText(tail);
+    }
+   }
   }
   if (hasTerminalEvent) recordOnce(false);
   const elapsed = ((Date.now() - startAt) / 1000).toFixed(1);
   if (!hasTerminalEvent && totalChunks > 0) {
+   // Upstream FIN without a terminal marker: offer the proxy one silent
+   // re-fire on a sibling relay before falling back to the synthetic
+   // terminal below. A resumed turn keeps streaming into the same client
+   // response; the final outcome is logged when that stream ends.
+   if (await tryRefire()) return;
    // Clean upstream end without a detectable marker: keep the host
    // contract (synthetic terminal) but never blame the relay.
    ensureTerminalEvent(
@@ -794,16 +1020,26 @@ export function pipeUpstreamStream(
   try {
    if (!res.writableEnded) res.end();
   } catch { }
- });
+ };
 
- nodeStream.on("close", () => {
+ const onClose = async (): Promise<void> => {
+  // A stalled `close` trailing an `end` that is mid-rescue must neither
+  // inject a terminal nor end res — the replacement stream owns the turn now.
+  if (refirePending) return;
   try {
    if (!hasTerminalEvent && totalChunks > 0) {
     if (clientAborted || upstreamEnded) {
      // Client disconnect teardown or post-end cleanup — the relay
      // is not at fault; still give the host a terminal event.
+     sseBuffer = "";
+     terminalScanCarry = Buffer.alloc(0);
      ensureTerminalEvent(false, "stream interrupted by client", false);
     } else {
+     // Same offer as the clean-end path above: one silent re-fire before
+     // marking this relay and terminating the turn.
+     if (await tryRefire()) return;
+     sseBuffer = "";
+     terminalScanCarry = Buffer.alloc(0);
      // Upstream socket died mid-stream with no error event.
      // For muse-spark large payloads: raxtant 514KB failed but feoni 802KB
      // succeeded with same 2.6MB in — so this is edge-specific, not pure
@@ -815,7 +1051,16 @@ export function pipeUpstreamStream(
    }
    if (!res.writableEnded) res.end();
   } catch { }
- });
+ };
+ const watch = (s: Readable): void => {
+  // Generation check: after a rescue swaps nodeStream, the cut stream's
+  // late events are stale and must not touch the rescued turn.
+  s.on("data", (c) => { if (s === nodeStream) onData(c); });
+  s.on("error", (e) => { if (s === nodeStream) void onError(e); });
+  s.on("end", () => { if (s === nodeStream) void onEnd(); });
+  s.on("close", () => { if (s === nodeStream) void onClose(); });
+ };
+ watch(nodeStream);
 
  req.on("aborted", () => {
   clientAborted = true;
@@ -824,7 +1069,7 @@ export function pipeUpstreamStream(
  });
 
  req.on("close", () => {
-  if (!upstreamEnded && !nodeStream.destroyed) {
+  if ((!upstreamEnded || refirePending) && !nodeStream.destroyed) {
    clientAborted = true;
    nodeStream.destroy();
   }
@@ -832,7 +1077,7 @@ export function pipeUpstreamStream(
 
  res.on("close", () => {
   if (
-   !upstreamEnded &&
+   (!upstreamEnded || refirePending) &&
    !res.writableEnded &&
    !nodeStream.destroyed
   ) {
@@ -842,7 +1087,7 @@ export function pipeUpstreamStream(
  });
 
  res.on("error", () => {
-  if (!upstreamEnded && !nodeStream.destroyed) {
+  if ((!upstreamEnded || refirePending) && !nodeStream.destroyed) {
    clientAborted = true;
    nodeStream.destroy();
   }