fix(agent-runtime): calibrate the context estimate against what requests cost

docs/spec/03-runtime/02-agent-runtime.md

@@ -481,6 +481,26 @@ boundary falls, not what survives it. The active-user retention limit is 20,000
 tokens, capped at half the hard budget so retention alone cannot fill a small
 window and leave the summary no room. None of these values are configurable.
 
+**Estimate calibration (D606).** Every threshold above is compared against one
+number, and that number is corrected against what requests actually cost. pi's
+`estimateContextTokens` anchors on the last assistant usage and estimates
+everything after it as `chars / 4`: that constant under-counts CJK text, and
+with no anchor left it omits the system prompt and the tool schemas, which the
+next request still pays for. The two errors are measured and applied
+separately — the per-character bias as a scale-free ratio over the guessed
+tail, and an unanchored residual as a ratio only for observations taken at a
+comparable scale (0.5×–2× of the estimate), otherwise as the observed overhead
+capped at 32,000 tokens.
+
+The correction is asymmetric because this number gates compaction: upward
+applies once three observations exist, downward needs three agreeing samples,
+is capped at 15 % per step and can never take the value below 85 % of the raw
+estimate, so a projection at 1.18× the hard limit (`1 / 0.85`) still compacts.
+A report outside 0.5×–3× of what the calibration predicted is treated as a
+misreport, and two consecutive misreports freeze the downward direction until a
+usable report arrives.
+
+
 The provider request layer also caps the concrete output budget before every
 parent, subagent, and one-shot request. It estimates the serialized input with
 the pi-ai chars/4 baseline plus a CJK correction, then reserves the larger of

docs/spec/06-delivery/04-e2e-test-plan.md

@@ -8002,6 +8002,7 @@ identify the platform validation still needed.
 | C — Conversation & stream (delegate context budget) | E2E-SUBAGENT-context-overflow-compacts-before-failing, E2E-SUBAGENT-context-overflow-reports-actionable-failure, E2E-SUBAGENT-resume-seeds-within-context-budget |
 | Quality (delegate context budget) | E2E-SUBAGENT-context-overflow-compacts-before-failing, E2E-SUBAGENT-context-overflow-reports-actionable-failure, E2E-SUBAGENT-resume-seeds-within-context-budget |
 | M6+ (delegate context budget) | E2E-SUBAGENT-context-overflow-compacts-before-failing, E2E-SUBAGENT-context-overflow-reports-actionable-failure, E2E-SUBAGENT-resume-seeds-within-context-budget |
+| C / F / Quality — The context estimate stays safe (calibration) | E2E-CONTEXT-estimate-calibration-stays-safe |
 | C — Conversation & stream (unique tool-call ids) | E2E-RUNTIME-unique-tool-call-ids-per-request |
 | Quality (unique tool-call ids) | E2E-RUNTIME-unique-tool-call-ids-per-request |
 | G — Plugin host lifecycle (crash report) | E2E-PLUGIN-crash-report-names-the-exit-code |
@@ -14161,6 +14162,27 @@ the latest destination. These assertions measure work counts, not device FPS.
   success fixture uses a child-only extra CA; it does not reproduce a specific
   antivirus installation or claim native macOS/Linux verification.
 
+### E2E-CONTEXT-estimate-calibration-stays-safe
+
+- **Preconditions:** Deterministic provider fixture whose reported usage can be
+  scripted; a session whose occupancy is close to the hard boundary; no real
+  provider credentials.
+- **Steps:** Report usage below the prediction repeatedly and confirm the
+  displayed occupancy never falls below the floor and compaction still fires;
+  report usage far outside the plausible band and confirm the value does not
+  move; run a CJK-heavy session and compare the displayed occupancy with the
+  reported usage.
+- **Expected:** The calibrated occupancy stays within 0.85×–6× of the raw
+  estimate, moves up as soon as there is evidence, moves down only after
+  agreeing samples, and a projection at 1.18× the hard limit still compacts.
+  Misreports move it in neither direction. CJK text no longer reads at a
+  quarter of its measured cost.
+- **Specs linked:** `03-runtime/02-agent-runtime.md` §5.1,
+  `08-meta/decisions-log.md` D606
+- **Acceptance:** C (chat and stream), F (persistence), Quality
+- **Status:** Unit-covered (`context-calibration.test.ts`, including the CJK and
+  boundary cases); desktop E2E pending
+
 ### E2E-RUNTIME-unique-tool-call-ids-per-request
 
 - **Preconditions:** A session transcript that carries the same tool call twice

