feat: double soft-nudge growth step to 100K and log fold geometry on applied (#359)

[ranxianglei]

Closes #359

What

Two changes from #359 (fold-cadence cache economics), both adapter-level — no acp-kernel release needed:

1. Soft-nudge growth step default 50K → 100K (src/config.ts)
Per the corrected economics in #359 (fold re-pay is (1−hit)×V', not ~0.75V; summary output at ≈3–5× input price is a real per-fold cost), folds are net-positive even at the old cadence — so the rationale for raising the threshold is lowering interruption frequency and per-fold summary output overhead, not break-even. New default DEFAULT_NUDGE_GROWTH_TOKENS = 100_000 applies when the user doesn't set compress.nudgeGrowthTokens; explicit values still win. The kernel's own 50K default is untouched (other hosts keep their cadence); for windows ≤1M tokens the kernel's adaptive formula resolves the effective step to growthFloor anyway, so this cleanly doubles the cadence.

Side effect documented in CONFIGURATION.md(zh): the same-turn re-inject floor rises 22.5K → 45K tokens (max(minGrowthFloor, minGrowthRatio × adaptiveGrowth)).

2. Fold-geometry fields on event=applied (src/compress-tool.ts)
Each successful fold now logs its invalidation geometry straight from the log, no experiments needed:

• firstFoldStartPct = token offset of the earliest fold start / pre-fold view ≈ expected first-round prompt-cache hit fraction after the fold (earliest newly-covered message, or the anchor of a block consumed by tier distillation); measured on the same list/scale as beforeTokens
• retainedPctUpperBound = afterTokens/beforeTokens — an upper bound on prefix retention (longest common prefix of pre/post renders can never exceed the surviving token fraction)

Invariant: firstFoldStartPct ≤ retainedPctUpperBound. Fields only appear when blocks were actually created.

Tests (653 total, 650 pass / 0 fail / 3 pre-existing skips)

• new unit test for firstFoldStartTokens (prefix scale, covered-id exclusion, null case)
• new e2e test asserting both fields land in acp.log with sane bounds on a real fold
• config/e2e-config assertions updated to the 100K Pi-host default
• tests/nudge-reinject.test.ts recalibrated: its scenarios were built around absolute deltas of the old 50K step; with the 45K re-inject floor and the 100K drop-reanchor span they become geometrically impossible under small windows, so the two affected tests run against 280K windows (the third, emergency-bypass, is unchanged)

Diff hygiene

8 files, all directly related to #359: src/config.ts, src/compress-tool.ts, 5 test files, 2 config docs. No version bump, no lockfile change, no unrelated churn.

---

中文摘要:把 Pi host 的软压缩 nudge 步长默认值从 50K 提到 100K(降低折叠打断频率与每次折叠的摘要输出开销,内核默认值不动),并在 event=applied 日志中新增 firstFoldStartPct / retainedPctUpperBound 两个失效几何观测字段,使缓存失效几何可从日志直读。测试全绿(650/650),可以合并。

[github-actions]

📦 Built Extension Artifact

Branch: 2026-09-10_fold-cadence-economics (21dc145)

Option A — Install from npm PR tag (recommended)

pi install npm:billion-context-pi@pr-360

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

Option B — Download artifact

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

tar xzf billion-context-pi-pr360.tgz
pi install ./package

---

This comment is automatically updated on each push.

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Review complete — verified, two small issues fixed directly on the branch, mergeable.

Duplicate screening. No duplicate. Lineage check: this PR closes #359, which was itself screened in its own triage against #343 (related-but-not-duplicate: #343 concluded the cache re-pay is inherent to in-place compression and locked by tests/prefix-stab.test.ts; #359 is the follow-up economics correction + cadence change). No other open/closed issue or PR touches the nudge growth step default or event=applied geometry fields.

Diff hygiene. Pass. 8 files, all directly related to #359 (src/config.ts, src/compress-tool.ts, 5 test files, 2 config docs). No version bump, no lockfile change, no unrelated churn, no whitespace drift.

Claim-by-claim verification (checked against acp-kernel 0.0.62 source, which is what this merges onto):

• Kernel defaults confirmed: growthRatio: 0.05, growthFloor: 5e4, growthCap: 5e4, minGrowthFloor: 2e4, minGrowthRatio: 0.45; resolveAdaptiveGrowth = min(growthCap, max(growthFloor, round(limit × growthRatio))). Since floor=cap, the effective step is fixed at the floor for all window sizes (not only ≤1M) — so the old default was fixed 50K everywhere and the new one is fixed 100K everywhere. The doc's "windows ≤1M resolve to growthFloor" framing is accurate but understated; the clean-doubling claim holds even beyond 1M. Not a defect.
• Re-inject floor math confirmed: max(20K, 0.45 × adaptiveGrowth) → 22.5K → 45K exactly as documented (adapter mirrors it verbatim in src/index.ts).
• Scale consistency confirmed: firstFoldStartTokens receives the identical messages / collectCoveredMessageIds(state) (pre-fold state) / imageTokens as the beforeTokens call (src/compress-tool.ts:372) — "same list/scale" holds by construction.
• Tier-distillation anchors: kernel's summary message id scheme is acp_summary_${blockId} (SUMMARY_ID_PREFIX, dist line 107) — acp_summary_${childId} matches. For a T2 block its raw effectiveMessageIds aren't in the rendered view anymore, so findIndex correctly falls through to the child acp_summary_bN anchor = the true divergence point. Mixed folds take the union, earliest wins.
• Invariant firstFoldStartPct ≤ retainedPctUpperBound: prefix messages survive the fold unchanged and the summary adds σ>0 tokens, so afterTokens ≥ P+σ > P deterministically. Sound.

Fixed directly on the branch (commit 21dc145, pushed):

1. Missing CHANGELOG entry — house convention for user-facing features (precedent: Title: Context never auto-compresses when the model ignores the nudge — climbs 75%→95%+ on long agentic tasks (no enforcement path) #269, reasoning-drop never fires in single-user-message marathon sessions (closed-turn gate unreachable) #348, [bug] 长会话末尾 thinking 退化为连续重复的「【」(4655 个) 后 turn 被 abort,会话停死 #351) is a bullet under ## Unreleased; added the entry describing both changes. (Recent internal-only PRs like fix: degeneration guard — collapse single-codepoint runs in assistant text/thinking + one-shot recovery notice #352/[bug] thinking tokens 不计入 ACP 计量：extractText 跳过 thinking 块，无 usage 上报的会话压缩带盲区 #353 skipped it, but this is a user-visible default change, so it gets one.)
2. Wrong bound in tests/nudge-reinject.test.ts comment — said "impossible under 233K windows"; correct boundary is L > 225K (first inject ≥0.75L non-emergency, re-inject ≥ first+45K < 0.95L ⟺ 0.75L + 45K < 0.95L). Comment corrected with the derivation; the chosen 280K window satisfies it either way.

Mergeability. The branch had drifted behind master (#352/#353/#357/#358 landed since, including the kernel pin 0.0.60→0.0.62). I rebased it onto current master b5e4333 — clean, zero conflicts (overlap was only docs + config.ts, different sections) — so the PR is now current and GitHub reports mergeable: true (state blocked = pending checks only). Full verification on the final branch state: npm ci ok, tsc --noEmit clean, 698 tests / 695 pass / 0 fail / 3 pre-existing skips, build clean (dist 748.59 KB). No cross-repo publish-order concern: no kernel bump needed, merged result rides the already-published 0.0.62.

Verdict: ready to merge once CI checks pass.

---

中文摘要:核对并修复了两个小问题——补上了缺失的 CHANGELOG 条目、更正了重注入窗口边界注释(233K→正确的 ≤225K),并把分支 rebase 到最新 master(kernel 0.0.62)后全量验证通过(typecheck 干净、695/698 通过、构建正常),可以合并。