feat(proxy): opt-in compression for catch-all passthrough routes (#1699)

## Description

Requests whose path doesn't match a built-in API route fall through to
`handle_passthrough`, which forwarded the body verbatim — bypassing
ContentRouter/Kompress/TOIN entirely. Wrapper-proxy setups that front
Headroom on custom paths (e.g. `/api/codex-proxy/<key>/v1/responses`)
got zero compression on coding-agent traffic and hit context-limit 400s
in long sessions. This adds an opt-in flag that routes OpenAI
Responses-shaped passthrough bodies through the same compression path
the native `/v1/responses` handler uses.

Closes #1546

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [x] 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

- Added `ProxyConfig.compress_passthrough` (default `False`) +
`--compress-passthrough` CLI flag + `HEADROOM_COMPRESS_PASSTHROUGH=1`
env.
- `handle_passthrough`: when enabled, POST requests whose path ends in
`/responses` with an OpenAI Responses-shaped body are compressed via the
existing `_compress_openai_responses_payload_in_executor` before
forwarding; stale `Content-Length` is dropped so httpx recomputes it.
- New `_maybe_compress_passthrough_responses` helper — fail-open:
non-JSON, non-Responses payloads, unmodified results, and any compressor
error forward the original body unchanged.
- Documented the flag in `docs/content/docs/proxy.mdx`.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ .venv/bin/python -m pytest tests/test_compress_passthrough.py -q
collected 6 items
tests/test_compress_passthrough.py ......                                [100%]
============================== 6 passed in 0.35s ===============================

$ .venv/bin/ruff check headroom/proxy/handlers/openai.py headroom/proxy/models.py headroom/proxy/server.py tests/test_compress_passthrough.py
All checks passed!
```

## Real Behavior Proof

- Environment: macOS arm64, Python 3.14, repo `.venv`.
- Exact command / steps: `.venv/bin/python -m pytest
tests/test_compress_passthrough.py -q` — covers a Responses-shaped body
being compressed, non-JSON passthrough, non-Responses (`messages`)
payload untouched, unmodified-result short-circuit, compressor-error
fail-open, and `ProxyConfig().compress_passthrough is False` default.
Plus import smoke: `ProxyConfig(compress_passthrough=True)`,
server/handler modules import, helper present.
- Observed result: 6 passed; flag defaults off; enabled path reuses the
native Responses compressor and never raises out to the request.
- Not tested: live end-to-end through a real second proxy to a real
upstream (no external wrapper proxy / upstream credentials in sandbox);
the compression call is the same one `/v1/responses` already exercises
in CI.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [ ] I have updated the CHANGELOG.md if applicable

## Additional Notes

Scoped to OpenAI Responses-shaped bodies (the reporter's exact case).
Anthropic `/messages` and OpenAI `/chat/completions` passthrough
compression are natural follow-ups — deliberately left out to keep this
change focused and fail-safe. CHANGELOG is release-managed, left
unchecked.

docs/content/docs/proxy.mdx

@@ -124,11 +124,13 @@ HEADROOM_SAVINGS_PROFILE=agent-90 headroom proxy --port 8787
 | `--no-learn` | `false` | Explicitly disable traffic learning |
 | `--min-evidence` | `5` | Minimum observations before a learned pattern is persisted |
 | `--codex-wire-debug` | `false` | Write local Codex wire snapshots and matching proxy log traces |
+| `--compress-passthrough` | `false` | Also compress custom proxy paths that fall through to the catch-all handler (OpenAI Responses-shaped bodies, path ends in `/responses`). Also `HEADROOM_COMPRESS_PASSTHROUGH=1` |
 
 ```bash
 headroom proxy --memory
 headroom proxy --learn --min-evidence 3
 headroom proxy --codex-wire-debug
+headroom proxy --compress-passthrough
 ```
 
 <Callout type="info" title="LLMLingua removed from the proxy CLI">