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

[zhangqingkun976]

Successor of #748, which is closed: the branch was rebased onto main through the API, GitHub reads that as a force-push, and it refuses to reopen a closed PR whose branch was force-pushed (state cannot be changed. The … branch was force-pushed or recreated.). Same commits, same content, rebased head — nothing was rewritten except the base.

This reopens #683 with the four points from your review addressed. Thank you for the specific diagnosis — the asymmetry of the lower clamp and the fixed offset were both real defects in the first version.

1. Anomalous usage is handled conservatively

The correction is asymmetric now, because this number gates compaction:

direction	when it applies	bound
upward	as soon as three observations exist	up to CONTEXT_CALIBRATION_FACTOR_MAX (6×)
downward	only after CONTEXT_CALIBRATION_DOWNWARD_CONSECUTIVE (3) agreeing samples	≤ CONTEXT_CALIBRATION_DOWNWARD_STEP_MAX (15 %) per step, and never below CONTEXT_CALIBRATION_FACTOR_MIN (0.85) of the raw estimate

Consequences that are now asserted in tests rather than argued: a projection at CONTEXT_CALIBRATION_BOUNDARY_GUARD_RATIO (1 / 0.85 ≈ 1.18×) of the hard limit still compacts, and how far a correction may defer the boundary is bounded by 1 − FACTOR_MIN. A report outside 0.5×–3× of what the calibration predicted is treated as a misreport: it moves the value in neither direction and is counted, and CONTEXT_CALIBRATION_ANOMALY_FREEZE (2) consecutive ones freeze the downward direction until a usable report arrives.

2. Ratio and fixed offset are separate quantities

• The per-character bias is a ratio over the guessed tail — scale-free by construction, so the same correction applies at 2k or 200k tokens.
• An unanchored residual is split. The ratio form is used only for observations taken at a comparable scale (CONTEXT_CALIBRATION_SCALE_BAND_*, 0.5×–2× of the estimate being corrected). Out of band, only the fixed part is added — the observed overhead, capped at CONTEXT_CALIBRATION_OVERHEAD_CAP (32,000 tokens) so it stays an overhead.
• A 100k-scale sample therefore cannot be applied as a ratio to a 1M projection, and once the 1M scale has been observed the correction becomes proportional instead of staying at the small session's fixed offset.

3. Regression coverage

packages/agent-runtime/src/context-calibration.test.ts (13 cases) covers the four areas you named:

• Under-reporting — a full window of low reports cannot carry the value below the floor; no downward move happens before agreeing samples; upward applies immediately; two consecutive misreports freeze the direction and a usable report unfreezes it.
• Different context scales — ratio in band, capped overhead out of band, and the correction becoming proportional after observing the large scale.
• Real CJK text — a real Chinese paragraph: the corrected tail matches the measured cost within ±5 % and the ratio lands inside the documented 2–4 band.
• Compaction boundary — the guard ratio still compacts; the deferral is bounded by 1 − FACTOR_MIN; a wild report moves nothing.

4. Rebase and validation

Rebased onto main (79cd7ae8). The only conflict was the budget-formula extraction (#733): contextBudgetFor now owns the body, and the calibration is applied on top of that budget.

Local, on this branch: pnpm --filter @pi-desktop/agent-runtime build 0; pnpm --filter @pi-desktop/agent-runtime test 47/48 files — the single failure is the pre-existing native-pi-session case that fails identically on pristine main; node scripts/check-architecture.mjs passed; pnpm lint clean; pnpm docs:check (78 EN/zh pairs, 495 pages) exit 0.

E2E gate: NOT RUN. The scenario is written (E2E-CONTEXT-estimate-calibration-stays-safe) but no desktop E2E suite was executed: it needs a scripted-usage provider fixture that does not exist yet. Alternative validation: the module is pure arithmetic and fully unit-covered, including the CJK and boundary cases. Remaining risk: the calibrated number as it appears in the live occupancy ring has not been observed against a real provider's usage reports.

Specification and decisions

• docs/spec/03-runtime/02-agent-runtime.md §5.1 — the calibration paragraph, next to the boundary it protects; mirrored to docs/zh-CN/….
• 08-meta/decisions-log.md — D606 (numbered after the D604/D605 proposed in feat(agent-runtime): recall, a reversible compaction boundary, and per-model context settings #721; I will renumber if that lands later).
• 06-delivery/04-e2e-test-plan.md — the scenario above plus its traceability row; mirrored.