docs/spec/08-meta/decisions-log.md

@@ -6476,6 +6476,25 @@ that was sitting at the bottom — including after the turn had finished.
   state, protocol, persistence, theme schema, or permission change. See
   `04-ux/08-component-spec.md` and E2E-CHAT-opaque-floating-decision-and-retry-surfaces.
 
+## 2026-09-21 — The context estimate is calibrated conservatively (D606)
+
+- Every budget threshold reads one number, and that number is corrected against
+  what requests actually cost. pi's estimator anchors on the last assistant
+  usage and estimates the rest as `chars / 4`, which under-counts CJK text by
+  roughly a factor of 2–4 and, with no anchor left, omits the system prompt and
+  tool schemas entirely.
+- The two errors are applied separately: the per-character bias as a
+  scale-free ratio over the guessed tail, and an unanchored residual as a ratio
+  only for observations taken at a comparable scale (0.5×–2×), otherwise as the
+  observed overhead capped at 32,000 tokens. A 100k-scale sample therefore
+  cannot be applied as a ratio to a 1M projection.
+- The correction is asymmetric: upward applies once three observations exist;
+  downward needs three agreeing samples, is capped at 15 % per step, and can
+  never take the value below 85 % of the raw estimate, so a projection at
+  1.18× the hard limit still compacts. A report outside 0.5×–3× of what the
+  calibration predicted is a misreport, and two consecutive misreports freeze
+  the downward direction. See `03-runtime/02-agent-runtime.md` §5.1.
+
 ## 2026-09-21 — A tool-call id is unique in every request (D608, issue #718)
 
 - Anthropic-family endpoints, DeepSeek's included, reject a whole turn with

docs/zh-CN/spec/03-runtime/02-agent-runtime.md

@@ -377,6 +377,16 @@ Headroom 是 16,384 个代币储备底线的最大值，模型最大输出
 小窗口，没有留下摘要的空间。这些值都不是
 可配置。
 
+**估算校准（D606）。** 上述每个阈值都对着同一个数字比较，而该数字会按请求的真实开销校正。pi 的 `estimateContextTokens`
+以最后一条助手用量为锚，其余一律按 `chars / 4` 估算：该常数会低估中文文本，且在没有锚点时完全不含系统提示与工具结构，
+而下一次请求仍要为它们付费。两类误差分开处理——逐字符偏差以「猜测尾部」上的比例表示（与量级无关）；无锚点残差只在与之
+量级相当的样本（0.5×–2×）上按比例应用，否则只加上观测到的固定开销（上限 32,000 词元）。
+
+校正是不对称的，因为这个数字决定压缩：向上修正只要有三个观测即生效；向下修正需要三个方向一致的样本、每次最多 15 %，
+且永远不能把数值压到原始估算的 85 % 以下——因此处在硬限制 1.18×（`1 / 0.85`）的投影仍会触发压缩。偏离校准预测
+0.5×–3× 之外的报告视为误报；连续两次误报会冻结向下修正，直到出现可用报告。
+
+
 传入的用户提示先于第一个提供商参与预算
 请求。自动摘要请求在有界的 pi-ai 重试策略下重试瞬时的提供商失败
 （3 次重试，2s/4s/8s 退避，Stop 可取消）；配额、鉴权等确定性失败立即返回。

docs/zh-CN/spec/06-delivery/04-e2e-test-plan.md

@@ -5288,6 +5288,7 @@ eleven-tool-round desktop paths are verified by
 | C — 对话和直播（委托上下文预算） | E2E-SUBAGENT-context-overflow-compacts-before-failing、E2E-SUBAGENT-context-overflow-reports-actionable-failure、E2E-SUBAGENT-resume-seeds-within-context-budget |
 | 品质（委托上下文预算） | E2E-SUBAGENT-context-overflow-compacts-before-failing、E2E-SUBAGENT-context-overflow-reports-actionable-failure、E2E-SUBAGENT-resume-seeds-within-context-budget |
 | M6+（委托上下文预算） | E2E-SUBAGENT-context-overflow-compacts-before-failing、E2E-SUBAGENT-context-overflow-reports-actionable-failure、E2E-SUBAGENT-resume-seeds-within-context-budget |
