fix(llm): drain delegated retry recovery

.agents/notes/implemented/feature/2026-07-24-provider-retry-policies.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-2026-07-24-provider-retry-policies.md: 0b9456eb1563bfcbfa06d93403fd68124ed1f707
-2026-07-24-provider-retry-policies.zh.md: d3ef90ec739eec7300b7d0bb526cb5de958ed93f
+2026-07-24-provider-retry-policies.md: 3799dbee9658c883f4084ac9c792d4552cc8e2fb
+2026-07-24-provider-retry-policies.zh.md: 8024ea707343686d2d1b1351cd7c81ecb8767b85

.agents/notes/implemented/feature/2026-07-24-provider-retry-policies.md

@@ -36,7 +36,7 @@ providers:
 
 The listener reads the provider from the durable `request/header` in force when the failed step closed, excluding later recovery mutations, but never re-resolves policy from the mutable provider registry. Normal mode retains the bounded transient behavior: it retries configured codes up to `maxRetries`, counts retries scheduled by the same provider policy in the current consecutive failure sequence, and otherwise delegates.
 
-Always mode asks downstream recovery first so a specialized policy such as context-overflow compaction can make progress. A downstream retry wins. A downstream failure decision or thrown recovery error falls back to an unbounded retry of the same provider request; the thrown error is logged. Success, turn cancellation, and plugin disposal are the only termination paths.
+Always mode asks downstream recovery first so a specialized policy such as context-overflow compaction can make progress. A downstream retry wins. A downstream failure decision or thrown recovery error falls back to an unbounded retry of the same provider request; the thrown error is logged. The retry listener owns and drains delegated recovery before cancellation or plugin disposal can finish, then applies the abort instead of a late downstream decision. Success, turn cancellation, and plugin disposal are the only termination paths.
 
 Both modes use exponential local delays from `initialDelayMs` to `maxDelayMs`. `jitterRatio` multiplies each target by a uniform sample in `[1 - jitterRatio, 1 + jitterRatio]`, then applies the cap. A positive provider `Retry-After` within the cap remains exact and unjittered. An over-cap provider delay makes normal mode delegate; always mode retains its guarantee by using the configured local backoff.
 
@@ -56,7 +56,7 @@ Each scheduled retry appends a non-surface `llm/retry` event with the failed pro
 
 ## Verification
 
-Adapter tests validate nested policies at provider load, prove registration captures configured and default policies, and retain the serving policy across in-flight route replacement. Unit and real-Loader composition tests select policies from the failed request's serving registration, exercise always mode beyond the normal budget, pin jitter and delay caps, prove downstream recovery ordering, prove cancellation interrupts stalled downstream recovery, and prove cancellation and disposal stop active backoff waits. Request-level coverage compares the complete messages of failed and retried attempts and rejects both provider error text and discarded partial output. JSONL and SQLite tests round-trip an always event without `Infinity`; invariant tests bind its provider to the request header and its retry number to the active provider policy; ACP and TUI tests render finite and infinite limits.
+Adapter tests validate nested policies at provider load, prove registration captures configured and default policies, and retain the serving policy across in-flight route replacement. Unit and real-Loader composition tests select policies from the failed request's serving registration, exercise always mode beyond the normal budget, pin jitter and delay caps, prove downstream recovery ordering, prove cancellation and disposal drain delegated recovery before reaching quiescence, and prove both abort active backoff waits. Request-level coverage compares the complete messages of failed and retried attempts and rejects both provider error text and discarded partial output. JSONL and SQLite tests round-trip an always event without `Infinity`; invariant tests bind its provider to the request header and its retry number to the active provider policy; TUI tests render finite and infinite limits.
 
 ## Consequences
 

.agents/notes/implemented/feature/2026-07-24-provider-retry-policies.zh.md

@@ -36,7 +36,7 @@ providers:
 
 监听器从失败步骤关闭时生效的持久 `request/header` 读取提供方，后续恢复产生的改动不参与选择，但绝不会从可变的提供方注册表重新解析策略。normal 模式保留有界瞬态错误处理行为：它重试配置的错误代码，次数不超过 `maxRetries`；在当前连续失败序列中，同一提供方策略安排的重试都计入次数；其他情况委托后续处理。
 
