mslxdff 0.1.203 → 0.1.208

package/src/routes/AGENTS.md

@@ -0,0 +1,37 @@
+# src/routes — 转发链契约（改 relay / 流式 / 用量前必读）
+
+> 从 `AGENTS.md` 下沉（2026-09-29 分层，就近生效）。改完跑：`node --test --test-concurrency=1 test/stream-*.test.js test/relay-*.test.js test/usage-*.test.js` + `npm run docs:check`。
+
+## 时间量测的两条口径（ADR-0039，最易被改错）
+
+- **保护闸门的零点 = `relay()` 入口的 `t0`**（首帧超时 / stall / MAX_STREAM / keepalive 四类）。**禁止**把上报锚点接进闸门判定，否则上游排队时间会吃掉超时预算、误杀正在出字的慢模型。
+- **上报时长（usage 行）的零点 = 本次上游尝试起点**（`serial-trial` 的 `tUp`，经 `attemptStartMs` 交进 relay）；relay 入口算 `preflightMs = t0 − 锚点` 并随**全部 4 个 return 点**带出，`relay-pipeline` 落行时相加。锚点缺失/负值一律 0。
+- 报表口径与 state 口径**彻底分离**：`recordModelStats`（→ `-status`/`-model stats` 的 EMA）仍吃转发入口相对值，勿"顺手统一"。
+- 首字与总耗时同加一个常数 → `总 − 首字` 恒等 → 速度读数不变（已锁为单测）。
+- usage 行**只增字段**演进（`src/usage/record.js` 拥有行形状）；旧行缺字段 = 未知，不得当 0。
+- 模型日志里 `relay-first-chunk ttfMs=` 是**转发入口相对值**（故意与报表不同源），排查时别混。
+
+## relay 的行为契约（既有测试锁死）
+
+- **超时是显式字段 `timedOut`**，`status` 数值只是 HTTP 语义展示，不得再拿 status 当"是否可 failover"的信号。
+- **注释帧（`: keepalive`）不算首块**：不解除闸门、不触发超时救回，但照常透传；能否安全 failover 看 `detail.wrotePayload`（=是否已**提交**模型产出，见下条留口）。
+- 闸门到点后上游仍吐出真实数据 → **撤销超时判定照常转发**（cancel 是异步的，竞态窗口内已到达的数据是纯收益），记 `detail.recoveries`。
+- 任一闸门到点且未写真实数据 → 回退候选；唯一/末位候选无 failover 去向 → 闸门放宽到 `MSLXDFF_LAST_CANDIDATE_TIMEOUT_MS`（默认 120s，0=不限），防误杀慢模型。
+- **空转 200 判据单一真相** = `stream-scan.js:isEmptyTurnDetail`（`chatShaped===true` 且 `chars===0 && toolCalls===0` 且 `finish_reason ∉ {tool_calls, function_call}`）；relay 侧「要不要封口」与 pipeline 5a0「要不要重拉」都必须用它，两处各写一份必然错拍。判空 → 转 failover，不记 auto 冷却（空转≠模型坏）。错误包络暂扣 `holdableChunk` 与非 chat 形状放行同在 `stream-scan.js`（**不在 stream.js**）。
+- **空轮留口（ADR-0043）**：模型产出（正文/工具/**思考**）出现前，空 delta 帧与 `[DONE]` 一律暂扣不写（`stream-hold.js:createRevocablePrefix`）；流结束仍零产出且未断下游 → **不 `res.end()`**，返回 `heldOpen:true` 交回重拉/换候选，正文续写同一条连接。三条铁律：① 异形/解析失败帧必须立即透传（`isTrivialFrame` 白名单式），透传契约不得为救空轮让路；② `[DONE]` 是终点，错误帧要排在它之前（tail 槽）且全程只允许一个；③ 重入同一条连接时 headers 可能已 flush → `statusCode`/`setHeader` 一律门控，收场经 `endHeldFailure`/`endEmptyTurnStream`/`helpers.json` 的 `writableEnded`+`headersSent` 守卫保证**恰好一次**，禁止把 JSON 体混进 `text/event-stream`。
+- 断下游即掐上游：relay 自持 `reader`（`for-await` 会锁 ReadableStream 使 `body.cancel()` 必 reject），`reader.cancel()` 才真掐得断。
+
+## 组/组员与宽带中继（`src/routes/groups*.js`、`peers.js`、`relay-queue.js`）
+
+- 慢模型不掐当前流：首块 25s 内到即视为可用、后续无限等；stall 15s 仅作质量分，耗时 >20s 降权；`MSLXDFF_HEDGE_DELAY_MS=1000` 时 1s 并发组员赛跑，赢家 `x-mslxdff-via`；指定模型 429 时按延迟 EMA 择优切最快模型。
+- `SLOW_TOTAL_MS=20s` 标 slow 进 5 分钟冷却（普通 60s）；上游重试 `1次×100ms`；`MSLXDFF_STREAM_TIMEOUT_MS=25s`（**仅首块未到且未写出任何字节时**才 failover；`0`=显式关闭首块超时，给重思考模型用）；`MAX_STREAM_MS` **默认 0=关**（agent 长任务合法超 120s：实测 1.67% 的 relay 走 144s~449s 且完整收尾，默认设 120s 会腰斩它们；需要硬上限才显式设）。
+- 宽带 `relay://` 成员走 `GET /v1/groups/relay/stream` SSE 单长连 25s ping 直推（`pushToStream`），`MSLXDFF_BROADBAND_STREAM=0` 回退 1s poll，`MSLXDFF_BROADBAND_PING_MS=25000`/`_STALE_MS=90000` 可配（空闲 -96%）；用户明确反对 1s 轮询的空轮询。
+- 组命令语义：`-group list` 序号按 state 成员顺序（过滤 leader）固定渲染，`-group remove <seq>` 用同一顺序踢人（仅组长）；组长 `-leavegroup` 提示改用 `-delgroup`，`-delgroup` 在组员节点报错并提示该组由谁领导。
+- 模型可观测面：事件用**黑名单** `TRACE_DENY`（默认全可见，只排噪声与敏感面）；决定类事件只渲染 `DECISION_FIELDS` 登记过的标量，**"加日志"≠"倒数据"**，payload/正文一律不落；回显取头单一入口 `upstreamEcho(res)`。
+
+## Responses 端点（`routes/responses-route.js` + `responses/translate.js`，ADR-0012）
+
+- 复用 ChatPipeline 全链路，只做形状翻译；stateless（`previous_response_id` 不支持）；**思考档位已透传**：`reasoning.effort` → `reasoning_effort`（change fix-thinking-effort-passthrough / ADR-0053）。
+- Codex Rust 严格解码三特例（缺一整轮作废）：① 对 codex 调用者（UA/originator `codex_*` 或 `?client_version=`）`GET /v1/models` 追加顶层 `models: []`（**必须空**，填真目录会覆盖其内置 agent prompt）；② completed 的 usage 转 Responses 口径（`input_tokens/output_tokens` + details）；③ done 事件 `text` 带累积全文。
+- `-setto chatgpt`（`src/sync-codex.js`）写三端共用 `~/.codex/config.toml`（`wire_api="responses"` 显式、鉴权绝对路径 `node + -showtoken`，换模型需重跑 setto / `codex exec -m` / 手改 `model=`，单键覆盖无需剪枝）；排障 `MSLXDFF_RESPONSES_DEBUG=1` 看 `daemon.log [responses]` 四段 + Codex 侧 `~/.codex/logs_2.sqlite`（`Request completed ... status=`）与 `thread_history_1.sqlite`（正文）。
+- `@ai-sdk/openai` 只是客户端包，替代不了服务端翻译层；Qwen 上游走 `/v1/messages`（Anthropic 协议），接 Codex 要多一跳（未做）。

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

@@ -1,72 +1,72 @@
-import { relay, SLOW_TOTAL_MS, STREAM_TIMEOUT_MS, STALL_TIMEOUT_MS, SCORE_STALL_MS } from "../stream.js";
-import { buildFallbackInfo } from "../fallback.js";
-import { createRelayPipeline } from "./relay-pipeline.js";
-import { tryBroadbandRelay } from "../relay-queue.js";
-
-/** 薄适配：broadband 两种形态合一经由 pipeline */
-export async function handleBroadbandRelay({
-  model,
-  body,
-  hops,
-  lastErr,
-  requested,
-  useAuto,
-  lockModel,
-  auto,
-  groups,
-  token,
-  bus,
-  logs,
-  handlerCtx,
-  evt,
-  mark,
-  perf0,
-  attemptStartMs,
-  stages,
-  res,
-  startedAt,
-  plugins,
-  deps = {},
-}) {
-  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 = createPipeline({
-    relay,
-    buildFallbackInfo,
-    auto,
-    plugins,
-    evt,
-    mark,
-    logCall: () => {},
-    logError: () => {},
-    constants: { STREAM_TIMEOUT_MS, SLOW_TOTAL_MS, STALL_TIMEOUT_MS, SCORE_STALL_MS },
-    startedAt,
-    stages,
-  });
-  const isResponse = bb.result && typeof bb.result.status === "number" && typeof bb.result.headers?.get === "function";
-  if (isResponse) {
-    const r = await pipeline.execute({ res, upRes: bb.result, body, requested, actual: model, lastErr, via: "broadband", lockModel, useAuto, handlerCtx, mark, perf0, attemptStartMs, stages, startedAt });
-    if (!r.handled) return { handled: false, upRes: null, lastErr: r.lastErr };
-    return { handled: true };
-  }
-  if (bb.result && typeof bb.result.status === "number") {
-    const b = bb.result.body || "";
-    const str = typeof b === "string" ? b : JSON.stringify(b);
-    const isSSE = bb.result.headers?.["Content-Type"]?.includes("text/event-stream");
-    const fakeRes = {
-      status: bb.result.status,
-      headers: { get: (k) => bb.result.headers?.[k] || bb.result.headers?.[k.toLowerCase()] || null },
-      text: async () => str,
-      body: isSSE ? (async function* () { yield Buffer.from(str); })() : null,
-    };
-    const r = await pipeline.execute({ res, upRes: fakeRes, body, requested, actual: model, lastErr, via: "broadband-local", lockModel, useAuto, handlerCtx, mark, perf0, attemptStartMs, stages, startedAt });
-    if (!r.handled) return { handled: false, upRes: null, lastErr: r.lastErr };
-    return { handled: true };
-  }
-  evt("relay-miss", { reqId: handlerCtx.reqId, model });
-  return { handled: false };
-}
+import { relay, SLOW_TOTAL_MS, STREAM_TIMEOUT_MS, STALL_TIMEOUT_MS, SCORE_STALL_MS } from "../stream.js";
+import { buildFallbackInfo } from "../fallback.js";
+import { createRelayPipeline } from "./relay-pipeline.js";
+import { tryBroadbandRelay } from "../relay-queue.js";
+
+/** 薄适配：broadband 两种形态合一经由 pipeline */
+export async function handleBroadbandRelay({
+  model,
+  body,
+  hops,
+  lastErr,
+  requested,
+  useAuto,
+  lockModel,
+  auto,
+  groups,
+  token,
+  bus,
+  logs,
+  handlerCtx,
+  evt,
+  mark,
+  perf0,
+  attemptStartMs,
+  stages,
+  res,
+  startedAt,
+  plugins,
+  deps = {},
+}) {
+  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 = createPipeline({
+    relay,
+    buildFallbackInfo,
+    auto,
+    plugins,
+    evt,
+    mark,
+    logCall: () => {},
+    logError: () => {},
+    constants: { STREAM_TIMEOUT_MS, SLOW_TOTAL_MS, STALL_TIMEOUT_MS, SCORE_STALL_MS },
+    startedAt,
+    stages,
+  });
+  const isResponse = bb.result && typeof bb.result.status === "number" && typeof bb.result.headers?.get === "function";
+  if (isResponse) {
+    const r = await pipeline.execute({ res, upRes: bb.result, body, requested, actual: model, lastErr, via: "broadband", lockModel, useAuto, handlerCtx, mark, perf0, attemptStartMs, stages, startedAt });
+    if (!r.handled) return { handled: false, upRes: null, lastErr: r.lastErr };
+    return { handled: true };
+  }
+  if (bb.result && typeof bb.result.status === "number") {
+    const b = bb.result.body || "";
+    const str = typeof b === "string" ? b : JSON.stringify(b);
+    const isSSE = bb.result.headers?.["Content-Type"]?.includes("text/event-stream");
+    const fakeRes = {
+      status: bb.result.status,
+      headers: { get: (k) => bb.result.headers?.[k] || bb.result.headers?.[k.toLowerCase()] || null },
+      text: async () => str,
+      body: isSSE ? (async function* () { yield Buffer.from(str); })() : null,
+    };
+    const r = await pipeline.execute({ res, upRes: fakeRes, body, requested, actual: model, lastErr, via: "broadband-local", lockModel, useAuto, handlerCtx, mark, perf0, attemptStartMs, stages, startedAt });
+    if (!r.handled) return { handled: false, upRes: null, lastErr: r.lastErr };
+    return { handled: true };
+  }
+  evt("relay-miss", { reqId: handlerCtx.reqId, model });
+  return { handled: false };
+}