+| C / F / 品质 —— 上下文估算保持安全（校准） | E2E-CONTEXT-estimate-calibration-stays-safe |
 | C — 对话与流式（工具调用 id 唯一） | E2E-RUNTIME-unique-tool-call-ids-per-request |
 | 品质（工具调用 id 唯一） | E2E-RUNTIME-unique-tool-call-ids-per-request |
 | G — 插件宿主生命周期（崩溃上报） | E2E-PLUGIN-crash-report-names-the-exit-code |
@@ -8341,6 +8342,16 @@ the latest destination. These assertions measure work counts, not device FPS.
 - **规格：** 04-ux/06-settings-ia、04-ux/08-component-spec、
   04-ux/09-interaction-patterns；ADR turn-process-and-thinking-display。
 
+### E2E-CONTEXT-estimate-calibration-stays-safe
+
+- **先决条件：** 可脚本化上报用量的确定性提供商夹具；占用接近硬边界的会话；不使用真实凭据。
+- **步骤：** 连续上报低于预测的用量，确认显示占用不低于下限且压缩仍然触发；上报远离合理区间的用量，确认数值不动；跑一个
+  中文为主的会话，比较显示占用与上报用量。
+- **预期：** 校准后的占用保持在原始估算的 0.85×–6× 之内；有证据即上调；只有方向一致的样本才下调；处在硬限制 1.18× 的
+  投影仍触发压缩；误报不产生任何方向的移动；中文文本不再只有实测成本的四分之一。
+- **规格：** 03-runtime/02-agent-runtime §5.1、08-meta/decisions-log D606。**验收：** C（对话与流）、F（持久化）、品质。
+  **状态：** 单元测试覆盖（含中文与边界用例）；桌面 E2E 待补。
+
 ### E2E-RUNTIME-unique-tool-call-ids-per-request
 
 - **先决条件：** 一份把同一次工具调用携带两次的会话转录（重试追加让该调用落在第二个行 id 上），在确定性提供商夹具下加载进

docs/zh-CN/spec/08-meta/decisions-log.md

@@ -4599,6 +4599,16 @@ that amendment are retired by ADR 0268; the upstream work-panel lifecycle stays.
   或权限。见 `04-ux/08-component-spec.md` 与
   E2E-CHAT-opaque-floating-decision-and-retry-surfaces。
 
+## 2026-09-21 —— 上下文估算采用保守校准（D606）
+
+- 所有预算阈值读取同一个数字，该数字按请求的真实开销校正。pi 的估算器以最后一条助手用量为锚、其余按 `chars / 4` 估算，
+  这会低估中文文本约 2–4 倍；没有锚点时还会完全漏掉系统提示与工具结构。
+- 两类误差分开应用：逐字符偏差是按比例（与量级无关）作用于猜测尾部；无锚点残差只在量级相当的样本（0.5×–2×）上按比例
+  应用，否则只加观测到的固定开销（上限 32,000 词元）。因此 100k 量级的样本不会作为比例系数套到 1M 的投影上。
+- 校正不对称：向上修正有三个观测即生效；向下修正需要三个方向一致的样本、每次最多 15 %，且不会低于原始估算的 85 %——
+  处在硬限制 1.18× 的投影仍会压缩。偏离预测 0.5×–3× 的报告视为误报，连续两次误报冻结向下修正。
+  见 `03-runtime/02-agent-runtime §5.1`。
+
 ## 2026-09-21 —— 每个请求里的工具调用 id 必须唯一（D608，issue #718）
 
 - Anthropic 系端点（含 DeepSeek）在请求中同一个调用 id 出现两次时，会以 `tool_use ids must be unique` 拒绝整个回合，
@@ -4607,7 +4617,7 @@ that amendment are retired by ADR 0268; the upstream work-panel lifecycle stays.
 - 因此上线前的最后一个视图对每个 `toolCall` id 只保留第一次出现，丢弃其后重复的调用或结果，使提供商校验的「一调用一结果」
   配对保持完整；没有重复的请求原样返回（返回同一对象，而非副本）。磁盘上的内容不会被改写，压缩与保留规则也不变。
 - 一旦发生丢弃，会在 `agent` 日志通道上报告一次，带上会话与 id，使下一次同类报障能指向写入方而不只是提供商那句话。
-  见 `03-runtime/02-agent-runtime.md` §5。
+  见 `03-runtime/02-agent-runtime §5`。
 - 守卫刻意放在请求边界而不是历史重建处：这样也能覆盖**会话运行期间**产生的重复，而重建期的过滤看不到它。
 
 ## 2026-09-21 —— 插件崩溃上报带上退出码但不复制原始输出（D607，issue #747）