-always 模式先请求下游恢复，使上下文溢出压缩（compaction）之类的专用策略有机会取得进展。下游若决定重试，则以该决定为准。下游若决定失败或恢复过程抛出错误，则回退为无界重试同一提供方请求；抛出的错误会写入日志。成功、轮次取消和插件 dispose（资源释放）是仅有的终止路径。
+always 模式先请求下游恢复，使上下文溢出压缩（compaction）之类的专用策略有机会取得进展。下游若决定重试，则以该决定为准。下游若决定失败或恢复过程抛出错误，则回退为无界重试同一提供方请求；抛出的错误会写入日志。重试监听器会持有并排空已委托的恢复，轮次取消或插件 dispose（资源释放）只能在其结束后完成；随后监听器会应用取消，而不会采用迟到的下游决定。成功、轮次取消和插件 dispose 是仅有的终止路径。
 
 两种模式的本地延迟都按指数增长，从 `initialDelayMs` 增至 `maxDelayMs`。`jitterRatio` 用 `[1 - jitterRatio, 1 + jitterRatio]` 区间内的均匀随机样本乘以每次目标值，再应用上限。提供方给出的正数 `Retry-After` 若未超过上限，则保持精确且不加抖动。若提供方延迟超过上限，normal 模式会委托后续处理；always 模式则改用配置的本地退避，以维持无限重试保证。
 
@@ -56,7 +56,7 @@ always 模式先请求下游恢复，使上下文溢出压缩（compaction）之
 
 ## 验证
 
-适配器测试会在提供方加载时校验嵌套策略，证明注册流程会捕获已配置策略和默认策略，并证明请求进行期间替换路由后仍会保留实际提供服务的策略。单元测试与真实 Loader 组合测试根据失败请求实际使用的注册项选择策略、验证 always 模式可越过 normal 预算、固定抖动和延迟上限、证明下游恢复顺序、证明取消会中断停滞的下游恢复，并证明取消与 dispose 会停止正在进行的退避等待。请求级覆盖会比较失败尝试与重试尝试的完整消息，并排除提供方错误文本和丢弃的部分输出。JSONL 与 SQLite 测试会往返读写不含 `Infinity` 的 always 事件；不变式测试会将事件中的提供方绑定到请求头，并将重试编号绑定到活跃的提供方策略；ACP 与 TUI 测试会分别渲染有限和无限上限。
+适配器测试会在提供方加载时校验嵌套策略，证明注册流程会捕获已配置策略和默认策略，并证明请求进行期间替换路由后仍会保留实际提供服务的策略。单元测试与真实 Loader 组合测试根据失败请求实际使用的注册项选择策略、验证 always 模式可越过 normal 预算、固定抖动和延迟上限、证明下游恢复顺序、证明取消与 dispose 会在达到静止状态前排空已委托的恢复，并证明二者都会停止正在进行的退避等待。请求级覆盖会比较失败尝试与重试尝试的完整消息，并排除提供方错误文本和丢弃的部分输出。JSONL 与 SQLite 测试会往返读写不含 `Infinity` 的 always 事件；不变式测试会将事件中的提供方绑定到请求头，并将重试编号绑定到活跃的提供方策略；TUI 测试会渲染有限和无限上限。
 
 ## 后果
 

packages/examples/acp-demo/README.md

@@ -33,7 +33,6 @@ The app does not install commands, user interaction, session navigation, configu
 | `toolBash` | owner defaults | Model-facing bash tool config. |
 | `toolTasks` | owner defaults | Generic background-task control config, or `false`. |
 | `goals` | owner defaults | Persisted same-session goal domain and model tools, or `false`. |
-| `llmRetry` | owner defaults | Provider-owned normal or unbounded model-request retry policy. |
 
 The shipped [`examples/acp-agent/cordis.yml`](../../../examples/acp-agent/cordis.yml) adds the DeepSeek adapter, sandboxed bash and filesystem providers, one-shot approval policy, compaction, subagents, workflows, hooks, and model-facing tools. Snapshot overlays replace only nondeterministic providers or policy values.
 

packages/llm/llm-retry/README.md

@@ -2,11 +2,11 @@
 
 Function plugin that applies exact-provider retry policy on the agent loop's closed-step recovery seam. It does not wrap `ctx.llm.stream()`: every adapter call remains one provider attempt, and every retry opens a fresh numbered step.
 
