dsh-router-core 0.3.21 → 0.4.1

package/src/router/account-pool.ts

@@ -24,7 +24,7 @@
  * 得落盘，届时加 stateFile 即可，接口不用变。
  */
 import type { AccountState, SupplierAccountNow } from '../suppliers/contract.ts'
-import { prefixFingerprint } from './prefix-affinity.ts'
+import { sessionFingerprint } from './prefix-affinity.ts'
 
 /** 各 AccountState 的处置：冷却策略 / 是否计入连续错误。 */
 interface Rule {
@@ -182,9 +182,9 @@ export class AccountPool {
   private rrCursor = 0
   /** (supplier, model) → 当前驻留的号（只有**无亲和**的回退路径用它）。 */
   private blocks = new Map<string, string>()
-  /** (supplier, model, uid) → 该号的缓存质量样本（降权判据，跨驻留累计）。 */
+  /** (supplier, model, uid[, session]) → 该号在某会话下的缓存质量样本。 */
   private samples = new Map<string, Sample>()
-  /** (supplier, model, uid) → 缓存无效降权。 */
+  /** 同上键 → 缓存无效降权。 */
   private demoted = new Map<string, DemoteEntry>()
   /** (supplier, model) → Map<前缀指纹, uid>：前缀亲和的选号记忆（LRU 封顶）。 */
   private affinity = new Map<string, Map<string, string>>()
@@ -197,6 +197,23 @@ export class AccountPool {
     return `${this.supplierId}${SEP}${model}${SEP}${uid}`
   }
 
+  /**
+   * 缓存质量样本/降权的键。
+   *
+   * **按会话隔离**（team 场景的关键）：同一个号被多个会话共用时，各会话的
+   * 前缀会互相驱逐，把它们混在一起算命中率，会把「多会话互踩」误判成
+   * 「这个号缓存坏了」→ 错误降权 → 只剩一个号 → 那个号又被打低 → 降权串。
+   * 所以有会话身份时按 (model, uid, session) 记，降权只反映**该会话自己**
+   * 在这个号上的真实缓存表现。
+   *
+   * 无会话身份（外部 OpenAI 客户端，走无指纹回退路径）→ 保持 (model, uid)，
+   * 与块轮询的原语义一致（那时本就是单会话视角）。
+   */
+  private sampleKey(model: string, uid: string, session?: string): string {
+    const base = this.key(model, uid)
+    return session === undefined || session === '' ? base : `${base}${SEP}${session}`
+  }
+
   private entry(model: string, uid: string): CooldownEntry {
     const k = this.key(model, uid)
     let e = this.cooldowns.get(k)
@@ -236,30 +253,32 @@ export class AccountPool {
   }
 
   /**
-   * 按策略为「某个模型」选一个健康账号。
+   * 为「某个模型」选一个健康账号 —— **会话亲和选号，无策略旋钮**。
    *
-   * round-robin = **前缀亲和定号 + 块统计只用来判定缓存无效**：
+   * 旧的两策略（fallback 取第一个 / round-robin 轮转）都删了：前者让所有
+   * 会话挤同一个号（team/多会话必互踩），后者的"轮转"与亲和"同会话永不换号"
+   * 直接冲突。正确模型只有一条：
    *
    *  1. 算请求的前缀指纹（messages 前几条），查绑定表 → 命中且该号健康 → 用它。
-   *     这是第一优先：同一个会话的连续请求**永远落回同一个号**，前缀在该号的
-   *     缓存里只写一份。块轮询治不了跨会话驱逐（多会话大前缀在同一号互踩，
-   *     实测 3 会话 3.8% vs 单会话 82.5%），亲和才是根治。
+   *     同一个会话的连续请求**永远落回同一个号**，前缀在该号缓存里只写一份。
    *  2. 新指纹（或绑定的号不健康）→ 按游标挑一个号并**记下绑定**，之后就固定。
    *     新会话用游标分发，所以不同会话天然散到不同号上（均衡）。
-   *  3. 块统计不再驱动轮转（亲和已经保证驻留，再轮转只会把会话踢出已热前缀），
-   *     只保留 `BLOCK_MAX` 次不达标 → 降权该号（缓存无效，可恢复）。
+   *  3. 指纹算不出（拿不到 messages）→ **块轮询兜底**（§2 旧行为）。这不是
+   *     "策略"，是无会话身份时的替身。
+   *  4. 块统计不驱动轮转（亲和已保证驻留），只保留 `BLOCK_MAX` 次不达标 →
+   *     降权该号（缓存无效，可恢复）。
    *
-   * 亲和失效（拿不到 messages / 指纹算不出）时**回退到块轮询**，行为与之前一致。
-   * 设计见 docs/pool-sticky-block.md §8。
+   * 天花板：号数 < 并发会话数时必然有会话共用号 → 互踩，无法用选号手法消除
+   * （缓存空间是账号侧物理限制）。见 docs/pool-sticky-block.md §10。
    *
    * @param accounts 插件报告的「现在状态」（顺序即插件的自然顺序）
    * @param poolOrder 用户在面板拖出来的顺序（核心管）
-   * @param strategy fallback 取第一个健康 / round-robin 前缀亲和
    * @param modelId 当前要路由的模型（决定查哪个 (model, uid) 冷却单元）
-   * @param messages 请求体的 messages（可选；给了才能算前缀指纹）
+   * @param messages 请求体的 messages（算亲和指纹的内容兜底）
+   * @param session 宿主会话身份；给了就以它为主键（精确、零撞车）
    * @returns 选中的 uid；无健康账号返回 undefined
    */
-  pick(accounts: SupplierAccountNow[], poolOrder: string[], strategy: string, modelId: string, messages?: unknown): string | undefined {
+  pick(accounts: SupplierAccountNow[], poolOrder: string[], modelId: string, messages?: unknown, session?: string): string | undefined {
     const now = Date.now()
     const byUid = new Map(accounts.map((a) => [a.uid, a]))
     // 池顺序优先，未配置的按插件自然顺序追加
@@ -268,35 +287,98 @@ export class AccountPool {
       ...accounts.map((a) => a.uid).filter((uid) => !poolOrder.includes(uid)),
     ]
     const healthy = ordered.filter((uid) => this.healthy(uid, modelId, now))
-    if (healthy.length === 0) return undefined
-    if (strategy !== 'round-robin') return healthy[0]
+    if (healthy.length === 0) {
+      this.lastWhy = '全池无健康号（都在冷却）'
+      return undefined
+    }
     // 缓存无效降权：该号缓存质量样本长期不达标 → 跳过它（可到期恢复）
-    const usable = healthy.filter((uid) => !this.isDemoted(uid, modelId, now))
+    const usable = healthy.filter((uid) => !this.isDemoted(uid, modelId, now, session))
     const pool = usable.length > 0 ? usable : healthy
     // 前缀亲和：指纹有绑定且该号仍可用 → 直接复用（不进驻留逻辑）
-    const fp = messages === undefined ? '' : prefixFingerprint(messages)
-    if (fp !== '' && pool.includes(this.affinity.get(this.blockKey(modelId))?.get(fp) ?? '')) {
-      return this.affinity.get(this.blockKey(modelId))!.get(fp)!
+    const fp = sessionFingerprint(session, messages)
+    const bound = fp === '' ? undefined : this.affinity.get(this.blockKey(modelId))?.get(fp)
+    if (bound !== undefined && pool.includes(bound)) {
+      this.lastWhy = `亲和命中 ${bound}（会话/前缀已绑定）`
+      return bound
+    }
+    // 走到这里说明没粘住：把「为什么没用原绑定」记清楚，否则每次换号都要靠猜
+    const why: string[] = []
+    if (fp === '') {
+      why.push('无指纹（拿不到 messages/会话）')
+    } else if (bound === undefined) {
+      why.push('该指纹无绑定（会话首次出现）')
+    } else {
+      if (!healthy.includes(bound)) {
+        const c = this.cooldowns.get(this.key(modelId, bound))
+        why.push(`原绑定 ${bound} 正在冷却${c?.reason ? `(${c.reason})` : ''}`)
+      } else if (!usable.includes(bound)) {
+        why.push(`原绑定 ${bound} 被降权（本会话样本不达标）`)
+      } else {
+        why.push(`原绑定 ${bound} 不在当前健康池`)
+      }
     }
+    // 无指纹：沿用块轮询语义 —— 块内粘住（blockKeeps）则留守当前 block。
     const block = this.blocks.get(this.blockKey(modelId))
     if (fp === '' && block !== undefined && pool.includes(block) && this.blockKeeps(modelId, block)) {
+      this.lastWhy = `块驻留 ${block}（无指纹路径）`
       return block
     }
-    // 无亲和（或块满/块达标）→ 前进游标。从当前号之后开始找，保证轮转顺序稳定。
-    const from = block === undefined ? this.rrCursor : Math.max(0, pool.indexOf(block) + 1)
-    const uid = pool[from % pool.length]!
+    // 分配一个号并记住绑定。
+    //
+    // 有指纹（新会话）：**优先铺开到未被其它会话占用的号**——同 model 下
+    // 每个 fresh 会话尽量独占一个号（缓存空间隔离、互不驱逐），号不够时
+    // 才回绕复用（共用号无害：样本按会话语义隔离，不会误降权）。
+    // 候选顺序：先「空闲号」，用完后才是「已被占用的号」。
+    // 无指纹：沿用块轮询（从 block 之后前进，原语义不变）。
+    const uid = fp !== ''
+      ? this.allocSession(pool, modelId, fp)
+      : pool[(block === undefined ? this.rrCursor : Math.max(0, pool.indexOf(block) + 1)) % pool.length]!
     this.rrCursor = (pool.indexOf(uid) + 1) % pool.length
     this.blocks.set(this.blockKey(modelId), uid)
     if (fp !== '') {
       this.bind(modelId, fp, uid)
+      const free = this.freeUids(pool, modelId, fp)
+      why.push(free.length === 0 ? `号已铺满，按游标复用 ${uid}` : `铺开到空闲号 ${uid}`)
     } else {
       // 新驻留 = 新观察窗口（旧行为：块计数从 0 开始）。样本是跨驻留累计的，
       // 不清的话上一个大样本会立刻把新驻留判走。
       this.samples.delete(this.key(modelId, uid))
+      why.push(`块推进到 ${uid}`)
     }
+    this.lastWhy = why.join('；')
+    return uid
+  }
+
+  /**
+   * 新会话分配：优先返回**未被其它会话占用**的号（按游标推进），
+   * 空闲号用尽才回绕到已占用的号（此时按游标复用，语义等同旧行为）。
+   *
+   * 「占用」= 该 model 的绑定表里，某个 **其它** 指纹当前指向该 uid。
+   * 同一会话自己的旧绑定不算占用（它已经在上面的亲和分支处理过，走到这里
+   * 说明原绑定不可用，允许它改绑到自己的其它号或空闲号）。
+   */
+  private allocSession(pool: string[], modelId: string, fp: string): string {
+    const free = this.freeUids(pool, modelId, fp)
+    const candidates = free.length > 0 ? free : pool
+    const uid = candidates[this.rrCursor % candidates.length]!
     return uid
   }
 
+  /** 当前 model 下、本指纹之外没有任何其它会话绑定的号（按 pool 原顺序）。 */
+  private freeUids(pool: string[], modelId: string, fp: string): string[] {
+    const taken = new Set<string>()
+    const m = this.affinity.get(this.blockKey(modelId))
+    if (m !== undefined) {
+      for (const [k, v] of m) {
+        if (k !== fp) taken.add(v)
+      }
+    }
+    return pool.filter((uid) => !taken.has(uid))
+  }
+
+  /** 上一次 pick 的选号理由（诊断用：解释"为什么没粘住原号"）。 */
+  lastWhy = ''
+
   /** 记下「前缀指纹 → 号」的绑定（LRU：超上限丢最久未用的）。 */
   private bind(modelId: string, fp: string, uid: string): void {
     const k = this.blockKey(modelId)
@@ -314,9 +396,14 @@ export class AccountPool {
     }
   }
 
-  /** 该号在本模型上是否被判定「缓存无效」（降权中）。 */
-  private isDemoted(uid: string, modelId: string, now: number): boolean {
-    const e = this.demoted.get(this.key(modelId, uid))
+  /**
+   * 该号在**本会话**（有身份时）本模型上是否被判定「缓存无效」（降权中）。
+   *
+   * 判据按会话隔离（见 sampleKey）：降权只惩罚「这个会话在这个号上真的
+   * 反复不命中」，不会因别的会话共用同号互踩而被牵连。
+   */
+  private isDemoted(uid: string, modelId: string, now: number, session?: string): boolean {
+    const e = this.demoted.get(this.sampleKey(modelId, uid, session))
     return e !== undefined && e.until > now
   }
 
@@ -344,14 +431,16 @@ export class AccountPool {
    * 记录一次成功请求的缓存命中情况（降权判据的反馈信号）。
    *
    * 只有**成功**请求才计入：失败没产生缓存，计入会污染命中率并导致错降权。
-   * 统计按 (model, uid) 记，**不管这个号是不是「当前驻留」**——亲和开启后
-   * 多个会话各绑各的号交错服务，按驻留记会漏掉大部分真实反馈。
+   * 统计按 (model, uid[, session]) 记，**不管这个号是不是「当前驻留」**——
+   * 亲和开启后多个会话各绑各的号交错服务，按驻留记会漏掉大部分真实反馈。
+   * 按会话隔离（见 sampleKey）则保证「多会话共用同号互踩」不会误伤降权。
    * @param uid 实际服务的号
    * @param modelId 模型（块粒度）
    * @param cachedTokens 上游报的命中 token 数；0 = 全量重算
+   * @param session 宿主会话身份；有则按会话隔离统计
    */
-  noteCache(uid: string, modelId: string, cachedTokens: number): void {
-    const k = this.key(modelId, uid)
+  noteCache(uid: string, modelId: string, cachedTokens: number, session?: string): void {
+    const k = this.sampleKey(modelId, uid, session)
     const s = this.samples.get(k) ?? { served: 0, hits: 0 }
     s.served += 1
     if (cachedTokens > 0) s.hits += 1

package/src/router/disconnect-leak.test.ts

@@ -158,28 +158,24 @@ test('客户端断开：上游流 cancel 链要穿过 tapStreamUsage / normalize
   assert.equal(leak.cancelled(), true, '取消必须穿过两层 wrapper 到达上游')
 })
 
-test('聚合失败：reader 必须被解绑（否则连接还活着时上层无法 cancel）', async () => {
+test('聚合失败：上游流必须被回收（解锁，不能永久锁死）', async () => {
   // 这一条测的**不是**「cancel 回调有没有触发」——那测不出东西：
   // 实测结论（两个都验过）：
   //   - 流 error 后调 cancel()，只会以同一错误 reject，**不触发** cancel 回调
   //     （`pull()` 抛错会把流置为 errored；上游拆连接则流直接 error）
   //   - 这两种情况下 undici **已经自己关了连接**，不需要我们 cancel
-  // 所以聚合失败路径真正要保证的是 **reader 被解绑**：流锁着的话，上层
+  // 所以聚合失败路径真正要保证的是 **上游流不再被锁着**：锁着的话上层
   // （writeChatResult 的失败路径 / 未来的取消逻辑）想 cancel 都会抛
   // `Invalid state: ReadableStream is locked`，连接就永久漏了。
-  let releaseLocked = false
+  //
+  // 注意拓扑：核心现在隔着「首字节截止」wrapper（withFirstByteDeadline）读上游，
+  // 所以判据只能是**最终状态**（locked=false），不能再断言核心直接 releaseLock
+  // 上游的 reader —— 中间隔了一层，核心只会解锁 wrapper 那个 reader。
   const enc = new TextEncoder()
   const failing = new ReadableStream<Uint8Array>({
     start(c) { c.enqueue(enc.encode('data: {"choices":[{"delta":{"content":"a"}}]}\n\n')) },
     pull() { throw new Error('aggregate read failed') },
   })
-  const origGetReader = failing.getReader.bind(failing)
-  ;(failing as unknown as { getReader: () => unknown }).getReader = () => {
-    const r = origGetReader()
-    const origRelease = r.releaseLock.bind(r)
-    r.releaseLock = () => { releaseLocked = true; origRelease() }
-    return r
-  }
 
   const router = new Router('')
   router.add(supplierWith(failing) as never)
@@ -195,8 +191,7 @@ test('聚合失败：reader 必须被解绑（否则连接还活着时上层无
   )
   await new Promise((r) => setTimeout(r, 150))
 
-  assert.equal(releaseLocked, true, '聚合失败后必须 releaseLock，否则流锁死、上层无法回收')
-  assert.equal(failing.locked, false, '流必须处于未锁定状态（可被 cancel / 已被回收）')
+  assert.equal(failing.locked, false, '上游流必须处于未锁定状态（可被 cancel / 已被回收）')
 })
 
 test('fixFrame：把后续 delta 里重发成 null 的 id/name 剥掉（否则外部 OpenAI 客户端会丢工具名）', async () => {

package/src/router/first-byte-budget.test.ts

@@ -0,0 +1,160 @@
+/**
+ * 首字节预算测试 —— 组合的一条腿「连上了、200 了、就是不吐字节」时必须降级。
+ *
+ * 2026-09-24 夜里的现场（usage.json / 三个 session 的 step 时间线互相对齐）：
+ * money 组合第一腿 codebuddy-en 卡住，ttfb 分别 84s / 122s / 151s / 244s / 246s /
+ * 250s / 254s / 255s，**8 次全部 ok: true**——全都最终成功了，只是晚了四分钟。
+ * 用户干等 200 多秒手动暂停。
+ *
+ * 为什么以前不会降级：停滞既不是成功也不是失败，所以
+ *   - 插件的 120s 只守「连接 + 响应头」（fetch 一返回就撤表），守不到 body
+ *   - 核心写响应的路径没有计时器，组合链卡在这一条腿上一动不动
+ *   - 该号也不会被冷却（没失败 → noteFailure 不触发）→ 下次还挑它
+ *
+ * 这里守的是修复后的语义：**预算到就判失败，链往前走**。没装这个闸门时
+ * 下面两条测试都会在 5s 的看门狗里超时变红（而不是把测试进程挂死）。
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import type { ServerResponse } from 'node:http'
+import { Router, withFirstByteDeadline } from './index.ts'
+import { AccountPool } from './account-pool.ts'
+import type { ModelInfo } from './types.ts'
+import type { AccountPool as Pool } from './account-pool.ts'
+import type { ChatOnceResult, SupplierAccountNow, SupplierStatusNow } from '../suppliers/contract.ts'
+
+const enc = new TextEncoder()
+
+/** 永不吐字节的流（模拟「200 响应头到手，body 停摆」），记录有没有被 cancel。 */
+function stallingStream(): { stream: ReadableStream<Uint8Array>; cancelled: () => boolean } {
+  let cancelled = false
+  const stream = new ReadableStream<Uint8Array>({
+    cancel() { cancelled = true },
+  })
+  return { stream, cancelled: () => cancelled }
+}
+
+/** 立刻吐一帧 + [DONE] 的正常流。 */
+function healthyStream(text: string): ReadableStream<Uint8Array> {
+  return new ReadableStream<Uint8Array>({
+    start(ctrl) {
+      ctrl.enqueue(enc.encode(`data: {"choices":[{"delta":{"content":"${text}"}}]}\n\n`))
+      ctrl.enqueue(enc.encode('data: [DONE]\n\n'))
+      ctrl.close()
+    },
+  })
+}
+
+function supplier(id: string, uids: string[], chatOnce: (uid: string) => Promise<ChatOnceResult>) {
+  const accounts: SupplierAccountNow[] = uids.map((uid) => ({ uid, credits: 0, state: 'ok' as const }))
+  return {
+    id, name: id, priority: 0, pool: new AccountPool(id) as Pool,
+    status: (): SupplierStatusNow => ({ id, name: id, accounts }),
+    listModels: async (): Promise<ModelInfo[]> => [{ id: 'm1' }],
+    getAlias: () => id,
+    accounts: () => accounts,
+    chatOnce,
+    dispose: () => {},
+  }
+}
+
+function captureRes(): { res: ServerResponse; body: () => string } {
+  const chunks: string[] = []
+  const text = (chunk: unknown): string =>
+    chunk instanceof Uint8Array ? new TextDecoder().decode(chunk) : String(chunk)
+  const res = {
+    writableEnded: false,
+    destroyed: false,
+    writeHead: (): unknown => undefined,
+    write: (chunk?: unknown): boolean => { chunks.push(text(chunk)); return true },
+    end: (chunk?: unknown): unknown => { if (chunk !== undefined) chunks.push(text(chunk)); return undefined },
+    once: (): unknown => undefined,
+    removeListener: (): unknown => undefined,
+    destroy: (): unknown => undefined,
+  } as unknown as ServerResponse
+  return { res, body: () => chunks.join('') }
+}
+
+const req = {
+  model: 'c',
+  stream: true,
+  rawBody: JSON.stringify({ model: 'c', messages: [{ role: 'user', content: 'hi' }], stream: true }),
+}
+
+/** 给等待加看门狗：闸门没装时这里是 5s 超时（红），而不是把测试挂死。 */
+async function within<T>(ms: number, run: () => Promise<T>): Promise<T> {
+  return await Promise.race([
+    run(),
+    new Promise<T>((_, reject) => setTimeout(() => reject(new Error(`组合 ${ms}ms 内没有降级`)), ms)),
+  ])
+}
+
+test('第一腿停滞：预算到就判失败，落到下一条腿（而不是把请求挂到客户端自己放弃）', async () => {
+  const stall = stallingStream()
+  const router = new Router('', undefined, undefined, { firstByteBudgetMs: 150 })
+  router.add(supplier('supA', ['a1'], async () => ({ ok: true, stream: stall.stream })) as never)
+  router.add(supplier('supB', ['b1'], async () => ({ ok: true, stream: healthyStream('ok-from-B') })) as never)
+  assert.equal(router.createCombo('c', ['supA,m1', 'supB,m1']).ok, true)
+
+  const { res, body } = captureRes()
+  const t0 = Date.now()
+  await within(5_000, () => router.chatCompletions(req, res))
+  const elapsed = Date.now() - t0
+
+  assert.match(body(), /ok-from-B/, '必须由第二条腿服务（第一腿 200 了但不吐字节）')
+  assert.equal(stall.cancelled(), true, '停滞的上游流必须被 cancel，否则连接原样挂着')
+  // 2s 是组合「喘口气」等待（TRANSIENT_SETTLE_MS）——停滞按 transport 归类，
+  // 该等就得等；这里断言它确实走了「失败→降级」这条路，而不是瞬间成功。
+  assert.ok(elapsed >= 2_000, `应先等喘口气窗口再降级，实际 ${elapsed}ms`)
+  assert.ok(elapsed < 5_000, `降级必须发生在预算+喘口气附近，实际 ${elapsed}ms`)
+})
+
+test('预算是「每条腿」一份：腿内第二个号不再各等一次（否则 60s × 号数）', async () => {
+  const stallA1 = stallingStream()
+  const stallA2 = stallingStream()
+  let a1 = 0
+  let a2 = 0
+  const router = new Router('', undefined, undefined, { firstByteBudgetMs: 150 })
+  router.add(supplier('supA', ['a1', 'a2'], async (uid) => {
+    if (uid === 'a1') { a1 += 1; return { ok: true, stream: stallA1.stream } }
+    a2 += 1
+    return { ok: true, stream: stallA2.stream }
+  }) as never)
+  router.add(supplier('supB', ['b1'], async () => ({ ok: true, stream: healthyStream('ok-from-B') })) as never)
+  assert.equal(router.createCombo('c', ['supA,m1', 'supB,m1']).ok, true)
+
+  const { res, body } = captureRes()
+  const t0 = Date.now()
+  await within(5_000, () => router.chatCompletions(req, res))
+  const elapsed = Date.now() - t0
+
+  assert.match(body(), /ok-from-B/)
+  assert.equal(a1, 1, '第一个号被调了一次')
+  assert.equal(a2, 0, '预算已耗尽：同一个号池里的第二个号不该再各等 150ms（停滞是上游级的）')
+  assert.ok(elapsed < 5_000, `不能按号数翻倍地等，实际 ${elapsed}ms`)
+})
+
+test('wrapper：第一个字节到手后不再计时（长生成不能被砍）', async () => {
+  let ctrlRef: ReadableStreamDefaultController<Uint8Array> | undefined
+  const src = new ReadableStream<Uint8Array>({ start: (c) => { ctrlRef = c } })
+  const reader = withFirstByteDeadline(src, 60).getReader()
+
+  ctrlRef?.enqueue(enc.encode('first'))
+  assert.equal(dec((await reader.read()).value!), 'first')
+  // 停 3 倍预算才吐第二块：过了截止点也必须原样透传
+  await new Promise((r) => setTimeout(r, 200))
+  ctrlRef?.enqueue(enc.encode('second'))
+  assert.equal(dec((await reader.read()).value!), 'second')
+  await reader.cancel()
+})
+
+test('wrapper：源流一个字节都不吐就到期 → 流判失败（上层据此换号/换模型）', async () => {
+  const { stream, cancelled } = stallingStream()
+  const reader = withFirstByteDeadline(stream, 60).getReader()
+  await assert.rejects(() => reader.read(), /no first byte within 60ms/)
+  assert.equal(cancelled(), true, '到期时必须把取消传给源流（否则上游连接原样挂着）')
+})
+
+function dec(v: Uint8Array): string {
+  return new TextDecoder().decode(v)
+}