fix(nudge): render distinct wording tiers for over-limit vs emergency bands (#312)

[ranxianglei]

Closes #312

来源: ranxianglei/billion-context#847 (ranxianglei/billion-context#847) 分析 nudge 文案与阈值语义不一致 时发现

Problem

decideNudge has three usage bands (gentle < maxContextLimitPct < over-limit < emergencyThresholdPct <= emergency), but renderNudgeText only had two wording tiers: isEmergency = emergencyOverride || overLimit, so usage >= 0.75 rendered "⚠️ Context limit reached" even though the true emergency threshold is 0.95. The efficiencyNote/emergencyHeader selection boundary was equally misplaced at 0.75, and the tier>=2 branch always led with the efficiencyNote ("not an overflow warning") — which coexisted in the same message as "Context limit reached", contradicting itself.

In the #847 incident (usage 76% -> 89%, reason OVER-LIMIT T1) the nudge kept shouting "limit reached" while valid pending targets existed, amplifying the model's overreaction.

Fix (option (a): wording tiers)

• Split isEmergency = !!emergencyOverride from isOverLimit = isEmergency || !!overLimit.
• New middle wording pressureHeader: ⚠️ Context pressure high — compress now to stay under the limit. Prioritize consumed tool outputs. — used for [maxContextLimitPct, emergencyThresholdPct).

• = emergencyThresholdPct still renders ⚠️ Context limit reached (text unchanged).

• Tier>=2 trigger line is now three-way: [TIER N ... TRIGGER] / [OVER-LIMIT — TIER N ...] Context pressure high — distill now to reclaim tokens. / [EMERGENCY — TIER N ...] Context limit reached — distill NOW ... (emergency line unchanged).
• Tier-null emergency and pressure branches merged; body parts/order unchanged so emergency output stays byte-identical.
• Voice stays binary ("emergency" = pressure band or above) -> host behavior unchanged; reason labels untouched (already correctly tiered).
• No overall usage percentage anywhere in the injected wording (owner ruling on billion-context#847); per-range token counts and [tool X% | text Y%] composition stay.
• pressureHeader added to NudgePromptSections and NUDGE_SECTION_KEYS (same tri-state semantics as existing keys).
• Fixed stale types.ts comment (emergencyThresholdPct "Default 0.98" -> 0.95); DESIGN-prompts.md synced.

Option (b) (renaming config keys) rejected: breaking API change for adapters that read the current key names; the names themselves are unambiguous — the rendering was wrong.

Verification

• npm run typecheck clean
• npm test: 774/774 pass (new: pressure-tier unit tests, no-usage-% assertions, three-way trigger-line tests, pressureHeader tri-state override tests, byte-stability for the new mode, end-to-end processTurn at 80% -> "Context pressure high" and NOT "Context limit reached", at 96% -> "Context limit reached")
• npm run build clean
• Emergency and gentle outputs byte-identical to before (back-compat loop covers all modes incl. the new over-limit mode)

修复了 nudge 文案在 usage>=0.75(maxContextLimitPct) 就渲染 "Context limit reached" 的档位错位——新增压力档中间文案、emergency 档保留原话,voice/reason 与渲染档位一致,宿主行为零变化,可以合并。

[github-actions]

📦 Built Package Artifact

Branch: 2026-09-16_nudge-band-wording (6500e6a)

Option A — Install from npm PR tag (recommended)

In your adapter project:

npm install acp-kernel@pr-315

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

Option B — Download artifact

1. Download the artifact from the Actions run
2. Extract the tarball and install:

tar xzf acp-kernel-pr315.tgz
npm install ./package

---

This comment is automatically updated on each push.

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 PR #315 复核完成(本 agent 处理 #312 时完成的 PR,未重做,拉分支逐行核对代码 + 本地复验 + CI 状态)。

CI 状态 ✅

head commit 6500e6a 四项检查全绿:test (22)、test (24)、build-artifact、pr-validation。

代码核对(8 文件,+135/-13,diff 干净、无跑题改动)

• src/nudge-text.ts:174-176:isEmergency = !!emergencyOverride(严格 ≥0.95/override)、isOverLimit = isEmergency || !!overLimit([0.75, ∞))——档位分离正确;
• tier≥2 trigger line 三档化([TIER N … TRIGGER] / [OVER-LIMIT — TIER N …] Context pressure high… / [EMERGENCY — TIER N …] … distill NOW…),emergency 行原文不变;
• voice 映射逐档核对与改前完全一致(gentle / over-limit→emergency / emergency→emergency)→ 宿主行为零变化成立;reason label 在 compress.ts,本 PR 未触碰,本来就分档正确;
• tier-null 分支 pressure/emergency 合并后 body 部件顺序不变 → emergency 输出字节稳定,gentle 路径零改动;
• pressureHeader tri-state(string 替换/null 移除/缺省默认)已进 NudgePromptSections + NUDGE_SECTION_KEYS;types.ts 过期注释 0.98→0.95、DESIGN-prompts.md 同步;
• 三档注入文案均无整体 usage 百分比(符合你在 nudge 文案与阈值语义错位:usage≥maxContextLimitPct(0.75)即渲染 "Context limit reached",而 emergency 阈值为 0.95 #312 的裁定);新测试对压力档显式断言不含 "85%";
• 测试覆盖到位:压力档单测、trigger line 三档断言、tri-state 覆盖、back-compat/byte-stability 循环加入 over-limit 模式、端到端 processTurn @80% → "Context pressure high" 且不含 "Context limit reached"、@96% → "Context limit reached"。
• 一处易误读处已核实不是问题:tests/nudge.test.ts:577 注释 "below the 98% emergency threshold" 指该测试文件 buildConfig 的局部配置值 0.98(既有约定),非 kernel 默认值;第二个 e2e 测试显式设 0.95 并对应断言,两者自洽。

本地复验 ✅

• PR base(v0.0.73):typecheck ✓、774/774 ✓、build ✓
• 试 rebase 到最新 master(v0.0.74):无冲突;rebase 后 typecheck ✓、811/811 ✓、build ✓

PR 目前 behind master 但无冲突,GitHub 直接 merge(merge commit)即可,无需先 rebase;若想更干净也可先 rebase 再合,两种方式我都验证过。

一句话中文摘要

修复了 nudge 文案在 usage≥0.75(maxContextLimitPct)就渲染 "Context limit reached" 的档位错位——新增 [0.75, 0.95) 压力档中间文案("Context pressure high")、emergency 档保留原话,voice/reason 与渲染档位一致、宿主行为零变化;CI 全绿、本地 typecheck/test/build 及 rebase 到 v0.0.74 复验全部通过,可以合并:https://github.com//pull/315

[ranxianglei]

继续