package/src/routes/chat/empty-turn-report.js

@@ -1,31 +1,31 @@
-// 空转 200 的收场记账（从 relay-pipeline.js 抽出：那儿是 20KB 硬门的存量超标文件，先拆后写）。
-// 只做「把这一轮判成空转后该记什么、该把 lastErr 造成什么形状」，不碰网络/闸门/响应体。
-// 判据本身不在这里：单一真相是 stream-scan.js 的 isEmptyTurnDetail（relay 侧「要不要封口」与
-// 这里「要不要重拉」必须同源，否则会出现留了口却不再救、或已终结却仍重拉的错拍）。
-import { upstreamEcho } from "../../model-trace.js";
-
-/**
- * 空转 200 收场：记 errors.log + upstream-error/fallback 事件，返回交给 serial-trial 的 lastErr。
- * @param {{ out: object, actual: string, reqId: string, upRes: object, logError: Function, evt: Function }} p
- * @returns {{ handled: false, upRes: null, lastErr: object }}
- */
-export function reportEmptyTurn({ out, actual, reqId, upRes, logError, evt }) {
-  const d = out.detail || {};
-  const why = d.sawFinishReason ? ` (finish_reason=${d.sawFinishReason})` : " (no content, no tool calls)";
-  // 错误包络暂扣后下游不再直观看到上游原文：把摘要带进最终报错（截断 200 字），排障不断线。
-  const err = d.upstreamErrorText ? ` upstream=${String(d.upstreamErrorText).slice(0, 200)}` : "";
-  // 零正文的成因直接写进报错（不只给现象）：finish_reason=length + 大量思考 = 额度被 reasoning 吃光
-  // （实测 cline-free deepseek reasoningChars=28151、completion_tokens=8192=max_tokens、chars=0）。
-  // 同参重拉必复现，故 serial-trial 的空转重试会顺手把 max_tokens 抬一档（见 emptyRaiseCap）。
-  const lenCapped = d.sawFinishReason === "length";
-  const hint = lenCapped && (Number(d.reasoningChars) || 0) > 0
-    ? ` [思考 ${Number(d.reasoningChars) || 0} 字刷满 max_tokens，正文 0 字]`
-    : "";
-  try { logError(actual, 502, `empty turn${why}${err}${hint}`); } catch {}
-  evt("upstream-error", { reqId, model: actual, status: 502, message: "empty turn", timing: null, finish: d.sawFinishReason || null, reasoningChars: Number(d.reasoningChars) || 0, wroteFrames: Number(d.wroteChunks) || 0, heldOpen: out.heldOpen === true, ...upstreamEcho(upRes) });
-  evt("fallback", { reqId, from: actual, to: null, reason: "empty turn" });
-  let errMsg = `EMPTY_MODEL_RESPONSE: upstream returned 200 with no content${why}${err}${hint} — retry or rephrase`;
-  // 上游报了 retryAfterSeconds：原样透出（客户端等得起），别被我们的包装话术盖掉。
-  if (d.upstreamErrorText && d.upstreamErrorText.includes("retryAfterSeconds")) errMsg = d.upstreamErrorText;
-  return { handled: false, upRes: null, lastErr: { model: actual, upstream: null, status: 502, message: errMsg, emptyTurn: true, heldOpen: out.heldOpen === true } };
-}
+// 空转 200 的收场记账（从 relay-pipeline.js 抽出：那儿是 20KB 硬门的存量超标文件，先拆后写）。
+// 只做「把这一轮判成空转后该记什么、该把 lastErr 造成什么形状」，不碰网络/闸门/响应体。
+// 判据本身不在这里：单一真相是 stream-scan.js 的 isEmptyTurnDetail（relay 侧「要不要封口」与
+// 这里「要不要重拉」必须同源，否则会出现留了口却不再救、或已终结却仍重拉的错拍）。
+import { upstreamEcho } from "../../model-trace.js";
+
+/**
+ * 空转 200 收场：记 errors.log + upstream-error/fallback 事件，返回交给 serial-trial 的 lastErr。
+ * @param {{ out: object, actual: string, reqId: string, upRes: object, logError: Function, evt: Function }} p
+ * @returns {{ handled: false, upRes: null, lastErr: object }}
+ */
+export function reportEmptyTurn({ out, actual, reqId, upRes, logError, evt }) {
+  const d = out.detail || {};
+  const why = d.sawFinishReason ? ` (finish_reason=${d.sawFinishReason})` : " (no content, no tool calls)";
+  // 错误包络暂扣后下游不再直观看到上游原文：把摘要带进最终报错（截断 200 字），排障不断线。
+  const err = d.upstreamErrorText ? ` upstream=${String(d.upstreamErrorText).slice(0, 200)}` : "";
+  // 零正文的成因直接写进报错（不只给现象）：finish_reason=length + 大量思考 = 额度被 reasoning 吃光
+  // （实测 cline-free deepseek reasoningChars=28151、completion_tokens=8192=max_tokens、chars=0）。
+  // 同参重拉必复现，故 serial-trial 的空转重试会顺手把 max_tokens 抬一档（见 emptyRaiseCap）。
+  const lenCapped = d.sawFinishReason === "length";
+  const hint = lenCapped && (Number(d.reasoningChars) || 0) > 0
+    ? ` [思考 ${Number(d.reasoningChars) || 0} 字刷满 max_tokens，正文 0 字]`
+    : "";
+  try { logError(actual, 502, `empty turn${why}${err}${hint}`); } catch {}
+  evt("upstream-error", { reqId, model: actual, status: 502, message: "empty turn", timing: null, finish: d.sawFinishReason || null, reasoningChars: Number(d.reasoningChars) || 0, wroteFrames: Number(d.wroteChunks) || 0, heldOpen: out.heldOpen === true, ...upstreamEcho(upRes) });
+  evt("fallback", { reqId, from: actual, to: null, reason: "empty turn" });
+  let errMsg = `EMPTY_MODEL_RESPONSE: upstream returned 200 with no content${why}${err}${hint} — retry or rephrase`;
+  // 上游报了 retryAfterSeconds：原样透出（客户端等得起），别被我们的包装话术盖掉。
+  if (d.upstreamErrorText && d.upstreamErrorText.includes("retryAfterSeconds")) errMsg = d.upstreamErrorText;
+  return { handled: false, upRes: null, lastErr: { model: actual, upstream: null, status: 502, message: errMsg, emptyTurn: true, heldOpen: out.heldOpen === true } };
+}

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

