Skip to content

fix: preflight chunked retry — snap split boundaries past BLOCKED/unreferenced messages - #2726

Merged
ranxianglei merged 2 commits into
masterfrom
wt-2672-ework-daemon
Oct 13, 2026
Merged

ranxianglei merged 2 commits into
masterfrom
wt-2672-ework-daemon

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #2672

What

Preflight's chunked retry after a summary failure split the failed span IN HALF ON RAW MESSAGE INDICES. Protected messages hold the truthy BLOCKED sentinel in state.messageRefs.byRaw, so when the blind midpoint landed on one, BOTH halves carried an unresolvable boundary, every sub-chunk was rejected at preview with Invalid boundary ref(s): startId="BLOCKED", and the whole range was abandoned — even though each half was summarizable once its rim snapped past the protected message(s). In the issue log one timeout thus poisoned the entire range and burned the full pass deadline (~180s passes saving nothing).

Root cause

Two compounding facts:

  1. The pop-time guard only checked truthiness (if (!startRef || !endRef)) — "BLOCKED" is truthy, so protected boundaries sailed through into the kernel, which rejects them.
  2. Both halving sites chose mid = floor((cs+ce)/2) blind to the ref map — nothing ensured the resulting span boundaries were resolvable.

The kernel already excludes protected messages from a block's effective ids (interior protected messages were always fine); only the BOUNDARIES must name resolvable messages.

