Skip to content

fix: preflight logs every silent skip reason and reports real causes (#1372) - #1374

Merged
ranxianglei merged 1 commit into
masterfrom
2026-09-26_preflight-skip-diagnostics
Sep 26, 2026
Merged

ranxianglei merged 1 commit into
masterfrom
2026-09-26_preflight-skip-diagnostics

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

What & why

#1372: when the preflight fallback cannot compress, it fails with no range could be compressed across N viable range(s) while zero logs explain where each range died — and the hardcoded cause list in the message misrepresents the actual failure stage. In #1365 this left a stuck session completely undiagnosable (the check was millisecond-scale with zero upstream calls, i.e. every range died at preview/apply before any summarization), and the plugin compress path succeeded on the exact same ranges.

Triage verified two distinct defects with one root cause — silent skip points in src/preflight.ts:

  1. Seven skip points logged nothing: unresolvable refs, span boundary without ref, kernel preview rejection (!planned — the kernel's result.errors/warnings verdict was read and then discarded), per-item render drops, empty content after render, plus the already-logged summary-unusable/apply-failed paths never contributed to the final message.
  2. The final 502 detail was a static boilerplate (each was below minCompressRange, had an unusable summary, or failed to apply) regardless of what actually happened — including saying "across 0 viable ranges" when every range died at ref-resolution.

On the alignment question (issue item 2): both paths call the same kernel applyCompression with symmetric validation, so identical inputs yield identical verdicts. The inputs legitimately differ by pipeline position (preflight = current-request messages + live config, pre-forward; plugin = remembered snapshot + stamped effectiveConfig, post-response). Full unification is neither possible nor appropriate — the fix makes both sides' verdicts diffable: the plugin path already surfaces kernel errors (applyRanges, src/stream.ts); now the preflight path does too.

Changes (src/preflight.ts only + tests)

  • Every silent skip point now emits a warn log with the concrete reason (the preview-rejection case includes the kernel's own errors/warnings text, e.g. Summary too long (L chars, max M) or the minCompressRange gate message).
  • Skip reasons are collected (capped/deduped) and the final exhaustion detail now reports the actual top-3 causes instead of the boilerplate list; new phrasing for the all-died-at-ref-resolution edge (no viable range could be compressed).
  • Sub-minimum ranges no longer surface as "no compressible ranges remain" — the detail names them: no foldable compressible ranges remain: all N viable range(s) are below minCompressRange (M chars).
  • No changes to thresholds, defaults, wire shape, config schema, or compression decision logic.

Behavior change disclosure (output format)

Tests

  • New tests/issue1372-preflight-skip-diagnostics.test.ts: (a) forces every range to die at the preview stage (dummy summary violates the kernel length gate) against an unreachable port — asserts zero upstream calls, warn log carries the kernel's Summary too long verdict, and the 502 detail names the real cause instead of the boilerplate; (b) injects nudge ranges citing refs from another session generation (the bug: dsh-native — attach 目标瞬时不可达 → 回退 spawn 第二实例:routed baseURL 下工具/模型通道必然脑裂(工具 404 → preflight 502 → 会话不可自愈) #1365 brain-split shape) — asserts the unresolvable-refs warn and truthful detail.
  • tests/preflight-covered-ranges.test.ts: replaced one assertion that pinned the OLD silent behavior (logs.every(!includes("already covered"))) with one pinning the new diagnostic (preview rejected … already covered). The behavioral guarantee itself (covered raw is never re-summarized) remains pinned by the existing HIDDEN_RAW assertion.

Pre-flight (rebased onto current master d3c8af8)

  • npm run typecheck — clean
  • npm test — 2637 pass / 0 fail (2648 total)
  • npm run build — success
  • E2E (e2e-codex): NOT run locally — sandbox has no reachable Responses upstream (127.0.0.1:8199 refused), and src/preflight.ts is not in .github/workflows/ci-e2e.yml auto-trigger paths, so this PR does not trigger the e2e job automatically. The change is strictly additive diagnostics (log lines + failure-detail text); no wire-path or decision-logic change. Recommend a manual dispatch of the e2e workflow if desired.

Fixes #1372

@github-actions

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-09-26_preflight-skip-diagnostics (98c4acb)

Option A — Install from npm PR tag (recommended)

npm install -g billion-context@pr-1374

Each push to this PR publishes a new version under the pr-1374 npm tag.

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr1374.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] 🏷 Picked up this [PR] mirror. This is completed work (PR for #1372), so I'm not redoing it — verifying now: pulling branch 2026-09-26_preflight-skip-diagnostics, cross-checking the diff against current master, re-running typecheck/tests/build locally, and checking CI status. Will follow up with the full conclusion.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Verification complete — PR verified clean, ready to merge. This is completed work, so I did not redo it: pulled the branch, cross-checked the code against live master, re-ran the full pre-flight locally, and audited CI.

Branch / base. Single linear commit 98c4acbe on top of d3c8af84 = current origin/master HEAD — fresh rebase, no drift. Diff is exactly the declared scope: src/preflight.ts (+~70/−13), new tests/issue1372-preflight-skip-diagnostics.test.ts (91 lines), tests/preflight-covered-ranges.test.ts (5 lines). No version bump, no lockfile churn, no unrelated files. Hot-file check: the only other open PR touching src/preflight.ts (#1360) changes just the import line and the ccrLoopConfig expression at line 859 — textually disjoint from this diff, semantically orthogonal.

Code review (main gate).

Tests (quality gate). The new file is a real regression pair, both would fail on master: (a) unreachable upstream + minSummaryLength forced above the kernel max makes every preview reject with zero upstream calls — asserts the warn carries the kernel's own Summary too long verdict, the detail names it, and explicitly asserts the stale boilerplate parenthetical is ABSENT; (b) the #1365 brain-split shape (nudge refs from another generation, m99999/m99998) asserts the unresolvable-ref warn + truthful detail with no blocks created or destroyed. The modified assertion swaps a pinned-silence for a pinned-diagnosis while leaving the behavioral pin intact — the right call.

Pre-flight (re-run by me on the rebased head). npm run typecheck clean · npm test 2637 pass / 0 fail (2648 total, 11 skipped) — identical to the PR's claim · npm run build success.

CI. All 10 check runs on 98c4acbe completed/success (test matrix ubuntu/windows × node 22/24, version-guard, build-artifact, hermetic registry e2e, real codex + pi lanes vs deterministic fake upstream). The real-upstream E2E-codex suite was not auto-triggered — src/preflight.ts is outside its trigger paths, consistent with the PR body; optional manual dispatch if you want it.

Behavior changes (disclosed, intentional). (1) The 502 preflight-exhaustion detail now reports the ACTUAL per-range skip causes (top 3, joined) instead of the static (each was below minCompressRange, had an unusable summary, or failed to apply); old wording retained only as the zero-evidence fallback, plus a new phrasing when nothing was even tried. (2) New warn/debug log lines at the formerly-silent skip points. No thresholds, defaults, timing, or wire-format changes.

Auto-merge gate (§7.4). Passes all eight conditions: single-module fix, reproducing regression tests, green on the rebased head, no config/persistence/wire/cross-repo impact, pure fix:, clean diff, references Fixes #1372, no load-bearing infra touched. Eligible for auto-merge; merging itself stays human-only — #1374

中文摘要:核验了 preflight 静默跳过诊断修复(#1372)——七个跳过点全部补上日志、502 详情改为报告真实原因(旧文案仅作零证据兜底),diff 范围干净、本地 typecheck/测试(2637 过 0 败)/构建全绿、CI 十项全过、与唯一同文件在途 PR(#1360)无冲突,符合 auto-merge 标准,可以合并。

@ranxianglei

Copy link
Copy Markdown
Owner Author

深审通过(独立验证,零改动):

设计核验:#1372 的两个病灶都堵上了——

  1. 零诊断:noteSkip 收集器挂在全部 6 类跳过点(列表级 minCompressRange 过滤/引用不可解析(preview rejected/计划块渲染空文本/摘要不可用/apply 失败),失败回执从硬编码猜测句(each was below minCompressRange...)换成真实前三条原因;rangesTried===0 与 >0 分开措辞,不再谎报"N 个 viable range 都试过"。
  2. 与插件路径分叉:注释点明两者在不同管线位置裁决同一范围、判决可以合法分叉,现在有 trace 可 diff。

实测:新 issue1372 测试 10/10(含端口 9 反证——若 preflight 真发了摘要调用会以 upstream 而非 exhausted 暴露);全 preflight 家族 94/94。

一处行为翻转核实:already covered 从静默跳过改为 warn + 断言翻转——这正是 #1372 的盲点本体,"covered 原文绝不被重摘"的行为保证由 HIDDEN_RAW 断言独立承担,翻转合理。

合并无阻塞。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 收到——你的独立深审与我的核验结论完全一致(6 类跳过点全覆盖、真实前三条原因替换猜测句、rangesTried===0/>0 分措辞、already covered 翻转由 HIDDEN_RAW 断言独立兜底)。两边互为佐证,无分歧项。

我这边额外留档的两个数据点供合并参考:CI 十项 check runs 全绿(test 矩阵 ubuntu/windows × node 22/24 + version-guard + build-artifact + hermetic registry e2e + codex/pi 双 lane);本地全量测试 2637 pass / 0 fail(2648 total),与 PR 声明的 pre-flight 数字逐字一致。

按规矩合并只能由你操作:#1374 —— 合并后 CI 会自动发布。

中文摘要:独立复核与我的验证结论一致,PR 已确认零改动可合,等待人工合并。

@ranxianglei
ranxianglei merged commit f301754 into master Sep 26, 2026
10 checks passed
@ranxianglei
ranxianglei deleted the 2026-09-26_preflight-skip-diagnostics branch October 15, 2026 05:32
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