feat(proxy): report the mean of each request's saving on session and project rows

[Mearman]

Description

Session and project rows report savings_percent as everything saved over everything that would have been sent, so a few large requests dominate it. The mean of each request's own saving, where every request weighs the same, cannot be recovered from the totals the entries keep.

Each entry now also keeps the sum of its requests' saving percentages and a count of the requests that contributed, and the row presents the quotient as avg_request_savings_percent next to savings_percent. The count is separate from requests because an entry persisted before these fields existed has requests the sum never saw; it reports null until new requests accumulate instead of a mean that is understated for good. The accumulation and the row derivation were written out twice, once for projects and once for sessions, and are now shared.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Performance improvement
• Code refactoring (no functional changes)

Changes Made

• headroom/proxy/savings_tracker.py: per-entry accumulators request_savings_percent_sum and request_savings_percent_requests, normalised on load so a state file without them reads as no contributing requests.
• _accumulate_entry and _entry_view replace the duplicated project and session accumulation and row derivation.
• docs/content/docs/proxy.mdx: the two percentages on a session row.
• tests/test_request_savings_percent.py: the mean against the overall figure, the project row, a reload, and a state file from before the fields.

Testing

• Unit tests pass (pytest)
• Linting passes (ruff check .)
• Type checking passes (mypy headroom)
• New tests added for new functionality
• Manual testing performed

Test Output

$ uv run --extra dev python -m pytest tests/test_request_savings_percent.py -q
collected 4 items
tests/test_request_savings_percent.py ....                               [100%]
4 passed

CI's lint, test shards, test-extras and the other test jobs pass on this head.

Real Behavior Proof

• Environment: the repository's uv development environment, Python 3.14.
• Exact command / steps: uv run --extra dev python -m pytest tests/test_request_savings_percent.py -q
• Observed result: four passed; the mean differs from savings_percent when request sizes differ, and an entry loaded from a pre-change state file reports avg_request_savings_percent as null.
• Not tested: a live proxy run against a provider.

Runtime Rollout Safety

• Rollout-managed feature(s): none
• Minimum rollout channel: not applicable
• Stable/default behavior changed: no; savings_percent is unchanged and avg_request_savings_percent is an added field
• Kill switch / disable path: not applicable
• Unsafe override required: no
• Qualification impact: none
• Rollback path: revert the commit; the extra accumulators in a persisted state file are ignored by the previous code

Review Readiness

• I have performed a self-review
• This PR is ready for human review

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• I did not edit CHANGELOG.md (it is generated by release-please from my Conventional Commit PR title)

Additional Notes

The Dependency audit (pip-audit) and Rust advisories (cargo audit) checks fail on advisories against dependencies in the lock files (mcp, quinn-proto, rustls), which this change does not touch; they fail the same way on any branch cut from main until those dependencies are bumped.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
🔒 Security Review	⚠️ Failed 2026-10-16T09:56:53.179988Z	e2b7313	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

This security review couldn’t start because the paying account has exhausted its Codex allowance and has insufficient available credits. The payer can check their balance and add credits in the Codex usage dashboard, then try again. If you do not manage the paying account, contact this repository's admins.

[github-actions]

PR governance

This PR follows the template and is marked ready for human review.