Fix (src/preflight.ts)

  • New snapToUsableBounds(idxToRef, lo, hi): walks inward to the nearest index whose ref is defined and !== BLOCKED_REF; null when nothing usable remains.
  • New pushSpanHalves(...): both halving sites now route through it — each half is snapped before being pushed; a half left with no usable message is dropped instead of pushing a doomed span (oldest-half-first worklist order preserved, [Bug] Codex 额度中断后恢复长会话,preflight SSE 摘要为空并持续 502 #726).
  • The pop-time guard now snaps instead of dropping the whole span: a span loses at most its unreferencable rim. A span with NO usable message anywhere gets a distinct warn/noteSkip ("no message carries a usable ref") instead of silently dying at the kernel.

Implements issue proposals 1+2 (split on non-protected boundaries; an invalid boundary can never reach the kernel) and proposal 3 (distinct logging for abandoned spans). Proposal 4 (a separate budget for the chunked retry) belongs to the external-summary batch domain (#2667/#2639) and is out of scope here.

Behavior change (disclosed)

  • Old: a span whose boundary lacked a plain ref was dropped WHOLE; a span whose boundary held the BLOCKED sentinel died at the kernel preview — and since the sibling half usually carried BLOCKED too, the whole range was abandoned.
  • New: such spans snap inward and summarize the referencable rim-minus remainder (strictly more recovery); fully-unreferencable spans are dropped with a distinct log line. Halving never mints an unresolvable boundary anymore.
  • No wire format, config schema, persistence-format, or kernel changes. No new config surface.

Regression test

tests/issue2672-preflight-blocked-split.test.ts — deterministic 16-message geometry where the oversized first chunk's midpoint lands exactly on a protected pair (plus one protected message parked so the residual chunk stays sub-minimum regardless of recent-zone endpoint drift). Asserts 200 recovery via strictly-smaller snapped halves, no protected bytes in any summary body, forward happened, no dead-end marker.

Verified both directions: PASSES with the fix; FAILS without it (502 with Invalid boundary ref(s): startId="BLOCKED" — the exact production signature from the issue log).

Targeted siblings green locally: preflight-empty-summary (#726 halving owner), preflight-multi-range, issue1841-preflight-futility, preflight-fail-fast, preflight-round-budget (24/24). Full suite via CI.

@github-actions

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: wt-2672-ework-daemon (8350da0)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.2962-pr.2726.63161fa

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-pr2726.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 #2726 审核中(agent 自产 PR,核对代码 + CI,不重做)

查重:无重复。相邻但不相同——#2723(多 range 合并成一次 external-summary 调用)、#2721(按 payoff 派发 fold)、#2660(structurally-dead span 不再每轮重提名)机制各不同;本 PR 独占「chunked retry 分裂边界落在 BLOCKED/无 ref 消息上」这一失效域。

代码审查(已完成):

  • 根因与 issue 描述一致,且已对照 kernel 源码逐点验证:kernel/src/refs.ts:95(protected → byRaw = BLOCKED_REF)、kernel/src/boundaries.ts:90(parseBoundary("BLOCKED") → null → throw Invalid boundary ref(s))、kernel/src/boundaries.ts:333-344(块内 protected 消息被跳过——只有边界必须可解析)。PR 的因果链成立。
  • snapToUsableBounds:向内侧走到最近 usable(defined 且 ≠ BLOCKED)索引,全不可用返回 null。正确。
  • pushSpanHalves:两个 halving 站点统一走它;push 顺序不变(upper 先 push、lower 后 push、pop 取尾),[Bug] Codex 额度中断后恢复长会话,preflight SSE 摘要为空并持续 502 #726 oldest-half-first 保持。
  • pop 时守卫从「truthy 检查」改为「snap」:旧守卫 !startRef 对 "BLOCKED"(truthy)放行、对 undefined 整段丢弃;新逻辑两种情况都只丢不可引用的 rim。全不可用的 span 有独立 warn/noteSkip(issue proposal 3 ✓)。
  • 终止性:每次分裂严格变小且有 floor gate,snap 只会更小,无死循环风险。
  • 回归面:snap 只在边界本身不可用时触发——这类 span 旧行为是「整段丢弃」或「preview 被拒」,从未成功过;边界可解析时 snap 返回原区间,字节级无变化。不改变任何原本成功路径的输出。模型切换后压缩块跨模型失配,新模型收到 61.3 万 token 全量上下文 #1001 ascending-pair 归一化在 snap 之后照旧执行。不涉及 wire 格式/config/persistence/kernel。
  • 测试有效性:真 server + fake upstream 的行为级 e2e,断言有牙(严格更小的恢复 chunk、≥minCompressRange、protected 字节不进 summary body、forward 发生、无 dead-end marker),并声称双向验证过(fix 后过 / fix 前 502 复现生产签名)。

CI:15 job 中 11 绿(lock-sync、kernel-guard、version-guard、config-surface-guard、pi-subagents-guard、lane-guard、docs-sync、docs-coverage、unused-exports、build-artifact、real-image billing e2e);4 个 test 矩阵 job(ubuntu/windows × node 22/24)仍在跑。

基线新鲜度:分支落后 master 152 commit,但 src/preflight.ts 自 PR base 以来在 master 上零改动(唯一相关 merge 是 pi-subagent 域),rebase 应干净。正在本地 rebase 到当前 master 后跑定向测试(新回归测试 + preflight 兄弟套件)+ typecheck + build,结论稍后跟进。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 审核结论:可合并(八问体例)

证据(本地在 rebase 到当前 master 4ecd82f3f 后的 head 上独立验证):rebase 干净(src/preflight.ts 自 PR base 以来 master 零改动)→ typecheck 干净 → 定向测试 25/25(新回归测试 + preflight-empty-summary/preflight-multi-range/issue1841-preflight-futility/preflight-fail-fast/preflight-round-budget)→ build 成功。回归测试双向验证过:撤掉 fix 后该测试失败于 502(正是 issue 日志里的生产签名),带 fix 通过——断言有牙。CI 13/15 绿:ubuntu×node22/24 全量套件均 success,windows 两腿仍在跑(纯 TS 逻辑、无 OS 面,不阻塞判定)。

① 是什么问题:preflight 摘要失败后的 chunked retry 按原始消息下标把失败 span 对半切;切点落在 protected 消息上时,两个半段都带着不可解析的边界,所有子块在 preview 被拒,整个 range 被放弃——尽管每个半段把 rim 挪过 protected 消息后本可正常摘要。生产表现:一次 timeout 毒化整个 range,烧光整轮 deadline(~180s)什么都没存下。

② 什么原因导致的:两个事实叠加。(a) pop 时守卫只查 truthiness(!startRef),而 "BLOCKED" 是 truthy,protected 边界直接放行进 kernel 被拒;(b) 两个 halving 站点盲选 mid=floor((cs+ce)/2),从不保证切出来的边界可解析。已对照 kernel 源码逐点核实:kernel/src/refs.ts:95(protected→byRaw=BLOCKED_REF)、kernel/src/boundaries.ts:90(解析失败 throw Invalid boundary ref(s))、kernel/src/boundaries.ts:333-344(块内 protected 消息本来就被跳过——只有边界必须可解析)。因果链成立,修的是根因不是症状。

③ 影响范围与严重程度:proxy-mode preflight 自动折叠路径;触发条件=摘要失败触发 chunked retry 且切点落在 protected/无 ref 消息上。特定条件下有问题:整个可折叠 range 静默放弃 → payload 保持超窗 → 请求 502 而非恢复。非数据损坏类。

④ 怎么修复的:snap 而非 drop/mint——新 snapToUsableBounds(lo,hi) 向内侧走到最近 usable(defined 且 ≠ BLOCKED)索引;两个 halving 站点统一走 pushSpanHalves,每半先 snap 再入列(无可用消息的半段直接丢弃);pop 时守卫也改为 snap,全不可用的 span 给独立 warn/noteSkip(issue proposal 1+2+3 全部落实;proposal 4 预算隔离明确划归 external-summary batch 域 #2667/#2639)。不变量:不可解析边界从此不可能到达 kernel。

⑤ 是否有回归问题:无。触碰路径既有行为逐项清点:#726 oldest-half-first 工作表序保持(push 顺序未变);分裂前 floor gate 未变;#1001 ascending-pair 归一化未变(snap 之后照旧执行);#1372 preview 拒绝诊断未变;budget/deadline 逻辑未变。关键论证:snap 只在边界本身不可用时触发——这类 span 旧行为必败(整段丢弃或 kernel 拒绝),从未成功过;边界可解析时 snap 返回原区间,字节级无变化。原本成功的任何路径输出均不变。终止性:每次分裂严格变小且有 floor gate,无死循环。

⑥ 是否破坏缓存:不涉及——未触碰任何缓存/重试/增量游标/去重键机制。

⑦ 是否改了设计方向:不涉及——同一套 worklist halving 设计,只是使其边界安全。

⑧ 是否引入了新的配置:不涉及——无新 env/config/默认值。

auto-merge gate(§7.4)核对:单模块 fix ✓ / 有牙回归测试 ✓ / rebased head 绿 ✓ / 无 config schema、persistence、wire、kernel 变更 ✓(kernel-guard 绿)/ 纯 fix: ✓ / diff 干净(2 文件 +341−12,每行相关)✓ / Fixes #2672 ✓ / 不碰 load-bearing infra ✓。分支落后 master 152 commit 但已验证 rebase 干净,合并前可选 rebase 或按现状合(GitHub mergeable=True)。合并动作留给人工。

@ranxianglei
ranxianglei merged commit e99de4a into master Oct 13, 2026
15 checks passed
@github-actions

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.350-master.e99de4a (rolling master tag).

npm install -g billion-context@0.0.350-master.e99de4a  # 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

1 participant