Skip to content

fix: don't arm the auto-fold backoff on pure queue-drops (#2662) - #2665

Merged
ranxianglei merged 3 commits into
masterfrom
2026-10-10_autofold-backoff-queue-drop
Oct 11, 2026
Merged

ranxianglei merged 3 commits into
masterfrom
2026-10-10_autofold-backoff-queue-drop

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #2662

来源: #2657 分析 external-summary 并发池配置化时发现(issue 自带来源标记)。相关但不同机制:#2661(池大小可配置——缓解拥塞本身)、#2639(deadline harvest)——均不在本 PR 范围。

Behavior change disclosure (old → new)

Old: a growth-armed auto-fold request that ended with zero folds (site A) or short of autoFoldTargetTokens (site B) ALWAYS armed the 10-minute AUTO_FOLD_BACKOFF_MS cooldown — regardless of why nothing folded. A batch dropped by the saturated process-wide pool before any summary call dispatched (executeBatch status deadline/cancelled, all attempts=[]) was indistinguishable from a real provider failure, so congested hosts lost 10 minutes of auto-fold per pure queue drop — the oscillation #2657's reporter observed (32/402 batches, all attempts=[]).

New: dispatch telemetry flows from ConfiguredSummaryPlan.stats through PreflightResult.externalDispatch to both arm sites. A pure queue drop (calls > 0 && attempts === 0) logs a distinct warn line ("no summary attempt was ever dispatched … congestion, not a chain failure — NOT backing off") and does not arm the cooldown; auto-fold retries on the next turn. Any fold that actually dispatched at least one candidate call (provider error / timeout / invalid summary) arms exactly as before. Classic non-external preflights are unchanged (externalDispatch absent → predicate false).

Why: a queue drop is scheduler congestion — transient by nature, cleared by the pool draining. Cooling down for 10 minutes punishes the session exactly while the host is most loaded. The backoff exists to cool down against chain failures, which requires evidence that a call was attempted.

Changes

  • src/external-summary-runtime.ts: ConfiguredSummaryPlan.stats = { calls, attempts } incremented in summarize() (both the early-return deadline path and post-batch); _executorForTest seam for deterministic pool saturation.
  • src/preflight.ts: PreflightResult.externalDispatch?: { calls, attempts }, set when a chain ran.
  • src/external-summary-surface.ts: externalQueueDroppedAll(dispatch) predicate with policy docstring.
  • src/server.ts: both growth-fold arm sites split into queue-drop (distinct warn, no arm/markDirty) vs existing behavior (warn + armAutoFoldBackoff + markDirty).
  • Docs: CONFIGURATION.md en + zh autoFold fail-open paragraph gains the auto-fold backoff arms on pure queue-drops (attempts=[]) as if the summary service had failed #2662 exception sentence.