@@ -1,87 +1,87 @@
-// Note: 失败收尾四分支在 result 后补 client-response，与成功路径对账口径一致（result 条数 == client-response 条数）— 见 .agents/notes/implemented/bug-fix/2026-09-25-sdk-headers-timeout-and-failure-client-response.md
-import { relay } from "../stream.js";
-import { endHeldFailure } from "../stream-hold.js"; // 终局收场出口（502 JSON 或 SSE 错误帧 + [DONE]）
-import { json } from "../helpers.js";
-import { performance } from "node:perf_hooks";
-import { recordRelayTalk } from "../../talk-log.js"; // 环形对话日志：exhausted 收尾直连 relay，落盘点必须自己补一份
-import { recordAgentLoop } from "../../talk-full.js"; // agent 回路全量语料（talk/full）：与 talk.log 并排各调一次，见 openspec add-agent-loop-capture D1
-import { captureTalkFlush } from "../stream-scan.js"; // 收场回收缺尾换行的末行，record* 读桶前调用（openspec fix-talk-capture-frame-loss D4）
-
-// 最后一站的收场：relay 的「不写响应」路径（超时 / 空轮延后封口）都汇到这里，没有上层 failover 了，
-// 必须把响应「恰好一次」地关掉。形状由 endHeldFailure 按 headers 是否已 flush 决定
-// （未 flush → 502 JSON；已 flush 的 SSE → 错误帧 + [DONE]），这里不再自己 json() 打已 flush 的流。
-function terminal(res, message) {
-  endHeldFailure(res, message || "all auto models failed");
-}
-
-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 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] }),
-    });
-    // 收场回收（须在 relay-done 事件快照 detail 之前，review P2-6）：flush 缺尾换行的末行，语料与线上字节对齐（fix-talk-capture-frame-loss D4）
-    try { captureTalkFlush(out?.detail?.talk); } catch {}
-    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 });
-    // 绕过 relay-pipeline 的最后一站：对话日志照常落盘（正文只进 talk/*.log，不进 events.log）
-    // 本收尾点没有 attemptStartMs 可取（绕过 relay-pipeline 直连 relay）→ 不传 attemptMs，按回退路径走：
-    // elapsed=relay 内部计时（与 relayMs 同值，spec 降级 scenario）；finishReason 传 out.detail.sawFinishReason 与 3.3 同源。
-    try { recordRelayTalk({ reqId: handlerCtx.reqId, api: handlerCtx?.api, model: lastErr.model, via: "local-exhausted", body, out, finishReason: out.detail?.sawFinishReason }); } catch {}
-    // 回路语料另起一条独立 try：talk.log 是人读环形稿、capture 是机读全量语料，两者生死独立。
-    // hops 走 handlerCtx.hops（serial-trial 以 {...handlerCtx} 展开传进来，与 reqId 同源）；缺值时不兜 0 ——
-    // 交给 talk-full 落 null（「hops 未知」在语料里看得见，比伪造成 0 诚实），组员流量拦截靠真值。
-    try { recordAgentLoop({ reqId: handlerCtx.reqId, api: handlerCtx?.api, model: lastErr.model, via: "local-exhausted", hops: handlerCtx?.hops, body, out, sessionKey: handlerCtx?.sessionId, clientIp: handlerCtx?.clientIp }); } catch {} // attemptMs 缺省 → 回退 out.totalMs；缺 echo 的既有形状本期不补（tasks 3.4）
-    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 });
-    evt("client-response", { requested, actual: lastErr.model, via: "local", fallback: false, status: out.status, reqId: handlerCtx.reqId });
-    // 最后一站：relay 超时/空轮留口路径都不写响应，这里没有上层，必须自己收尾
-    if (out.timedOut || out.heldOpen) {
-      terminal(res, out.detail?.exitReason === "empty-turn-hold"
-        ? "EMPTY_MODEL_RESPONSE: 空轮重拉与换候选全部用尽，仍无正文"
-        : 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 });
-  evt("client-response", { requested, actual: model, via: "none", fallback: false, status: lastErr?.status ?? 502, reqId: handlerCtx.reqId });
-  done({ via: "none", status: lastErr?.status ?? 502, error: lastErr?.message || "all auto models failed" });
-  terminal(res, lastErr?.message);
-  return true;
-}
-
-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 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] }),
-    });
-    // 收场回收：与 local-exhausted 同理，须在 relay-done 事件快照 detail 之前（fix-talk-capture-frame-loss D4 / review P2-6）
-    try { captureTalkFlush(out?.detail?.talk); } catch {}
-    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 });
-    // 同上：全链耗尽的最终转发也要留下问答原文
-    // 同上：本收尾点没有 attemptStartMs 可取（relay 直连、无尝试起点）→ 不传 attemptMs，
-    // recordRelayTalk/recordAgentLoop 内部按回退路径走 elapsed=relay 计时（与 relayMs 同值，spec 降级 scenario）；finishReason 同源传 out.detail.sawFinishReason。
-    try { recordRelayTalk({ reqId: handlerCtx.reqId, api: handlerCtx?.api, model: lastErr.model, via: "local-final", body, out, finishReason: out.detail?.sawFinishReason }); } catch {}
-    // 同上：全链耗尽的最终转发也要进语料（这条往往是「客户端只看到 502」时唯一的现场材料）
-    try { recordAgentLoop({ reqId: handlerCtx.reqId, api: handlerCtx?.api, model: lastErr.model, via: "local-final", hops: handlerCtx?.hops, body, out, sessionKey: handlerCtx?.sessionId, clientIp: handlerCtx?.clientIp }); } catch {} // attemptMs 缺省 → 回退 out.totalMs（见上行注释；缺 echo 的形状本期不补）
-    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 });
-    evt("client-response", { requested, actual: lastErr.model, via: "local", fallback: false, status: out.status, reqId: handlerCtx.reqId });
-    // 最后一站：relay 超时/空轮留口路径不写响应，这里没有上层 failover，必须自己收尾
-    if (out.timedOut || out.heldOpen) {
-      terminal(res, 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 });
-  evt("client-response", { requested, actual: lastErr?.model ?? requested, via: "none", fallback: false, status: lastErr?.status ?? 502, reqId: handlerCtx.reqId });
-  terminal(res, lastErr?.message);
-  return true;
-}
+// Note: 失败收尾四分支在 result 后补 client-response，与成功路径对账口径一致（result 条数 == client-response 条数）— 见 .agents/notes/implemented/bug-fix/2026-09-25-sdk-headers-timeout-and-failure-client-response.md
+import { relay } from "../stream.js";
+import { endHeldFailure } from "../stream-hold.js"; // 终局收场出口（502 JSON 或 SSE 错误帧 + [DONE]）
+import { json } from "../helpers.js";
+import { performance } from "node:perf_hooks";
+import { recordRelayTalk } from "../../talk-log.js"; // 环形对话日志：exhausted 收尾直连 relay，落盘点必须自己补一份
+import { recordAgentLoop } from "../../talk-full.js"; // agent 回路全量语料（talk/full）：与 talk.log 并排各调一次，见 openspec add-agent-loop-capture D1
+import { captureTalkFlush } from "../stream-scan.js"; // 收场回收缺尾换行的末行，record* 读桶前调用（openspec fix-talk-capture-frame-loss D4）
+
+// 最后一站的收场：relay 的「不写响应」路径（超时 / 空轮延后封口）都汇到这里，没有上层 failover 了，
+// 必须把响应「恰好一次」地关掉。形状由 endHeldFailure 按 headers 是否已 flush 决定
+// （未 flush → 502 JSON；已 flush 的 SSE → 错误帧 + [DONE]），这里不再自己 json() 打已 flush 的流。
+function terminal(res, message) {
+  endHeldFailure(res, message || "all auto models failed");
+}
+
+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 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] }),
+    });
+    // 收场回收（须在 relay-done 事件快照 detail 之前，review P2-6）：flush 缺尾换行的末行，语料与线上字节对齐（fix-talk-capture-frame-loss D4）
+    try { captureTalkFlush(out?.detail?.talk); } catch {}
+    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 });
+    // 绕过 relay-pipeline 的最后一站：对话日志照常落盘（正文只进 talk/*.log，不进 events.log）
+    // 本收尾点没有 attemptStartMs 可取（绕过 relay-pipeline 直连 relay）→ 不传 attemptMs，按回退路径走：
+    // elapsed=relay 内部计时（与 relayMs 同值，spec 降级 scenario）；finishReason 传 out.detail.sawFinishReason 与 3.3 同源。
+    try { recordRelayTalk({ reqId: handlerCtx.reqId, api: handlerCtx?.api, model: lastErr.model, via: "local-exhausted", body, out, finishReason: out.detail?.sawFinishReason }); } catch {}
+    // 回路语料另起一条独立 try：talk.log 是人读环形稿、capture 是机读全量语料，两者生死独立。
+    // hops 走 handlerCtx.hops（serial-trial 以 {...handlerCtx} 展开传进来，与 reqId 同源）；缺值时不兜 0 ——
+    // 交给 talk-full 落 null（「hops 未知」在语料里看得见，比伪造成 0 诚实），组员流量拦截靠真值。
+    try { recordAgentLoop({ reqId: handlerCtx.reqId, api: handlerCtx?.api, model: lastErr.model, via: "local-exhausted", hops: handlerCtx?.hops, body, out, sessionKey: handlerCtx?.sessionId, clientIp: handlerCtx?.clientIp }); } catch {} // attemptMs 缺省 → 回退 out.totalMs；缺 echo 的既有形状本期不补（tasks 3.4）
+    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 });
+    evt("client-response", { requested, actual: lastErr.model, via: "local", fallback: false, status: out.status, reqId: handlerCtx.reqId });
+    // 最后一站：relay 超时/空轮留口路径都不写响应，这里没有上层，必须自己收尾
+    if (out.timedOut || out.heldOpen) {
+      terminal(res, out.detail?.exitReason === "empty-turn-hold"
+        ? "EMPTY_MODEL_RESPONSE: 空轮重拉与换候选全部用尽，仍无正文"
+        : 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 });
+  evt("client-response", { requested, actual: model, via: "none", fallback: false, status: lastErr?.status ?? 502, reqId: handlerCtx.reqId });
+  done({ via: "none", status: lastErr?.status ?? 502, error: lastErr?.message || "all auto models failed" });
+  terminal(res, lastErr?.message);
+  return true;
+}
+
+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 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] }),
+    });
+    // 收场回收：与 local-exhausted 同理，须在 relay-done 事件快照 detail 之前（fix-talk-capture-frame-loss D4 / review P2-6）
+    try { captureTalkFlush(out?.detail?.talk); } catch {}
+    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 });
+    // 同上：全链耗尽的最终转发也要留下问答原文
+    // 同上：本收尾点没有 attemptStartMs 可取（relay 直连、无尝试起点）→ 不传 attemptMs，
+    // recordRelayTalk/recordAgentLoop 内部按回退路径走 elapsed=relay 计时（与 relayMs 同值，spec 降级 scenario）；finishReason 同源传 out.detail.sawFinishReason。
+    try { recordRelayTalk({ reqId: handlerCtx.reqId, api: handlerCtx?.api, model: lastErr.model, via: "local-final", body, out, finishReason: out.detail?.sawFinishReason }); } catch {}
+    // 同上：全链耗尽的最终转发也要进语料（这条往往是「客户端只看到 502」时唯一的现场材料）
+    try { recordAgentLoop({ reqId: handlerCtx.reqId, api: handlerCtx?.api, model: lastErr.model, via: "local-final", hops: handlerCtx?.hops, body, out, sessionKey: handlerCtx?.sessionId, clientIp: handlerCtx?.clientIp }); } catch {} // attemptMs 缺省 → 回退 out.totalMs（见上行注释；缺 echo 的形状本期不补）
+    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 });
+    evt("client-response", { requested, actual: lastErr.model, via: "local", fallback: false, status: out.status, reqId: handlerCtx.reqId });
+    // 最后一站：relay 超时/空轮留口路径不写响应，这里没有上层 failover，必须自己收尾
+    if (out.timedOut || out.heldOpen) {
+      terminal(res, 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 });
+  evt("client-response", { requested, actual: lastErr?.model ?? requested, via: "none", fallback: false, status: lastErr?.status ?? 502, reqId: handlerCtx.reqId });
+  terminal(res, lastErr?.message);
+  return true;
+}