-Each provider adapter owns an optional nested `retryPolicy`, captured when its route registers on `ctx.llm` and carried with each call that reaches that registration's final adapter boundary. An in-flight failure retains that serving policy if the route is later disposed or replaced; a failure before any final adapter is selected has no provider policy and delegates. Omission uses normal mode: two retries for `RATE_LIMIT`, `SERVER`, `TIMEOUT`, and `TRANSPORT`. A normal policy can change its finite budget, eligible codes, and backoff. Always mode asks downstream recovery first, then retries every model-request failure without an attempt limit; success, cancellation, or plugin disposal stops it.
+Each provider adapter owns an optional nested `retryPolicy`, captured when its route registers on `ctx.llm` and carried with each call that reaches that registration's final adapter boundary. An in-flight failure retains that serving policy if the route is later disposed or replaced; a failure before any final adapter is selected has no provider policy and delegates. Omission uses normal mode: two retries for `RATE_LIMIT`, `SERVER`, `TIMEOUT`, and `TRANSPORT`. A normal policy can change its finite budget, eligible codes, and backoff. Always mode asks downstream recovery first, then retries every model-request failure without an attempt limit; success, cancellation, or plugin disposal stops it after active delegated recovery reaches quiescence.
 
 Both modes use bounded exponential backoff with symmetric jitter. A valid `providerRetryAfterMs` at or below `maxDelayMs` replaces local backoff without jitter. An over-cap provider delay makes normal mode delegate, while always mode uses its configured local backoff so it cannot terminate on that instruction.
 
-Before waiting, the plugin appends a non-surface `llm/retry` event with the provider, mode, failure, and scheduled delay. Normal events include the finite maximum; always events omit it, and UIs render `∞`. Cancellation and plugin disposal abort the wait; disposal drains active backoffs, and a callback captured before disposal fails closed.
+Before waiting, the plugin appends a non-surface `llm/retry` event with the provider, mode, failure, and scheduled delay. Normal events include the finite maximum; always events omit it, and UIs render `∞`. Cancellation and plugin disposal abort active backoff, drain active delegated recovery before applying the abort, and make a callback captured before disposal fail closed.
 
 The separately published `./invariant` companion checks that every retry record names the current open turn and latest closed step, matches the failed request's durable provider, has a unique step record and correct provider-policy retry number, and carries a valid mode-specific budget and bounded timer delay. Full jitter may schedule zero milliseconds at its lower boundary.
 
@@ -46,5 +46,5 @@ The reconstructed request preserves the prior prefix and is eligible for provide
 
 - **Agent steps are the only retry boundary** — direct `ctx.llm.stream()` consumers remain single-attempt because a raw stream cannot separate already-emitted chunks durably.
 - **Always mode retries permanent failures** — authentication, quota, invalid-request, protocol, and unrecoverable context errors continue until success, cancellation, or disposal; deployments own provider-specific cost and latency controls.
-- **Recovery policies compose by waterfall order** — always mode accepts a downstream retry before applying its fallback. A later policy that never settles also prevents the fallback from running.
+- **Recovery policies compose by waterfall order** — always mode accepts a downstream retry before applying its fallback. A later policy that ignores cancellation and never settles also prevents fallback, turn quiescence, and plugin disposal from completing.
 - **`llm/retry` records scheduling, not completion** — later step and turn events establish success, exhaustion, or cancellation.

packages/llm/llm-retry/src/index.ts