Tests

  • New e2e auto-fold backoff: a pure queue-drop (zero dispatched attempts) does NOT arm the cooldown — the next turn retries (tests/external-summary-autofold.test.ts): saturates the real pool with 4 holders, asserts ZERO HTTP summary calls on turn 1 (pure-drop proof), releases the pool, then asserts turn 2 DOES dispatch and fold (old code would show 0 external calls here).
  • New unit tests (tests/external-summary-runtime.test.ts): saturated-pool preflight reports calls>0, attempts=0; dispatched-but-failing attempts are NOT queue drops; externalQueueDroppedAll truth table.
  • Negative check performed locally: forcing the gate off (false && queueDroppedAll) makes the new e2e fail with backoff must NOT have armed on pure queue-drops; expected external calls on turn 2, got 0 — the test pins the regression.
  • Targeted suites green locally: all tests/external-summary-*.test.ts + tests/*preflight*.test.ts → 278 pass / 0 fail / 1 gated skip; typecheck clean. Full suite left to CI.

Scope notes

  • Implements issue directions (1)+(3): full backoff only when ≥1 attempt was dispatched, plus distinct warn lines so operators can tell the two failure shapes apart in logs today. Direction (2) (consecutive no-attempt-drop escalation) deliberately not implemented — kept minimal; happy to follow up if the owner wants it.
  • Both compression modes considered: no wire/message-shape change in either mode — this is proxy-internal backoff policy plus additive telemetry on PreflightResult (an internal value, not a wire artifact). The exception applies wherever the growth-fold arm sites run — the only places AUTO_FOLD_BACKOFF_MS is armed.
  • No new config surface, no kernel/ or pi-subagents/ changes, no version bump.

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-10_autofold-backoff-queue-drop (c8455ed)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.3027-pr.2665.22203a9

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr2665.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷

PR #2665 review([PR] 类型:不重做,拉分支逐行核对代码 + 核查 CI)

结论先行:方向正确、修在根因、测试有牙、diff 干净,可合并——待两个 Windows 单测矩阵 job 转绿即合(新增测试正跑在那里)。我顺手推了一个标注的 cosmetic commit(docs:,仅改一处 docstring 措辞,零行为影响),见文末。

结构化八问

  1. 是什么问题:auto-fold 的两个退避 arm 点只按「折叠是否产生进展」(compressedRanges/fold progress)判定,无法区分「批次在共享池队列里被丢弃(attempts=[],[Feature] expose external-summary concurrency as config — hard-coded ExternalSummaryExecutor(4) throttles every session on the host #2657 池饱和)」与「摘要链真的失败」。纯队列丢弃也会让会话白白背 10 分钟 AUTO_FOLD_BACKOFF_MS,恰好在宿主最拥塞时把 auto-fold 关掉。
  2. 什么原因导致的:arm 决策点缺「派发遥测」——它只知道「没进展」,不知道「是没尝试还是尝试后失败」。根因是决策点拿不到 dispatch 事实,不是某阈值错。fix 把遥测送到决策点,是治本而非堵症状。
  3. 影响范围与严重程度:多会话宿主 + 拥塞摘要端点上,每次纯队列丢弃损失 10 分钟 auto-fold。属「特定条件下有问题」(externalSummary 启用 + autoFold + 共享池饱和到零派发),非全量不可用;fail-open 转发不受影响(请求照常 200)。
  4. 怎么修复的:ConfiguredSummaryPlan.stats(calls/attempts) → PreflightResult.externalDispatch → 谓词 externalQueueDroppedAll(calls>0 && attempts===0),让两个 growth-fold arm 点区分调度拥塞 vs 链故障:纯队列丢弃打一条独立 warn 且不 arm,下一轮直接重试;真实失败(≥1 次派发)与经典非 external preflight 行为完全不变。
  5. 是否有回归问题(逐项过既有行为):
    • 真实 provider 失败仍 arm ✅(attempts≥1 → 谓词 false → 照旧 arm;单测 b 钉住)
    • 经典非 external preflight 不变 ✅(externalDispatch undefined → false)
    • 成功折叠路径不受触碰 ✅(if(fits) return rebuilt 在两个 arm 点之前返回)
    • 有进展但未达标的 growth fold 仍 arm ✅(Site B,growthArmed&&payloadFitsWindow,queueDroppedAll=false)
    • 跳过 markDirty 正确 ✅(零进展 case 未改任何 metadata,无需持久化)
    • nudge 抑制一致 ✅(不 arm → autoFoldEngaged 保持 true → nudge 继续抑制、auto-fold 重试)
    • wire/message shape 两种压缩模式均无变化 ✅(仅加内部字段,不动线上字节)
    • 高危域点名:自动更新/src/update.ts 未触碰;dsh 未触碰;lockfile/version 未触碰;wire 协议 未触碰。src/server.ts 是热文件,但改动局限在两 arm 点 + 一行谓词计算,无语义漂移外溢。
    • 本版本引入回归:0 处。
  6. 是否破坏缓存:否。前缀缓存/重试/增量游标/去重键均不受影响——只改「是否 arm 冷却计时器」,不涉及任何失效策略。
  7. 是否改了设计方向:否。架构/边界/数据流未转向;只是给既有退避机制补一个更细的判定维度(拥塞 vs 故障)。
  8. 是否引入新配置:否。无新 env/config/默认值。CONFIGURATION.md en+zh 各加一句文档说明该例外(纯文档,非配置面)。

行为变更清单(必须披露 old→new)

测试有效性(§④:真测试还是假测试)

  • e2e(tests/external-summary-autofold.test.ts):真起 proxy + 真饱和进程级池(4 holder 持 2500ms > victim 500ms deadline)。turn1 断言 200 + sum.bodies.length===0(零 HTTP,证明纯丢弃) + 消息数 73(未折叠);释放池后 turn2 断言 sum.bodies.length>=1(折叠真的派发了 = 退避没 arm,这是回归命门)+ 消息数<73(折叠落地)。作者已验证把 gate 强制置 false 会让 turn2 失败("expected external calls on turn 2, got 0")——测试确实抓得住这个 bug。
  • 单测(tests/external-summary-runtime.test.ts):(a) 饱和池 → preflight reports calls>0/attempts=0/endpointCalls=0;(b) 负例:503 派发失败 → attempts>=1 → 谓词 false(钉住「别过度放宽 carve-out」);(c) 谓词 truth table。覆盖显式传 plan 与 lazy-build 两条构造路径。
  • 判定:真测试、确定性、有牙、正反例齐备 ✅。

小问题处置

  • 已顺手修(独立 commit 95421122b,docs:):src/external-summary-runtime.ts 的 stats.calls docstring 原写 "batches submitted",但 early-deadline 分支(remaining<=0,未提交任何 batch 到池)也 calls+=1,措辞与代码事实不符 → 改为 "summarize() invocations" 并补注两种丢弃形态。零行为影响,仅澄清谓词语义。
  • 非阻断观察:PR 分支落后 master(merge-base e1cd9e11c,origin/master 已到 7c993f9e)。GitHub 报 mergeable=true 无文本冲突;后续 master 提交虽同触 src/server.ts preflight 区但落在不同区域(masking/audit),语义风险低。建议合并前 rebase 到当前 master(§7.2 卫生),但不阻断。

CI

review 时点(head 5e9056f):28 checks 中 26 success,仅剩 2 个 Windows 单测矩阵 job in_progress(新增测试正跑在其中)。我推的 cosmetic commit 会触发新一轮全量 CI。本地未跑全量套件(全局回归交 CI,按本地测试纪律);作者本地已定向绿(external-summary-* + preflight → 278 pass / 0 fail / 1 gated skip,typecheck clean)。

收工判定

可合并——待新 head 的 CI(尤其单测矩阵)转绿即合。方向对、修在根因、双压缩模式都考虑过、行为变更已披露、测试有牙、diff 收敛到目的本身。

ework-agent added 2 commits October 11, 2026 09:21
The two auto-fold backoff arm sites keyed off compressedRanges/fold progress only, so a batch dropped by the saturated shared pool before any summary call dispatched (executeBatch status deadline/cancelled, attempts=[]) looked identical to a real provider failure and cost the session 10 minutes of auto-fold (AUTO_FOLD_BACKOFF_MS) exactly while the host was congested.

Propagate dispatch telemetry from ConfiguredSummaryPlan.stats through PreflightResult.externalDispatch, add the externalQueueDroppedAll predicate (calls>0 && attempts===0), and let both growth-fold arm sites distinguish scheduler congestion from chain failure: pure queue-drops log a distinct warn and do NOT arm the cooldown, so auto-fold retries on the next turn. Provider failures (>=1 attempt dispatched) and classic non-external preflights behave exactly as before.
@ranxianglei
ranxianglei force-pushed the 2026-10-10_autofold-backoff-queue-drop branch from 9542112 to 9681b01 Compare October 11, 2026 01:22
@ranxianglei
ranxianglei merged commit 2e95ed4 into master Oct 11, 2026
26 checks passed
@github-actions

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.273-master.2e95ed4 (rolling master tag).

npm install -g billion-context@0.0.273-master.2e95ed4  # this exact build
npm install -g billion-context@master  # always the newest merged build

npm view billion-context@master prints the current version at any time.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

auto-fold backoff arms on pure queue-drops (attempts=[]) as if the summary service had failed

1 participant