fix(content-router): honor target_ratio in compression cache + add proxy --target-ratio flag (#1108)

## Summary

Two small, focused changes around the Kompress **target_ratio** knob
(the keep-ratio for the text/prose/code compression path).

### 1. Bug fix — compression cache ignored `target_ratio`
`ContentRouter`'s two-tier cache (`skip_set` + `result_cache`) keyed on
`hash(content)` **alone**. Compressing the *same* content at a
*different* `target_ratio` returned the first call's cached result, so
the ratio knob silently did nothing on repeated/identical content. Now
the runtime `target_ratio` is part of the cache key at all three sites,
so a different ratio is a distinct cache entry.

### 2. Feature — `headroom proxy --target-ratio`
The keep-ratio was only settable via the `HEADROOM_TARGET_RATIO` env
var. This adds a first-class CLI flag (precedence: **flag > env >
unset**).

- **Default is unset** — Kompress keeps deciding via its own importance
threshold (`score_threshold=0.5`, conservative). No behavior change out
of the box.
- Pass `--target-ratio 0.4` to force ~40% keep for aggressive prose/code
compression (lower = more aggressive).

## Why
While building a context-compression demo, prose/RAG payloads barely
compressed and tuning `target_ratio` appeared to have no effect. Root
cause was the cache key (#1) masking the ratio on identical content; the
flag (#2) makes the knob discoverable. Verified: with the cache fix, the
same prose compresses 18% → 54% → 75% at `target_ratio` None → 0.4 →
0.2.

## Testing
- `ruff check` + `ruff format` + `mypy` clean on both files.
- `tests/test_compression_cache.py`, `tests/test_cli_proxy_env.py`,
`tests/test_cli_proxy_improvements.py` — 121 passed.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

headroom/cli/proxy.py

@@ -164,6 +164,19 @@ def _selected_context_tool() -> str:
         "cost_savings) are still accepted. Env: HEADROOM_MODE."
     ),
 )
+@click.option(
+    "--target-ratio",
+    type=float,
+    default=None,
+    show_default=True,
+    envvar="HEADROOM_TARGET_RATIO",
+    help=(
+        "Override Kompress keep-ratio for text (prose/code) compression — lower is "
+        "more aggressive (e.g. 0.4 keeps ~40% of tokens). Unset (default): let "
+        "Kompress decide via its own importance threshold (conservative). "
+        "Env: HEADROOM_TARGET_RATIO."
+    ),
+)
 @click.option(
     "--intercept-tool-results",
     is_flag=True,
@@ -616,6 +629,7 @@ def _selected_context_tool() -> str:
 def proxy(
     ctx: click.Context,
     mode: str | None,
+    target_ratio: float | None,
     host: str,
     port: int,
     workers: int,
@@ -818,7 +832,7 @@ def proxy(
         tool_profiles=_parse_tool_profiles([]) or None,
         smart_crusher_with_compaction=_get_env_bool_optional("HEADROOM_SMART_CRUSHER_COMPACTION"),
         savings_profile=os.environ.get("HEADROOM_SAVINGS_PROFILE") or None,
-        target_ratio=_get_env_float_optional("HEADROOM_TARGET_RATIO"),
+        target_ratio=target_ratio,
         compress_system_messages=_get_env_bool_optional("HEADROOM_COMPRESS_SYSTEM_MESSAGES"),
         protect_recent=_get_env_int_optional("HEADROOM_PROTECT_RECENT"),
         protect_analysis_context=_get_env_bool_optional("HEADROOM_PROTECT_ANALYSIS_CONTEXT"),

headroom/transforms/content_router.py

@@ -2486,7 +2486,9 @@ class ContentRouter(Transform):
             # Two-tier compression cache.
             # Tier 1 (skip): known won't-compress → instant skip.
             # Tier 2 (result): known compresses → reuse compressed text.
-            content_key = hash(content)
+            # Key on the runtime target_ratio too: the same content compressed at
+            # a different ratio is a different result, so it must not alias.
+            content_key = hash((content, getattr(self, "_runtime_target_ratio", None)))
 
             # Tier 1: skip set — instant rejection
             if self._cache.is_skipped(content_key):
@@ -2861,7 +2863,9 @@ class ContentRouter(Transform):
                     # Two-tier compression cache → shared helper
                     compressed_content, was_compressed = self._compress_block_content(
                         content=tool_content,
-                        content_key=hash(tool_content),
+                        content_key=hash(
+                            (tool_content, getattr(self, "_runtime_target_ratio", None))
+                        ),
                         context=context,
                         bias=bias,
                         min_ratio=min_ratio,
@@ -2904,7 +2908,9 @@ class ContentRouter(Transform):
                     # Two-tier compression cache → shared helper
                     compressed_content, _was_compressed = self._compress_block_content(
                         content=text_content,
-                        content_key=hash(text_content),
+                        content_key=hash(
+                            (text_content, getattr(self, "_runtime_target_ratio", None))
+                        ),
                         context=context,
                         bias=1.0,
                         min_ratio=min_ratio,