@@ -63,32 +63,15 @@ export interface RetryInternals {
 type DownstreamOutcome =
   | { readonly type: 'decision'; readonly decision: RequestErrorDecision }
   | { readonly type: 'error'; readonly error: unknown }
-  | { readonly type: 'aborted' }
 
-function downstreamUntilAbort(
+async function settleDownstream(
   next: () => Promise<RequestErrorDecision>,
-  signal: AbortSignal,
 ): Promise<DownstreamOutcome> {
-  if (signal.aborted) return Promise.resolve({ type: 'aborted' })
-  return new Promise((resolve) => {
-    const finish = (outcome: DownstreamOutcome): void => {
-      signal.removeEventListener('abort', onAbort)
-      resolve(outcome)
-    }
-    const onAbort = (): void => { finish({ type: 'aborted' }) }
-    signal.addEventListener('abort', onAbort, { once: true })
-    let downstream: Promise<RequestErrorDecision>
-    try {
-      downstream = next()
-    } catch (error: unknown) {
-      finish({ type: 'error', error })
-      return
-    }
-    void downstream.then(
-      (decision) => { finish({ type: 'decision', decision }) },
-      (error: unknown) => { finish({ type: 'error', error }) },
-    )
-  })
+  try {
+    return { type: 'decision', decision: await next() }
+  } catch (error: unknown) {
+    return { type: 'error', error }
+  }
 }
 
 function localDelay(config: ResolvedRetryPolicy, retry: number, random: () => number): number {
@@ -125,6 +108,12 @@ export function apply(ctx: Context, config: Config = {}, internals: RetryInterna
   const lifetime = new AbortController()
   const active = new Set<Promise<RequestErrorDecision>>()
 
+  function track(operation: Promise<RequestErrorDecision>): Promise<RequestErrorDecision> {
+    const tracked = operation.finally(() => active.delete(tracked))
+    active.add(tracked)
+    return tracked
+  }
+
   async function backoff(
     agent: Agent,
     turn: number,
@@ -163,7 +152,7 @@ export function apply(ctx: Context, config: Config = {}, internals: RetryInterna
     return { action: 'retry' }
   }
 
-  const disposeListener = ctx.on('agent/request-error', async (
+  async function recover(
     agent: Agent,
     turn: number,
     step: number,
@@ -173,11 +162,7 @@ export function apply(ctx: Context, config: Config = {}, internals: RetryInterna
     policy: ResolvedRetryPolicy | undefined,
     signal: AbortSignal,
     next: () => Promise<RequestErrorDecision>,
-  ) => {
-    // A waterfall may have captured this callback before its registration was
-    // removed. Lifetime cancellation must prevent that stale callback from
-    // entering a downstream policy after disposal.
-    if (lifetime.signal.aborted) return Promise.resolve<RequestErrorDecision>({ action: 'fail' })
+  ): Promise<RequestErrorDecision> {
     if (policy === undefined) return next()
     // The call-local policy belongs to the registration that served this
     // failure. Recover only the durable provider identity from the header;
@@ -188,11 +173,12 @@ export function apply(ctx: Context, config: Config = {}, internals: RetryInterna
       throw new Error(`llm-retry: no request provider for closed turn ${turn}/step ${step}`)
     }
     if (policy.mode === 'always') {
-      const downstream = await downstreamUntilAbort(
-        next,
-        AbortSignal.any([signal, lifetime.signal]),
-      )
-      if (downstream.type === 'aborted') return { action: 'fail' }
+      if (signal.aborted || lifetime.signal.aborted) return { action: 'fail' }
+      const fusedSignal = AbortSignal.any([signal, lifetime.signal])
+      // The loop and plugin lifetime stay open until delegated recovery settles.
+      // An abort then wins before the decision or fallback can mutate later state.
+      const downstream = await settleDownstream(next)
+      if (fusedSignal.aborted) return { action: 'fail' }
       if (downstream.type === 'error') {
         ctx.logger.warn(
           `llm-retry: provider "${provider}" always policy ignored a downstream recovery failure: %o`,
@@ -232,15 +218,30 @@ export function apply(ctx: Context, config: Config = {}, internals: RetryInterna
       delayMs = localDelay(policy, retry, random)
     }
 
-    const tracked = backoff(agent, turn, step, failure, provider, policy, retry, delayMs, signal)
-      .finally(() => active.delete(tracked))
-    active.add(tracked)
-    return tracked
+    return backoff(agent, turn, step, failure, provider, policy, retry, delayMs, signal)
+  }
+
+  const disposeListener = ctx.on('agent/request-error', (
+    agent: Agent,
+    turn: number,
+    step: number,
+    error: RequestError,
+    failure: LlmFailure,
+    priorFailures: readonly LlmFailure[],
+    policy: ResolvedRetryPolicy | undefined,
+    signal: AbortSignal,
+    next: () => Promise<RequestErrorDecision>,
+  ) => {
+    // A waterfall may have captured this callback before its registration was
+    // removed. Lifetime cancellation must prevent that stale callback from
+    // entering a downstream policy after disposal.
+    if (lifetime.signal.aborted) return Promise.resolve<RequestErrorDecision>({ action: 'fail' })
+    return track(recover(agent, turn, step, error, failure, priorFailures, policy, signal, next))
   })
 
   ctx.effect(() => async () => {
     disposeListener()
     lifetime.abort(new Error('llm-retry plugin disposed'))
     await Promise.allSettled([...active])
-  }, 'llm-retry: abort and drain backoffs')
+  }, 'llm-retry: abort and drain active recovery')
 }

packages/llm/llm-retry/tests/retry.spec.ts

@@ -706,61 +706,80 @@ describe('provider-routed retry policy', () => {
     expect(vi.getTimerCount()).toBe(0)
   })
 
-  it('does not make plugin disposal wait for a delegated recovery policy', async () => {
+  it('drains delegated recovery before completing plugin disposal', async () => {
     const adapter = new ScriptedAdapter([new LlmError('bad key', 'AUTH')])
     const mounted = await harness(adapter, { mock: alwaysConfig() })
     context = mounted.ctx
-    const downstream = Promise.withResolvers<RequestErrorDecision>()
+    const release = Promise.withResolvers<undefined>()
     const entered = Promise.withResolvers<undefined>()
-    context.on('agent/request-error', () => {
+    const order: string[] = []
+    context.on('agent/request-error', async () => {
       entered.resolve(undefined)
-      return downstream.promise
+      await release.promise
+      order.push('downstream')
+      return { action: 'retry' }
     })
     const agent = context.agentLoop.create(SessionId('retry-delegated-disposal'), {
       provider: 'mock',
       model: 'mock',
     })
-    const idle = waitForIdle(context, agent)
+    const idle = waitForIdle(context, agent).then(() => { order.push('idle') })
     agent.followup([{ type: 'text', text: 'go' }])
     await entered.promise
 
-    const disposing = mounted.retryFiber.dispose()
+    const disposing = mounted.retryFiber.dispose().then(() => { order.push('disposed') })
     let timer: ReturnType<typeof setTimeout> | undefined
     const outcome = await Promise.race([
       disposing.then(() => 'disposed' as const),
       new Promise<'blocked'>((resolve) => { timer = setTimeout(() => { resolve('blocked') }, 100) }),
     ])
     if (timer !== undefined) clearTimeout(timer)
-    downstream.resolve({ action: 'fail' })
+    expect(outcome).toBe('blocked')
+
+    release.resolve(undefined)
     await disposing
     await idle
 
-    expect(outcome).toBe('disposed')
+    expect(order[0]).toBe('downstream')
+    expect(order).toEqual(expect.arrayContaining(['disposed', 'idle']))
     expect(adapter.requests).toHaveLength(1)
+    expect(agent.session.events.some(event => event.type === 'llm/retry')).toBe(false)
   })
 
-  it('lets turn cancellation interrupt a delegated recovery policy', async () => {
+  it('drains delegated recovery before turn cancellation reaches idle', async () => {
     const adapter = new ScriptedAdapter([new LlmError('bad key', 'AUTH')])
     const mounted = await harness(adapter, { mock: alwaysConfig() })
     context = mounted.ctx
     const downstream = Promise.withResolvers<RequestErrorDecision>()
     const entered = Promise.withResolvers<undefined>()
-    context.on('agent/request-error', () => {
+    const order: string[] = []
+    context.on('agent/request-error', async () => {
       entered.resolve(undefined)
-      return downstream.promise
+      const decision = await downstream.promise
+      order.push('downstream')
+      return decision
     })
     const agent = context.agentLoop.create(SessionId('retry-delegated-cancel'), {
       provider: 'mock',
       model: 'mock',
     })
-    const idle = waitForIdle(context, agent)
+    const idle = waitForIdle(context, agent).then(() => { order.push('idle') })
     agent.followup([{ type: 'text', text: 'go' }])
     await entered.promise
 
     agent.cancel({ kind: 'user' })
-    await idle
-    downstream.resolve({ action: 'fail' })
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const outcome = await Promise.race([
+      idle.then(() => 'idle' as const),
+      new Promise<'blocked'>((resolve) => { timer = setTimeout(() => { resolve('blocked') }, 100) }),
+    ])
+    if (timer !== undefined) clearTimeout(timer)
+    expect(outcome).toBe('blocked')
 
+    downstream.resolve({ action: 'retry' })
+    await idle
+
+    expect(order).toEqual(['downstream', 'idle'])
     expect(adapter.requests).toHaveLength(1)
     expect(agent.session.events.at(-1)).toMatchObject({
       type: 'turn/end',
@@ -773,8 +792,10 @@ describe('provider-routed retry policy', () => {
     const mounted = await harness(adapter, { mock: alwaysConfig() })
     context = mounted.ctx
     const downstream = Promise.withResolvers<RequestErrorDecision>()
+    const entered = Promise.withResolvers<undefined>()
     context.on('agent/request-error', (agent) => {
       agent.cancel({ kind: 'user' })
+      entered.resolve(undefined)
       return downstream.promise
     })
     const agent = context.agentLoop.create(SessionId('retry-delegated-sync-cancel'), {
@@ -784,8 +805,17 @@ describe('provider-routed retry policy', () => {
     const idle = waitForIdle(context, agent)
 
     agent.followup([{ type: 'text', text: 'go' }])
+    await entered.promise
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const outcome = await Promise.race([
+      idle.then(() => 'idle' as const),
+      new Promise<'blocked'>((resolve) => { timer = setTimeout(() => { resolve('blocked') }, 100) }),
+    ])
+    if (timer !== undefined) clearTimeout(timer)
+    expect(outcome).toBe('blocked')
+
+    downstream.resolve({ action: 'retry' })
     await idle
-    downstream.resolve({ action: 'fail' })
 
     expect(adapter.requests).toHaveLength(1)
     expect(agent.session.events.at(-1)).toMatchObject({